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

Attribute	Description
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

Attribute

Description

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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

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

Attribute

Description

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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
responseTimestamp string	EPOCH timestamp of the time at which response is being sent.

Body

Attribute

Description

txnInfo

object

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

TransactionInfo

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
url string	DeepLink URL

deepLinkInfo

object

It contain deep link in case UPI_INTENT

DeepLinkInfo

Attribute	Description
url string	DeepLink URL

resultInfo

object

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

resultInfo

Attribute	Description
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

resultCode	resultStatus	resultMsg
0000	S	Success
501	F	System Error
2013	F	Mid in the query param doesn’t match with the Mid sent in the request
2014	F	OrderId in the query param doesn't match with the orderId sent in the request
1001	F	Request 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
1010	F	Merchant is inactive. Please ask Merchant to contact Paytm Helpdesk
1006	F	Your Session has expired
1007	F	Missing mandatory element
2006	F	Mid is invalid
1011	F	Parameter 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]'"
2222	F	Invalid request body
1012	F	param missing
312	F	Invalid card details
9999	F	Something went wrong
324	F	Duplicate Order Id
317	F	Invalid payment mode.
410	F	order status is closed
201	F	order 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"}}'