search

POSTProcess Transaction API

Use Case

It is used to process the transaction with respect to paymentMode provided by merchant in the request. We either return bank form for paymentMode like NET_BANKING, CREDIT_CARD, DEBIT_CARD or provide the result of payment in case of paymentMode like BALANCE, PAYTM_DIGITAL_CREDIT and Decoupled flow transaction (Authorization only) etc.

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string
optional

Version of the API.

Example: v1

requestTimestamp
string
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

channelId
string
optional

The parameter value identifies the Channel for which API call is initiated.

Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
txnToken
string
mandatory

This is the unique transaction token received in the response of Initiate Transaction API or Initiate Subscription API. It is valid for 15 minutes.

Example:f0bed899539742309eebd8XXXX7edcf61588842333227

Body

AttributeDescription
mid
string
mandatory

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.

Example: INTEGR7769XXXXXX9383

orderId
string
mandatory

It is unique reference ID for a transaction passed in Initiate Transaction API or Initiate Subscription API.

Example: OREDRID_98765

paymentMode
string
mandatory

The payment mode used by customer for transaction.

Possible values:
BALANCE
For Paytm Wallet
,
PAYTM_DIGITAL_CREDIT
For Paytm Postpaid
,
UPI
For Bhim Upi
,
UPI_INTENT
For Upi Intent
,
CREDIT_CARD
For Credit Card
,
DEBIT_CARD
For Debit Card
,
NET_BANKING
For Net Banking
,
EMI
For emi options
cardInfo
string
optional

It contains the details of the saved and new card in the format below:
cardInfo: saveCardId|cardNo|cvv|expDate.

Possible Values:
For New Card - |4111111111111111|123|122032
For Token Card - 123123||123|
For Token Card of non-Paytm TG- ||111|

authMode
string
optional

Authentication mode for cards

Possible values:
otp
For Mobile OTP
,
pin
For ATM PIN
channelCode
string
optional

BankCode (only in NET_BANKING)

Possible Values: PYTM, SBI, ICICI, HDFC, Refer here for other bank codes

paymentFlow
string
optional

Define the payment flow applied on merchant.

Possible values:
NONE
For Default
,
ADDANDPAY
For Add and Pay
,
HYBRID
For Hybrid
payerAccount
string
optional

VPA, this is needed for a UPI transaction.

Example: 7777777777@paytm

planId
string
optional

This is the plan chosen for EMI, Input could be: BankCode|Month.

Example: ICICI|3

requestType
string
mandatory

Request type

Possible Values: NATIVE

walletType
string
optional

Only required for Intelligent Router when paymentMode is WALLET.

Possible Values: PAYTMPG

emiType
string
conditional

Mandatory, in case of transaction for Debit card EMI

Possible Values: DEBIT_CARD, CREDIT_CARD

preferredOtpPage
string
optional

Possible Values: bank, merchant
bank - If merchant desires that authentication takes place on bank page
merchant - If merchant desires that authentication takes merchant or Paytm hosted OTP page

In case the merchant chooses to authenticate on the merchant page and Paytm cannot honour the request then Paytm will fail the transaction. 

coftConsent
object
optional

Consent to tokenize the instrument or not.

Possible values: 1 ,  0

coftConsent
+
AttributeDescription
userConsent
boolean
mandatory

Tokenisation consent from the user in a boolean expression.Sample Value: (1,0) 

createdAt
string
mandatory

Timestamp when user consented for tokenization was captured
Sample Value: Jul 22, 2021 02:46:54 PM

userConsentId
string
optional

The ID of the message displayed to the user for consent

language
string
optional

Language in which consent was accepted by end customer
Language in which consent was accepted by end customer
Sample Value: en en

platform
string
optional

PHONE, TABLET, PC, WATCH, OTHER,APP
Sample Value: APP

os
string
optional

The OS on which consent was given by the user such as Android, IOS, Windows, Web, Others
Sample Value:androidapp

appVersion
string
optional

App version of merchant or Paytm on which consent was collected
Sample Value: 9.10.2

locale
string
optional

Location of application communicating to cardholder
sample value. en-IN

ip
string
optional

IP address of the device that accepted the consent
Sample Value: 157.35.79.240

deviceId
string
optional

Device ID of the device that accepted the consent 
Sample Value : samsung-SM-A260G-01b9ec5dc11fc570

deviceName
string
optional

Device Name of the device that accepted the consent
Sample Value: SM-A260G\

cardTokenInfo
object
optional

Token data required to process a token transaction.

cardTokenInfo
+
AttributeDescription
cardToken
string
mandatory

16 digits Token PAN

tokenExpiry
string
mandatory

Token expiry. Format: MMYYYY

TAVV
string
mandatory

Token Verification Value generated by the network valid for a single token card  payment

Note: This param is not required for Diners saved card payments
cardSuffix
string
mandatory

Last 4 digits of the actual card.

panUniqueReference
string
mandatory

