Integration Guide

Credit Card - Merchant Hosted Checkout Integration

Suggest Edits

When your customer wants to opt for the EMI option with credit cards, you can use EMI APIs to check the customer’s eligibility and get the EMI amount, interest, processing fee, or No-Cost EMI and tenure. If the customer is eligible, you can post the transaction with EMI conversion.

📘

Note:

  • You can create EMI offers using the PayU Dashboard and use them for collecting payments as described in this procedure. For more information, refer to Create a No-Cost EMI Offer
  • For Server-to-Server integration, CC-EMI works on txn_s2s_flow=1, 2, or 4, whereas, DC-EMI only works on txn_s2s_flow=1. The same base64Decoder logic will be used to decode the encrypted acsTemplate (in case of txn_s2s_flow=4) and post_data (in case of txn_s2s_flow=1 or 2).

🚧

Test Environment Limitation for Tokens (Saved Cards)

PayU does not support network tokens or issuer tokens in Test Environment, so you cannot try using API Reference for network tokens or issuer tokens.

Step 1: Check the card EMI eligibility

After collecting the customer’s card and the amount to be paid, check the EMI eligibility based on the card BIN from the customer’s credit card number using the eligibleBINsforEMI API. For more information on how to use eligibleBINsforEMI API, refer to Eligible BINs for EMI API

Step 2: Calculate the EMI interest

Use the getEmiAmountAccordingToInterest API to calculate the EMI interest. For more information, refer to Get EMI According to Interest API

Step 3: Initiate the payment

When your customer has an account on your shopping website, they may store their card details to use when they visit/revisit your website. They can use a following options to initiate the payment with EMI:

Environment

Testhttps://test.payu.in/_payment
Productionhttps://secure.payu.in/_payment

Using complete card details

Request parameters

Post the following parameters for cards. For complete list of parameters, refer to Collect Payment API - EMI for the complete list parameters with Try It experience.

ParameterDescriptionExample
key
mandatory		StringMerchant key provided by PayU during onboarding.
txnid
mandatory		StringThe transaction ID is a reference number for a specific order that is generated by the merchant.
amount mandatoryStringThe payment amount for the transaction.
productinfo mandatoryStringA brief description of the product.
firstname mandatoryString The first name of the customer.Ashish
email
mandatory		StringThe email address of the customer.
phone
mandatory		StringThe phone number of the customer.
pg
mandatory		String It defines the payment category that the merchant wants the customer to see by default on the PayU’s payment page. In this integration, "EMI" must be specified.EMI
bankcode mandatoryString Post this parameter to identify payment options with unique bank codes and use getEmiAmountAccordingToInterest API to check for EMI code for corresponding tenure. For the list of EMI codes, refer to EMI Codes .EMI03
ccnum
mandatory		String Use 13-19 digit card number for credit/debit cards (15 digits for AMEX, 13-19 for Maestro) and validate with LUHN algorithm. Refer to Card Number Formats and display error message on invalid input.5123456789012346
ccname mandatoryString This parameter must contain the name on card – as entered by the customer for the transaction.Ashish Kumar
ccvv
mandatory		String Use 3-digit CVV number for credit/debit cards and 4-digit security code (4DBC/CID) for AMEX cards. Validate with BIN API.123
ccexpmon mandatoryString This parameter must contain the card’s expiry month – as entered by the user for the transaction. It must always be in 2 digits or in MM format. For months 1-9, this parameter must be appended with 0 – like 01, 02…09. For months 10-12, this parameter must not be appended – It should be 10,11 and 12 respectively.10
ccexpyr
mandatory		String This parameter must contain the card’s expiry year – as entered by the customer for the transaction. It must be of four digits.2021
threeDS2RequestData
optional		JSON This parameter must contain the following information in JSON format. For more information, refer to Handling 3DS Secure 2.0 Transaction.
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.

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.

Sample request

curl -X POST "https://test.payu.in/_payment" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "key=JP***g&txnid=H6mUfE0ccAY94j&amount=20000.00&firstname=Ashish&[email protected]&phone=9876543210&productinfo=iPhone&pg=EMI&bankcode=EMIA3&surl=https://apiplayground-response.herokuapp.com/&furl=https://apiplayground-response.herokuapp.com/&ccnum=5123456789012346&ccexpmon=05&ccexpyr=2022&ccvv=123&ccname=&hash=782057a8bb0288c858149b4805103befa22041bb3092bc45a813738b43742e31baeae92375be5286a98b44ed66c36121aba0fff6a3170339a4949bc880125d36"

Using network tokens

Applicable scenarios

  • Merchant has the card token, TAVV(Cryptogram), and the last four digits of the card
  • The token could be created by the merchant or through another partner

📘

Note:

This scenario is applicable if you are PCI compliant and got the network token and TAVV from any other aggregator or schemes and then sending the card transaction request in the form of authentication.

Additional request parameters

Along the parameters listed in the Collect Payment API - Merchant Hosted Checkout, include the following additional request parameters in your collect payment request with PayU. Check the response when you try enter the values in API Reference.

