Native OTP Flow for BNPL

This section describes what is Native OTP flow with benefits and how to implement Native OTP flow when collecting payments using BNPL.

What is Native OTP flow

In general, the transaction OTP is captured on Bank pages through multiple hops. With Native OTP Flow, it will be triggered and captured on merchants or the PayU Payment page. The customer stays on the merchant’s (or PayU’s) website/app and completes the Card authentication process of entering OTP on the merchant’s (or PayU) website itself, rather than redirecting the user to a 3d-secure page to complete the transaction. This reduces hops, points of failure, or drops in the checkout process hence faster completion of transactions, better experience, and improved success rate so preferred over OTP on Bank’s Page.

Benefits

What are the advantages and why should merchants integrate this flow with PayU?

  • Native OTP flow improves Success Rates of card transactions by 3-5% depending upon the source of transactions.
  • It improves the overall user experience since multiple redirections are removed. Also, the customer never leaves the merchant website, which helps in providing a seamless experience. It also reduces drop rates due to users’ fluctuating internet speed issues.
  • PayU supports all major banks – 15+ banks including HDFC, AXIS, ICICI, SBI, KOTAK, RBL, etc. – on this flow for Cards, cardless, CC EMI, DC EMI’s, and BNPLs.

The flow supports the latest native OTP generation flows through the Payment (_payment)API, followed by Submit OTP API, to initiate an S2S=4 transaction.

πŸ“˜

Note:

If you don’t have BNPL enabled, try requesting using Dashboard. For more information, refer to Checkout payment modes. If you could not request through Dashboard, contact your PayU Key Account Manager or PayU Support.

Steps to Integrate

  1. Check the BNPL eligibility
  2. Initiate the payment
  3. Check the response from PayU
  4. Submit the OTP

Step 1: Check the BNPL eligibility

For request parameters and response to perform BNPL Eligibility Check, refer to Get Checkout Details API.

Step 2: Initiate the payment

πŸ“˜

Reference:

For Try It experience, refer to Collect Payments API - BNPL under API Reference.

Request parameters

ParameterDescriptionExample
key
mandatory
StringMerchant key provided by PayU during onboarding. JPg***r
txnid
mandatory
StringThe transaction ID is a reference number for a specific order that is generated by the merchant. ypl938459435
amount mandatoryStringThe payment amount for the transaction. 10.00
productinfo mandatoryStringA brief description of the product. iPhone
firstname mandatoryString The first name of the customer.Ashish
email
mandatory
StringThe email address of the customer. [email protected]
phone
mandatory
StringThe phone number of the customer.
pg mandatoryString It defines the payment category using the Merchant Hosted Checkout integration. For a BNPL payment, "BNPL" must be specified in the pg parameter.BNPL
bankcode mandatoryString The merchant must post this parameter with the corresponding payment option’s bank code value in it. For the list of bankcodes for BNPL, refer to BNPL Codes .LAZYPAY
furl
mandatory
StringThe success URL, which is the page PayU will redirect to if the transaction is successful.
surl
mandatory
StringThe Failure URL, which is the page PayU will redirect to if the transaction is failed.
hash
mandatory
StringIt is the hash calculated by the merchant. The hash calculation logic is:
sha512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT)
address1
optional
String The first line of the billing address.
For Fraud Detection: This information is helpful when it comes to issues related to fraud detection and chargebacks. Hence, it is must to provide the correct information.
address2
optional
String The second line of the billing address.
city
optional
String The city where your customer resides as part of the billing address.
state
optional
String The state where your customer resides as part of the billing address,
country
optional
String The country where your customer resides.
zipcode
optional
String Billing address zip code is mandatory for the cardless EMI option.
Character Limit-20
udf1
optional
String User-defined fields (udf) are used to store any information corresponding to a particular transaction. You can use up to five udfs in the post designated as udf1, udf2, udf3, udf4, udf5.
udf2
optional
String User-defined fields (udf) are used to store any information corresponding to a particular transaction. You can use up to five udfs in the post designated as udf1, udf2, udf3, udf4, udf5.
udf3
optional
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.
udf4
optional
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.
udf5
optional
String User-defined fields (udf) are used to store any information corresponding to a particular transaction.

Checked the response mentioned inCollect Payments API - BNPL under API Reference..

Hashing

You must hash the request parameters using the following hash logic:

sha512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT)

For more information, refer to Generate Hash.

Step 3: Check the response from PayU

Sample payment response

