Paytm Auto Debit Integration - Overview

  • Auto Debit flow provides single click payment solution for customers. Here the merchant links their customer’s account with Paytm registered mobile number. This enables them to debit the required amount from linked Paytm Wallet without any intervention from end user. This flow guarantees high success rates in less response time.

    • Customer Flow
    • Product Flow
    In Store Banner
  • This section details out the use cases of all APIs used in this payment gateway flow.

    API Name with signature linkPurpose
    Send OTP APICommunicate customer’s details to whom Paytm will send the OTP
    Validate OTP API
    1. To verify the OTP entered by the customer
    2. Upon successful validation, a token is provided which is an input to later requests. The validity of the token will be dependent on Client-ID internally set by Paytm
    Validate Token API
    1. Verify the validity of the existing token
    2. Fetch customer information associated with that token (email and phone number)
    Revoke Access APIUsed for expiring a user’s token. Merchant can use this API whenever customer deletes his account or logs in with other mobile number. Merchant should also provide an option to the customer to discontinue the link between his merchant and Paytm account
    Balance Consult APITo check if required customer balance is available in Paytm proprietary instruments. In case sufficient fund is not available, merchant will direct the customer to add the balance amount
    Add Money APITo initiate a request on Paytm Gateway for addition of funds. Here customer will be redirected to Paytm by opening the URL in web-view of merchant app
    Withdraw APITo withdraw from customer’s Paytm balance
    Status Query API
    1. For terminal state (success/fail) transactions, merchant is required to re-verify transaction status with this API. The status provided in the response should be treated as the final status of transaction. Additionally merchant should match the transaction amount received with that sent in transaction request API. In case of mismatch, merchant should mark this transaction as disputed and raise it to KAM/helpdesk team
    2. In event of a network failure or genuine user dropout during the payment process, response of transaction request is not posted to the merchant. Hence in case merchant does not receive the response after considerable time has passed, it should status query after regular intervals till the terminal status of transaction is received
    3. Sometimes “pending” status is received from banks which is passed in response to the merchants. In these cases too, merchant should status query at regular intervals till the terminal status of transaction is received
    Refund API*To initiate refund transaction
    Refund Status API
    1. For terminal state (success/fail) refund transactions, merchant is required to re-verify refund transaction status with this API. The status provided in the response should be treated as the final status of refund transaction. Additionally merchant should match the transaction amount received with that sent in refund transaction request API. In case of mismatch, merchant should mark this refund transaction as disputed and raise it to KAM/helpdesk team
    2. In event of a network failure or genuine user dropout during the payment process, response of refund transaction request is not posted to the merchant. Hence in case merchant does not receive the response after considerable time has passed, it should status query after regular intervals till the terminal status of refund transaction is received
    3. Sometimes “pending” status is received from banks which is passed in response to the merchants. In these cases too, merchant should status query at regular intervals till the terminal status of refund transaction is received

    * Note – The refund request can fail due to insufficient funds in merchant payable account (MPA). MPA is unsettled merchant balance present with Paytm

  • In order to safeguard against request/response tampering, merchant must verify the transaction/refund status by following two ways:

    1. Validation request/response via checksum: Paytm posts the transaction status to merchant. With these parameters (other than Checksumhash), merchant has to generate Checksumhash at his end and validate with one received in response. In case of mismatch merchant should check the final details of transaction with transaction status API
    2. Reconciling final status with transaction/refund Status API: For terminal state (success/fail) transactions (withdraw and add money), merchant is required to re-verify status of the transaction with Transaction Status API. The status provided in the response should be treated as the final status of transaction. Additionally merchant should match the transaction amount received with the one sent in transaction request API. In case of mismatch, merchant should mark this transaction as disputed and raise it to KAM/helpdesk team

    Checksumhash ensures integrity of the request and is generated using the secret merchant key. Checksum is always generated on merchant server (where merchant key is placed) and then is passed to client or directly to Paytm depending on the flow. Server side utility code for generating checksumhash in popular development languages is available here

    Checksum must include all parameters i.e. all the mandatory and optional parameters which have been received or is being posted If Merchant code is in Java then merchant should pass TreeMap of all the parameters (parameter name would be key of TreeMap) to checksum utility method along with key to generate CHECKSUMHASH

    CheckSumServiceHelper checksumHelper = CheckSumServiceHelper.getCheckSumServiceHelper();

    String checksum = checksumHelper.genrateCheckSum(key,paramMap); // Key : Merchant Key, map : TreeMap of request parameters

  • Merchant Staging Credentials MID, Merchant Key, Industry type id, Channel id, Client Id, Client secretStaging Wallet details

    Staging credentials are provided after document and platform verification

    Production credentials are provided after merchant has signed the agreement & complying to integration checklist on staging environment

    • Mobile Number – 7777777777
    • Password – Paytm12345
    • OTP – 489871
    • After every 5 minutes, the Wallet balance is topped up to Rs. 7,000

    Mandatory checks to be ensured by merchants with Auto-Debit flow

    1. Mobile number used for linking Paytm should be same as the customer login mobile number in merchant’s platform. This will nullify scenarios wherein a fraudulent customer links/consumes Paytm account for another customer
    2. For a particular OTP, the merchant should hit the OTP validation API only once
    3. Merchant should always validate a customer’s token and not rely on token expiry time. This is because there are many scenarios due to which a token can expire before the expiry time (log out of customer from Paytm account)
    4. Transactions via Auto-debit flow should be initiated by the customer. Merchant cannot take one time permission from the user for subsequent transactions
    5. Merchant should give provision to customer for terminating his account linked with merchant APP. This can be done by Revoke Access API
    6. The merchant should provide an option to customer for resending OTP. This is required as sometimes due to telecom network congestion, the customer does not receive OTP. Additionally merchant should auto read OTP on its APP