Get User Cards API

The Get User Cards API fetches all active stored card tokens for a specific customer in PayU Vault, formatted with masked card numbers, card brands, and expiration metadata.

Endpoint & Environments

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

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 = '<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}"`;
  }

Query Parameters

The table has 2 rows, so here it is in Markdown format. Also, noting that no Example column was present in the original, it has been omitted:

Mandatory parameters

Parameter	Description
`userCredentials`	`String` Plaintext identifier representing merchant key and customer ID in format `<merchantKey>:<customerId>` (e.g. `sms:user12345`). URL-encoded in HTTP GET. Max 100 characters.

Optional parameters

Parameter	Description
`getSoftDeleted`	`Integer` Pass `1` to retrieve soft-deleted cards if permitted by merchant vault settings. Default is `0`.

Sample Request

curl --location --request GET '<redacted URL>' \
--header 'Date: Mon, 05 Oct 2026 08:30:00 GMT' \
--header 'Authorization: hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'

import requests

url = "<redacted URL>"
params = {
    "userCredentials": "sms:user12345"
}
headers = {
    "Date": "Mon, 05 Oct 2026 08:30:00 GMT",
    "Authorization": 'hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => '<redacted URL>',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    '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 GetUserCards {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("<redacted URL>"))
            .header("Date", "Mon, 05 Oct 2026 08:30:00 GMT")
            .header("Authorization", "hmac username=\"merchant_key\", algorithm=\"sha512\", headers=\"date\", signature=\"<SIGNATURE>\"")
            .GET()
            .build();

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

const axios = require('axios');

const config = {
  method: 'get',
  url: '<redacted URL>',
  headers: { 
    'Date': 'Mon, 05 Oct 2026 08:30:00 GMT',
    'Authorization': 'hmac username="merchant_key", algorithm="sha512", headers="date", signature="<SIGNATURE>"'
  }
};

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

Response Parameters

The endpoint returns an object with status, msg, and the user_cards array.

The table has 12 rows, so here it is in HTML format. Also, noting that no Required or Example columns were present in the original, the table has not been split and those columns have been omitted:

Parameter	Description
`status`	`Integer` Status indicator: `1` (Success) or `0` (Failure).
`msg`	`String` Outcome message.
`cardToken`	`String` Unique token identifier representing the stored card in PayU Vault.
`cardNo`	`String` Masked card number (e.g. `512345XXXXXX2346`).
`cardName`	`String` Cardholder name.
`cardType`	`String` Card network brand (e.g. `MAST`, `VISA`, `RUPAY`, `AMEX`).
`cardCategory`	`String` Card category: `CC` (Credit Card) or `DC` (Debit Card).
`cardExpiryYear`	`String` 4-digit card expiry year.
`cardExpiryMonth`	`String` 2-digit card expiry month.
`isExpired`	`Boolean` Indicates whether the card has expired.
`networkToken`	`String` Network-generated token identifier (returned if network token exists).
`issuerToken`	`String` Issuer-generated token identifier.

Sample Response (Success)

{
  "status": 1,
  "msg": "Cards fetched successfully",
  "user_cards": [
    {
      "cardToken": "29850879bf39848ca078727b8e1a95165a41cea1",
      "cardNo": "512345XXXXXX2346",
      "cardName": "John Doe",
      "cardType": "MAST",
      "cardCategory": "CC",
      "cardExpiryYear": "2029",
      "cardExpiryMonth": "12",
      "isExpired": false
    }
  ]
}

Sample Response (Failure)

{
  "status": 0,
  "msg": "No cards found for this user"
}

Next Steps

Populate Checkout UI:
- Render the returned list of saved cards with masked PANs and card brand icons.
Execute Saved Card Payment:
- Submit the selected cardToken and customer CVV to the Process Transaction with a Saved Card API.
Allow Customer to Remove Card:
- Provide a "Delete" button that triggers the Delete a Saved Card API.