• Getting Started
    • Website Integration
      Mobile Integration (Android/IOS)
      Enterprise Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Webhooks
      Testing
      Refunds
      Guides
      Other Processes

      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

      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
      

      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' --header 'Content-Type: application/json' --data '{"ReqType":"CAPTURE","PREAUTH_ID":"{preauth-id}","SSOToken":"{paytm-user-token}","MID":"{mid}","TxnAmount":"{transaction-amount}","AppIP":"{client-ip}","OrderId":"{order-id}","Currency":"{transaction-currency}","DeviceId":"{mobile-number}","PaymentMode":"{payment-mode}","CustId":"{customer-id}","IndustryType":"{industry-type}","Channel":"{channel-code}","AuthMode":"{authorization-mode}","CheckSum":"{checksum}"}'