Android Arsenal: October 2015

Hello Friends,

Today I am going to share about how you can integrate PayUMoney in your application to make flexible transactions.

Introduction:

PayU is the Online Payment Gateway to accept Payments Online. PayU is India's most comprehensive payment gateway with credit cards, debit cards and net banking.Go live with all payment options fastest in India.

PayU Group is owned by Naspers MIH that provides services base on different media and communication technologies all over the world. PayU is a comprehensive operator of online payments. The highest level of provided services is guaranteed by innovative technological platforms,high functionality,stable development as well as a wide and constantly extended offer.

The aim of PayU is to integrate existing online payment services and develop new ones as well as provide tools to facilitate e-commerce activity in the web. PayU supports mostly all the frameworks available like HTML,PHP,ASP,ASP.NET,VB.NET,JAVA,Ruby on Rails,Perl,Paython. PayU avails you the readymade kits for mentioned frameworks and renowned shopping carts to make the integration easy.

A wide range of credit card,debit card,internet and mobile banking options.
Secure and flexible payments to existing bank accounts of merchants.
Faster settlements and instant reports on dropped transactions.
Verified By Visa & Master Card Secure Code enabled gateway.
Ability to offer services on the Web,Mobile & IVR.

PayU Payment Gateway

PayU offers electronic payment services to merchant website through its partnerships with various banks and payment instrument companies. Through PayU, the customers would be able to make electronic payments through a variety of modes which are mentioned below:

Credit cards
Debit cards
Online net banking accounts
EMI payments
Cash Cards
Email Invoicing
IVR
Cash on Delivery (COD)

PayU also offers an online interface (known as PayU Dashboard) using the username and password provided to you, where the merchant has access to various features like viewing all the transaction details, settlement reports, analytical reports etc.Through this interface, the merchant can also execute actions like capturing, cancelling and refunding the transactions.

Payment Process Flow

The following diagram explains how the customer makes the payment and how the process flows:

Step 1: The consumer selects the product on your website and clicks on “Pay Now” button.
Step 2: The consumer is then taken from your website to the transaction page of www.payumoney.com where in all the payment related details are entered by the consumer.
Step 3: Payumoney.com.com redirects the consumer to Visa, MasterCard or the relevant bank for the next level of authorization.
Step 4: The Bank/Visa/MasterCard authorizes and confirms the transaction.
Step 5: The consumer is sent back to PayUMoney.
Step 6: PayUMoney sends the consumer back to your website along with the transaction status.

Status of a Transaction

A transaction can have several different statuses as explained below.

Not Started – The transaction has not been started yet.
Initiated – The transaction has been started but not completed.
Money With PayUMoney– The transaction was successful and the transaction amount is with PayUMoney.
Under Dispute – A dispute for the transaction has been raised.
Refunded – The entire amount of the transaction has been refunded.
Partially Refunded – A part of the amount of the transaction has been refunded.
Bounced – Incomplete or no details provided at PayUMoney payment page.
Failed – The transaction didn’t complete due to a failure.
Settlement in Process – Settlement for the transaction is in process.
Completed – The transaction is settled and complete.

PayUMoney Integration Methods:

The merchant can integrate with PayU by using one of the below methods:

1) Non-Seamless Integration – In this mode during the transaction, the customer would be re-directed from merchant website to PayU payment page. On the PayU payment page, he would need to select the payment option and enter the respective card details. After this, PayU would re-direct the customer to the desired bank webpage for further authentication.

2) Seamless Integration - In this mode, the merchant needs to collect the customer card details on their own website and post them to PayU. Here, the customer would not be stopped at PayU payment page at all, as the payment option and card details are already received from the merchant. The merchant must be PCI-DSS certified in this case. For further information on PCI-DSS certification please contact your Account Manager at PayU.

Also, the merchant website can be based either on a shopping cart or can be developed by the

merchant (not based upon any shopping cart). Based on the type (out of these two), PayU would

provide integration kit (code) to the merchant which they needs to incorporate at their end.

Steps for Integration Process

The steps for integrating with PayU can technically be described as below:

1) To start off the integration process, you would be provided a test setup by PayU where you would be given a test merchant account and test credit card credentials to have a first-hand experience of the overall transaction flow. Here, you need to make the transaction request on our test server (and not the production server). Once your testing is complete, then only you will be ready to move to the PayU production server.