ParameterDescriptionValue
ccvv
mandatory		String This parameter must contain the CVV number of the card – as entered by the customer for the transaction. Note: If your customer is returning to your website to shop, you must fetch all the customer's stored cards from PayU, collect the CVV for the card the customer will be using to make payment and then post the CVV number to PayU.
ccexpmon
mandatory		String This parameter must contain the network token expiry month.
ccexpyr
mandatory		StringThis parameter must contain the network token expiry year.
store_card_token mandatoryStringThis must include the Network token generated at your end.1234 4567 2456 3566
storecard_token_type mandatoryStringThis parameter is used to specify the store card token type. For this scenario, you must include 1.1
additional_info mandatoryStringThis parameter will contain the additional information in the following JSON format: {“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”} Where:{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}

Using issuer tokens

This scenario is applicable if you wanted to collect payments using issuer tokens.

Applicable scenarios

  • Merchant has the card token, trMerchantId, tokenReferenceId, and the last four digits of the card
  • The token could be created by the issuer

📘

Note:

This scenario is applicable if you are PCI compliant and got the issuer token, trMerchantId, and tokenReferenceId and then sending the card transaction request in the form of authentication.

Additional request parameters

Along the parameters listed in the Collect Payment API - Merchant Hosted Checkout., include the following additional request parameters in your collect payment request with PayU. Check the response when you try enter the values in API Reference.

ParameterDescriptionValue
ccvv
mandatory		String This parameter must contain the CVV number of the card – as entered by the customer for the transaction. Note: If your customer is returning to your website to shop, you must fetch all the customer’s stored cards from PayU, collect the CVV for the card the customer will be using to make payment and then post the CVV number to PayU.123
ccexpmon mandatoryString This parameter must contain the network token expiry month.10
ccexpyr
mandatory		String This parameter must contain the network token expiry year.2022
store_card_token mandatoryString This must include the issuer token generated at your end.1234 4567 2456 3566
storecard_token_type mandatoryString This parameter is used to specify the store card token type. For this scenario, you must include 2.2
additional_info mandatoryJSON This parameter will contain the additional information in the following JSON format: {“trMerchantId”:”INBANPAYUWIBPAY011″,”tokenReferenceId”:”02ac786d-0081-4b1a-a2a6-b0755a83964c”,”tokenBank”:”HDFC”,”last4Digits”:”8179″} Where: trMerchantId is the Token Requestor Merchant ID. tokenReferenceId (Token Reference ID) is generated specifically for card tokens. tokenBank is the issuing token bank name. For example, “HDFC” can be sent in the request for Diners cards. last4Digits must contain the last four digits of the card.{“trMerchantId”:”INBANPAYUWIBPAY011″,”tokenReferenceId”:”02ac786d-0081-4b1a-a2a6-b0755a83964c”,”tokenBank”:”HDFC”,”last4Digits”:”8179″}

Using card tokenized with PayU

If the merchant has tokenized the card with PayU and needs to process the transaction using PayU token only.

Applicable scenarios

  • Merchant has created the token using PayU as the partner

📘

Note:

This scenario is applicable if any PCI or Non-PCI complied merchant sends the PayU token in a request for fulfilment purposes.

Additional request parameters

Along the parameters listed in the Collect Payment API - Merchant Hosted Checkout. include the following additional request parameters in your collect payment request with PayU. Check the response when you try enter the values in API Reference.

ParameterDescriptionExample
ccvv
mandatory		String This parameter must contain the CVV number of the card – as entered by the customer for the transaction. Note: If your customer is returning to your website to shop, you must fetch all the customer’s stored cards from PayU, collect the CVV for the card the customer will use to make payment, and then post the CVV number to PayU.123
storecard_token_typeStringThis parameter is used to specify the store card token type. For this scenario, you must include 0.0
user_credentials mandatoryString This parameter must contain the user credentials.a:b
store_card_tokenString This must include the token generated by PayU for the card.1234 4567 2456 3566

Using card on a decoupled flow with network token or other partner tokenization

Applicable scenario

This scenario is applicable where you are on a decoupled flow. This is where you are using the PayU for either authentication or authorization only while using tokens created by the network or some other partner.

Decoupled flow: You are sending the authentication request to PayU and if the merchant wishes to send the authorization request eventually or to other aggregators.

Additional request parameters

Along the parameters listed in the Collect Payment API - Merchant Hosted Checkout, include the following additional request parameters in your collect payment request with PayU. Check the response when you try enter the values in API Reference.

