paytm developer docs logoDeveloperDocumentation
search

POSTTransaction Status API

Use Case

This API gets the transaction status corresponding to requested OrderId for specific merchant.

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string
optional

Version of the API.

Example: v1

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"
requestTimestamp
string
optional

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

clientId
string
optional

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

signature
string
mandatory

Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.

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

The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”.
Example: OREDRID_98765

txnType
string
optional

Transaction type of the payment

The parameter that would define which status will be presented in the response. 
If value = PREAUTH the status and  amount in response would be that of pre-auth 
If value = CAPTURE the status and  amount in response would be that of capture
If value = RELEASE the status and  amount in response would be that of release
If value is blank then order amount and status will be provided in response

Possible Values: PREAUTH, RELEASE, CAPTURE, WITHDRAW

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

channelId
string

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"
clientId
string

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

signature
string

Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.

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 is the result specific to the phase of the transaction mentioned in the txnType field  
 

Possible Values: TXN_SUCCESS, TXN_FAILURE, PENDING, NO_RECORD_FOUND

resultMsg
string

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

txnId
string

Transaction Id of the payment

Example: 202005081112128XXXXXX68470101509706

bankTxnId
string

Bank transaction Id from the bank

Example: 77700XXXX215242

orderId
string

Unique reference ID for an Order request generated by merchant for payment.

Example: OREDRID_98765

txnAmount
string

Payment transaction amount

Possible Values: 1.00

txnType
string

Transaction type of the payment

gatewayName
string

Name of the gateway used to process the transaction. In case of Super Router, this is the payment aggregator chosen to process the transaction.

gatewayInfo
string

Response provided by the gateway during payment or transaction. This is available for Super Router product only.

bankName
string

Bank Name used in payment

Example: Paytm Payments Bank

Example: ICICI Bank

mid
string

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

paymentMode
string

Payment Mode used in payment

Possible values:
PPI
For Paytm Wallet
,
UPI
For Bhim Upi
,
CC
For Credit Card
,
DC
For Debit Card
,
NB
For Net Banking
refundAmt
string

refund amount of the payment

Example: 1.00

txnDate
string

Date on which the pre-auth/capture/release/order was created (depending on the value of txnType)

Example: 2020-05-05 14:00:28

subsId
string

Subscription ID - Only Subscription flow

payableAmount
string

Original order value before offer was applied.
Only for SimplifiedPaymentOffers (Bank Offers).

paymentPromoCheckoutData
string

Only for SimplifiedPaymentOffers (Bank Offers).
promocode: Actual promocode which got applied
promotext: Promo message
savings: Benefit amount
redemptionType: discount/cashback

vanInfo
object

VAN account details. This is only provided for bank account transfer paymode.

vanInfo
+
AttributeDescription
van
string

Virtual Account Number. This is the 16 alphanumeric account number to which customer has initiated the transfer.

Example: PY2222K735789128.

beneficiaryName
string

Beneficiary name of the VAN

ifscCode
string

Ifsc code of van account

Example: PYTM0123456

 

bankName
string

Bank in which VAN is created

purpose
string

Purpose of the txn

Example: Dont

userDefinedFields
object

Object containing five types of udf passed at the time of VAN creation. This is only provided for bank account transfer.

userDefinedFields
+
AttributeDescription
udf1
string

User define parameter 1

udf2
string

User define parameter 2

udf3
string

User define parameter 3

udf4
string

User define parameter 4

udf5
string

User define parameter 5

customerDetails
object

Contains details of customer like name/email/mobile passed at the time of VAN creation. This is only provided for bank account transfer.

customerDetails
+
AttributeDescription
name
string

Name of the person who initiated refund

Example: Test

email
string

Valid email of the user.

Example: vaibhav41094@gmail.com

phone
string

Phone number of end user

sourceAccountDetails
object

Remitter/Source account detail information from where the money has been received. This is only provided for bank account transfer.

sourceAccountDetails
+
AttributeDescription
maskedAccountNumber
string

Account number of customer

Example: 915555**0164

accountHolderName
string

Account holder name

Example: Srivastava Kumar Prateek1597233845332

ifscCode
string

Ifsc code of bank

Example: BACB0000003

transferMode
string

Mode by which remitter has made the transfer. Possible values are IMPS, NEFT, RTGS, and XFER. This is only provided for bank account transfer.

utr
string

Unique transaction reference number from bank. This is only provided for bank account transfer.

Example: 5R01IY000V27.

bankTransactionDate
string

Timestamp at which partner bank received the payment. This is only provided for bank account transfer.

Example: 2020-09-25 11:35:07.0.

rrnCode
string

Reference number which is also generated by the bank

Example: 777001344756752

arnCode
string

Unique Reference Number generated by the Acquirer Bank for Visa, Master and Rupay networks that indicates the settlement between the acquirer and card issuing bank is complete.

Please note ARN is 23 digit number typically starting with 3, 7 or 8 and is not the same as RRN (Retrieval Reference Number).