{ 
  "metaData": { 
    "message": null, 
    "referenceId": "6a037a290af9253a1d300c8ad0b24c94",// mihpayencoded payuid 
    "statusCode": null, 
    "txnId": "5b7d06c6bf7d4dc2d3a8", 
    "txnStatus": "pending", 
    "unmappedStatus": "pending" 
  }, 
  "result": { "acsTemplate": "PGh0bWw+PGJvZHk+PGZvcm0gbmFtZT0icGF5bWVudF9wb3N0IiBpZD0icGF5bWVu 12 dF9wb3N0IiBhY3Rpb249Imh0dHBzOi8vcHA5NHNlY3VyZS5wYXl1LmluL19wYXltZW50X29wdGlvbnM 13 /bWlocGF5aWQ9NzI0MGQ0OTE5NDJiYzg2NmE1ZTZiNDc2ZTNhZTVkODkmcmVzZW5kRWxpZ2liaWxpdHl 14 SZXM9MzU5NGM3M2IxOGY3Y2E5ZTgxNDZmMGJiM2QwYmQ4NDI5ZTVhMjBjMmY2MWQ3NzhiZmQwZmI0YjB 15 kNDMwZWJkMjFhOGQ4ZmYyMGU3Nzc1OGM5MDNhNzFmZTIyZDM5ZDE0OTQxMjcwMzRlZDdkNTA1MjM3Y2I 16 2ZjdiZjgwY2MzMTA3YTAyY2JkMjIyMTdjMTlmNjY2MmVmYWM4ZThmODNkY2E5MDI0NzBhOTgxYmRkMGE 17 wYzAzODQ3ZDU0NmY0MWFkOGYzMDY2YjJjY2M4YTM1OWUwMzAzMjk1M2YzNjExMmQwZTU1MWVjMTliYTc 18 xOTU0ZGZlNzg4ZDE4YTI4YWM3NjA5YmE1M2JkNzc1NDhjZmZiODE4ODIzNDdmYzhiOTczMTU1MDlhZmR 19 mOGEwODk0NDQzY2Y5MWUwYjFmZGU4NDU5NGJlZTZmYzlkMzlkYTg4NGYzMDIxZWIyMjI0NjE4ZTJjN2Y 20 xMTVhMDIwNTcwNTE5ODcyMjBlYzc4NjRlY2M0NGEwMTI0MTdlNDg4MGIxODdlZTFmMTIzNjNhMjVhNGJ 21 lYzYyZDgzMjJlYjFiMTg1MTk1YTcxNDEyNGI1ZGU5NDMwOWE2ZGNlNDJlZjQ0MTQ2NGQzNDYyZTc4MDk 22 2NzBjIiBtZXRob2Q9InBvc3QiPjwvZm9ybT48c2NyaXB0IHR5cGU9J3RleHQvamF2YXNjcmlwdCc+CiA 23 gICAgICAgICAgICAgICAgICAgICAgICAgICB3aW5kb3cub25sb2FkPWZ1bmN0aW9uKCl7CiAgICAgICA 24 gICAgICAgICAgICAgICAgICAgICAgICAgZG9jdW1lbnQuZm9ybXNbJ3BheW1lbnRfcG9zdCddLnN1Ym1 25 pdCgpOwogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICA 26 8L3NjcmlwdD48L2JvZHk+PC9odG1sPg==",// Base64 Encoded HTML 27 "otpPostUrl": "https://test.payu.in/ResponseHandler.php} 
} 

Handling payment response

This sub-section describes the components of the payment response received with Native OTP or Zero Redirection flow. It contains the metaData and result JSON as described in this subsection:

metaData JSON fields description

FieldDescription
messageThis field contains any additional message about the transaction.
referenceIdThis field contains the reference ID of the transaction.
statusCodeThis field contains the status code for the transaction.
txnIdThis field contains the transaction ID of the transaction that was posted in the request.
unmappedStatusThis field contains the unmapped status of the transaction. For more information, refer to Payment State Explanations.

result JSON fields description

The result JSON contains the acsTemplate with base64 encoding.

FieldDescription
mihpayidIt is a unique reference number created for each transaction at PayU’s end. You must note this transaction ID as this will be used as a reference for all the future actions on this transaction like Inquiry or Refund.
modeThis parameter describes the payment category by which the transaction was completed or attempted by the customer. For the payment categories, refer to Payment Mode Codes.
statusThis parameter gives the status of the transaction as either success, failed or pending.
Possible values:Β success, failure, pending
If the value of the β€˜status’ parameter is ’success’, the transaction is successful.
If the value of β€˜status’ is β€˜failure’ or β€˜pending’, must be treated as a failed transaction only.
keyThis parameter contains the merchant key for the merchant’s account at PayU. It would be the same as the key used while the transaction request is being posted from the merchant’s end to PayU.
txnidThis parameter would contain the transaction ID value posted by the merchant during the transaction request.
amountThis parameter would contain the original amount which was sent in the transaction request by the merchant.
productinfoThis parameter would contain the same value of product information which was sent in the transaction request from the merchant’s end to PayU.
firstnameThis parameter would contain the same value of first name which was sent in the transaction request from the merchant’s end to PayU.
lastnameThis parameter would contain the same value of last name which was sent in the transaction request from the merchant’s end to PayU.
emailThis parameter would contain the same value of email which was sent.
phoneThis parameter would contain the same value of phone which was sent in the transaction request from the merchant’s end to PayU.
udfThis parameter would contain the same value of udf values that were sent in the transaction request from the merchant’s end to PayU. It ranges from udf1 to udf5.
hashPayU calculates theΒ hashΒ using a string of other parameters and returns it to the merchant. The merchant must verify the hash, and only then mark a transaction as success/failure. This is to make sure that the transaction hasn’t been tampered with.
errorFor the failed transactions, this parameter provides the reason for 
failure.

Note: The reason for failure depends upon theΒ error codesΒ provided by different banks and hence the detailing of error reasons may differ from one transaction to another. The merchant can use this parameter to retrieve the reason for failure for a particular transaction.
bankcodeThis parameter contains the code indicating the payment option used for the transaction. For example, in the Debit Card mode, there are different options like Visa Debit Card, Mastercard, Maestro etc. For each option, a unique bank code exists. It would be returned in this bank code parameter. For example, Visa Debit Card – VISA, Master Debit Card – MAST.
PG_TYPEThis parameter gives information on the payment gateway used for the transaction. For example, if CC PG was used, it would contain the value CC-PG. Similarly, it would have a unique value for all different types of payment gateways.
bank_ref_numFor each successful transaction – this parameter would contain the bank reference number generated by the bank.
unmappedstatusThis parameter contains the status of a transaction as per the internal database of PayU. PayU’s system has several intermediate status which are used for tracking various activities internal to the system. For more information, refer to Payment State Explanations.

πŸ“˜

Notes:

To request OTP on a page, you can utilize the URLs in the response itself. There are two URLs to use:

  • otpPostUrl (Merchant Hosted OTP page)
  • acsTemplate (PayU Hosted OTP page) which acts as a fallback

If you are getting a URL in otpPostUrl, use otpPostUrl, otherwise, you can use acsTemplate, which acts as a fallback. In this scenario, use PayU (or WebView or Checkout) OTP page as this is a fallback case.

Hence, for cases where the above response is not successful, it could either be Failed or Pending. In the Pending state, you can send a fallback URL (as above) which can be shown to the customer.

acsTemplate

acsTemplate is base64 encoded, after decoding we’ll get an HTML like below:

<html> 
   <body> 
      <form name="payment_post" id="payment_post" action="https://test.payu.in/ 
      _payment_options?mihpayid=1983a7cf520b567155ed95ca181e37e3&resendEligibilityRes       =3594c73b18f7ca9e8146f0bb3d0bd8429e5a20c2f61d778bfd0fb4b0d430ebd21a8d8ff20e7775       8c903a71fe22d39d1494127034ed7d505237cb6f7bf80cc3107a02cbd22217c19f6662efac8e8f8       3dca902470a981bdd0a0c03847d546f41ad8f3066b2ccc8a359e03032953f36112d0e551ec19ba7       1954dfe788d18a28ac7609ba53bd77548cffb81882347fc8b97315509afdf8a0894443cf91e0b1f       de84594bee6fc9d39da884f3021eb2224618e2c7f115a02057051987220ec7864ecc44a012417e4      880b187ee1f12363a25a4bec62d8322eb1b185195a714124b5de94309a6dce42ef441464d3462e7 
      809670c" method="post"></form> 
      <script type='text/javascript'> 
         window.onload=function(){ 
             document.forms['payment_post'].submit(); 
         } 
      </script> 
   </body> 
</html> 

On opening the above HTML, you will get a PayU checkout OTP page similar to the following:

From here, the steps are as in PayU Hosted (non-seamless) or Merchant Hosted or Server-to-Server (seamless) transactions.

Handling Failure Response

This is a situation where the _payment API has a complete failure. Hence, you will be getting β€˜failed’ in txnStatus and otpPostUrl is also not received in the result object.

{ 
  "metaData": 
  { 
    "message": "Transaction Failed at bank end.", 
    "referenceId": "ea68a970115a9d87c6ece8d0218e6c2a", 
    "statusCode": "E308", 
    "txnId": "54d2d883f8e4a3fff6ba", 
    "txnStatus": "failed", 
    "unmappedStatus": "failure" 
  }, 
  "result": {} 
} 

Step 4: Submit the OTP

After you have collected the OTP from the customer, the reference ID can be found in the Payment API (_payment) response. Submit the OTP that is entered by the customer is submitted along with the reference ID using the Submit OTP API.