paytm developer docs logoDeveloperDocumentation
search

POSTPay API

Use Case

It is used to process the transaction with respect to paymentMode provided by the 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.This API is called to initiate the payment for any order created in the AI router system.
 

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestTimeStamp
string
optional

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

channelId
Enum
optional

DeviceName from which request is sent.
 

Possible values: APP , WEB , WAP

tokenType
Enum
mandatory

Token Type 

 

Possible Values: TXN_TOKEN

token
string
mandatory

Transaction Token

Body

AttributeDescription
mid
string
mandatory

AI router provides MID as a unique identifier to each merchant.
 

Example: 216820000002516036253

orderId
string
mandatory

It is unique reference ID for a transaction passed in Create Order API

paymentMode
Enum
mandatory

The payment mode used by the customer for the transaction.


 

Possible values that can be selected:
PAYMENT_DIGITAL_CREDIT, UPI, UPI_INTENT, CREDIT_CARD, DEBIT_CARD, NET_BANKING, EMI, WALLET, PPBL

requestType
Enum
mandatory

Request Type values that can be selected:
SUBSCRIPTION, PAYMENT

channelCode
string
conditional

BankCodes which are supported by AI router ( list )
 

 Note: Mandatory when paymentMode is NET_BANKING

Possible Values: AXIS, HDFC

cardInfo
object
conditional

It contains the details of the saved and new card for payment transaction 

 

 Notes:  Mandatory when paymentMode is CREDIT_CARD or DEBIT_CARD

CardInfo
+
AttributeDescription
cardUniqueId
string
mandatory

It should be either cardNumber or token Number.
TOKEN_INDEX_NO : Unique Id for Super router tokenised cards
CARD_TOKEN : 16 digits Token PAN
NEW_CARD : Card Number
 

cvv
string
mandatory

cvv of card

expiryMonth
string
conditional

Month of expiry of card or token
 

Note : Mandatory when cardFlowType is CARD_TOKEN or NEW_CARD

expiryYear
string
conditional

Year of expiry of card or token

Note: Mandatory when cardFlowType is CARD_TOKEN or NEW_CARD

cardFlowType
string
mandatory

Possible Values : TOKEN_INDEX_NO , CARD_TOKEN, NEW_CARD

cardTokenInfo
object
conditional

Token data required to process a token transaction.

Note: Mandatory when cardFlowType is CARD_TOKEN

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

payerAccount
string
conditional

VPA is needed for a UPI transaction.
Note:  Mandatory when paymentMode is UPI

Example: 7777777777@paytm

coftConsent
object
optional

Consent to tokenize the instrument or not.

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\

integrationType
Enum
optional

Values that can be selected:
CUSTOM_CHECKOUT, JS_CHECKOUT, SDK
 

mpin
string
conditional

passcode of PPBL Account.
 

 Notes:  Mandatory when paymentMode is PPBL

gatewayInfo
Map
optional

Information related to gateway

txnNote
string
optional

Transaction note providing a short description

osType
string
optional

Possible values are "IOS/ANDROID/KAIOS" Default value is "ANDROID"

walletInfo
object
conditional

It contains the wallet Information when PaymentMode is WALLET

 

 Note: Mandatory when paymentMode is WALLET

WalletInfo
+
AttributeDescription
walletType
Enum
optional

PossibleValue: PAYTM

paymentFlow
string
mandatory

Add and Pay or Pay flow for wallet.

 

POSSIBLE VALUE: PAY , ADDNAPAY

addMoneyPaymentDetails
string
conditional

It contains the information of secondary payment.
 

Note: Mandatory when paymentFlow is ADDNAPAY

AddMonetPaymentDetail
+
AttributeDescription
payMethod
Enum
mandatory

The secondary payment mode used by customer for the transaction.

Values that can be selected:
 UPI, UPI_INTENT, CREDIT_CARD, DEBIT_CARD, NET_BANKING, PPBL
 

bankCode
string
conditional

BankCode 
 

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

 Notes:  Mandatory when payMethod is NET_BANKING

cardInfo
string
conditional

It contains the details of the saved and new card for payment transaction 

 Notes:  Mandatory when payMethod is CREDIT_CARD or DEBIT_CARD

CardInfo
+
AttributeDescription
cardUniqueId
string
mandatory

It should be either cardNumber or token Number.
TOKEN_INDEX_NO : Unique Id for Super router tokenised cards
CARD_TOKEN : 16 digits Token PAN
NEW_CARD : Card Number
 

cvv
string
mandatory

cvv of card

expiryMonth
string
conditional

Month of expiry of card or token
 

Note : Mandatory when cardFlowType is CARD_TOKEN or NEW_CARD

expiryYear
string
conditional

Year of expiry of card or token

Note: Mandatory when cardFlowType is CARD_TOKEN or NEW_CARD

cardFlowType
string
mandatory

