Bolt Checkout

The PayUmoney BOLT Checkout gives your customers a simplified checkout experience that keeps them in the context of your website throughout the payment process and enables them to use their Net Banking account, UPI Account or Credit/Debit Card to pay without sharing or entering any sensitive information on your site.

The payment page opens as a pop-up (aka modal) on your website which is a completely redirection less payment experience. The modal is served from PayU servers which ensures that you need not get into the complications of a PCI-DSS compliance, all the while providing a world-class payment experience as shown in the image below.

Note: BOLT Checkout is a superior payment experience to PayUmoney Redirect checkout.Features like Advanced caching, zero redirections and customer’s ability to retry payment without generating a fresh payment request makes BOLT Checkout the best payment experience any merchant can offer to the customers.

Why Bolt?

Lower failure rates using retry feature

Our internal metrics show that around 15% transactions are failing at bank or 3D secure page. In such cases usually, the consumers have to restart the entire checkout process. But with BOLT, the consumer remains in the payment context always. In the event, if any system, network or user error occurs, the consumer is given a chance to retry seamlessly by landing back on BOLT’s payment form without compromising current order. Thus consumers are empowered to start from where they left without reinitiating the transaction process all over again.

Boost Success rates and checkout speed using Nitro Flow

In Nitro flow, we remove for your customer the pain of remembering and entering the login credentials, every time they try to pay online and thus quickly access their saved cards with PayUmoney. Using Nitro, our merchants have seen 6-7% increase in success rates. Read more about Nitro Flow here.

Intuitive, Responsive design

BOLT is built with highly optimized & responsive design approach. It automatically adjusts checkout page for any device be it smartphones, tablets, desktop or laptops. This gives your consumer a seamless payment experience irrespective of the device or browser he uses. Besides all our experience and data in Payments domain has been put into practice in this constantly improving checkout experience.

Beat the OCD using Advanced Caching

Yes, we all tend to double check (sometimes even triple check) the details before making the final payment be it your address details or the color or the size of the product you buy. But what if we allow a convenient way to cater to this infamous obtrusive compulsive disorder that hampers success rates? With advanced caching, we cache the payment details entered by the user for a transaction temporarily, thereby ensuring he doesn’t have to re-enter details even if he closes the BOLT checkout and re-initiates the payment.

Simple Onetime Integration

Nothing better than a few lines of coding solving a complex problem. You can have the best in payments powered by PayUMoney that works smoothly across all platforms. You’ll need to just add a few lines of mostly JavaScript code and we’ll take care of the other complexities of the payments ecosystem. To add to it, this is just a one-time effort and all the future enhancements and fixes will be done at our end.

Features Supported

The following features are supported in the PayUmoney BOLT Checkout.

Payment Modes Supported

The PayUmoney Redirect Checkout supports the following Payment Modes.

Steps to Integrate

1

Prerequisites

Meet the Prerequisites

2
Include Meta Tag & Scripts

Include the HTML meta tag & JS libraries as given in the doc

3
Launch Payment Overlay

Call the launch() function after passing transaction parameters

4
Compute Request Hash

Calculate the request hash on the server and pass it to the launch() function.

6
Compute Response Hash

Verify response hash on the server side

5
Handle Payment Response

Handle the callback response given to the client side handler

Getting Started

This section describes the how to do the technical integration of PayUmoney Payment Gateway on your website for collecting payment online using BOLT Checkout. This Checkout handles collecting, saving, and reusing your user’s payment details, also can be used to collect billing info.

The BOLT Checkout provides your users with a redirection-less, streamlined, mobile-ready payment experience that is constantly improving. If you need any help after reading this, check out the FAQs section.

This integration requires basic JavaScript skills and intermediate level knowledge in your favorite server-side programming language.

The payment request is essentially calling a JavaScript function passing a data object prefilled with transaction details as its first input argument. If all the parameters are correctly passed an overlay is launched on top of your website where your customer can fill in his card or other payment details. Once the customer completes the payment on PayU’s overlay or if he cancels the payment in-between, a call back is provided to the response handler function which is passed as the second argument to the launch function. All of these steps are discussed in detail in the following sections.

Prerequisites

To Integrate PayUmoney Bolt Checkout, you must :

  • Signup with PayUmoney as the merchant
  • Get the Key and Salt, which are available on your merchant dashboard

Steps to Integrate

1

Prerequisites

Meet the Prerequisites

2

Include Meta Tag & Scripts

Include the html meta tag and JS libraries as given in doc

3
Launch Payment Overlay