The unique reference allocated to the Primary Account Number by the card network also known as PAR.

Note: Merchant can pass unique card identifier of their ecosystem if Network PAR is not available.
tokenUniqueReference
string
conditional

Token reference number is provided by the card or issuer for a given tokenization request.

This param is mandatory to process Diner Card Tokens

Possible Value: Any

merchantTokenRequestorId
string
conditional

Merchant's token requestor id provided by the Network or issuer

This param is mandatory to process Diner Card Tokens

Possible Value: Any

tokenType
string
mandatory

This parameter indicates whether the card transaction is a saved card transaction or a guest checkout transaction.

Possible Values: COFT/ALTERNATE

mobileNumber
string
conditional

Merchant should take mobile number from user for checking the Debit Card EMI eligibility

eci
string
mandatory

Electronic Commerce Indicator (ECI) is a value returned by the Directory Servers (Visa, Master, American Express...) indicating the result of the authentication requested.

This is required only for Decoupled flow (Authorization Only) transactions

Example:
05, 02

acsAuthenticationToken
string
mandatory

This is generated by the issuer's Access Control Server. This provides evidence that cardholder authentication occurred or that the merchant attempted authentication.

This is required only for Decoupled flow (Authorization Only) transactions

Example:  AAIBB0CCAwAABK9qNWMIdAAAAAA=,

dsReferenceNumber
string
optional

This is a unique transaction identifier assigned by the Directory Servers to identify a single transaction. The Directory Server is the element that enables the communication between the 3DS Server and the ACS.

This is required only for Decoupled flow (Authorization Only) transactions

Example:

f6039c96-63a3-4891-9581-d7f2832c5585

acsTransactionId
string
optional

This is a unique transaction identifier assigned by the ACS to identify a single transaction.

This is required only for Decoupled flow (Authorization Only) transactions

Example: 5e46213d-06e0-11ef-9e6c-8f7fc88d7e73

secureVersion3D
string
optional

3-D Secure is a protocol designed to be an additional security layer for online credit and debit card transactions.

This is required only for Decoupled flow (Authorization Only) transactions

Example:

2.1.0, 2.2.0

Example of sample inputs based on different paymentMode

  1. Card transaction (without saved card):
    paymentMode: DEBIT_CARD ( CREDIT_CARD or DEBIT_CARD as per the card )
    cardInfo: |4111111111111111|123|092017
    storeInstrument: 1

  2. Card transaction (with saved card):
    paymentMode: CREDIT_CARD (CREDIT_CARD or DEBIT_CARD as per the card )
    cardInfo: 123456||123|

  3. Card transaction (with auth mode option):
    paymentMode: DEBIT_CARD (CREDIT_CARD or DEBIT_CARD as per the card )
    cardInfo: |4111111111111111|123|092017
    storeInstrument: 1
    authMode: atm (atm and otp in case of user selected option)

  4. Net banking transaction:
    paymentMode: NET_BANKING
    channelCode : PYTM, SBI, ICICI, HDFC, Refer here for other bank codes

  5. Paytm wallet transaction:
    paymentMode: BALANCE

    For intelligent router, please use below:
    paymentMode: WALLET
    walletType: PAYTMPG

  6. UPI Payment Transaction:
    paymentMode: UPI
    channelCode : collect
    payerAccount: abcdefgh@paytm

  7. Paytm Payments Bank
    paymentMode: PPBL

  8. Add and Pay with Cards
    paymentMode: DEBIT_CARD (CREDIT_CARD or DEBIT_CARD as per the card )
    cardInfo: |4111111111111111|123|092017
    paymentFlow: ADDANDPAY

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string

Version of the API passed in the request.
Example: v1

responseTimestamp
string

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

Body

AttributeDescription
resultInfo
object

This parameter gives the information about the result of the API response

ResultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter indicates the status of API call.

Possible values:
S
For Success
,
F
For Failure
resultMsg
string(256)

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

isRedirect
boolean

This flag indicates that number of retries are over and user is to be redirected from cashier page.

bankRetry
boolean

This flag indicates that retry is allowed at bank's end or not.

retry
boolean

This flag indicates whether retry is allowed or not.

txnInfo
object

Basic information about this transaction

TxnInfo
+
AttributeDescription
MID
string

This is a unique identifier provided to every merchant by Paytm.

Example: INTEGR7769XXXXXX9383

TXNID
string

This is a unique Paytm transaction ID that is issued by Paytm for each merchant.

Example: 202005081112128XXXXXX68470101509706

ORDERID
string

Unique reference ID for a transaction which is generated by merchant and sent in the request

Example: OREDRID_98765

BANKTXNID
string

The transaction ID sent by the bank. In case of Paytm proprietary instruments too, there is unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be NULL or empty string. Primary reason for this is user dropping out of the payment flow before the transaction reaches to bank servers.

Example: 77700XXXX215242

TXNAMOUNT
string

Amount to be paid by customer in INR

Example: 1.00