Possible Values : TOKEN_INDEX_NO , CARD_TOKEN, NEW_CARD

cardTokenInfo
object
conditional

Token data required to process a token transaction.

Note: Mandatory when cardFlowType is CARD_TOKEN

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

payerAccount
string
conditional

VPA, is needed for a UPI transaction.

 Notes:  Mandatory when payMethod is UPI

Example: 7777777777@paytm
 

mpin
string
conditional

passcode of PPBL Account.
 

 Notes :  Mandatory when payMethod is PPBL

emiInfo
object
conditional

It contains the EMI information when PaymentMode is EMI
 

 Note: Mandatory when paymentMode is EMI

EMIinfo
+
AttributeDescription
planId
string
mandatory

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

 

Example: ICICI|3

channelCode
string
mandatory

ChannelCode of the bank Chosen

emiType
Enum
mandatory

Possible Values: STANDARD_EMI

cardType
Enum
mandatory

Possible Values: DEBIT_CARD, CREDIT_CARD

txnRoutingParams
Map<String,Object>
optional

Routing Configuration Input entered for the Enforced routing rule creation must be passed here for the Routing rule adherence.

 Note : If we have received txnRoutingParams in both createOrder And Payment API then Payment API has a higher priority.

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string

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

Body

AttributeDescription
txnInfo
object

It contain the transaction Information in case of WALLET PAY or PAYMENT_DIGITAL_CREDIT

TransactionInfo
+
AttributeDescription
MID
string

This is a unique identifier provided to every merchant by Super router.
Example: 216820000002516036253

txnID
string

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

orderID
string

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

bankTxnID
string

The transaction ID sent by the bank. In case of Super router proprietary instruments too, there is unique reference number generated by Super router'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.

txnAmount
string

Amount to be paid by customer in INR

currency
string

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

status
string

This contains the transaction status.
 

Possible Values: TXN_SUCCESS, TXN_FAILURE and PENDING

txnDate
string

Date and Time of transaction.

gatewayName
string

Gateway used by Super router to process the transactions.
 

Example: Paytm,Billdesk

paymentMode
string

The payment mode used by customer for transaction.

 

Possible values: PPI , 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.

VPA
string

VPA address which comes in request payload.

callBackUrl
string

Call back URL

bankForm
object

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

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

It contain deep link in case UPI_INTENT

DeepLinkInfo
+
AttributeDescription
url
string

DeepLink URL

resultInfo
object

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

resultInfo
+
AttributeDescription
resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field

resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64.

resultMsg
string

This parameter is the result message which contains information about the result.

gatewayrespcode
string

Result code from payment gateways / aggregators

gatewayrespmsg
string

Result message from payment gateways / aggregators

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSuccess
501FSystem Error
2013F Mid in the query param doesn’t match with the Mid sent in the request
2014FOrderId in the query param doesn't match with the orderId sent in the request
1001FRequest parameters are not valid Note: If the value is not valid in the request parameter then the result message should be in the format of "Invalid {field name}" For example: Invalid requestType, Invalid tokenType, etc
1010FMerchant is inactive. Please ask Merchant to contact Paytm Helpdesk
1006FYour Session has expired
1007FMissing mandatory element
2006FMid is invalid
1011FParameter illegal Note: If the value is not allowed in request parameters then the result message should be in the format of "Parameter '[field name]' has invalid value '[value]'" For example: If we will send PAYMENT1(invalid value) in requestType in create order request then the result message should be "Parameter '[body->requestType]' has invalid value '[PAYMENT1]'"
2222FInvalid request body
1012Fparam missing
312FInvalid card details
9999FSomething went wrong
324FDuplicate Order Id
317FInvalid payment mode.
410Forder status is closed
201Forder is paid
⇾
Staging
Production
https://stage-router.paytm.in/aoa-acquiring-biz/v2/payment?mid={mid}&orderId={orderId}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
New card



curl --location --request POST 'https://stage-router.paytm.in/aoa-acquiring-biz/v2/payment?mid=YOUR_MID_HERE&orderId=Ravi1367' \
--header 'Content-Type: application/json' \
--header 'Postman-Token: a7787b37-ae19-4bdd-8690-aee47a3e7934,e057b2ec-9707-4460-b705-dac48a701f78' \
--header 'cache-control: no-cache,no-cache' \
--data-raw '{"head": {"version": "v1","channelId":"WEB","token": "63241c05-f461-4993-bb17-4b08672788d2","tokenType":"TXN_TOKEN"},"body": {"mid": "YOUR_MID_HERE","orderId": "Ravi1382","paymentMode": "CREDIT_CARD","requestType": "PAYMENT","cardInfo": {"cardUniqueId": "4718650100010336","cvv": "233","expiryMonth":"01","expiryYear":"2024","cardFlowType": "NEW_CARD"},"integrationType":"CUSTOM_CHECKOUT"}}'




 
copy icon