search

POSTCapture API

Use Case

The API is used when a merchant actually captures the fund.

Order id sent in pre-auth and order_id sent in capture request should be the same as both these requests belong to the same merchant order.

We have PENDING status for capture transaction other than SUCCESS and FAILED which is returned when the system is not sure whether money has been debited from customer wallet or not.

 

To verify the final Status of transaction Merchant can call Transaction Status API and Merchant has to send txn type in the request of Transaction Status API to know the current status of txn.

 

Txn Type valid values will be PREAUTH,RELEASE,CAPTURE for preauth, release and capture txn respectively.

 

In case final status is FAILED, Merchant can call capture again with same order id and Paytm will honor that capture if pre-auth is still valid.

 

99% of PENDING STATUS will be converted into final status with in 10 min.


Constraints

Cases of Capture (Wallet and Postpaid):

    Pre-Auth Amount (P), Capture Amount (C), Balance (B)
    P < C
If user’s token is valid then
    If [B+ P] >= C, then C is Debited.
    If [B+P] < C, then capture request fails
If user’s token is invalid then capture request fails
    P >= C
C is Debited. irrespective of validity of token

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string
optional

Application version(provided by Paytm)

Example : 1.0.0

channelId
string
optional

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

Example: APP, WEB, WAP, SYSTEM

requestTimestamp
string
optional

Unix Timestamp of request

clientId
string
mandatory

Paytm uses the merchant key on the basis of clientId parameter value. It is required only if the merchant has more than one key.

signature
string
mandatory

Checksum string created by using paytm checksum logic/library

Body

AttributeDescription
mid
string(20)
mandatory

This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different in staging and production environment. Your staging MID is available here & production MID will be available once your activation is complete.

preAuthId
string
mandatory

The Unique ID generated for the blocked amount by Paytm.

txnAmount
float(2 decimal)
mandatory

This is the “Transaction Amount” that is to be charged to the customer’s credit/debit card. Only numeric values are allowed. Please ensure that the amount is in the same currency as defined for the Merchant ID being used.
Example :  1025.00

appIp
string
optional

IP of the device by which call is initiated.

orderId
string(50)
mandatory

Unique reference ID for an Order request which is generated by merchant and sent in the transaction request payload. Duplicate order request are rejected by Paytm. It's alphanumeric and special characters allowed are “@” “-” “_” “.”.

deviceId
string
optional

A unique identification number of the Device like a customer's phone number.

paytmSsoToken
string
optional

This is a unique token linked with the user's Paytm wallet and is provided in the response while linking the user's Paytm wallet.

It is mandatory for excess capture requests with paymode = BALANCE or PAYTM_DIGITAL_CREDIT

promoCampId
string(128)
optional

This parameter is required to pass when a merchant is running any promotional campaign and it is configured at Paytm payment gateway. Merchant will get in contact with Paytm to launch any promo code campaign.

mercUnqRef
string(128)
optional

This parameter accepts merchant defined value. In transaction request, the merchant can send his choice of value and Paytm payment gateway shall return the same value in the transaction response.

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string

Timestamp at which response was sent

version
string

Application version(provided by paytm)
Example : 1.0.0

clientId
string

Paytm uses the merchant key on the basis of clientId parameter value. It is required only if the merchant has more than one key.

signature
string

Checksum string created by using paytm checksum logic/library

Body

AttributeDescription
txnID
string(64)

 A unique ID generated by Paytm for each txn.

txnAmount
float(2 decimal)

This is the “Transaction Amount” that is to be charged to the customer’s credit/debit card. Only numeric values are allowed. Please ensure that the amount is in the same currency as defined for the Merchant ID being used.
Example :  1025.00

mid
string(20)

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

bankTxnId
string

A unique ID generated for each txn by the Paytm Wallet.

statusCode
string

This is the ResponseCode corresponding to a particular message and is returned to the merchant. Its maximum length is 64. The different response codes corresponding to this API are mentioned below.

statusMessage
string

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

status
string

This parameter indicates the status of the API call. It's possible values are:
    • TXN_SUCCESS - Success
    • TXN_FAILURE - Failure
    • PENDING - Pending

paymentMode
string

The payment mode used by the customer for a transaction.

promoCampId
string

Promo code if sent in a request.

promoStatus
string

This parameter will indicate if the Promo is successfully applied or failed. Below are values which may return in this parameter. PROMO_SUCCESS,PROMO_FAILURE.
Optional (if a merchant has not requested for any promo campaign)

promoRespCode
string

This is a numeric response code. “01” implies promo applied successfully. All other codes refer to the promo code that has not been applied. Each code represents a different reason for failures.
Optional if a merchant has not requested for any promo campaign.

mercUnqRef
string

This parameter accepts merchant defined value. In transaction request, a merchant can send his choice of value and Paytm payment gateway shall return the same value in the transaction response.

Response Codes & Messages

resultCoderesultStatusresultMsg
01TXN_SUCCESSTxn Successful
228PENDINGTxn Pending
100TXN_FAILUREPaytm has classified this transaction as suspicious
118TXN_FAILUREThe transaction amount specified by the user exceeds the per transaction limit for this merchant
130TXN_FAILUREThis user is blocked at Paytm end
151TXN_FAILURETransaction with the same order Id already exists
156TXN_FAILUREPerday Txn amount is crossed for Paytm
158TXN_FAILUREPerMonth Txn amount is crossed for Paytm
159TXN_FAILUREPerday Txn count is crossed for Paytm
161TXN_FAILUREPerMonth Txn count is crossed for Paytm
165TXN_FAILUREUser has crossed the monthly debit limit prescribed by RBI
227TXN_FAILURETransaction failed
237TXN_FAILURECould not complete request. Please retry again
239TXN_FAILUREMerchant does not exist
240TXN_FAILUREInvalid total amount
243TXN_FAILUREWallet not exist for the user
260TXN_FAILUREMaximum allowed amount in Wallet exceeds limit
267TXN_FAILUREUser does not exist
274TXN_FAILUREUser not verified
302TXN_FAILUREInvalid Request type
327TXN_FAILUREChannel is not associated
334TXN_FAILUREDuplicate Order Id
345TXN_FAILURERequest not unique
355TXN_FAILUREPreauth and capture id is not same
411TXN_FAILUREInvalid Amount sent to Paytm
712TXN_FAILUREApplying Promo Code Failed

Capture Error Codes and Messages

ErrorCode ErrorMessage
140 Invalid Input Parameter from Merchant
238 Invalid currency code
240 Invalid total amount
303 Merchant Id can not be blank
304 App IP is blank
305 Merchant Id not registered
311 Invalid device id
317 Invalid payment mode
318 Invalid customer id
319 Invalid industry type
325 Duplicate order id
327 Channel is not associated
330 Paytm checksum mismatch
332 Order id can't be greater than 50 characters
333 Customer id can't be greater than 50 characters
343 Invalid Token
357 Invalid order Id
501 System Error
VAER-PID101 PreAuth Id is required
⇾
Staging
Production
https://securegw-stage.paytm.in/order/v2/capturecopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/order/v2/capture' \
--header 'Content-Type: application/json' \
--data '{"head":{"requestTimestamp":"1539601338741","clientId":"c11","version":"v2","channelId":"WEB","signature":"KVQ5YrYS/pcQtZ0gghKLWc="},"body":{"preAuthId":"202005031112128001**********","orderId":"GRA3CMA184276025","mid":"{mid}","deviceId":"12345","mercUnqRef":"online","txnAmount":"1025"}}' 
copy icon