2) To initiate a transaction, the merchant needs to generate a POST REQUEST - which must consist of mandatory and optional parameters. This POST REQUEST needs to be hit on the below mentioned PayU URLs:

For PayU Production (LIVE) Server:

POST URL: https://secure.payu.in/_payment

For PayU Test Server:

POST URL: https://test.payu.in/_payment

Test Key – JBZaLc
Test Salt – GQs7yium
Test Card Name: any name
Test Card Number: 5123456789012346
Test CVV: 123
Test Expiry: May 2017

In order to integrate your website with PayUMoney, you can use our test server and test key if your

application is not yet approved.

Please note that the Key and Salt for test server are different and should be used only with test server.The purpose of the test server & Key-Salt is to enable you to integrate and do test transaction. It cannot be used for actual transactions from your website.

Key notes and terms

Key (MerchantID) : This ID is generated at the time of activation of your site and helps to uniquely identify you to PayUMoney.
TxnID: A Unique alphanumeric Transaction ID generated by you to uniquely identify a transaction. The TxnID should be unique since it would allow you to identify the transaction easily.
Amount: Amount is the total amount of the transaction (greater than 0) in INR, without a currency symbol or other non-numeric character. Only a decimal allowed.
MIHPayID: Unique ID generated for a transaction by PayU.in.
Hash (Checksum): This refers to a random numeric string generated using a mathematical algorithm to ensure that data is not tampered along the way. Let’s say a message has to be sent from location X to Y. X and Y both mutually agree on a Secret Key called “Salt” that only both of them possess. A checksum is generated by a mathematical function using the message and the Salt as input. This checksum is then sent along with the message to Y. Y then recalculates this checksum using the Salt and the same algorithm. If the checksum that Y calculates is different from the checksum that X passed then the data was tampered along the way and is thus rejected.

The Checksum algorithm used is SHA2 which is globally well known algorithm. To need help with implementation, feel free to call us, mail us or use Google to find the desired function library for your implementation. Some example codes are also mentioned at the end of this document.

Product Info: It is a json encoded array of various payment parts where each part contains ‘name’,‘description’, ‘value’ and ‘isRequired’ fields. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.

It is based on a subset of the JavaScript Programming Language. JSON is a text format that is completely language independent.

The format of the json encoding for productinfo is as follows:-

 Productinfo={  
  “paymentParts”: [  
   {  
    "name": "abc",  
    "description": "abcd",  
    "value": "500",  
    "isRequired": "true",  
    “settlementEvent”: “EmailConfirmation”  
   },  
   {  
    "name": "xyz",  
    "description": "wxyz",  
    "value": "1500",  
    "isRequired": "false",  
    “settlementEvent”: “EmailConfirmation”  
   }  
  ],  
  {  
   “paymentIdentifiers”: [  
    {  
     "field": "CompletionDate",  
     "value": "31/10/2012” },   
 { "field":"TxnId", "value":"abced" }]}

3) In the merchant initiated POST REQUEST, one of the mandatory parameters is named as

hash. The details of this hash parameter have been covered in the later section. But it is absolutely critical for the merchant to calculate the hash correctly and post to us in the request.

4) When the transaction POST REQUEST hits the PayU server, a new transaction entry is

created in the PayU Database. To identify each new transaction in the PayU Database, a unique identifier is created every time at PayU’s end. This identifier is known as the PayU ID (or MihPayID).

5) With the POST REQUEST, customer would be re-directed to PayU’s payment page. Customer now selects the particular payment option on PayU’s page (Credit Card/Debit Card/Net Banking etc) and clicks on ‘Pay Now’. PayU re-directs the customer to the chosen bank. The customer goes through the necessary authorization/authentication process at bank’s login page, and the bank gives the success/failure response back to PayU.

6) PayU marks the transaction status on the basis of response received from Bank. PayU provides the final transaction response string to the merchant through a POST RESPONSE. The parameters in this response are covered in the subsequent sections.

7) In the POST RESPONSE sent by PayU, you would receive the final status of the transaction. You will receive the hash parameter here also. Similar to step 3, it is absolutely crucial to verify this hash value at your end and then only accept/reject the invoice order. This is done to strictly avoid any tampering attempt by the user.

DISCLAIMER:

1. Test URL: The Test URL is provided to PayU merchants to test the integration of their server with that of PayU or Bank. It is understood that since this is merely a Test URL, the Merchant should not treat any transactions done on this Test server as live and should not deliver the products/services with respect to any such test transactions even in the case your server receive a successful transaction confirmation from PayU/Bank.