ParameterDescriptionValue
store_card_token mandatoryString This must include the network token available with the merchant.1234 4567 2456 3566
storecard_token_type mandatoryInteger This parameter is used to specify any of the following store card token type, that is, tokenization partner. 0 – PayU token 1 – Network token 2 – Issuer token *
*Note: For this scenario, you must include 1**.		1
additional_info mandatoryJSON This parameter will contain the additional information in the following JSON format that PayU would fetch TAVV/Cryptogram internally. { “last4Digits”: “1234”, “tavv”: “ABCDEFGH”} Where: trid (Token Requestor ID) is the identity given by the networks for creating the tokens. You should be able to get the same from your token provider. tokenRefNo (Token Reference Number) is generated along with the network token. . You should be able to get the same from your token provider. TAVV is a 20-byte Base64-encoded binary value that is used with tokens.
Notes: The last 4 digits of cards is mandatory for all transactions. Some payment gateways require the Token Requester ID (trid) and Token Reference Number (tokenRefNo) to be passed for processing the transaction. Not passing these values will restrict the number of payment gateways available for processing the transaction. Token Requester ID (trid) and Token Reference Number (tokenRefNo) are mandatory for Diners token transactions.		{ “last4Digits”: “1234”, “tavv”: “ABCDEFGH” }

Using card on a decoupled flow with PayU tokenization

Applicable scenario

This scenario is the application on a decoupled flow using the PayU for either authentication or authorization only with tokens created in partnership with PayU.

Direct Authorisation Flow: When you have done the authentication from some other aggregator and authorization request is coming to PayU.

Additional Request Parameters

Along the parameters listed in the Collect Payment API - Merchant Hosted Checkout, include the following additional request parameters in your collect payment request with PayU. Check the response when you try enter the values in API Reference.

ParameterDescriptionValue
ccvv
mandatory		varchar This parameter must contain the CVV number of the card – as entered by the customer for the transaction.
Note: If your customer is returning to your website to shop, you must fetch all the customer’s stored cards from PayU, collect the CVV for the card the customer will be using to make payment and then post the CVV number to PayU.		123
store_card_token mandatoryvarchar This must include the token generated by PayU for the card.1234 4567 2456 3566
storecard_token_type mandatoryinteger This parameter is used to specify any of the following store card token type, that is, tokenization partner. 0 – PayU token 1 – Network token 2 – Issuer token
Note: For this scenario, you must include 0.		0
additional_info mandatoryJSON This parameter will contain the additional information in the following JSON format that PayU would fetch TAVV/Cryptogram internally. {“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”} Where: trid (Token Requestor ID) is the identity given by the networks for creating the tokens. You should be able to get the same from your token provider. tokenRefNo (Token Reference Number) is generated along with the network token. . You should be able to get the same from your token provider. TAVV is a 20-byte Base64-encoded binary value that is used with tokens.
Notes: The last 4 digits of cards is mandatory for all transactions. Some payment gateways require the Token Requester ID (trid) and Token Reference Number (tokenRefNo) to be passed for processing the transaction. Not passing these values will restrict the number of payment gateways available for processing the transaction. Token Requester ID (trid) and Token Reference Number (tokenRefNo) are mandatory for Diners token transactions.		{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}

Step 4: Check the PayU response

Hash validation logic for payment response (Reverse Hashing)

While sending the response, PayU takes the exact same parameters that were sent in the request (in reverse order) to calculate the hash and returns it to you. You must verify the hash and then mark a transaction as a success or failure. This is to make sure the transaction has not tampered within the response.

The order of the parameters is similar to the following code block:

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

Sample response

You need to look for the following parameters in the response:

  • PG_TYPE
  • bankcode

The formatted sample response from PayU is similar to the following:

Array
(
    [mihpayid] => 403993715523602563
    [status] => success
    [unmappedstatus] => captured
    [key] => JP***g
    [txnid] => v2tWbbdUOuacK9
    [amount] => 20000.00
    [discount] => 0.00
    [net_amount_debit] => 20000.00
    [addedon] => 2021-07-27 11:14:44
    [productinfo] => iPhone
    [firstname] => Ashish
    [lastname] => 
    [address1] => 
    [address2] => 
    [city] => 
    [state] => 
    [country] => 
    [zipcode] => 
    [email] => [email protected]
    [phone] => 1234567890
    [udf1] => 
    [udf2] => 
    [udf3] => 
    [udf4] => 
    [udf5] => 
    [udf6] => 
    [udf7] => 
    [udf8] => 
    [udf9] => 
    [udf10] => 
    [hash] => 10f8ead10cdf5f9b7bf9046987de046d63d62d6679dded9d5da8145f459066943570eec4aa184494ae77f99a8bcd55452af3c4eff0d7a7d3ba809c97b7c73045
    [field1] => 
    [field2] => 
    [field3] => 
    [field4] => 
    [field5] => 
    [field6] => 
    [field7] =>
    [field8] => 
    [field9] => Transaction Completed Successfully
    [payment_source] => payu
    [PG_TYPE] => EMI-PG
    [bank_ref_num] => 3d7cc4a4-00c8-4705-a0e7-5708d2c2bb75
    [bankcode]=> EMIA3
    [error] => E000
    [error_Message] => No Error
    [name_on_card] => payu
    [cardnum] =>512345XXXXXX2346
)

Updated about 2 months ago