CreateCall the launch() function after passing transaction parameters.

4
Compute Request Hash

Calculate the request hash on the server and pass it to launch() function.

6
Compute Response Hash

Verify the response hash on the server side.

5
Handle Payment Response

Handle the callback response given to the response handler

Client Side Changes

Integration of Bolt Checkout into your website is really simple. You need to follow the three steps as mentioned below:

  • Include BOLT JavaScript libraries as provided by PayU on your checkout page ( Payment request page).
  • Create a JavaScript request object with PayUmoney transaction request parameters.
  • Call the launch function with two arguments as describe below to trigger the BOLT checkout and handle payment response.

Include MetaTag and Scripts

The following meta tag should be added to the payment request page within the <head> tags. This makes the BOLT checkout responsive and makes it work on all mobile devices.

<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" >

The following JavaScript libraries are to be included using Script tag with id=”bolt” in the HTML header of the checkout page.

<script id="bolt" src="https://sboxcheckout-static.citruspay.com/bolt/run/bolt.min.js" bolt-
color="<color-code>" bolt-logo="<image path>"></script>

Once your integration is done and tested on the sandbox, replace the sandbox JavaScript library with the production library provided by PayU.

<script id="bolt" src="https://checkout-static.citruspay.com/bolt/run/bolt.min.js" bolt-color="<color-
code>" bolt-logo="<image path>"></script>

Launch Payment Overlay

As mentioned in the sections above, with Bolt checkout the user enters payment details like credit card number or choose payment mode like net banking in an overlay/popup served by PayU. To launch the payment overlay, you need to call the launch function as mentioned below.

The bolt.launch() function accepts two arguments.

  • The First argument object, also called as data object contains the transaction request data. The format of the data object is as shown below. The details of the parameters to be passed as data object are detailed in transaction request parameters section.
 var RequestData = {
      key: 'rjQUPktU',
      txnid: '123456789'
      hash: 'defdfaadgerhetiwerer',
      amount: '1',
      firstname: 'Jaysinh',
      email: 'dummyemail@dummy.com',
      phone: '6111111111',
      productinfo: 'Bag',
      surl : 'https://sucess-url.in',
      furl: 'https://fail-url.in',
      mode:'dropout'// non-mandatory for Customized Response Handling
  }
  • The second argument object, also called as Handler which contains two functions. 
    • One is a ResponseHandler function which will receive a response callback from PayUMoney after the transaction is complete or if any action is taken by the user to close the overlay. 
    • Second is a CatchException function which will receive any errors that have occurred during execution. 
var Handler = {

      responseHandler: function(BOLT){

        // your payment response Code goes here, BOLT is the response object

      },
      catchException: function(BOLT){

        // the code you use to handle the integration errors goes here

      }
  }
  • With above mentioned objects need to call bolt.launch function to initiate payment with BOLT .
  bolt.launch( data , handler ); 

The details of data object properties to be passed which form the transaction request are explained in the table below:

TRANSACTION REQUEST PARAMETERS

S.No. Parameter Name Mandatory Description
1. key Yes Merchant Key provided by PayUmoney. This is available on the dashboard.
2. txnid Yes A Unique alphanumeric Transaction ID generated by you to uniquely identify a transaction.  String value.  Limit 30 characters
3. amount Yes Transaction amount (Type cast the amount to float)
4. productinfo Yes Product Description. Pass your product information as text here if you are not an aggregator. If you are an aggregator, a JSON value needs to be passed here as explained in aggregator section.
5. firstname Yes First Name of the payer. Allowed characters: (only alphabets a-z are allowed)
6. email Yes Email Id of the payer.
7. phone Yes mobile number or landline number of the payer (numeric value only)
8. surl Yes Success URL where PayUmoney will redirect after successful payment.
9. furl Yes Failure URL where PayUmoney will redirect after failed payment.
10. hash Yes This is an encrypted value generated to protect against data tampering during transaction. Refer Server Side changes section for more details.
11. lastname No Last Name of the payer. Allowed characters: (only alphabets a-z are allowed)
12. address1 No Address of the payer. Allowed characters: (Length of address1 and address2 must not more than 100 characters each and the allowed characters are only) A TO Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot).
13. address2 No Address of the payer. Allowed characters: (Length of address1 and address2 must not more than 100 characters each and the allowed characters are only) A TO Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)
14. city No City of the payer. Allowed characters: (Length of address1 and address2 must not more than 100 characters each and the allowed characters are only) A TO Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)
15. state No Address State of the payer. Allowed characters: (Length of address1 and address2 must not more than 100 characters each and the allowed characters are only) A TO Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)
16. country No Country of the payer. Allowed characters: (Length of address1 and address2 must not more than 100 characters each and the allowed characters are only) A TO Z, a to z, 0 to 9, @, – (Minus), _ (Underscore), / (Backslash), (Space), (Dot)
17. zipcode No Zipcode of the payer. Numeric value only
18. udf1 No User defined field 1
19. udf2 No User defined field 2
20. udf3 No User defined field 3
21. udf4 No User defined field 4
22. udf5 No User defined field 5

