Your Paytm for business app is working and will keep working beyond March 15th, 2024. Click to know more
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
User adds a product / service to the cart and proceeds to checkout.
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.
Merchant validates the token and passes the txn token to the merchant app / browser.
Paytm validates the promoDetails and subventionDetails param values and accordingly may or may not internally hit our promo engine.
Paytm checks the applicable offers for the transaction.
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:
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.
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:
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.