Cards Integration
This document provides a comprehensive guide for integrating with PayU Cards Seamless Integration v2 using the v2/payments
API. The seamless integration allows you to process card payments directly through server-to-server communication, providing a streamlined payment experience while maintaining control over the user interface.
We recommend testing your integration in the PayU test environment before going live.
Supported Card Types
PayU v2 Cards integration supports the following card types:
- American Express (AMEX)
- Visa
- Mastercard
- Diners Club
- RuPay
Both domestic and international transactions are supported (international transactions require special enablement).
The v2 Cards seamless integration consists of three main steps:
- Validate card type using the BIN API (check_isDomestic)
- Create the payment request to PayU's v2/payments API with card payment method
- Verify the payment status using the verification API
Step 1: Validate Card Type (Optional)
Before processing the payment, you can validate the card type using PayU's BIN API to check if the card is domestic or international.
Step 2: Create the payment request
Environment
Environment
Test Environment | https://apitest.payu.in/v2/payments |
Production Environment | https://api.payu.in/v2/payments> |
Request Headers
Request Headers
Parameter | Description |
---|---|
date | The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT. |
authorization | The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description. |
authorization fields description
Field | Description |
---|---|
username | Represents the username or identifier for the client or merchant, for example smsplus. |
algorithm | Use SHA512 algorithm for hashing and send this as header value. |
headers | Specifies which headers have been used in generating the hash, for example date. |
signature | The HMAC signature generated using the specified algorithm. For more information, refer to hashing algorithm. |
hashing algorithm
You must hash the request parameters using the following hash logic:
Hash logic: sha512(<Body data>
+ '|' + date + '|' + merchant_secret)
Where <Body data>
contains the request body posted with the request.
Sample header code
var merchant_key = 'smsplus';
var merchant_secret = 'izF09TlpX4ZOwmf9MvXijwYsBPUmxYHD';
// date
var date = new Date();
date = date.toUTCString();
// authorization
var authorization = getAuthHeader(date);
function getAuthHeader(date) {
var AUTH_TYPE = 'sha512';
var data = isEmpty(request['data']) ? "" : request['data'];
var hash_string = data + '|' + date + '|' + merchant_secret;
var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
return `hmac username="${merchant_key}", algorithm="${AUTH_TYPE}", headers="date", signature="${hash}"`;
}
Request body
The v2/payments API request for Cards seamless integration contains the following main parameters:
Parameter | Description | Example |
---|---|---|
accountIdmandatory |
Represents the merchant key provided by PayU during onboarding. | MERCHANT123 |
txnIdmandatory |
Transaction ID for transaction tracking. Must be unique for every transaction. | TXN123456 |
amountoptional |
Amount of the transaction. This will not be considered as the transaction amount, only the order.paymentChargeSpecification.price field will be considered. | 1000 |
paymentMethodmandatory |
Contains details of the payment method. For more information, refer to Payment Method Object. | Object |
ordermandatory |
Contains transaction order details such as product info, ordered items, user-defined fields, and payment charge details. For more information, refer to Order Object. | Object |
additionalInfomandatory |
Additional metadata for the transaction. For more information, refer to Additional Info Object. | Object |
callBackActionsmandatory |
URL actions for payments (e.g., success, failure, cancel). For more information, refer to Callback Actions Object. | Object |
billingDetailsmandatory |
Customer billing details including name, phone, and address. For more information, refer to Billing Details Object. | Object |
authorizationmandatory |
Authorization details for the payment process, including 3DS metadata. For more information, refer to Authorization Object. | Object |
Payment method object
Payment Method Object
For Cards seamless integration, the payment method object should contain:
Parameter | Type | Description | Required |
---|---|---|---|
name | String | Must be "CreditCard" for credit cards or "DebitCard" for debit cards | Yes |
bankCode | String | Bank code for the card type (e.g., "CC" for credit cards, "DC" for debit cards) | Yes |
paymentCard | Object | Card details including card number, CVV, expiry, etc. | Yes |
Example:
{
"name": "CreditCard",
"bankCode": "CC",
"paymentCard": {
"cardNumber": "5004461234560000",
"validThrough": "04/2025",
"ownerName": "John Doe",
"cvv": "123"
}
}
Payment Card Object
Payment Card Object
For new card payments:
Parameter | Type | Description | Required |
---|---|---|---|
cardNumber | String | Full card number | Yes |
validThrough | String | Card expiry date in MM/YYYY format | Yes |
ownerName | String | Cardholder name as on card | No |
cvv | String | Card Verification Value | Yes |
For saved card payments:
Parameter | Type | Description | Required |
---|---|---|---|
cardToken | String | Saved card token | Yes |
cardTokenType | String | Token type (PAYU, NETWORK, ISSUER) | Yes |
tavv | String | Cryptogram for saved cards | Yes |
last4Digits | String | Last 4 digits of saved card | Yes |
cvv | String | Card Verification Value | Yes |
Example - New Card:
{
"cardNumber": "5004461234560000",
"validThrough": "04/2025",
"ownerName": "John Doe",
"cvv": "123"
}
Example - Saved Card:
{
"cardToken": "29850879bf39848ca078727b8e1a95165a41cea1",
"cardTokenType": "NETWORK",
"tavv": "/wAAAAAAPtP+g6IAmbSeg1gAAAA=",
"last4Digits": "0000",
"cvv": "123"
}
Order object
Order Object
Parameter | Description | Example |
---|---|---|
productInfomandatory |
Product details. | Product details |
orderedItemoptional |
Details about the items ordered. | Array of Objects |
userDefinedFieldsoptional |
Custom fields for additional information. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10. For more information, refer to | Object |
paymentChargeSpecificationmandatory |
Includes amount and charges. For more information, refer to paymentChargeSpecification object fields description | Object |
paymentChargeSpecification object fields description
Parameter | Description | Example |
---|---|---|
pricemandatory |
The transaction amount. | 1000 |
netAmountDebitoptional |
Net amount to be debited. | 1000 |
taxSpecificationoptional |
Tax details of the product/order. | Object |
convenienceFeeoptional |
Fees format (e.g., CC:12). | CC:12 |
offersoptional |
Offers applied or available for the payment. | Object |
userDefinedFields object fields description
Field | Description |
---|---|
udf1 | User defined field. |
udf2 | User defined field. |
udf3 | User defined field. |
udf4 | User defined field. |
udf5 | User defined field. |
udf6 | User defined field. |
udf7 | User defined field. |
udf8 | User defined field. |
udf9 | User defined field. |
udf10 | User defined field. |
Payment charge specification object
Payment Charge Specification Object
Parameter | Description | Example |
---|---|---|
pricemandatory |
The transaction amount. | 1000 |
netAmountDebitoptional |
Net amount to be debited. | 1000 |
taxSpecificationoptional |
Tax details of the product/order. | Object |
convenienceFeeoptional |
Fees format (e.g., CC:12). | CC:12 |
offersoptional |
Offers applied or available for the payment. | Object |
Additional Info Object
Additional Info Object
Parameter | Description | Example |
---|---|---|
enforcePaymethodoptional |
Force a transaction with a specified method (e.g., CC, DC). | CC |
forcePgidoptional |
Forces identification for payment gateway. | PG123 |
partnerHoldTimeoptional |
Time held by the partner for the transaction. | 60 |
userCredentialsoptional |
Credentials for user authentication. | string |
userTokenoptional |
Token for the customer. | user_token_123 |
subventionAmountoptional |
Amount paid through EMI subvention payments. | 100 |
authOnlyoptional |
Initiates an authentication-only payment (true/false). | false |
createOrderoptional |
A flag to store the order details (true/false). | true |
txnS2sFlowoptional |
For defining seamless/non-seamless flows in handling payments. | seamless |
Callback Actions Object
Callback Actions Object
Parameter | Description | Example |
---|---|---|
successActionmandatory |
URL to be called on payment success. | https://example.com/success |
failureActionmandatory |
URL to be called on payment failure. | https://example.com/failure |
cancelActionmandatory |
URL to be called if user cancels the payment. | https://example.com/cancel |
codActionoptional |
URL for Cash on Delivery (COD) action. | https://example.com/cod |
Billing Details Object
Billing Details Object
Parameter | Description | Example |
---|---|---|
firstNamemandatory |
First name of the billing contact. | Ashish |
lastNameoptional |
Last name of the billing contact. | Kumar |
address1mandatory |
Primary billing address. | 123 Main Street |
address2optional |
Secondary billing address. | Apt 4B |
phoneoptional |
Phone number of the billing contact. | 9123456789 |
emailmandatory |
Email address of the billing contact. | [email protected] |
cityoptional |
City of the billing address. | Bharatpur |
stateoptional |
State of the billing address. | Rajasthan |
countryoptional |
Country of the billing address. | India |
zipCodeoptional |
Postal/Zip code of the billing address. | 321028 |
Authorization Object
Authorization Object
Parameter | Description | Example |
---|---|---|
ecioptional |
Electronic Commerce Indicator. | 05 |
cavvoptional |
Cardholder Authentication Verification Value. | AAABAWFlmQAAAABjRWWZEEFgFz |
paresoptional |
Payer Authentication Response for 3D Secure 1.0. | eJzVWFmTokoWfrMABXXOtgSL... |
bankDataoptional |
Additional bank data for processing the payment. | fGpDiuSMy8FjxQHDla5kFwVr |
messageDigestoptional |
Security hash value for message verification. | 3a4df2b5c8e7f9a1d6b0c3e9 |
xidoptional |
Transaction identifier for 3D Secure authentication. | MDAwMDAwMDAwMDAwMDAwMDEyMzQ= |
threeDSenrolledoptional |
Indicates if the card is enrolled in 3D Secure. | Y |
threeDSstatusoptional |
Status of the 3D Secure authentication. | SUCCESS |
flowTypeoptional |
Flow type for 3D Secure. | Frictionless |
threeDSTransIDoptional |
3DS Transaction ID. | 67b4c71f-19bf-4d97-bd09-4e3687dc9e42 |
threeDSServerTransIDoptional |
3DS Server Transaction ID. | eea30d14-71cf-41af-b961-f95b7d67dc93 |
threeDSTransStatusoptional |
3DS transaction status. | Y |
threeDSTransStatusReasonoptional |
Reason for 3DS transaction status. | 01 |
aquirer_binoptional |
Bank Identification Number of the acquirer. | 401200 |
additionalInfooptional |
Object containing additional authorization information including payment gateway identifier, authentication flow, 3DS2 request data, and user-defined fields. | Object |
additionalInfo.paymentGatewayIdentifieroptional |
Identifier for the payment gateway. | gateway_123 |
additionalInfo.authenticationFlowoptional |
Type of authentication flow used. | 3DS2 |
additionalInfo.threeDS2RequestDataoptional |
Object containing 3DS2 request data. | {} |
additionalInfo.authUdf1optional |
User-defined field 1 for additional authorization data. | custom_value_1 |
additionalInfo.authUdf2optional |
User-defined field 2 for additional authorization data. | custom_value_2 |
additionalInfo.authUdf3optional |
User-defined field 3 for additional authorization data. | custom_value_3 |
additionalInfo.authUdf4optional |
User-defined field 4 for additional authorization data. | custom_value_4 |
additionalInfo.authUdf5optional |
User-defined field 5 for additional authorization data. | custom_value_5 |
additionalInfo.authUdf6optional |
User-defined field 6 for additional authorization data. | custom_value_6 |
additionalInfo.authUdf7optional |
User-defined field 7 for additional authorization data. | custom_value_7 |
additionalInfo.authUdf8optional |
User-defined field 8 for additional authorization data. | custom_value_8 |
additionalInfo.authUdf9optional |
User-defined field 9 for additional authorization data. | custom_value_9 |
additionalInfo.authUdf10optional |
User-defined field 10 for additional authorization data. | custom_value_10 |
ThreeDS2 Request Data Object
ThreeDS2 Request Data Object
Parameter | Description | Example |
---|---|---|
threeDSVersionoptional |
The version of 3D Secure used. | 2.2.0 |
deviceChanneloptional |
The device used for the transaction channel. | APP |
Sample request
curl -X POST \
https://apitest.payu.in/v2/payments \
-H 'date: Mon, 05 Oct 2024 11:00:00 GMT' \
-H 'authorization: HMAC smsplus:4d1ea4e74243ea5b2b5b8b1d8a7b1a2e3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9' \
-H 'content-type: application/json' \
-d {
"accountId": "smsplus",
"referenceId": "b5f2d8785768087678fn4",
"currency": "INR",
"paymentSource": "WEB",
"paymentMethod": {
"name": "CreditCard",
"bankCode": "CC",
"paymentCard": {
"cardNumber": "5004461234560000",
"validThrough": "04/2025",
"ownerName": "John Doe",
"cvv": "123"
}
},
"order": {
"productInfo": "Credit Card Test Product",
"orderedItem": [
{
"itemId": "ITEM001",
"description": "Test Product for Credit Card",
"quantity": 1
}
],
"paymentChargeSpecification": {
"price": 100.00
},
"userDefinedFields": {
"udf1": "",
"udf2": "",
"udf3": "",
"udf4": "",
"udf5": ""
}
},
"additionalInfo": {
"txnS2sFlow": "2",
"createOrder": false,
"storeCard": "1",
"oneClickCheckout": "1",
"preAuthorize": "0"
},
"callBackActions": {
"successAction": "https://example.com/success",
"failureAction": "https://example.com/failure",
"cancelAction": "https://example.com/cancel"
},
"billingDetails": {
"firstName": "John",
"lastName": "Doe",
"phone": "9876543210",
"email": "[email protected]",
"address": {
"address1": "123 Main Street",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"zipCode": "400001"
}
},
"authorization": {
"eci": "05",
"cavv": "AAABAWFlmQAAAABjRWWZEEFgFz",
"threeDSTransID": "67b4c71f-4e6b-4f98-9f2a-1234567890ab",
"threeDSenrolled": "Y",
"threeDSstatus": "Success"
},
"threeDS2RequestData": {
"threeDSVersion": "2.2.0",
"deviceChannel": "APP"
}
}'
Request Body (Saved Card):
curl -X POST \
https://apitest.payu.in/v2/payments \
-H 'date: Mon, 05 Oct 2024 11:00:00 GMT' \
-H 'authorization: HMAC smsplus:4d1ea4e74243ea5b2b5b8b1d8a7b1a2e3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9' \
-H 'content-type: application/json' \
-d
{
"accountId": "smsplus",
"referenceId": "b5f2d8785768087678fn5",
"currency": "INR",
"paymentSource": "WEB",
"paymentMethod": {
"name": "CreditCard",
"bankCode": "CC",
"paymentCard": {
"cardToken": "29850879bf39848ca078727b8e1a95165a41cea1",
"cardTokenType": "NETWORK",
"tavv": "/wAAAAAAPtP+g6IAmbSeg1gAAAA=",
"last4Digits": "0000",
"cvv": "123"
}
},
"order": {
"productInfo": "Saved Card Test Product",
"paymentChargeSpecification": {
"price": 100.00
}
},
"additionalInfo": {
"txnS2sFlow": "2",
"oneClickCheckout": "1"
},
"callBackActions": {
"successAction": "https://example.com/success",
"failureAction": "https://example.com/failure"
},
"billingDetails": {
"firstName": "John",
"lastName": "Doe",
"phone": "9876543210",
"email": "[email protected]"
}
}'
Sample Response
{
"result": {
"paymentId": "1999110000001769",
"redirectUrl": "https://secure.payu.in/ResponseHandler.php",
"authAction": "https://apitest.payu.in/v2/payments/1999110000001769/auth"
},
"status": "PENDING"
}
Step 3: Verify the Payment
After the payment is processed, you must verify the payment status using the verification API to get the final transaction status.
Sample request
Environment
Environment | URL |
---|---|
Test | https://test.payu.in/v3/transaction |
Production | https://api.payu.in/v3/transaction |
curl --location 'https://test.payu.in/v3/transaction' \
--header 'Content-Type: application/json' \
--header 'date: Thu, 27 Mar 2025 06:35:21 GMT' \
--header 'authorization: hmac username="PRiQvJ", algorithm="sha512", headers="date", signature="42a54cc7450fe1e7a3cf35ebfaed1b828e37062964266fd33186c7b2526e85e3ea2d46946a728ca50e46423ea9a6b2edb8c1315b58fa69297e1e91d3d34804a1"' \
--header 'Info-Command: verify_payment' \
--data '{
"txnId":["512345678901234"]
}'
Sample response
{
"message": "Success",
"status": 1,
"result": [
{
"mihpayId": 21612493009,
"bankReferenceNumber": "2411194544",
"amount": 10.00,
"mode": "CC",
"requestId": "",
"originalAmount": 10.00,
"additionalCharges": 0.00,
"discount": 0.00,
"netDebitAmount": 10.00,
"productInfo": "Test Product",
"firstName": "John",
"bankcode": "VISA",
"nameOnCard": "JOHN DOE",
"cardNo": "XXXXXXXXXXXX1234",
"cardType": "VISA",
"udf1": null,
"udf2": null,
"udf3": null,
"udf4": null,
"udf5": null,
"field2": "140455",
"field9": "Transaction is Successful",
"errorCode": "E000",
"errorMessage": "No Error",
"addedOn": "2024-11-19 21:17:55",
"settledAt": "0000-00-00 00:00:00",
"paymentSource": "WEB",
"pgType": "CC-PG",
"status": "success",
"unmappedStatus": "captured",
"merchantUTR": null,
"rupayAuthRefNo": null,
"authRefNo": "123456789",
"originalCurrency": "INR",
"threeDSVersion": "2.2.0",
"message": "Found TxnId",
"txnId": "b5f2d8785768087678fm9"
}
]
}
Card-specific features
Card storage and tokenization
You can store cards for future use by setting storeCard: "1"
in the additionalInfo
object. This enables:
- Card tokenization for PCI compliance
- One-click checkout for returning customers
- Secure card storage without storing sensitive data
3D Secure authentication
PayU supports 3D Secure 1.0 and 2.0 for enhanced security:
- 3D Secure 1.0: Traditional authentication with ACS redirect
- 3D Secure 2.0: Enhanced authentication with device fingerprinting
Pre-authorization
Enable pre-authorization mode by setting preAuthorize: "1"
to:
- Authorize payments without immediate capture
- Capture authorized payments later using capture API
- Handle partial captures and refunds
EMI support
PayU supports EMI (Equated Monthly Installments) for eligible cards:
- Check EMI eligibility using bank-specific parameters
- Configure subvention amounts for merchant-funded EMI
- Support for both bank EMI and cardless EMI
Updated 5 days ago