CURRENCY
string

This parameter indicates the currency in which transaction amount is to be deducted.

Possible Values: INR

STATUS
string

This contains the transaction status.

Possible Values: TXN_SUCCESS, TXN_FAILURE and PENDING

RESPCODE
string

Codes refer to a particular reason of payment.

RESPMSG
string

Description message is linked with each respcode.

TXNDATE
string

Date and Time of transaction.

Example: 2015-11- 02 11:40:46.0

GATEWAYNAME
string

Gateway used by Paytm to process the transactions.

Example: HDFC

PAYMENTMODE
string

The payment mode used by customer for transaction.

Possible values:
PPI
For Paytm Wallet
,
UPI
For Bhim Upi
CHECKSUMHASH
string

You should validate the txnInfo object parameter values by verifying the CHECKSUMHASH comes in txnInfo object. It ensures that parameter values are not tempered. CHECKSUMHASH string can be verified by using Paytm checksum library.

VPA
string

VPA address which comes in request payload.

Example: 7777777777@paytm

PROMO_CAMP_ID
string

Promo code

PROMO_RESPCODE
string

Response code of promo code for this transaction

PROMO_STATUS
string

Status of promo code for this transaction

Possible values:
SUCCESS
For Success
,
FAILURE
For Failure
callBackUrl
string

Call back URL which is given in Initiate Transaction API or Initiate Subscription API.

bankForm
object

BankForm Details returned in case of following paymentModes:
CREDIT_CARD, DEBIT_CARD, NET_BANKING, EMI, UPI.

BankForm
+
AttributeDescription
pageType
string

It describe the page type.

 

Possible values:
redirect
For Paytm Form
,
direct
For Bank Form
redirectForm
object

Contains Bank URL , Http method, headers and content to be used by merchant to open bankForm.

FormDetail
+
AttributeDescription
actionURL
string

URL that merchant needs to call.

method
string

http method to be used by merchant to call the above URL.

Example: post

type
string

It describe the form type.

Possible Values: redirect, submit, cancel, resend, payonbank

headers
object

http headers to be used when calling actionURL.

Example: {'Content-Type':'application/json'}

content
object

Map of data that needs to be provided in the request body when calling actionURL.

Example: {"MD":"1386959067","PaReq":"eJxVUsFy4jAM3036f4C56Zvls=", "TermUrl":"https://securegw-stage.paytm.in/instaproxy/bankresponse/HDFC/CC/90200XXXXXXXXXX71676"}

directForms
array of object

Contains APIs (URLs, Header, Payload) to be used on merchant owned Bank Page.

FormDetail
+
AttributeDescription
actionURL
string

URL that merchant needs to call.

method
string

http method to be used by merchant to call the above URL.

Example: post

type
string

It describe the form type.

Possible Values: redirect, submit, cancel, resend, payonbank

headers
object

http headers to be used when calling actionURL.

Example: {'Content-Type':'application/json'}

content
object

Map of data that needs to be provided in the request body when calling actionURL.

Example: {"MD":"1386959067","PaReq":"eJxVUsFy4jAM3036f4C56Zvls=", "TermUrl":"https://securegw-stage.paytm.in/instaproxy/bankresponse/HDFC/CC/90200XXXXXXXXXX71676"}

displayField
object

Contains field like Amount, Bank Name, URL for bank logo etc. which can be used for display purpose.

Example:{ "amount" : "1.0", "headerText" : "", "bankName" : "HDFC", "bankLogo" : "", "descriptionText" : "" }

isForceResendOtp
boolean

Status of resend OTP feature

deepLink
string

DeepLink URL

DeepLink
+
AttributeDescription
url
string

DeepLink URL

deepLinkInfo
object

Information of DeepLink.
UPI_INTENT only

 
DeepLinkInfo
+
AttributeDescription
deepLink
string

DeepLink URL

orderId
string

Order ID is merchant’s unique reference ID for a transaction sent in request.

cashierRequestId
string

Cashier Request ID

transId
string

Transaction ID

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSuccess
0001FFAILED
RC-00018FPayment failed as merchant has crossed his daily/monthly/weekly acceptance limit
309FInvalid Order ID
312FThis card is not supported. Please use another card.
315FInvalid Year
372FRetry count breached
501FSystem Error
510FMerchant Transaction Failure
931FIncorrect Passcode
1001FRequest parameters are not valid
1005FDuplicate payment request exception
1006FYour Session has expired.
1007FMissing mandatory element
2004FInvalid User Token
⇾
Staging
Production
https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid={mid}&orderId={order-id}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/theia/api/v1/processTransaction?mid={mid}&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"head":{"txnToken":"f0bed899539742309eebd8XXXX7edcf61588842333227"},"body":{"requestType":"NATIVE","mid":"{mid}","orderId":"ORDERID_98765","paymentMode":"CREDIT_CARD","authMode":"otp","cardInfo":"|4111111111111111|111|122032"}}'
copy icon