Cards - v2 Payment API

You can collect payments from customers with credit and debit cards using the Merchant Hosted (seamless) integration.

You need to pass "CreditCard" or "DebitCard" for paymentMethod.name, the card provider code (e.g. CC, MAST, VISA, RUPAY) for paymentMethod.bankCode, and the card details or saved card token in paymentMethod.paymentCard.

📘
International Cards: PayU accepts domestic and international cards. International card processing must be enabled for your account by the PayU Integration and Risk teams.

Environment


Test Environment	https://apitest.payu.in/v2/payments
Production Environment	https://api.payu.in/v2/payments

Request header

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 = '<YOUR_TEST_KEY>';
  var merchant_secret = 'YOUR_TEST_SALT';
  // 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

Here is the converted table, split into Mandatory and Optional parameters with the mandatory/optional labels removed from the Parameter column:

Mandatory parameters

Parameter	Description	Example
accountId	The unique merchant key provided by PayU. Character limit: 50.	MERCHANT123
txnId	Transaction ID for transaction tracking. Must be unique for every transaction. Character limit: 50.	TXN_CARD_20261005
currency	Three-letter ISO currency code. Must be `"INR"`.	INR
paymentMethod	Card payment details including card number, expiry, CVV, or saved token. See paymentMethod object.	Object
order	Transaction order details such as product info and price. See order object.	Object
additionalInfo	Transaction flow options and order flags. See additionalInfo object.	Object
callBackActions	Redirection URLs following 3DS authentication. See callBackActions object.	Object
billingDetails	Customer billing details including name, phone, email, and address. See billingDetails object.	Object

Optional parameters

Parameter	Description	Example
authorization	Pre-authenticated 3DS 2.0 metadata (ECI, CAVV, 3DS Trans ID) if the merchant performs 3DS authentication directly. For more information, refer to authorization object fields description.	Object

paymentMethod object fields description

Parameter	Description	Example
name `mandatory`	Card instrument type. Set to `"CreditCard"` or `"DebitCard"`.	CreditCard
bankCode `mandatory`	Card network/provider code. Valid values: `CC` (generic credit), `DC` (generic debit), `MAST`, `VISA`, `RUPAY`, `AMEX`.	CC
paymentCard `mandatory for cards`	Contains physical card or saved card token details. See paymentCard object.	Object

paymentCard object fields description

Field	Description	Example
cardNumber `mandatory for new card`	Card number (13–19 digits). Must pass Luhn check. Omit when using saved card token.	5497774415170603
validThrough `mandatory`	Card expiry date formatted as `MM/YYYY`.	12/2026
ownerName `mandatory for new card`	Cardholder name as printed on card.	John Doe
cvv `mandatory`	Card verification code (3 digits; 4 digits for AMEX).	123
cardToken `mandatory for saved cards`	Network or PayU token string. Replaces `cardNumber` and `ownerName`.	token_123456
cardTokenType `mandatory for saved cards`	Token type: `PAYU`, `NETWORK`, or `ISSUER`.	NETWORK

order object fields description

Parameter	Description	Example
productInfo `mandatory`	Product details. Type: `String`	Product details
orderedItem `optional`	Details about the items ordered. Type: `Array of Objects`
userDefinedFields `optional`	Custom fields for additional information. Type: `Object`. Fields: udf1, udf2, udf3, udf4, udf5, udf6, udf7, udf8, udf9, udf10.
paymentChargeSpecification `mandatory`	Includes amount and charges. Type: `Object`. For more information, refer to paymentChargeSpecification object fields description

paymentChargeSpecification object fields description

