Pre-auth flow serves the need of the merchant when they want to accept payment details from the customer at the start of the journey but capture the amount only once the delivery of the service/goods has been successfully completed. This is an ideal solution for merchants where :
Delivery of service/order fulfilment is not immediate
Actual payment amount may vary from the estimated amount at the time of order booking
High frequency of cancellations are expected
Taking the above points into account some of the key business verticals for which pre-auth flow is beneficial are : cab aggregators, hotel chains, e-commerce website, metro trains, etc. Currently, Paytm supports the Standard Auth flow of Pre-auth.
Standard Auth
Standard Auth is the pre-auth flow which involves the blocking of the transaction amount in the user's account/wallet at the start of the service/goods delivery by the merchant. The merchant can capture the amount once the service/goods has been successfully delivered. The merchant can choose to capture any amount less than or equal to the initially blocked amount.For wallet and postpaid transactions, amount greater than initially blocked amount can also be captured.
In case the user chooses to cancel the transaction before capture the merchant can simply choose to release the amount back into the user's account/wallet. If a merchant does not capture the amount within a stipulated time period then it gets automatically released. This stipulated time period varies depending on the merchant configuration and the payment source of the transaction.
The flow would be applicable for merchants whose business use case needs a guarantee of availability of sufficient funds in the user's account once the service has been successfully delivered.
Payment Sources Supported for Standard Auth
Currently, Paytm supports the below payment sources for Standard Auth transactions :
Attribute
Wallet & Postpaid
UPI
Cards
Blocking of money
Yes, money blocked in user's account
Yes, money blocked in user's account
Yes, money blocked in user's account
Maximum time period for capture
72 hours (recommended)
90 days
96 Hours
Transaction Amount limit
No limit
No limit
No limit
Under Capture
Supported
Supported
Supported
Excess Capture
Supported
Not Supported
Not Supported
Multiple Capture
Not Supported
Not Supported
Not Supported
Release TAT
Instant
Depends on customer bank
Depends on issuing bank
Use case application
Ride booking apps
Hotel booking
E-commerce websites
Metro train tokens
Demo of Standard Auth
Overview of Standard Auth
Below are the three phases of a typical Standard Auth payment :
Pre-Auth
Capture
Release
Pre-Auth
This phase involves the blocking of funds by the issuing entity post successful user authentication. The merchant generally raises the pre-auth request at the time of order booking (or before the start of the service/order delivery).The following details would be required while raising a pre-auth request :
The merchant and order level details.
The payment source to be used for making the transaction
The maximum period before which a capture call can be made for the transaction.
The amount to be blocked for the transaction
Capture
This phase involves transferring the blocked amount to Paytm, which is later settled with the merchant by Paytm. The merchant can initiate a capture post the successful delivery of the service/goods to the end customer. Merchant needs to keep the below points into consideration while making the capture call :
Merchant can call capture anytime before the maximum block period allocated for that transaction. Maximum block period for a transaction is generally passed by the merchant in the corresponding pre-auth request.
Note:In case the pre-auth request does not provide the maximum block period, the default block period provided in the merchant contract is used.
Any amount less than or equal to the blocked amount can be captured by the merchant.For wallet and postpaid transactions, amount greater than initially blocked amount can also be captured
Merchant can only make one successful capture corresponding to a standard auth transaction. (Multiple captures are currently not supported)
In case the merchant captures an amount less than the blocked amount, the differential amount is automatically released back into the user's account. The time period required for the remaining amount to reflect back into the user account varies with respect to payment sources :
Payment Source
Partial release TAT
Wallet
Instant
Postpaid
Instant
UPI
Depends on customer bank
Debit/Credit card
Depends on issuing bank
The following details would be required for raising the capture request :
The merchant and order level details
Unique ID to identify the pre-auth request corresponding to which merchant wants to make the capture call.
The amount that the merchant wants to capture.
Release
This phase involves the reversal of the blocked amount back into the user's account. Release of blocked amount happens due to any of the below three reasons :
If the user chooses to cancel the delivery of service/goods before merchant had captured the blocked amount. This release will have to be raised by the merchant. The following details would be required to make a release request :
The merchant and order level details
Unique ID to identify the pre-auth request corresponding to which merchant wants to make the release call.
If the merchant fails to capture the amount within the stipulated maximum block period. In such a scenario the release will be automatically generated by the system.
If the merchant captures can amount less than the blocked amount then the differential amount would be auto released in the user bank account. The differential amount would be automatically released by the system.
The time period for the released amount to be reflected back into the user account depends on the payment source :
Payment Source
Release TAT
Wallet
Instant
Postpaid
Instant
UPI
Depends on customer bank
Debit/Credit card
Depends on issuing bank
Integration Steps
Click on the links below to get the details on the integration steps for each phase of the Standard auth payment :
This API is used to check if the Pre-Auth details entered by the merchant are valid as per their contract. For wallet transactions this API also entails the blocking of the amount in the user wallet
This API is used to release the blocked amount back into the user's account in case the transaction was cancelled by the user
Steps of onboarding on Pre-auth
Get the below authentication keys .
Client ID: A unique alphanumeric identifier issued by Paytm for your account
Client Secret: A unique alphanumeric key issued by Paytm for your account
MID: A unique merchant identifier issued by Paytm for your account
Merchant Key: This is a unique secret key used to secure encryption of every request. This needs to be kept on server side and should not be shared with anyone.
Get in touch with your KAM to get your MID enabled on pre-auth
Choose the payment sources for which you want to make pre-auth transactions.
Provide the below required attribute values depending on your business requirement :
Attribute
Definition
Default Pre-Auth Block Time
The default maximum block time to be used for transactions when no information is passed in the order level APIs
Maximum Pre-Auth Block Time
The maximum block time allowed for any transaction as per your business use case.
Extent of overcapture allowed
The maximum percentage overcapture required by your business use case.
(Note : In case no value is provided then overcapture will not be supported. Support of overcapture also depends on your merchant category)
Maximum overcapture amount allowed
Maximum limit on the amount of over-capture allowed for your pre-auth transaction
Choose the pre-auth flows which you want to onboard for your transactions.
In case you choose more than one pre-auth flow you will have to set a default pre-auth flow which will be used to complete the payment in case no pre-auth flow is mentioned order level APIs.
Managing Refunds
If you need to cancel or refund a successful transaction, simply send a Refund API request and ensuring success using the Refund Status API.
Post Integration steps
Post completion of integration on your staging environment, do a complete transaction from order summary page on your website or mobile app.
Ensure you re-verify transaction response with Transaction Status API via server to server call in payment flow and not separately as a one-time activity.
See the transaction details in the “Test Data” mode on your dashboard.
Once the test transaction is complete, move your code to live environment with production account details, which you would have received from Paytm.