API Reference

Cards Consent Transaction

This section provides the request parameters, sample request and response for a Cards Recurring Payment Consent transaction.

📘

Note:

During integration with PayU, first integrate with the Test Server environment. PayU will provide you the necessary Merchant Key for the test serve. After testing is done, you are ready to move to the Production server.

HTTP Method: POST

Environment

Test Environmenthttps://test.payu.in/_payment
Production Environmenthttps://secure.payu.in/_payment

Content Type: application/x-www-form-urlencoded

Request parameters

ParameterDescriptionValue
key
mandatory		String The merchant key is a unique identifier for a merchant account in PayU's database. For more information, Check your API Key and Salt.Your Test Key
api_version
optional		ng` The API version for this API.7
txnid
mandatory		String The transaction ID is a reference number for a specific order that is generated by the merchant. It is used to track the order and must be unique. PayU's system will not accept duplicate transaction IDs.s7hhDQVWvbhBdN
amount
mandatory		String This field should contain the payment amount for the transaction.
Note: The transaction limit are as per the card holders limit or Rs.10,00,000 (if the card limit is more than Rs.10,00,000).		10.00
productinfo
mandatory		String It should be a string containing a brief description of the product.Character Limit-100iPhone
firstname
mandatory		String The first name of the customer.Character Limit-60Ashish
email
mandatory		String The email of the customer.Character Limit-50[email protected]
phone
mandatory		String The phone number of the customer.9876543210
lastname
mandatory		String The last name of the customer.Character Limit-60Verma
address1
optional		String The first line of the billing address.Character Limit-100H.No- 17, Block C, Kalyan Bldg, Khardilkar Road, Mumbai
address2
optional		String The second line of the billing address.Character Limit-10034 Saikripa-Estate, Tilak Nagar
city
optional		String The city where your customer resides as part of the billing address.Mumbai
state
optional		String The state where your customer resides as part of the billing address,Maharashtra
country
optional		String The country where your customer resides.Character Limit-50India
zipcode
optional		String Billing address zip code is mandatory for the cardless EMI option.Character Limit-20400004
si
mandatory		This parameter signifies a successful consent taken from the user by the merchant. This parameter must contain 1 for a successful consent. Without this parameter sent as 1, subscription cannot be set up.
Notes: You can modify or cancel existing recurring payment registration as described in the following sections:
. Manage Recurring Payment for Cards
. Manage UPI Recurring Transaction		1
si_details
mandatory		This parameter represents mandatory details which need to be passed to during registration transaction from merchant system to PayU.

Note: It is mandatory as per the latest RBI guidelines to pass this information to the payment processor so that same can be forwarded to acquirers and issuers ( for more details refer – https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=11668&Mode=0 )

This is a JSON object and it includes a set of fields. For more information, refer to SI Parameter JSON Details
hash
mandatory		String It is used to avoid the possibility of transaction tampering. For more information on hash generation process, refer to Hashing Request and Response.eabec285da28fd
0e3054d41a4d24fe
9f7599c9d0b6664
6f7a9984303fd612
4044b6206daf831
e9a8bda28a6200d
318293a13d6c193
109b60bd4b4f8b09
c90972
pg
mandatory		String The pg parameter must include 'CC' for cards.CC
bankcode
mandatory		String Each payment option is identified with a unique bank code at PayU. The merchant must post this parameter with the corresponding payment option’s bank code value in it.
 For more information, refer Card Type Codes and Supported Banks for CardsAMEX
udf1 - udf5
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.
Character Limit-255		Payment Preference, Shipping Method, Shipping Address1, Shipping City, Shipping Zip Code, etc.
ccnum
conditional		IntegerThis parameter must contain the card number.
This parameter is required if you are trying to create a mandate using the card details.
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
ccexpmon
mandatory		integer This parameter must contain the network token expiry month. For stored card using network or issuer, enter the expiry month of the token.10
ccexpyr
mandatory		integer This parameter must contain the network token expiry year.. For stored card using network or issuer, enter the expiry year of the token.2022
store_card_token
conditional		varchar This must include the Network token generated at your end.
This parameter is required if you are using the stored card token to register the mandate.		1234 4567 2456 3566
storecard_token_type
conditional		integer This parameter is used to specify the store card token type. It must include any of the following values:

- 0: If PayU token is used.
- 1: If Network token is used.
- 2: If Issuer token is used.
This parameter is required if you are using the stored card token to register the mandate.		1
additional_info
conditional		varchar This parameter will contain the additional information in the following JSON format:{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}
This parameter is required if you are using the stored card token to register the mandate, where network or issuer token is used.		{“last4Digits”: “1234”, “tavv”: “ABCDEFGH”,”trid”:”1234567890”, “tokenRefNo”:”abcde123456”}
free_trial
conditional		This is mandatory only if the merchant wants to support free trial use case with card and net banking together that too on PayU Hosted Checkout integration.

In this case, PayU adjusts the transaction amount as INR 2.00 for cards. INR 0.00 for Net Banking and UPI registration irrespective of what amount is passed against the amount field in the request.
This parameter has no significance in the case of seamless flow.

📘

Notes for additional_info parameter:

The JSON format contains the following fields:

 

  • trid (Token Requestor ID) is the identifier 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 token authentication verification value given by schemes or interchange. Also, known as cryptogram.

Additional 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.

📘

Notes for Bankcode

Debit Card or Credit Card: There are different options like Visa Debit Card, Mastercard, Maestro, etc. For each option, a unique bank code exists and it would be returned in this bankcode parameter. For more information, refer to Card Type Codes. For example, VISA for VISA Debit Card.

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)
  • @ ()
  • / (Slash)
  • (Space)
  • . (Dot)

Sample request

The sample code block for cards Seamless integration (Merchant-Hosted Checkout) is similar to the following:

curl -X POST "https://test.payu.in/_payment-H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d”key=Q*****U&txnid=56bb2e3fcb510f1c1521&amount=10000&firstname=Payu-Admin&[email protected]&phone=1234567890&productinfo=iPhone&api_version=7&si=1&pg=CC&bankcode=UTIBENCC&surl=https://test.payu.in/admin/test_response
/&furl=https://test.payu.in/admin/test_response
&ccnum=5123456789012346&ccexpmon=05&ccexpyr=2022&ccvv=123&ccname=Test User&si_details={“billingAmount”: “100.00”,”billingCurrency”: “INR”,”billingCycle”: “MONTHLY”,”billingInterval”: 1,”paymentStartDate”: “2022-09-01″,”paymentEndDate”: “2022-12-01”}
&hash=e36568b2dfc460eab0eb3387fb7d90543ed861154f273b9593d6fcc152ed93a91e529c2f4be0965eeb57104e82d58889fa5efb52811ec78cbd1ad646e39c29a0”

Sample response

In the case of Cards, you must ensure that the payment response from PayU has the expected values as described in the following table so that they successfully registered for a recurring plan or subscription for the customer:

Response ParameterExpected ValueDescription
statussuccessThis indicates that the transaction is successful
cardToken<card_token> sent by PayUIndicates that card details are saved correctly in PayUBiz Database
payment_sourcesistIndicates that card details have been marked correctly for Standing Instruction
mihpayid<mihpayid number> sent. by PayUIndicates PayU’s transaction acknowledgment for a Consent transaction

📘

Notes:

  • If any of the above four checks are not satisfied, that means the transaction has not been correctly authorized for Standing Instruction. The merchant must not consider this transaction eligible for the Recurring platform.
  • Registration transaction must be successful in making it eligible for the Recurring platform.

At this step, if the status of the consent transaction is returned as success along with the other three conditions explained above, you can consider that the subscription setup is completed successfully.

The response URL returned from PayU is in the form URL format (application/x-www-form-urlencoded).

Parsed response

Array
(
    [mihpayid] => 403993715525316543
    [mode] => CC
    [status] => success
    [unmappedstatus] => captured
    [key] => JP***g
    [txnid] => eF5yY4ArrynoIV
    [amount] => 10.00
    [cardCategory] => domestic
    [discount] => 0.00
    [net_amount_debit] => 10
    [addedon] => 2022-02-02 15:15:07
    [productinfo] => iPhone
    [firstname] => Ashish
    [lastname] => 
    [address1] => 
    [address2] => 
    [city] => 
    [state] => 
    [country] => 
    [zipcode] => 
    [email] => [email protected]
    [phone] => 9876543210
    [udf1] => 
    [udf2] => 
    [udf3] => 
    [udf4] => 
    [udf5] => 
    [udf6] => 
    [udf7] => 
    [udf8] => 
    [udf9] => 
    [udf10] => 
    [hash] => 499fa5f6d9019cc7bda9750b18bf3ba52f161da42cb065cab094595cb9d1c90058a3f1c7f3fcb057c371baa077052522847826be269060140580a7c345206020
    [field1] => 4296837871969451239257
    [field2] => 601248
    [field3] => 10.00
    [field4] => 403993715525316543
    [field5] => 100
    [field6] => 02
    [field7] => AUTHPOSITIVE
    [field8] => 
    [field9] => Transaction is Successful
    [payment_source] => payu
    [PG_TYPE] => CC-PG
    [bank_ref_num] => 4296837871969451239257
    [bankcode] => CC
    [error] => E000
    [error_Message] => No Error
    [name_on_card] => payu
    [cardnum] => 512345XXXXXX2346
    [cardhash] => This field is no longer supported in postback params.
)


Array
(
    [mihpayid] => 403993715525316543
    [mode] => CC
    [status] => success
    [unmappedstatus] => captured
    [key] => JP***g
    [txnid] => eF5yY4ArrynoIV
    [amount] => 10.00
    [cardCategory] => domestic
    [discount] => 0.00
    [net_amount_debit] => 10
    [addedon] => 2022-02-02 15:15:07
    [productinfo] => iPhone
    [firstname] => Ashish
    [lastname] => 
    [address1] => 
    [address2] => 
    [city] => 
    [state] => 
    [country] => 
    [zipcode] => 
    [email] => [email protected]
    [phone] => 9876543210
    [udf1] => 
    [udf2] => 
    [udf3] => 
    [udf4] => 
    [udf5] => 
    [udf6] => 
    [udf7] => 
    [udf8] => 
    [udf9] => 
    [udf10] => 
    [hash] => 499fa5f6d9019cc7bda9750b18bf3ba52f161da42cb065cab094595cb9d1c90058a3f1c7f3fcb057c371baa077052522847826be269060140580a7c345206020
    [field1] => 4296837871969451239257
    [field2] => 601248
    [field3] => 10.00
    [field4] => 403993715525316543
    [field5] => 100
    [field6] => 02
    [field7] => AUTHPOSITIVE
    [field8] => 
    [field9] => Transaction is Successful
    [payment_source] => payu
    [PG_TYPE] => CC-PG
    [bank_ref_num] => 4296837871969451239257
    [bankcode] => CC
    [error] => E000
    [error_Message] => No Error
    [name_on_card] => payu
    [cardnum] => 512345XXXXXX2346
    [cardhash] => This field is no longer supported in postback params.
)

Webhook for Getting Transaction Details

You can expose a webhook by requesting the PayU Integration team to configure the same against the ws_online_response parameter. If this webhook is configured, you will receive the above response object over HTTP form post method similar to the following:

unmappedstatus=success&phone=9999999999&txnid=FCDA1R100870163781&hash=84e335094bbcb2ddaa0f9a488eb338e143b273765d89c9dfa502402562d0b6f3c7935e28194ca92f380be7c84c3695415b106dcf52cb016a15fcf6adc98d724&status=success&curl=https://www.abc.in/payment/handlepayuresposne&firstname=NA&card_no=519619XXXXXX5049&furl=https://www.abc.in/payment/handlepayuresposne&productinfo=2&mode=DC&amount=800.00&field4=6807112311042810&field3=6807112311042810&field2=838264&field9=SUCCESS&email=NA&mihpayid=175477248&surl=https://www.ABC.in/payment/handlepayuresposne&card_hash=9e88cb0573d4a826b61d808c0a870ed4a990682459b0ec9e95ea421e8e47be8c&field1=42812&payment_source=sist

If the mandate is not confirmed by the customer or the mandate is confirmed by the customer, but the mandate registration is rejected from the banks, the status is communicated as a “failure” over webhook. For more information, refer to Set up WebHook to Receive Cancellation or Modification Update from the Issuer Bank.