2. Merchants are herein forth requested to set up required control checks on their (merchant)

systems/servers to ensure that only those transactions should get routed to the PayU test server

which are initiated with sole intention of test the environment.

Additional Charges – Convenience Fee Model (To be used only if recommended by Account Manager at PayU)

There are 2 different methods to implement Additional Charges on PayU.

Method 1: Enabled from backend at PayU

The merchant would be posting the transaction amount of the product in the transaction request.

1) Once the customer lands on PayU payment page and clicks on 'Pay Now' option, the additional amount would be added to the amount of the product by PayU (based upon the TDR values) and the total amount would be passed on to the bank’s page while re-directing.

2) After PayU receives the status of transaction from the bank, it sends the response of back to

the merchant. In this response, the amount and additional amount can be differentiated with the below parameters.

Original Transaction Amount - amount
Additional Amount - additionalCharges

3) Once you receive the response from PayU, you need to check for reverse hash. If you are verifying the reverse hash at your end (which is strictly recommended to avoid any tamper cases), its formula will also change in case additionalCharges value is sent.

Here, if the additionalCharges parameter is posted in the transaction response, then hash formula is:

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

4) If additionalCharges parameter is not posted in the transaction response, then hash formula

is the generic reverse hash formula:

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

Method 2: Merchant Calculates and Posts Additional Charges to PayU

1) The merchant would be posting both the transaction amount and additional charges in the transaction request. The parameters used for these are amount and additional_charges respectively.

The way to pass the additional_charges parameter is as below:

<bankcode1> :< additional charge value>, < bankcode2> :< additional charge value>

Example: CC:12,AMEX:19,SBIB:98,DINR:2,DC:25,NB:55

2) In this method of applying additional charges, hash sequence would be affected for both Pre-Transaction and Post-Transaction.

Pre-Transaction hash sequence:

Merchant needs to form the below hash sequence before posting the transaction to PayU:

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

Where additional_charges value would be same as the value posted in transaction request.

For example, CC:12,AMEX:19,SBIB:98,DINR:2,DC:25,NB:55

3) Now, once the transaction request hits PayU server and re-direction happens, the customer lands upon PayU payment page. Here, depending on the payment option selection by the customer, the additional charge value would be added to transaction amount. For example, for the above example, if the customer selects Credit Card, Rs 12 would be added to the transaction amount. If the customer selects AMEX option, Rs 19 would be added to the transaction amount. For SBI Net Banking, Rs 98 would be added to the transaction amount and so on. Please note that the additional charges would be added only once the customer clicks on ‘Pay Now’ option.

4) When PayU receives the response from Bank, a POST Response is sent to the merchant.

Here also, the hash sequence needs to be changed.

Post-Transaction hash sequence:

Merchant needs to form the below hash sequence and verify it with the hash sent by PayU

in the Post Response:

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

Where, additionalCharges value must be same as the value Posted from PayU to the

merchant in the response.

5) This hash value must be compared with the hash value posted by PayU to the merchant. If both match, then only the order should be processed. If they don’t match, then the transaction has been tampered with by the user and hence should not be processed further.

Important Things to remember: Characters allowed for parameters

For parameters address1, address2, city, state, country, product info, email, and phone following characters are allowed:
Characters: A to Z, a to z, 0 to 9

-(Minus)
_ (Underscore)
@ (At the Rate)
/ (Slash)
(Space)
. (Dot)

If the merchant sends any other special characters then they will be automatically removed. The address parameter will consider only first 100 characters.

Formula for hash (checksum) after transaction

This time the variables are in reverse order and status variable is added between salt and udf1.

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

It is absolutely mandatory that the hash (or checksum) is computed again after you receive

response from PayU and compare it with post back parameters below. This will protect you from any tampering by the user and help in ensuring safe and secure transaction experience.

Reference:

For more details here i am sharing the integration documents and sdk download links.

1. APIs -Integration Document Version 2.5.pdf

2. Android SDK -

Integration Steps - Integration Document PayU Android SDK v3.0.pdf

Android SDK (Custom browser included) Android-SDK

Android Sample App (see branches) Android-SDK-Sample-App

3.Android Custom Browser -

Integration Steps - Integration Document PayU Android Custom Browser.pdf

Android Custom Browser Download - Android-Custom-Browser

Android Custom Browser Sample App Download - CBWithoutSDK