paytm developer docs logoDeveloperDocumentation
search

Express Integration

Overview

 

Express Integration has been introduced to further simplify the integration of Bank Offers and Subvention on Custom Checkout. Paytm intends to make this integration with minimal changes with a quick turnaround time. With this integration, a merchant will no longer have to integrate multiple offer APIs but rather will have to just pass an object simplifiedUnifiedOffers in the Initiate transaction API.

 

In this integration of Bank Offers and Subvention, merchant won't be able to show discount / cashback details to their end users before the transaction is processed.

 

For example: In a discount-led offer transaction on a credit card, the user will be able to see the reduced transaction amount(post discount) once he / she lands on the bank page. Here, Merchant and Paytm both will modify the order once the offer is successfully applied to any transaction for reconciliation purposes.

 

To know about prerequisites for integration, please refer to the Prerequisites section.

Demo

Transaction Flow

 

 

  1. User adds a product / service to the cart and proceeds to checkout.
  2. Merchant calls the Initiate transaction API with simplifiedUnifiedOffers as an object.
  3. For Bank Offers

    a. Merchant calls the Initiate transaction API with simplifiedUnifiedOffers as an object with promoDetails object populated in it. To apply a specific offer, the merchant uses the offerId parameter in the above object 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.

     

    b. If merchant wants to execute a transaction only with the promo code successfully applied, then they need to send the validatePromo parameter as True as the default value is False.

     Note: For running item-based offers, items in the cart must be sent in the items object in the simplifiedUnifiedOffers and isAmountBasedBankOffer must be set to false in the promoDetails object.

     

    For EMI Subvention

    a. User selects EMI and merchant shows different plans available to the user by fetching from the database.

     

    b. User selects one of the zero-cost EMI tenures and proceeds with the payment.

     

    c. Merchant calls the Initiate transaction API with the simplifiedUnifiedOffers object with subvention details in the subventionDetails object. This object shall have the parameters of plan information and subvention identifiers.

     

     Note: For running item-based subvention, items in the cart must be sent in the items object in the simplifiedUnifiedOffers, and isAmountBasedBankOffer must be set to false in the subventionDetails object.

  4. Merchant validates the token and passes the txn token to the merchant app / browser.
  5. Merchant calls the Process transaction API.
  6. Paytm validates the promoDetails and subventionDetails param values and accordingly may or may not internally hit our promo engine.
  7. Paytm checks the applicable offers for the transaction.
  8. After applying the promo / subvention 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 more details refer here.

     

     Note: 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.

 

Key scenarios of simplifiedUnifiedOffers object

 

Merchant can see below a few key scenarios to understand the simplifiedUnifiedOffers object:

 

S.No Promo Code Apply Available Promo Validate Promo Subvention Details Description
1 Not Null True True   Both promo code and applyAvailablePromo can't be true for the same order. In this scenario, the Promocode param value would be given preference at the Paytm end.
2 Not Null Null True   Txn will only execute, if a given promocode is applicable, else the txn will fail.
3 Null Null False False This is invalid if both the 1st and 2nd params are null. There is no point in having this object at all let alone validatePromo
4 Null True False   Txn will be executed even if there is no valid promo applicable
5 Null True True   No txn will be executed if no valid promo is available

 

Steps to Process an Offer

 

1. Configure an offer

Merchant can configure a bank offer/Subvention campaign by providing the offer construct in an email to their Paytm’s account manager, client management team, or merchant can contact us. Paytm has introduced a solution for select merchants to configure and customize the bank offer/Subvention campaigns in a DIY mode through Paytm Dashboard. To know more, refer to the Offer configuration via Paytm Dashboard section.

 

2. Initiate transaction with Bank Offer/EMI Subvention

Merchants needs to pass an object promoDetails with offerId, applyAvailablePromo, and validatePromo in the simplifiedUnifiedOffers object in the Initiate transaction API parameter. Paytm provides a transaction token in response to this request.

 

In the case of EMI Subvention, user selects the EMI as a payment option on the checkout page. Merchant shows the different bank options and their tenures available for the cart item. These plans are fetched from your database itself. User selects a tenure of a bank, enters the card details, and proceeds with the payment. Merchant calls the Initiate Transaction API from the backend server with the simplifiedSubvention object as mentioned below:

 

"simplifiedUnifiedOffers": {
    "subventionDetails": {
        "subventionAmount": "1000", // Amount for which subvention has to be provided
        "offerId": "2141488" // Subvention Offer Id
    }
}

In the case of EMI Subvention, user selects the EMI as a payment option on the checkout page. Merchant shows the different bank options and their tenures available for the cart item. These plans are fetched from your database itself. User selects a tenure of a bank, enters the card details, and proceeds with the payment. Merchant calls the Initiate Transaction API from the backend server with the simplifiedSubvention object as mentioned below:

 

"simplifiedUnifiedOffers": {
    "item": [
        {
            "id": "15036688", // Merchant generated id
            "productId": "1", // Product identifier
            "brandId": "10002", // Brand identifier
            "categoryId": "10001", // Category identifier
            "price": 10000.00 // Price of the product
        }
    ],
    "subventionDetails": {
        "isAmountBasedSubvention": "false",
        "subventionAmount": "1000"
    }
}
"simplifiedUnifiedOffers": {
    "promoDetails": {
        "offerId": "",
        "applyAvailablePromo": "true",
        "validatePromo": false
    }
}

 

"simplifiedUnifiedOffers": {
    "promoDetails": {
        "offerId": "123321",
        "applyAvailablePromo": "false",
        "validatePromo": true,
        "isAmountBasedBankOffer": "false"
    },
    "item": [
        {
            "id": "15036688", // Merchant generated identifier
            "productId": "1",  // Product identifier
            "brandId": "10002", // Brand identifier
            "categoryId": "10001", // category identifier
            "price": 10000.00 // Price
        }
    ]
}

 

3. Process transaction

Call the Process Transaction API to process the transaction. 

In case of offers, Paytm validates the offer intent and applies the offer to calculate the final amount to be paid by the user. The order is modified and response is shared for the process transaction API though the modified order amount is not shared in the response.

 

4. Validating Checksum

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

 

5. Validate Transaction (Mandatory)

Merchant 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 contact us.

Transaction Status API: Merchant must 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 or 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:

     

    PARAMETER DESCRIPTION DATA TYPE SAMPLE VALUE
    promocode Actual promocode which got applied String HDFC10
    promotext Promo message String Payment OK
    savings Benefit amount Numeric string 100
    redemptionType discount/ cashback string Cashback