paytm developer docs logoDeveloperDocumentation
search

Pre-Auth Integration

Overview of Pre-auth processing steps

Step 1 : Link a user’s Paytm account with your application

  1. User visits merchant's website or mobile application.
  2. Merchant's ask the user to link their Paytm account with their website or mobile application for seamless payments.
  3. Merchant initiates the account linking process using Send OTP API and Validate OTP API.
  4. Once the user account is successfully linked, Paytm shares the user SSO_TOKEN with the merchant.

Demo of Paytm Account Linking

Paytm account linking flow

Please find below the list of APIs and their use cases with respect to the Paytm account linking on merchant App/website.

USECASE CATEGORY

 API NAME DESCRIPTION

Send OTP to entered mobile number

 Send OTP API This API is used to send an OTP to a user's mobile number so as to start linking of Paytm user’s account on merchant web/app

Linking of Paytm account

 Validate OTP API

This API is used to verify the OTP entered by a user and provide the required tokens in response.

  • The tokens received (Access and Refresh token) are specific to client Ids provided by Paytm

  • Access token which is also known as SSO token is an identifier for Paytm user account
  • Refresh token has longer validity and is used to retrieve a new SSO token on its expiry

Refresh Paytm user’s SSO token

 Refresh Token API This API is used to retrieve the new SSO token of Paytm user account upon its expiry

Validate Paytm user’s SSO token

 Validate Token API This API is used to validate the Paytm user’s SSO token

De-link Paytm user’s account

 Revoke Access API This API is used to expire the Paytm user’s SSO token. This is done in case a user deletes or de-links the account on your application.

 

Step 2 : Check Balance and Add Money

  1. User adds the goods and services into the shopping/order cart.
  2. Merchant calculates the total amount and calls the Paytm Check Balance API.
  3. Paytm validates if the given amount exists in any Paytm proprietary payment instrument (Paytm Balance and Paytm Postpaid).
  4. If any of the proprietary payment instruments don’t have sufficient balance then API returns the differential Amount.
  5. For example A user has Rs.100 in their Paytm Wallet and Rs.150 in Paytm Postpaid. The transaction amount for the order is Rs. 220. In this case, no payment method has sufficient funds so the API returns the differential amount (transaction amount - wallet amount) i.e Rs.120. You have to prompt the user to add money in their Wallet.
  6. In case a user needs to add money to pay for an order, you initiate the Add Money process.

Step 3 : Blocking of amount in user's Paytm wallet/postpaid account

  1. Merchant calls the Paytm Pre-auth API to block amount from the user's Paytm account (wallet/postpaid).
  2. Paytm blocks the amount in user's Paytm account and shares the unique Pre-auth ID in response to the merchant.

Pre-auth flow for Paytm Wallet/Postpaid

UPI Flows

Paytm supports the below UPI solutions to process merchant pre-auth transactions :

  • UPI Collect
  • UPI Intent

UPI Collect

UPI Collect is the simple way of collecting the payment by prompting the user to enter the VPA address through which they intend to pay. User is notified through SMS and is prompted to make the payment on the relevant bank App. 

Overview of Pre-Auth processing Steps 

  1. User visits the merchant platform to add goods/services into the cart
  2. User clicks on checkout and on the payment page select UPI as the payment instrument
  3. User inputs his active UPI address to be used for the payment
  4. Merchant calls Paytm to validate the UPI address provided by the user with the help of Validate VPA API.
  5. Paytm validates that the UPI address mentioned by the user is correct and the corresponding user PSP supports the standard auth flow. Paytm then returns the status to the merchant. 
  6. Merchant calls Paytm Preauth API. Paytm validates the pre-auth details and sends the txnToken in response.  
  7. Merchant uses the txnToken received to call the Process Transaction API. Paytm raises a request to their banking partners (acquiring bank & NPCI)
  8. Banking partners send an authentication request to the user PSP App linked to the VPA entered by the user. User PSP App asks the user to authenticate the transaction
  9. On successful authentication, banking partners sends a notification to the customer's bank to block the amount.
  10. Banking partners confirm the successful blocking of the amount to Paytm which then conveys the same to the merchant. 
  11. Merchant validates the response and initiates the fulfillment of service.
  12. On successful block user receives a debit message for the blocked amount from the bank and the same is reflected in their bank passbook as a debit transaction.

Pre-Auth Workflow for UPI Collect

UPI Intent

The UPI Intent flow to collect payment works on mobile browsers/applications with the use of UPI supported apps installed on a user’s mobile device that makes the payment process for them a lot smoother. Its Improved and seamless payment process results in an optimal user experience for your customers by avoiding the switching between multiple apps (merchant, SMS, UPI app) for payments.

Overview of Pre-Auth processing Steps 

  1. User visits the merchant platform and add goods/services into the cart.
  2. User clicks on checkout and on the payment page selects UPI
  3. Merchant calls the Preauth API. Paytm validates the pre-auth details and sends the txnToken in response. 
  4. Merchant calls the Process Transaction API with transaction token as received in response to Preauth API and paymentMode sent as UPI_INTENT. You will receive the deep link provided by the Paytm in response.
  5. You will call the deep link provided which will invoke all the UPI PSP Apps on the device and that can be shown to the user.
  6. User selects the PSP App using which they want to pay with and is redirected to it with details like amount, Payee VPA, unique transaction reference number
  7. User enters the UPI PIN to authenticate the payment. UPI PSP raises the request to banking partners (NPCI, acquiring bank)
  8. Banking partners raise the block request to the user's linked bank account.
  9. User's linked bank will block the amount and confirm the same to banking partners which in turn will confirm to Paytm. Paytm confirms the same to the merchant.
  10. Merchant initiates the fulfilment of service.
  11. On successful block user receives a debit message for the blocked amount from the bank and the same is reflected in their bank passbook as a debit transaction.

Pre-Auth Workflow for UPI Intent

Overview of Pre-auth processing steps

  1. User visits the merchant app or website to choose the goods/service to be delivered.
  2. User visits the cashier page to select cards as the mode of payment, provides the required card details and initiates the payment.
  3. Merchant calls the Access Token API to receive the accessToken from Paytm in response of the API call.
  4. Merchant uses the txnToken received in the Pre-Auth API response to call the Process Transaction API. Paytm gets the customer's bank URL via banking partners (acquiring bank and network partners)
  5. Merchant renders the bank URL on the customer's client to complete the authentication process.
  6. Upon successful authentication, Paytm initiates a block request of the stipulated amount in the user's bank account via banking partners. On failure authentication, the user is redirected back to the merchant with the respective status
  7. Once the block has been attempted against authentication, the user is redirected bank to the merchant's callback. Note the blocking can be failed for various reasons like insufficient balance, incorrect card details (CVV expiry) etc
  8. Post successful block of the transaction amount merchant can now initiate the service/goods delivery.

Pre-Auth flow for cards

On successful block of the amount Paytm shares a Pre-Auth webhook to the merchant. 

 

In case the pre-auth status is stated as pending, the merchant can use the Transaction Status API to find the latest status of pre-auth for that transaction. The pre-auth status of a transaction can be found from the Transaction Status API by using the txnType as "PREAUTH".