search

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)
mandatory

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
mandatory

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)
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
127.0.0.1
mandatory

IP of the device by which call is initiated.

OrderId

string(50)
mandatory

The “Order ID” is of Merchant’s. In case of capture same as Preauth Order Id

Currency

string(3)
mandatory

Currency in which the transaction has taken place. Currently, only "INR" is the supported currency of the transaction.

DeviceId

string
mandatory

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

SSOToken

string
mandatory

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)
mandatory

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)
mandatory

Industry type should pass here. This will be provided by Paytm.

Example: “Retail”

Channel

string
mandatory

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
mandatory

Possible values of this parameter:
USRPWD – for Net banking payment mode/Wallet.

CheckSum

string
mandatory

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)
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

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:
  • TXN_SUCCESS - Success
  • TXN_FAILURE- Failure
  • PENDING- Pending

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

ResponseCodeStatusResponseMessage
01 Txn SuccessfulTXN_SUCCESS
228 PENDING Could not complete request. Please retry again.
100 TXN_FAILURE Paytm has classified this transaction as suspicious
118 TXN_FAILUREThe 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_FAILURETransaction 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_FAILUREYou 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
⇾
Staging
Production
https://securegw-stage.paytm.in/order/capturecopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
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}"}' 
copy icon