Save Card API

The Save Card API enables merchants to store customer card details securely in PayU Vault and obtain a unique token (cardToken) for future recurring or one-click checkouts, ensuring compliance with RBI tokenization directives and PCI-DSS standards.

Endpoint & Environments

Environment	Method	URL
Test	`POST`	`<redacted URL>`
Production	`POST`	`<redacted URL>`

Headers

Parameter	Description
date	The current date and time. Use the date format only after the Authentication contract has been confirmed; the value here is an illustrative format.
authorization	Authorization value. The format and algorithm are pending engineering confirmation. For more information, refer to authorization fields description table below.

authorization fields description

Parameter	Description
username	Represents the username or identifier for the client or merchant, in this case, it's "<Your_TEST_KEY>".
algorithm	Use SHA512 algorithm for hashing and send this as header value.
headers	Specifies which headers have been used in generating the hash. In this case, only the "date" header is used.
signature	Authorization value. The format and algorithm are pending engineering confirmation. For more information, refer to hashing algorithm.

hashing algorithm

The following formula appears in the current source but is disputed by the audit. Do not use it until the API team confirms it:

sha512(<Body data> + '|' + date + '|' + merchant_secret}

Where, <Body data> contains the request Body posted with the request.

Sample authorization header code

var merchant_key = pm.environment.get('merchantKey') || '<YOUR_TEST_KEY>';
var merchant_secret = pm.environment.get('merchantSalt') || '<YOUR_TEST_SALT>';

// Generate current date in RFC 1123 format
var date = new Date().toUTCString();

// Get request body data (empty for GET/DELETE)
var data = "";
if (pm.request.method === "POST" && pm.request.body && pm.request.body.raw) {
    data = pm.request.body.raw;
}

// Generate authorization header
var hash_string = data + '|' + date + '|' + merchant_secret;
var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
var authorization = 'hmac username="' + merchant_key + '", algorithm="sha512", headers="date", signature="' + hash + '"';

// Set environment variables
pm.environment.set('date', date);
pm.environment.set('authorization', authorization);

Request Parameters

The table has 7 rows, so here it is in HTML format:

Mandatory parameters

Parameter	Description
`userCredential`	`String` Plaintext identifier representing the merchant key and customer ID in the format `<merchantKey>:<customerId>` (e.g. `sms:user12345`). Max 100 characters.
`cardNumber`	`String` 15- or 16-digit Primary Account Number (PAN).
`cardName`	`String` Name of the cardholder as embossed on the card.
`cardExpiryMonth`	`String` 2-digit expiry month (`01`–`12`).
`cardExpiryYear`	`String` 4-digit expiry year (e.g. `2029`).
`cardMode`	`String` Card type: `CC` (Credit Card) or `DC` (Debit Card).

Conditional parameters

Parameter	Description
`authRefNumber`	`String` Authorization Reference Number provided by issuing bank / card network during customer authentication. Mandatory for RuPay and AMEX (AEVV) tokenization; optional for Visa and Mastercard.

Sample Request

curl --location --request POST '<redacted URL>' \
--header 'Content-Type: application/json' \
--header 'Date: Mon, 05 Oct 2026 08:30:00 GMT' \
--header 'Authorization: hmac username="merchant_key", algorithm="sha512", headers="date", signature="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"' \
--data-raw '{
  "userCredential": "sms:user12345",
  "cardNumber": "5123456789012346",
  "cardName": "John Doe",
  "cardExpiryMonth": "12",
  "cardExpiryYear": "2029",
  "cardMode": "CC",
  "authRefNumber": "AUTH12345678"
}'

import requests
import json

url = "<redacted URL>"

payload = {
    "userCredential": "sms:user12345",
    "cardNumber": "5123456789012346",
    "cardName": "John Doe",
    "cardExpiryMonth": "12",
    "cardExpiryYear": "2029",
    "cardMode": "CC",
    "authRefNumber": "AUTH12345678"
}

headers = {
    "Content-Type": "application/json",
    "Date": "Mon, 05 Oct 2026 08:30:00 GMT",
    "Authorization": 'hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'
}

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

<?php
$curl = curl_init();

$payload = json_encode([
  "userCredential" => "sms:user12345",
  "cardNumber" => "5123456789012346",
  "cardName" => "John Doe",
  "cardExpiryMonth" => "12",
  "cardExpiryYear" => "2029",
  "cardMode" => "CC",
  "authRefNumber" => "AUTH12345678"
]);

curl_setopt_array($curl, [
  CURLOPT_URL => '<redacted URL>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Date: Mon, 05 Oct 2026 08:30:00 GMT',
    'Authorization: hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;

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

public class SaveCard {
    public static void main(String[] args) throws Exception {
        String payload = """
        {
          "userCredential": "sms:user12345",
          "cardNumber": "5123456789012346",
          "cardName": "John Doe",
          "cardExpiryMonth": "12",
          "cardExpiryYear": "2029",
          "cardMode": "CC",
          "authRefNumber": "AUTH12345678"
        }
        """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("<redacted URL>"))
            .header("Content-Type", "application/json")
            .header("Date", "Mon, 05 Oct 2026 08:30:00 GMT")
            .header("Authorization", "hmac username=\"merchant_key\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

const axios = require('axios');

const data = {
  userCredential: "sms:user12345",
  cardNumber: "5123456789012346",
  cardName: "John Doe",
  cardExpiryMonth: "12",
  cardExpiryYear: "2029",
  cardMode: "CC",
  authRefNumber: "AUTH12345678"
};

const config = {
  method: 'post',
  url: '<redacted URL>',
  headers: { 
    'Content-Type': 'application/json',
    'Date': 'Mon, 05 Oct 2026 08:30:00 GMT',
    'Authorization': 'hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'
  },
  data: data
};

axios(config)
  .then(response => console.log(JSON.stringify(response.data)))
  .catch(error => console.error(error));

Response Parameters

Parameter	Type	Description
status	Integer	Status flag: `1` (Success) or `0` (Failure).
message	String	Descriptive message detailing the operation outcome.
cardToken	String	Unique token identifier generated by PayU Vault for the stored card. Use this token in subsequent payment requests.
cardNo	String	Masked card number (e.g. `512345XXXXXX2346`).
cardType	String	Card network brand (e.g. `MAST`, `VISA`, `RUPAY`, `AMEX`).
cardCategory	String	Category of card: `CC` or `DC`.
cardExpiryYear	String	4-digit card expiry year.
cardExpiryMonth	String	2-digit card expiry month.
isExpired	Boolean	Indicates whether the card is expired (`true` / `false`).
networkToken	String	Network-generated token (returned if tokenization was processed via card network and merchant has requisite PCI-DSS permissions).
issuerToken	String	Issuer-generated token (returned for supported issuing banks).

Sample Response (Success)

{
  "status": 1,
  "message": "Card saved successfully",
  "cardToken": "29850879bf39848ca078727b8e1a95165a41cea1",
  "cardNo": "512345XXXXXX2346",
  "cardType": "MAST",
  "cardCategory": "CC",
  "cardExpiryYear": "2029",
  "cardExpiryMonth": "12",
  "isExpired": false
}

Sample Response (Failure)

{
  "status": 0,
  "message": "CardNumber is invalid"
}

Next Steps

Store Card Token:
- Save the returned cardToken in your database linked to the customer's profile for 1-click checkout.
Retrieve Customer Cards at Checkout:
- Use the Get User Cards API or Get Payment Instrument API to show saved cards on your payment screen.
Execute Payment with Saved Card:
- Pass the cardToken and cvv in the Process Transaction with a Saved Card API.