Capture API

Use Case


The Capture API is used when 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 format: JSON

PARAMETERDESCRIPTIONREQUIREDEXAMPLE VALUE
MIDMerchant ID assigned to merchant at time of onboardingYes
PREAUTH_IDThe Unique ID generated for the blocked amount by PaytmYes
ReqTypeThe type of transaction whose status needs to be checked by MERCHANTYesCAPTURE
TxnAmountThis 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.Yes
AppIPThe IP address of the Application from which the request has originated.Yes
OrderIdThe “Order ID” is of Merchant’s.In case of capture same as Preauth Order IdYes
Currency AlphaNumericCurrency used for transaction. INRYes
DeviceId numberThis needs to be the mobile number of the customerYes9876543210
SSOToken AlphaNumericThe token received from Paytm for that userYes
PaymentMode AlphaNumericThe payment mode used for transaction. PPI for Wallet txnYes
CustId NumericThe unique ID of each customer that was received from the MerchantYes
IndustryType AlphaNumericIndustry type should pass here. This will be provided by Paytm. Ex: “Recharge”Yes
Channel CharacterChannel IDs need to pass in thisYesparameter Ex: WEB(for desktop websites)/WAP(for mobile)
AuthModePossible values of this parameter: USRPWD – for Net banking payment mode/Wallet.YesUSRPWD
CheckSumCheckSum generated as per some logic by Paytm. This needs to be verified by the merchantYes
PROMO_CAMP_IDPromo code,if any,needs to be applied on txnNo
MercUnqRefUnique Reference for merchantNo

Response Attributes:

API Content format: JSON

PARAMETERDESCRIPTIONREQUIRED
TxnID NumericA unique ID generated by Paytm for each txn.Yes
MIDThis is a unique “Merchant Identifier” that is issued by Paytm to the MerchantYes
TxnAmount NumericThe amount that the Merchant needs to withdraw.Yes
BankTxnId NumericA unique ID generated for each txn by the Paytm WalletYes
ResponseCodeStatus code corresponding to status of txnYes
ResponseMessage Character(eg, Txn Successful)A description of the status of the txnYes
Status Character(eg, TXN_SUCCESS)The current status of the txn. TXN_SUCCESS/ TXN_FAILURE/ PENDINGYes
PaymentMode Character(eg, PPI)The PaymentMode that was used for this txn.Yes
BankName Character(eg, WALLET)The bank that was used for this txnYes
CustId AlphaNumericThe unique ID of each customer that was received from the MerchantYes
MBID AlphaNumericA unique ID generated by the bank for each Merchant.Yes
CheckSum AlphaNumericCheckSum generated as per some logic by Paytm. This needs to be verified by the merchant.Yes
PROMO_CAMP_ID AlphaNumericPromo code if sent in requestNo
PROMO_STATUS AlphaNumericPromo statusNo
PROMO_RESPCODE AlphaNumericPromo response codeNo
MercUnqRef AlphaNumericUnique reference for merchantNo

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

Capture Response Codes and Messages


RESPONSE CODERESPONSE MESSAGESTATUS
01Txn SuccessfulTXN_SUCCESS
100Paytm has classified this transaction as suspiciousTXN_FAILURE
118The transaction amount specified by the user exceeds the per transaction limit for this merchantTXN_FAILURE
130This user is blocked at Paytm endTXN_FAILURE
151Transaction with the same order Id already existsTXN_FAILURE
156Perday Txn amount is crossed for PaytmTXN_FAILURE
158PerMonth Txn amount is crossed for PaytmTXN_FAILURE
159Perday Txn count is crossed for PaytmTXN_FAILURE
161PerMonth Txn count is crossed for PaytmTXN_FAILURE
165User has crossed the monthly debit limit prescribed by RBITXN_FAILURE
227Transaction failedTXN_FAILURE
228Could not complete request. Please retry again.PENDING
235You don't have sufficient balance in your account. Please try with a different accountTXN_FAILURE
237Could not complete request. Please retry again.TXN_FAILURE
239Merchant does not existTXN_FAILURE
240Invalid total amountTXN_FAILURE
243Wallet not exist for the userTXN_FAILURE
260Maximum allowed amount in Wallet exceeds limitTXN_FAILURE
267User does not existTXN_FAILURE
274User not verifiedTXN_FAILURE
302Invalid Request typeTXN_FAILURE
327Channel is not associatedTXN_FAILURE
334Duplicate order idTXN_FAILURE
343Invalid TokenTXN_FAILURE
344Invalid wallet typeTXN_FAILURE
345Request not uniqueTXN_FAILURE
355Preauth and capture id is not sameTXN_FAILURE
411Invalid Amount sent to PaytmTXN_FAILURE
712Applying Promo Code FailedTXN_FAILURE

Capture Error Codes and Messages


ERROR CODEERROR MESSAGE
140Invalid Input Parameter from Merchant
238Invalid currency code
240Invalid total amount
303Merchant Id can not be blank
304App IP is blank
305Merchant Id not registered
311Invalid device id
317Invalid payment mode
318Invalid customer id
319Invalid industry type
325Duplicate order id
327Channel is not associated
330Paytm checksum mismatch
332Order id can't be greater than 50 characters
333Customer id can't be greater than 50 characters
343Invalid Token
357Invalid order Id
501System Error
VAER-PID101PreAuth Id is required

Endpoints

Staging: https://securegw-stage.paytm.in/order/capture

Production: https://securegw.paytm.in/order/capture

Request CodeResponse JSON

curl -X POST 'https://securegw-stage.paytm.in/order/capture' --data-urlencode 
'JsonData={
    "ReqType":"CAPTURE",
    "SSOToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "MID":"xxxxxxxxxxxxxxxxxxxx",
    "TxnAmount":"1",
    "AppIP":"xxx.xxx.xxx.xxx.",
    "OrderId":"xxxxxxxxxxxxxxxxxxxxxxxx",
    "Currency":"INR",
    "DeviceId":"xxxxxxxxxx",
    "PaymentMode":"PPI",
    "CustId":"xxxxxxx",
    "IndustryType":"Retail",
    "Channel":"WAP",
    "AuthMode":"USRPWD",
    "PREAUTH_ID":"xxxxx",
    "CheckSum":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    xxxxxxxxxxxxxxxx"
}'