Paytm Subscription Integration - Overview

  • Subscription payment flows enables merchant to collect recurring payments from customers without explicitly going through entire re-purchase flow. This flow is used for services/products which are consumed on an ongoing basis and payments are made periodically by the customer. Examples – payment of postpaid bill, water bill, magazines, movie channel subscription etc. In this flow customers authorize merchants to charge their credit/debit cards or Paytm wallet with specific amount on a regular basis – such as monthly, quarterly or yearly. Based on payment mode used, Paytm provides 3 types of subscription:

    Types of subscription flowsDescription
    Only WalletAmount for subscription and subsequent renewals will be charged from customer’s Paytm wallet. In case of insufficient balance in wallet, transaction will be failed
    Wallet & Saved CardCustomer can add a new card or can link existing saved cards with wallet for subscription payments. By default, balance will be debited from customer’s Paytm wallet. However, in case of insufficient balance, different saved cards will be used to add money to wallet
    Only CardsMerchant can opt for recurring payments via debit/credit cards. Restrictions on cards used -
    1. Debit cards – Issued by HDFC, Kotak or ICICI only
    2. Credit cards - All domestically approved cards

    For merchant opting for any of first two flows, RBI mandates the merchant has to take explicit customer's consent before initiating each successive payment/subscription transaction. Merchant has to preserve the customer’s consent log and share at the time of customer dispute/process audit with Paytm

    Subscription can be broken down into:

    1. Creating a subscription: Subscription configurations such as start date, length of billing cycle, subscription amount, subscription frequency, payment instrument to be used etc are established in this step. In case customer chooses to link a card with the subscription order, Paytm will process a 3D secure transaction. If merchant does not charge the customer in this step (trial period offered) or customer has sufficient balance in his Paytm wallet, Paytm will still process a 3D secure transaction for INR 1 from the saved card of the customer
    2. Renewing the subscription: This refers to subsequent deduction from merchant/customer authorized payment instrument. As mentioned earlier, for all flows involving Paytm wallet explicit customer consent needs to be taken from the customer by the merchant

    • Customer Flow
    • Product Flow - Wallet Only
    • Product Flow - Wallet with Saved Cards
    • Product Flow - Cards Only
    In Store Banner
    In Store Banner
    In Store Banner
  • This section details out the use cases of all APIs used in this payment flow. here.

    API Name with signature linkPurpose
    Process Transaction API* (Create subscription call)All details regarding the subscription such as start date, length of billing cycle, subscription amount, subscription frequency, payment instrument to be used etc are established in this API. In order to choose the payment mode, merchant should do the following:
    1. Wallet with Saved Cards- Default Subscription method
    2. Only Wallet –Merchant must pass parameter Subs_PPI_only and the value should be “Y”
    3. Only Cards- Merchant must pass parameter SUBS_PAYMENT_MODE as “CC”
    Renew Subscription APIRenewal subscription API can be called in order to charge customer for subsequent payments. For only wallet and wallet with saved cards, renewal API must be call only once consent is taken explicitly from the customer
    Status Query APIThis API has three use cases:
    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 TXN 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 in regular intervals till the terminal status of transaction is received
    Refund APITo initiate transaction via Paytm PG/wallet.Note that since Refund API is a server to server call, reverification of terminal state refund transactions via “Refund Status API” is not required
    Refund Status APISame guidelines as transaction status API
    1. Provision of free trial period to customer/ Variable subscription value – To provide free trial period to customer, merchant has to pass amount as zero in create subscription call. To ensure customer can charge an amount in the following renew calls, SUBS_AMOUNT_TYPE needs to be set as variable and SUBS_MAX_AMOUNT needs to set to the maximum value that can be charged in renew subscription calls
    2. Subscription Cycle:
      ScenarioCreate CallFrequencySubscription Start dateGrace Days1st renewal time period2nd renewal time period
      Without Subscription start dateTF--> T+F and T+2F Assuming this day is N. In case there is no successful transaction N = T+2F> N+F and N+2F
      With Subscription start dateTFSG

      Note:

      1. Merchant can only make a subscription call in above computed time period. Beyond that period the transactions will be failed
      2. Failure to make a successful renewal transaction does not impact the subsequent renewal subscription
      3. Merchant can only make one successful renewal transaction in renewal time period. This holds true even if the merchant is not able to make a successful transaction in the previous renewal time period/s
      4. The maximum number of failed transactions that can be attempted in renewal time period can be capped by SUBS_RERTY_COUNT in the create subscription call

    3. Retry Methodology – Merchant can control the number of maximum number times retry will be allowed for failed renew subscription call in one subscription cycle. This can be controlled by passing required value in SUBS_RERTY_COUNT.

      The system will try to add cash to wallet every X hours. In case there is more than one card saved, then every try will be with a fresh card till all the card options are exhausted. Once all the cards have been tried again random card selection will begin. This will continue for Y number of times

  • 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 secret

    Staging payment instrument 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

    Staging CC/DC Credentials

    • Card Number -: Any valid VISA or MASTER card number
    • Expiry Date-: Any future date from transaction date
    • CVV-: Any three digit number
    • OTP-: 123123 (To test successful transaction)

    Staging Wallet Credentials:

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

    Note: Netbanking, UPI and EMI cannot be currently tested in staging environment.