Example: 74056633031820896327619

arnAvailable
boolean

Indicates the eligibility of ARN for card transactions. 
Possible Values: false

authCode
string

Authentication code which comes from the bank

Example: 123456

merchantUniqueReference
string

Merchant's reference text which is sent in the order's request

cardScheme
string

Card Scheme

Example: VISA, MASTER

lastFourDigit
string

Last four digit of the card

Example: 0208

dccPaymentDetail
object

Details of the payment done through dcc

Note: For currency conversion flow only

DccPaymentDetails
+
AttributeDescription
dccId
string

There is an ID generated corresponding to each request by the bank.

Example: 79755374

amountPerUnitForeignAmount
string

Exchange Rate = FC/INR

Example: 10471.2

foreignCurrencyCode
string

3 letter currency code corresponding to a currency

Example: EUR

foreignCurrencySymbol
string

Currency symbol corresponding to the selected currency

Example: €

foreignPayableAmount
string

Total Amount paid in Foreign Currency (including markup)

Example: 2.00

foreignPaymentAmount
string

Total Amount paid in Foreign Currency(excluding markup)

Example: 1.91

foreignMarkupAmount
string

Markup amount charged by a gateway from the user calculated by PG

Example: 0.09

foreignMarkupRatePercentage
string

Markup % charged by a gateway from the user

Example: 4.5

expirationTimestamp
string

Standard format timestamp for foreign exchange rate validity

Example: 2021-06-29T06:36:38.000+02:00

isoForeignCurrencyCode
string

3 digit ISO Currency code corresponding to the selected currency

Example: 978

dccOffered
string

The flag indicates if the currency conversion option was selected by the customer

Possible Values: true, false

foreignCurrencyName
string

Currency name corresponding to the selected currency

Example: EURO

exchangeRateSourceName
string

Name of the source providing the currency exchange rate

Example: REUTERS WHOLESALE INTERBANK

internationalCardPayment
boolean

Indicates if the transaction was completed using an international card (issued by a non-indian bank)

Note: For currency conversion flow only

Possible Values: true

baseCurrency
string

Base currency used for currency conversion and is always INR.

Note: For currency conversion flow only

Example: INR

feeRateFactors
object

The fee factor DCC indicates that DCC fee/commission is applicable for the given international card transaction.

Note: For currency conversion flow only

FeeRateFactors
+
AttributeDescription
internationalCardPayment
string

Indicates if the transaction was completed using an international card (issued by a non-indian bank)

Possible Values: TRUE

dcc
string

Indicates if the transaction was completed using the dcc flow

Possible Values: TRUE, FALSE

preAuthId
string

In case of pre-auth transactions this parameter will provide the pre-authId specific to the transaction

blockedAmount
string

This field will have the value of the amount blocked in the customer’s account in case the txnType = PREAUTH

cardPreAuthType
string

The type of Pre-Auth flow - Standard/Delayed that is to be used for the pr-auth transaction

Example : STANDARD_AUTH, DELAYED_AUTH

STANDARD_AUTH : This pre-auth flow involves blocking of amount in the customer’s account to be captured/released at a later stage.

DELAYED_AUTH : This flow involves no blocking of amount but only the authorization for this transaction is done at a later stage.

authRefId
string

Authentication ID for the 2FA transaction generated as received from the acquirer.
Condition: To be provided mandatory for RupayCards.

Response Codes & Messages

resultCoderesultStatusresultMsg
01TXN_SUCCESSTxn Success
227TXN_FAILUREYour payment has been declined by your bank. Please contact your bank for any queries. If money has been deducted from your account, your bank will inform us within 48 hrs and we will refund the same.
235TXN_FAILUREWallet balance Insufficient, bankName=WALLET
295TXN_FAILUREYour payment failed as the UPI ID entered is incorrect. Please try again by entering a valid VPA or use a different method to complete the payment.
331NO_RECORD_FOUNDNo Record Found
334TXN_FAILUREInvalid Order ID
335TXN_FAILURE Mid is invalid
400PENDINGTransaction status not confirmed yet.
401TXN_FAILUREYour payment has been declined by your bank. Please contact your bank for any queries. If money has been deducted from your account, your bank will inform us within 48 hrs and we will refund the same.
402PENDINGLooks like the payment is not complete. Please wait while we confirm the status with your bank.
501TXN_FAILUREServer Down
810TXN_FAILURETxn Failed
843TXN_FAILURE

Your transaction has been declined by the bank. Remitting account is blocked or frozen.

820TXN_FAILUREMobile number linked to your bank account has changed. Please contact your bank and use different payment method to complete the payment
267TXN_FAILUREYour payment has been declined by your bank since at least a 24 hours gap is not maintained between successful pre-notify and mandate execution. Please try again later.
⇾
Staging
Production
https://securegw-stage.paytm.in/v3/order/statuscopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/v3/order/status' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","orderId":"{order-id}"},"head":{"signature":"{signature}"}}'
copy icon