POSTCapture API v1
Use Case
The Capture 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 same as both these requests belong to 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.
It happens when there are some system errors between two Paytm systems. We have internal reconciliation between systems after which this PENDING transaction moves to either SUCCESS or FAILED state.
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.
Request Attributes
API Content Type: JSON
| ATTRIBUTE | DESCRIPTION |
|---|---|
|
MID string(20) |
This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different on staging and production environment. Your staging MID is available here & production MID will be available once your activation is complete. |
|
PREAUTH_ID mandatory |
The Unique ID generated for the blocked amount by Paytm. |
|
ReqType string |
his parameter is used to identify the transaction flow. Its value shall be as mentioned below: “CAPTURE” for the amount to be captured. |
|
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. |
|
AppIP string |
IP of the device by which call is initiated. |
|
OrderId string(50) |
The “Order ID” is of Merchant’s. In case of capture same as Preauth Order Id |
|
Currency string(3) |
Currency in which the transaction has taken place. Currently, only "INR" is the supported currency of the transaction. |
|
DeviceId string |
A unique identification no of the Device like a customer's phone number. |
|
SSOToken string |
This is a unique token linked with the user's Paytm wallet and is provided in the response while linking user's Paytm wallet. |
|
PaymentMode string(3) |
The payment mode used for the transaction. PPI for Wallet transaction. |
| CustIdstring mandatory |
This parameter is the unique reference ID for every customer and is generated by the merchant. The allowed special characters for this parameter are @, ! ,_ ,$, . |
|
IndustryType string(16 char) |
Industry type should pass here. This will be provided by Paytm. Example: “Retail” |
|
Channel string |
Channel through which API call is initiated. For websites, the value to be passed should be "WEB" and for Mobile websites/App, the value to be passed should be "WAP". This parameter is used to control the theme of the payment page. Based on the channel passed, Paytm will render the layout suitable for that specific platform. |
|
AuthMode string |
Possible values of this parameter: USRPWD – for Net banking payment mode/Wallet. |
|
CheckSum string |
Signature encryption for validation. It's value to be sent should be the checksum string created by using Paytm checksum library. Note: Create the signature using all the request parameters. |
|
PROMO_CAMP_ID string(128) |
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) |
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
API Content Type: JSON
| ATTRIBUTE | DESCRIPTION |
|---|---|
|
TxnID string(64) |
A unique ID generated by Paytm for each txn. |
|
MID string(20) |
This is a unique identifier provided to every merchant by Paytm. |
|
TxnAmount float(2 decimal) |
The amount that the Merchant needs to withdraw. |
|
BankTxnId string |
A unique ID generated for each txn by the Paytm Wallet. |
|
ResponseCode 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. |
|
ResponseMessage string |
This parameter is the result message which contains information about the response. |
|
Status string(20) |
This parameter indicates the status of the API call. It's possible values are:
|
|
PaymentMode string(15) |
The payment mode used by the customer for a transaction. Paytm wallet - PPI |
|
BankName string |
The bank that was used for this txn e.g. WALLET |
|
CustId string |
This parameter is the unique reference ID for every customer and is generated by the merchant. The allowed special characters for this parameter are @, ! ,_ ,$, . |
|
MBID string |
A unique ID generated by the bank for each merchant. |
|
CheckSum string |
Signature encryption for validation. It's value to be sent should be the checksum string created by using Paytm checksum library. Note: Create the signature using all the request parameters. |
|
PROMO_CAMP_ID string |
Promo code if sent in a request. |
|
PROMO_STATUS 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) |
|
PROMO_RESPCODE string |
This is a numeric response code. “01” implies promo applied successfully. All other codes refer that promo code has not been applied. Each code representing 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. |
Constraints
Cases of Capture:
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 Dr.
If [B+P] < C, then capture request fails
If user’s token is invalid then capture request fails
P >= C
C is Dr. irrespective of validity of token
Response Codes & Messages
| ResponseCode | Status | ResponseMessage |
|---|---|---|
| 01 | Txn Successful | TXN_SUCCESS |
| 228 | PENDING | Could not complete request. Please retry again. |
| 100 | TXN_FAILURE | Paytm has classified this transaction as suspicious |
| 118 | TXN_FAILURE | The transaction amount specified by the user exceeds the per transaction limit for this merchant |
| 130 | TXN_FAILURE | This user is blocked at Paytm end |
| 151 | TXN_FAILURE | Transaction with the same order Id already exists |
| 156 | TXN_FAILURE | Perday Txn amount is crossed for Paytm |
| 158 | TXN_FAILURE | PerMonth Txn amount is crossed for Paytm |
| 159 | TXN_FAILURE | Perday Txn count is crossed for Paytm |
| 161 | TXN_FAILURE | PerMonth Txn count is crossed for Paytm |
| 165 | TXN_FAILURE | User has crossed the monthly debit limit prescribed by RBI |
| 227 | TXN_FAILURE | Transaction failed |
| 235 | TXN_FAILURE | You don't have sufficient balance in your account. Please try with a different account |
| 237 | TXN_FAILURE | Could not complete request. Please retry again. |
| 239 | TXN_FAILURE | Merchant does not exist |
| 240 | TXN_FAILURE | Invalid total amount |
| 243 | TXN_FAILURE | Wallet not exist for the user |
| 260 | TXN_FAILURE | Maximum allowed amount in Wallet exceeds limit |
| 267 | TXN_FAILURE | User does not exist |
| 274 | TXN_FAILURE | User not verified |
| 302 | TXN_FAILURE | Invalid Request type |
| 327 | TXN_FAILURE | Channel is not associated |
| 334 | TXN_FAILURE | Duplicate order id |
| 343 | TXN_FAILURE | Invalid Token |
| 344 | TXN_FAILURE | Invalid wallet type |
| 345 | TXN_FAILURE | Request not unique |
| 355 | TXN_FAILURE | Preauth and capture id is not same |
| 411 | TXN_FAILURE | Invalid Amount sent to Paytm |
| 712 | TXN_FAILURE | Applying 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 |
curl -X POST 'https://securegw-stage.paytm.in/order/capture' \
--header 'Content-Type: application/json' \
--data '{"ReqType":"CAPTURE","PREAUTH_ID":"2020052711121XXXXXXXX68304901660306","SSOToken":"eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..xxxxxxxxxxx.9iHTtWbCZ0I6qbn2sUnyz5siw1fqbmtEnFMFE7nSIX-yrwCkiGfAC6QmPr9q-tw8LMPOh5-3UXRbpeVZEupQd3wNyaArWybRX2HAxJDRD8mxJ_wxzJM6GZ1ov4O3EIsx2Y_Zr0aHCd3VbnTjRUnlVdxXJPFG8QZs0b_2TVdoAX3_QjZS8_dwcmIWoH8ebDzOIs7MJacETfMtyFGAo8Xc0LjznToUWvTsTbIXQoF1yB0.1fZFAYJVsY61BTv2htLcXQ8800","MID":"{mid}","TxnAmount":"1.00","AppIP":"45.251.51.117","OrderId":"ORDERID_98765","Currency":"INR","DeviceId":"7777777777","PaymentMode":"PPI","CustId":"CUST_001","IndustryType":"Retail","Channel":"WEB","AuthMode":"USRPWD","CheckSum":"{checksum}"}'
