Payment Gateway
QR Code
Payment Links
Payment Invoice
Subscriptions
International Merchants
AI Router
Food Wallet
Paytm Cash
Paytm Gold
Smart Retail
POS HardwarePOSTCapture 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
Head
| Attribute | Description |
|---|---|
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
| Attribute | Description |
|---|---|
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. |
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
Head
| Attribute | Description |
|---|---|
responseTimestamp string | Timestamp at which response was sent |
version string | Application version(provided by paytm) |
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
| Attribute | Description |
|---|---|
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. |
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: |
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. |
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. |
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
| resultCode | resultStatus | resultMsg |
|---|---|---|
| 01 | TXN_SUCCESS | Txn Successful |
| 228 | PENDING | Txn Pending |
| 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 |
| 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 |
| 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://securestage.paytmpayments.com/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"}}'