Parameter	Description	Example
price `mandatory`	The transaction amount. Type: `Number`	1000
netAmountDebit `optional`	Net amount to be debited. Type: `Number`	1000
taxSpecification `optional`	Tax details of the product/order. Type: `Object`
convenienceFee `optional`	Fees format. Type: `String`	CC:12
offers `optional`	Offers applied or available for the payment. Type: `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.

additionalInfo object fields description

Parameter	Description	Example
txnS2sFlow `mandatory`	Flow configuration. Set to `"4"` for seamless 3DS redirection.	4
createOrder `optional`	Flag to store order details in PayU (`true` / `false`).	true
enforcePaymethod `optional`	Enforces card mode. Set to `"CC"` or `"DC"`.	CC

callBackActions object fields description

Parameter	Description	Example
successAction `mandatory`	URL to be called on payment success.	https://example.com/success
failureAction `mandatory`	URL to be called on payment failure.	https://example.com/failure
cancelAction `mandatory`	URL to be called if user cancels the payment.	https://example.com/cancel
codAction `optional`	URL for Cash on Delivery (COD) action.	https://example.com/cod

billingDetails object fields description

Parameter	Description	Example
firstName `mandatory`	First name of the billing contact.	Ashish
lastName `optional`	Last name of the billing contact.	Kumar
address1 `mandatory`	Primary billing address.	123 Main Street
address2 `optional`	Secondary billing address.	Apt 4B
phone `optional`	Phone number of the billing contact.	9123456789
email `mandatory`	Email address of the billing contact.	[email protected]
city `optional`	City of the billing address.	Bharatpur
state `optional`	State of the billing address.	Rajasthan
country `optional`	Country of the billing address.	India
zipCode `optional`	Postal/Zip code of the billing address.	321028

authorization object fields description

Mandatory parameters

Parameter	Description	Example
eci	Electronic Commerce Indicator returned by Access Control Server (ACS) / Directory Server (DS).	`"05"`
cavv	Cardholder Authentication Verification Value (cryptogram validating 3DS authentication).	`"AAABAWFlmQAAAABjRWWZEEFgFz"`
threeDSTransID	Universally unique 3DS Transaction Identifier assigned by Directory Server (DS).	`"67b4c71f-19bf-4d97-bd09-4e3687dc9e42"`
threeDSServerTransID	Transaction ID assigned by the merchant's 3DS Server (MPI).	`"eea30d14-71cf-41af-b961-f95b7d67dc93"`
threeDSTransStatus	Authentication outcome code: `Y` (Authenticated), `A` (Attempted), `C` (Challenge), `N` (Failed).	`"Y"`
threeDSenrolled	Card 3DS enrollment flag: `Y` (Enrolled), `N` (Not Enrolled), `U` (Unable to Verify).	`"Y"`
threeDSstatus	3DS 1.x payer authentication status (e.g. `SUCCESS`).	`"SUCCESS"`
xid	Transaction identifier for 3D Secure 1.x protocol (Base64 encoded).	`"MDAwMDAwMDAwMDAwMDAwMDEyMzQ="`
pares	Payer Authentication Response received from issuing bank ACS.	`"eJzVWFmTokoWfrMABXXOtgSL..."`

Optional parameters

Parameter	Description	Example
threeDSTransStatusReason	Diagnostic reason code explaining why authentication was not successful or exempt.	`"01"`
flowType	3DS authentication flow type (`Frictionless` or `Challenge`).	`"Frictionless"`
messageDigest	Security digest value for 3DS 1.x message integrity verification (used with `pares`).	`"3a4df2b5c8e7f9a1d6b0c3e9"`
bankData	Additional bank-specific authorization payload returned by issuing banks.	`"fGpDiuSMy8FjxQHDla5kFwVr"`
additionalInfo	Additional MPI metadata: `paymentGatewayIdentifier` and `authenticationFlow`.	`{"paymentGatewayIdentifier": "MPI_01", "authenticationFlow": "3DS2"}`

Sample request

curl -X POST 'https://apitest.payu.in/v2/payments' \
  -H 'date: Mon, 05 Oct 2026 10:00:00 GMT' \
  -H 'authorization: hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"' \
  -H 'content-type: application/json' \
  -d '{
    "accountId": "<YOUR_TEST_KEY>",
    "txnId": "TXN_CARD_20261005",
    "currency": "INR",
    "paymentMethod": {
        "name": "CreditCard",
        "bankCode": "CC",
        "paymentCard": {
            "cardNumber": "5497774415170603",
            "validThrough": "12/2026",
            "cvv": "123",
            "ownerName": "John Doe"
        }
    },
    "order": {
        "productInfo": "Electronics Purchase",
        "paymentChargeSpecification": {
            "price": 1000.00
        },
        "userDefinedFields": {
            "udf1": "card_seamless",
            "udf2": "web_store"
        }
    },
    "additionalInfo": {
        "txnS2sFlow": "4",
        "createOrder": true
    },
    "callBackActions": {
        "successAction": "<redacted URL>",
        "failureAction": "<redacted URL>",
        "cancelAction": "<redacted URL>"
    },
    "billingDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "9876543210",
        "email": "[email protected]",
        "address1": "123 Main Street",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "zipCode": "400001"
    }
}'

import requests
import json

url = "https://apitest.payu.in/v2/payments"

headers = {
    "date": "Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization": 'hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"',
    "content-type": "application/json"
}

payload = {
    "accountId": "<YOUR_TEST_KEY>",
    "txnId": "TXN_CARD_20261005",
    "currency": "INR",
    "paymentMethod": {
        "name": "CreditCard",
        "bankCode": "CC",
        "paymentCard": {
            "cardNumber": "5497774415170603",
            "validThrough": "12/2026",
            "cvv": "123",
            "ownerName": "John Doe"
        }
    },
    "order": {
        "productInfo": "Electronics Purchase",
        "paymentChargeSpecification": {
            "price": 1000.00
        },
        "userDefinedFields": {
            "udf1": "card_seamless"
        }
    },
    "additionalInfo": {
        "txnS2sFlow": "4",
        "createOrder": True
    },
    "callBackActions": {
        "successAction": "<redacted URL>",
        "failureAction": "<redacted URL>",
        "cancelAction": "<redacted URL>"
    },
    "billingDetails": {
        "firstName": "John",
        "lastName": "Doe",
        "phone": "9876543210",
        "email": "[email protected]",
        "address1": "123 Main Street",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "zipCode": "400001"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

<?php
$url = "https://apitest.payu.in/v2/payments";

$payload = json_encode([
    "accountId" => "<YOUR_TEST_KEY>",
    "txnId" => "TXN_CARD_20261005",
    "currency" => "INR",
    "paymentMethod" => [
        "name" => "CreditCard",
        "bankCode" => "CC",
        "paymentCard" => [
            "cardNumber" => "5497774415170603",
            "validThrough" => "12/2026",
            "cvv" => "123",
            "ownerName" => "John Doe"
        ]
    ],
    "order" => [
        "productInfo" => "Electronics Purchase",
        "paymentChargeSpecification" => [
            "price" => 1000.00
        ]
    ],
    "additionalInfo" => [
        "txnS2sFlow" => "4",
        "createOrder" => true
    ],
    "callBackActions" => [
        "successAction" => "<redacted URL>",
        "failureAction" => "<redacted URL>",
        "cancelAction" => "<redacted URL>"
    ],
    "billingDetails" => [
        "firstName" => "John",
        "lastName" => "Doe",
        "phone" => "9876543210",
        "email" => "[email protected]",
        "address1" => "123 Main Street",
        "city" => "Mumbai",
        "state" => "Maharashtra",
        "country" => "India",
        "zipCode" => "400001"
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "date: Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization: hmac username=\"<YOUR_TEST_KEY>\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"",
    "content-type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PayUCardRequest {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String payload = """
            {
              "accountId": "<YOUR_TEST_KEY>",
              "txnId": "TXN_CARD_20261005",
              "currency": "INR",
              "paymentMethod": {
                "name": "CreditCard",
                "bankCode": "CC",
                "paymentCard": {
                  "cardNumber": "5497774415170603",
                  "validThrough": "12/2026",
                  "cvv": "123",
                  "ownerName": "John Doe"
                }
              },
              "order": {
                "productInfo": "Electronics Purchase",
                "paymentChargeSpecification": {
                  "price": 1000.00
                }
              },
              "additionalInfo": {
                "txnS2sFlow": "4",
                "createOrder": true
              },
              "callBackActions": {
                "successAction": "<redacted URL>",
                "failureAction": "<redacted URL>",
                "cancelAction": "<redacted URL>"
              },
              "billingDetails": {
                "firstName": "John",
                "lastName": "Doe",
                "phone": "9876543210",
                "email": "[email protected]",
                "address1": "123 Main Street",
                "city": "Mumbai",
                "state": "Maharashtra",
                "country": "India",
                "zipCode": "400001"
              }
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://apitest.payu.in/v2/payments"))
            .header("date", "Mon, 05 Oct 2026 10:00:00 GMT")
            .header("authorization", "hmac username=\"<YOUR_TEST_KEY>\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"")
            .header("content-type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

const url = "https://apitest.payu.in/v2/payments";

const payload = {
  accountId: "<YOUR_TEST_KEY>",
  txnId: "TXN_CARD_20261005",
  currency: "INR",
  paymentMethod: {
    name: "CreditCard",
    bankCode: "CC",
    paymentCard: {
      cardNumber: "5497774415170603",
      validThrough: "12/2026",
      cvv: "123",
      ownerName: "John Doe"
    }
  },
  order: {
    productInfo: "Electronics Purchase",
    paymentChargeSpecification: {
      price: 1000.00
    }
  },
  additionalInfo: {
    txnS2sFlow: "4",
    createOrder: true
  },
  callBackActions: {
    successAction: "<redacted URL>",
    failureAction: "<redacted URL>",
    cancelAction: "<redacted URL>"
  },
  billingDetails: {
    firstName: "John",
    lastName: "Doe",
    phone: "9876543210",
    email: "[email protected]",
    address1": "123 Main Street",
    city: "Mumbai",
    state: "Maharashtra",
    country: "India",
    zipCode: "400001"
  }
};

fetch(url, {
  method: "POST",
  headers: {
    "date": "Mon, 05 Oct 2026 10:00:00 GMT",
    "authorization": 'hmac username="<YOUR_TEST_KEY>", algorithm="sha512", headers="date", signature="<SIGNATURE>"',
    "content-type": "application/json"
  },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error("Error:", err));

Sample response

The card payment response returns a checkoutUrl to redirect the customer to their bank's 3DS OTP verification page:

{
  "status": "PENDING",
  "result": {
    "checkoutUrl": "<redacted URL>"
  },
  "txnId": "TXN_CARD_20261005",
  "paymentId": "1999110000001769",
  "message": "Redirect customer to checkoutUrl for 3DS authentication"
}

Response parameters

Parameter	Description
message	This parameter contains the status message of the transaction.
status	This parameter returns the status of web service call. The status can be any of the following: `0` - If web service call failed. `1` - If web service call succeeded.
result	This parameter contains the payment status details in a JSON format including payment ID of the transaction. For more detailes, refer to the result JSON Object fields description table (next accordion)

📘
Reference:
To check the final status of the transaction following 3DS redirection, refer to Verify Payment API.

Error Codes

Code	HTTP Status	Description	Resolution
`INVALID_CARD_NUMBER`	400	Card number failed Luhn validation	Check card number formatting
`INVALID_EXPIRY`	400	Expiry date expired or format incorrect	Use `MM/YYYY` format with valid future date
`INVALID_AMOUNT`	400	Invalid amount value	Ensure `price` is positive number
`INVALID_CURRENCY`	400	Unsupported currency	Set `currency: "INR"`
`AUTHENTICATION_FAILED`	401	Invalid token / signature	Verify HMAC SHA512 signature
`DUPLICATE_REFERENCE`	409	`txnId` already used	Use unique transaction ID
`PAYMENT_DECLINED`	422	Card issuer declined transaction	Customer should contact issuing bank

Next Steps

Handle Customer 3DS Authentication:
- Inspect the result.paymentUrl or redirection payload returned in the API response.
- Redirect the customer or render the 3D Secure ACS challenge screen in an in-app browser/webview to complete two-factor authentication (OTP / Biometric).
Process Post-Authentication Callback:
- Listen on your configured callBackActions.termAction or callBackActions.successAction for the final transaction response from the issuing bank.
Verify Transaction Integrity:
- Calculate and verify the response hash to confirm authenticity.
- Perform a server-to-server transaction status check using the Verify Payment API before fulfilling the order.
Support Saved Cards & Tokenization:
- If the customer opted to save their card, store the returned cardToken and cardTokenType to enable seamless one-click checkouts for future visits.

Request header

authorization fields description

hashing algorithm

Request body

paymentMethod object fields description

paymentCard object fields description

order object fields description

paymentChargeSpecification object fields description

userDefinedFields object fields description

additionalInfo object fields description

callBackActions object fields description

billingDetails object fields description

authorization object fields description

Sample request

Sample response

Response parameters

Reference:

Error Codes

Next Steps

EXAMPLE QUESTIONS