• Getting Started
    • Mobile Integration (Android/IOS)
      Enterprise Solutions
      Retail Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Testing
      Refunds
      Guides
      Other Processes
      Mini Program Platform

      Bank Offers

      Bank offers product empowers you to provide discounts/cashback to your customers, encouraging them to make transactions on your platforms regularly. Payment instrument based offer/Bank Offers will be provided by you in agreement with the banks. Paytm has the capability to search offers created at Paytm along with verifying and applying any one of the offers as selected by the customer.
      There are 2 type of Bank Offer integrations possible with custom checkout flow.
      1. Merchant wants to do offer validation before proceeding with the Payment
        In this integration, merchants would be be able to show and validate offers on their app/website. Fetching of offers and validation of offers is achieved with the help of a few APIs. Validation of offers on merchant app/website would help end users to see the offer benefit before they finalize their payment instrument to make payment.
      2. Merchant wants to do offer validation after proceeding with the Payment
        In this integration, offer validation happens once user proceeds with payment after choosing the payment instrument. For instance, in discount led offer transaction on credit card, user will be able to see reduced transaction amount (post discount) once he/she lands on bank page. Here, merchant won't be required to integrate Fetch BIN details API and Apply promo API anymore.

      Integration method 1 : Merchant wants to do offer validation before proceeding with Payment

      Bank offer integration on custom checkout flow uses promo APIs namely Fetch all Offers API, Fetch BIN API and Apply promo API to apply offers on any transaction. In this flow the merchant does not need to modify the order as offer details are passed on to the merchant before transaction is processed. Merchant can show the offer details (discount/cashback) against a payment instrument to its end users (as shown in demo below) before the users click on pay button and transaction gets processed at our end.

      Demo when merchant wants to do offer validation before proceeding with Payment

      paytm instrument offers

      Overview when merchant wants to do offer validation before proceeding with Payment

      1. User adds products into the cart and proceeds to checkout.
      2. You will call Fetch All Offer API to display the relevant offers on payment page to the customers. This is required to show promo codes/offers to your users otherwise this a non-mandatory step.
      3. Paytm will return all applicable offers configured for the merchant.
      4. User selects a payment instrument.
      5. You will call Fetch Bin Details API.
      6. This API will give you “issuingBankCode”, “payment Mode” etc in response. Bank code received here would be used in the next step.
      7. You will next call Apply Promo API, this API helps in validating an offer against the chosen instrument.
      8. This API will return the best offer available configured at Paytm end by you. Incase Promo code is already sent to Paytm in this API, this API would return applicability of that particular offer only against that selected instrument. Since it is mandatory to provide offer construct in Initiate transaction API. (next step), it is mandatory to call Apply Promo API, using which you will get offer construct which has to be passed in Initiate transaction API.
      9. Once validation part is done, you will call Initiate transaction API. Here both payment and offer intent will be passed to paytm. Offer intent will be as per the response of Apply Promo API, and payment intent would be payment related information of the transaction as entered by the user.
      10. Paytm will share a transaction token in the response of this API post validation.
      11. Using the transaction token received in the above step, merchant will validate the response and returns transaction token to merchant app/browser.
      12. You will call Process Transaction API using the token once user clicks on pay button.Since Paytm validates the transaction token as the unique parameter to honour the request to execute transaction, transaction token should be same as in the response received from Initiate transaction API.
      13. Paytm processes the transaction post validating the request and shares the status of the transaction with you. You would show the transaction status as received through Paytm.
      Note: In case of discount Paytm will only settle the discounted transaction amount.

      For example: If the cart value of customer is Rs 1000, and there is a Bank offer which entitles a user a discount of Rs 100 on min cart value/ order value of Rs 1000, then effective order value would be Rs 900 only. Paytm would process transaction which would be value of Rs 900. In case of cashbacks, the transaction value would be Rs 1000 only, as cashbacks have to be honoured by banks.
      overview of instrument based offers

      Prerequisite

      To apply Paytm instrument based offer you have to create your own payment experience using Paytm Custom Checkout APIs and process payment via Paytm.

      Steps to process an offer

      Step 1: Configure an offer

      You can configure a bank offer by providing the offer construct in an email to your Paytm’s account manager, client management team, or you may contact us. Paytm has introduced a solution for select merchants to configure and customize the bank offers campaigns in a DIY mode through Paytm Dashboard. To get more information on this, refer to documentation mentioned on Offer configuration via Paytm Dashboard page.

      Step 2: Display Offers to Customer

      Show the available offers which merchant will get in the response of Fetch All Offer API.

      Step 3: Apply an Offer

      Automatic Selection of an Offer : Paytm will apply best offer in case merchant will not pass any offer.
      Specific offer Validation : Merchant will pass specific offer in Apply Promo API as per user selection. Paytm will validate the offer and provide the response accordingly.

      Step 4: Initiate transaction with Bank Offer

      You will pass json string paymentoffer in the Initiate Transaction API under paymentoffersApplied parameter, this should be same as what you would have received in response of Apply Promo API. Paytm will provide transaction token in the response to this request.

      Step 5: Process transaction.

      Call the Process Transaction API API to process the transaction.

      Step 6: Validating Checksum

      Checksumhash received in response to process transaction needs to be verified on merchant server using Paytm library with all the parameters in key-value pairs.

      Step 7: Validate the Transaction

      You should always validate transaction response via server-side request using Transaction Status API. This API requires checksumhash in request and response. You must verify the Order Id and Amount with your DB entries. The status should be treated as the final status of the transaction in all cases.

      Integration method 2 : Merchant wants to do offer validation after proceeding with Payment.

      This solution has been introduced to further ease the integration of bank offers on custom checkout flow. We intend to make this integration with minimal changes with quick turnaround time. With this integration, a merchant will no longer have to integrate multiple promo APIs as mentioned in Integration method 1, rather will have to just pass an object in initiate transaction API. In this integration of bank offers, merchants won't be able to show discount/cashback details to its end users before the transaction is processed. For instance, in discount led offer transaction on credit card, user will be able to see reduced transaction amount(post discount) once he/she lands on bank page. Here, merchant and Paytm both will modify the order once offer is successfully applied to any transaction for reconciliation purpose. To know how to update your order details post transaction, click here.

      Demo when merchant wants to do offer validation after proceeding with Payment

      demo of simplified bank offers solution

      Overview when merchant wants to do offer validation after proceeding with Payment

      1. User adds a product/service to the cart and proceeds to checkout.
      2. You call the Initiate transaction API with “simplifiedPaymentOffers” as an object. To apply a specific promo code, you can use the “promoCode” parameter in the object above but to apply the best available offer as per the eligibility on a transaction, send the “applyAvailablePromo” parameter as “True” to get verified by Paytm. If you want to execute a transaction only with promo code successfully applied, then, you need to send the “validatePromo” parameter as “True”.
        The default value against the “validatePromo” parameter is false. It is always recommended to keep the value as it is, unless you want to handle a specific use case.
      3. Paytm validates the availability of “simplifiedPaymentOffers" object and its parameter in Initiate transaction API.
      4. Paytm creates an order corresponding to your order details shared in the Initiate transaction API.
      5. Paytm checks for "promocode", "applyavailablepromo" and "validatepromo" params within the object and will return a transaction token accordingly
      6. Merchant validates the token and passes the txn token to merchant app/browser
      7. Merchant calls the Process transaction API
      8. Paytm validates the "promocode" and "applyavailablepromo" param values and accordingly may or may not internally hit our promo engine.
      9. Paytm checks the applicable offers for the transaction.
      10. After applying the promo successfully, Paytm modifies the order accordingly and shares the Process Transaction API response. This response though, does not convey any change in order due to offer applicability (eg. change in order value due to discount or amount of cashback applied). Based on the offer applicability, merchants may have to modify the order at their end as well. Hence, they need to integrate Transaction status API and Payment status Webhook, failing which, merchants won't get to know the final order and offer construct details which got processed ultimately. This is a mandatory step for integration method 2.
        You may check for more details for the same here.
      In case of discount Paytm will only settle the discounted transaction amount.

      For example: If the cart value of a customer is Rs 1000, and there is a bank offer which entitles a user a discount of Rs 100 on min cart value/order value of Rs 1000, then the effective order value would be Rs 900 only. Paytm will process the transaction which would be worth Rs 900.
      In case of cashbacks, the transaction value would be Rs 1000 only, as cashbacks have to be honoured by banks.
      flowchart of simplified bank offers solution

      Key scenarios of “simplifiedPaymentOffers” object

      You can see below a few key scenarios to understand the “simplifiedPaymentOffers” object:
      S.noPromocodeapplyavailablepromovalidatepromoDescription
      1NOT NULLTRUETRUEBoth promo code and applyavailabelpromo can't be true for the same order. In this scenario, the Promocode param value would be given preference at paytm end.
      2NOT NULLNULLTRUETxn will only execute, if a given promocode is applicable, else the txn will fail.
      3NULLNULLFALSEThis is invalid, if both the 1st and 2nd params are null. There is no point of having this object at all let alone validatepromo
      4NULLTRUEFALSETxn will be executed even if there is no valid promo applicable
      5NULLTRUETRUENo txn will be executed, if no valid promo is available

      Prerequisite

      To apply the simplified bank offers on different Paytm instruments, you must comply with the following prerequisite:
      1. Create your own payment experience using the Paytm Custom Checkout API and process payment via Paytm.
      2. Configure the offers by contacting your Paytm's account manager or client management team.

      Steps to process simplified bank offer solution

      Step 1: Configure an offer

      You can configure a bank offer by providing the offer construct in an email to your Paytm’s account manager, client management team, or you may contact us. Paytm has introduced a solution for select merchants to configure and customize the bank offers campaigns in a DIY mode through Paytm Dashboard. To get more information on this, refer to documentation mentioned on Offer configuration via Paytm Dashboard page.

      Step 2: Initiate transaction with Bank Offer

      You will pass a object “simplifiedPaymentOffers” with “promocode”,”applyavailablepromo” and ”validatepromo” in the Initiate transaction API parameter. Paytm will provide a transaction token in the response to this request.

      Step 3: Process transaction

      Call the Process Transaction API to process the transaction.

      Step 4: Validating Checksum

      Checksumhash received in response to the process transaction needs to be verified on the merchant server using Paytm library with all the parameters in the key-value pairs.

      Step 5: Validate Transaction (Implementation: Mandatory for Integration Method 2)

      You must validate the transaction response via server-side request using the Transaction Status API or Payment Status Webhook.
      Webhook - Paytm sends a server to server (S2S) response in a key-value pair on the configured URL. Payment Status Webhook is sent only when the transaction has reached a terminal state (success/fail). To configure the URL, please connect with Paytm.

      Transaction Status API: You should always validate transaction response via server-side request using the Transaction Status API. This API requires checksumhash in request and response.

      The merchant receives “PAYABLE_AMOUNT” parameter and “PAYMENT_PROMO_CHECKOUT_DATA” object via Transaction Status API and Payment Status Webhook response which the merchant must mandatorily implement in their system to record the final payment details whenever a promocode or any bank offer is successfully applied.
      • PAYABLE_AMOUNT: Original amount of the transaction which is sent in the Initiate transaction API
      • PAYMENT_PROMO_CHECKOUT_DATA: This object contains the following parameters:
        ParameterDescriptionData typeSample value
        promocodeActual promocode which got appliedStringHDFC10
        promotextPromo messageStringPayment OK
        savingsBenefit amountNumeric string100
        redemptionTypediscount/ cashbackstringCashback