Card Data API

Using Card Data API, you can get card attributes before creating an order.

This is especially useful for precise campaign targeting based on card attributes (for example issuer, type, country). Thanks to the unique card identifier, you can also detect cases where the same user tries to save the same card on multiple accounts to reuse promotions or free trials.

With this API, you can get:

• card characteristics from BIN tables (Visa/Mastercard data), including:
  • scheme,
  • card type,
  • card classification,
  • card country,
  • issuer details (name and country),
  • and other fields described in the Retrieve Card Data API section,
• unique payment card identifier - stable for a physical PAN, especially useful with card tokenization when you want to detect whether a customer is reusing the same card,
• available installment options.

If you are interested in using Card Data API, contact your PayU account manager or PayU support team.

Integration using Card Token

To use Card Data API, the request must be authenticated at least with client_credentials or trusted_merchant level.

You do not need full card tokenization support to use this solution. It is enough to collect card data with Secure Form.

The API requires only the token field. You obtain it after successful card token creation (any type: SINGLE, SINGLE_LONGTERM, MULTI) using Secure Form. Such tokens always start with TOK_ or TOKD_.

You can call this API at any point in the payment lifecycle, with one limitation: SINGLE tokens are valid for up to 11 minutes.

If you already use card tokenization, you can retrieve and use card-on-file tokens (prefix TOKC_) in the same token field. In this case, you can call the API at any point during the token lifecycle.

Example Request Using Card Token

curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "TOK_1LPMUT7LMLPU0361cHh88Cr0hHnP"
  }'

Example Request Using Temporary Card Token (SINGLE)

curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "TOKD_1LPMUT4FPPSS9k46204E39L5S0k"
  }'

In response, you receive card attributes identified by the provided token.

Example Response

{
  "maskedNumber": "536447******6443",
  "expirationMonth": 8,
  "expirationYear": 2029,
  "scheme": "MC",
  "description": "World Debit Mastercard Card",
  "type": "MDH",
  "countryCode": "RO",
  "classification": "DEBIT",
  "profile": "CONSUMER",
  "uniqueReference": "b75ddfb250cd8d9a647fa787718ec67f3f984d54bb51432373427c0e874f68c42438945f330bd6be07f3b41fde422fb548ccbe23c9cb51d0c1792ec7004ed23e",
  "issuer": {
    "name": "SUPER BANK LIMITED",
    "region": "EUROPE",
    "countryCode": "RO"
  },
  "installmentOptions": {
    "numbers": [1, 6, 12, 20, 21, 22, 23, 24],
    "provider": "SUPERBANK"
  }
}

Detailed parameter descriptions are available in the Retrieve Card Data API section.

Integration using Card Data

PCI DSS Scope Required

This integration type is available only for entities that meet PCI DSS requirements and are approved to process card data on their side.

This integration also requires additional PayU-side configuration. Before implementation, contact your PayU account manager.

If you already collect card data in text form, you can use Card Data API by providing the payment card number (PAN) with expiration date.

If available in your flow, you can also provide a virtual account number (VAN) with its expiration date, for example from digital wallets such as Google Pay or Apple Pay.

The API request format is the same in both cases.

Example Request with Card Data

curl -X POST 'https://secure.payu.com/api/v2_1/cards/lookup' \
  -H 'Authorization: Bearer 52a0da5b-fc06-4e93-bf15-b97a35b627c9' \
  -H 'Content-Type: application/json' \
  -d '{
    "card": {
      "number": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2029
    }
  }'