The details of how to manage ResponseHandlerCatchException callback functions are mentioned in the Handle Payment Response section.

Handle the Payment Response

Making a payment using PayUmoney Bolt gives two types of payment response:

  • A client-side response on the response handler function or on the SURL/FURL sent by merchant in payment request.
  • A server to server callback on the Webhook, if set from the PayUmoney dashboard.

Before transaction response is displayed to the user, please verify the authenticity of the transaction by generating a response hash. The hash generated by you should match the one sent by PayUmoney Bolt in response.

Note:
 It is mandatory for the merchant to generate the response hash and check if it matches with the hash sent in the response by PayUmoney or your integration will be susceptible to the man in the middle attacks.

There are two ways of response handling.
 

  • Default Response Handling  

If the merchant sends mode in data object as “dropout”, on receiving a success/failure response, response is posted on the SURL/FURL/Webhook url. 

If you send mode param as ‘dropout’ in data object, you do not have to implement your own logic in response handler function. 

If you do not send mode param as ‘dropout’  in the data object, you will able to customize the payment response handling. Please see below section. 
 

  • Customized Response Handling

 If the mode param is not sent in data object, In the response handler function, you will receive the response as an object. You can write your own logic to redirect to return URL, update DB or show payment success screen on the same page.  

In the response handler function below, you can write the logic to redirect to return URL, update DB or show payment success screen on the same page.

BOLT Response handler code sample

  responseHandler: function(BOLT){

      console.log( BOLT.response.txnStatus );

      //  this is for capturing the status of the transaction

  }

  catchException: function(BOLT){

      alert( BOLT.message );

      // "amount: should be numeric"
      // "txnid: mandatory param is missing"
      // "Error in adding payment"

  }

Payment Success Response

For success case, below mentioned response will be returned in the response handler. In this case, the merchant has to write the corresponding logic in the responseHandler function. BOLT.response consists of the below response.

BOLT.response format for status “SUCCESS” :

{
"txnStatus":"SUCCESS",
"txnMessage": "",
"postBackParamId": "'',
"mihpayid": "",
"paymentId": '',
"status": "success",
"unmappedstatus": "",
"key": "",
"txnid": "",
"amount": "",
"addedon": "",
"createdOn": "",
"productinfo": "",
"firstname": "",
"email": "",
"phone": "",
"hash": "",
"field9": "",
"PG_TYPE": "",
"bank_ref_num": "",
"bankcode": "",
"error": "",
"error_Message": "",
"postUrl": "",
"calledStatus": false,
"additional_param": "",
"amount_split": "",
"paisa_mecode": "",
"meCode": "",
"payuMoneyId": ""
}

Once the hash is verified, this response has to be used to take relevant action. For eg. redirecting to the success page, update DB etc.

Failed Response

For failed case, below mentioned response will be returned in the response handler. In this case, the merchant has to create a new payment request with a new merchant transaction ID when the Pay Now button is clicked again.

BOLT.response format for status “FAILED”:

{
"txnStatus":"FAILED",
"txnMessage": "",
"postBackParamId": '',
"mihpayid": '',
"paymentId": '',
"status": "failure",
"unmappedstatus": "",
"key": "",
"txnid": "",
"amount": "",
"addedon": "",
"createdOn": "",
"productinfo": "",
"firstname": "",
"email": "",
"phone": "",
"hash": "",
"field9": "",
"PG_TYPE": "",
"bank_ref_num": "",
"bankcode": "",
"error": "",
"error_Message": "",
"postUrl": "",
"calledStatus": false,
"additional_param": "",
"amount_split": "",
"paisa_mecode": "",
"meCode": "",
"payuMoneyId": ""
}

Once the hash is verified, this response has to be used to take relevant action. For eg. redirecting to the success page, update DB etc.

Cancelled Response

If the overlay is closed by the consumer, the below payment response will be returned to the response handler. In this case, the merchant has to land the user back on the payment page. The next time he has to send the same payment request again (with the same transaction Id, amount etc) to take advantage of advanced caching feature.

BOLT.response format for status “CANCEL”

{
"txnStatus":"CANCEL",
"txnMessage":"Overlay closed by consumer"
}

The list of the response parameters sent by Bolt to response handler function and Webhook are shown in the table below:

TRANSACTION RESPONSE PARAMETERS

S.No. Parameter Name Description Sample Value
1. txnStatus Transaction Status from Bolt SUCCESS
2. txnMessage Transaction on related message Overlay closed by consumer
3. status PayUmoney Transaction Status. success
4. firstname Firstname of the payer Tom
5. amount Transaction Amount 1.0
6. txnid Transaction Id passed by the merchant 0nf725
7. hash Security hash generated in response to protect against data tampering.Merchant is required to generate a response hash and verify it against this hash. 127e2c44016aa4c3dd5bacc09b0239b09c6174f275c 0ec4c8ec7da3db915a754407849cf2537f8655255ac 54ee652c4ef972c721462ec9d0a67c08b66bdbb6ba;
8. productinfo Book1
9. phone Mobile No of the payer 7406740707
10. email Email Id of the payer abc@payu.in
11. payuMoneyId The payUmoney transaction id. 58876806
12. mode Payment Mode in:

  • Netbanking (NB)
  • Debit Card(DC)
  • Credit Card(CC)

etc.

NB
13. addedon The Timestamp when a transaction is done. 2017-04-26 15:22:05
14. createdOn Epoch time(Unix time) when transaction is done. 1493200111000
15. field9 string
16. PG_TYPE The payment gateway used to process the payment. HDFCPG
17. bank_ref_num string 1182885976
18. bankcode The payumoney code number of issuing bank involved in the transaction. MAST
19. error The error code associated with the transaction. E000
20. error_Message The error code associated with the transaction. No Error
21. postUrl The actual URL where response is posted in SURL/FURL https://test.payumoney.com/customer/dashboard/#/payment/notification/ success
22. calledStatus false
23. additional_param
24. amount_split The transaction amount split between wallet & other payment mode in a payumoney transaction. {“PAYU”:”106.1″}
25. paisa_mecode string ; Internal Codes
26. meCode String ; Internal Codes
27. key The merchant key available from Payumoney dashboard 40747T
28. unmappedstatus PayU parameter for internal use. captured
29. postBackParamId Internal processing identifier. 39803778
30. mihpayid Internal processing identifier. 70000000688113
31. paymentId The PayU generated Payment Id 58876806

Server Side Changes

The only server-side change required while integrating PayUmoney checkouts is to generate a hash parameter for both the payment request & response.

A hash is an encrypted value (checksum) that is to be sent by the merchant in a payment request and sent by PayU in the payment response. The hash is used to protect transactions against “man in the middle attack”.

PayUmoney uses the SHA-512 hash function which belongs to SHA-2 family of cryptographic functions. We have sample codes for generating the hash on major programming languages in this guide, however, if your preferred language is not in the list, a search on Google should definitely get you what you need.

The method of generating a request & response hash are exactly the same. Only the pattern and parameters to be encrypted differ.

Hash for Payment Request

#Sequence
hashSequence =
key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||salt;
$hash = hash("sha512", $hashSequence);
#Where salt is available on the PayUMoney dashboard.
Note:
 A blank udf field is to be used while computing hashSequence, even if a merchant is not passing any udf field in input request.

Hash for Normal Payment Response

For the response hash, the sequence of variables is in reverse order as compared to payment request hash. Also, a status variable added between salt and udf1

#Sequence
hashSequence = salt|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key;
$hash = hash("sha512", $hashSequence);
#Where salt is available on the PayUMoney dashboard.

Hash for Payment Response with Convenience Fee/Surcharge

For some of the merchants (mostly government entities), the transaction processing charges are paid by the consumer during payment. PayUmoney adds the payment extra processing charges to the transaction amount on the checkout page based on rules previously set based on the contract. In such cases/ for such merchants, an additional param by the name ‘additionalCharges’ is returned by PayUmoney in the transaction response. This parameter should also be used while computing response hash for transactions where customer incurred additional charges as shown below.

#Sequence
hashSequence = additionalCharges|salt|status||||||udf5|udf4|udf3|udf2|udf1|
email|firstname|productinfo|amount|txnid|key; 
$hash = hash("sha512", $hashSequence);
#Where salt is available on the PayUMoney dashboard.

Integration Kits Available

Sample Bolt integration kits for the following technologies are available with PayUmoney. But you can integrate Bolt in any server side language.