v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB

Payment Instrument Tokenization

Retrieve information about Card-on-Files

You can also use this endpoint to query all Card-on-Files for a customer, if a customer identifier was provided when cards were saved.

Note: If multiple query params are provided, ALL will be used to constrain the results returned.

get/payment-instruments

Query parameters

customerIdstring

Case-sensitive identifier for your customer.

Note: Symbols such as back-ticks and carriage returns are not permitted.

tokensstring[]

Comma-separated list of multi-use tokens.

This is useful if you track associations between your customers and Card-on-Files yourselves, but still want to access obfuscated card details on demand

showPanLeadingCharsboolean

The leading six digits of a cards PAN are the issuer identification number (IIN) sometimes referred to as the "bank identification number (BIN)" which may be required for some use cases.

By default this information is not provided, but you can opt-in by setting this flag to true if you specifically need it.

E.g. 1234 56## #### 7890 instead of the default #### #### #### 7890

Response

Map of obfuscatedCards, keyed by their multi-use token.

idstring

The ID of this request. If you can include these when querying the outcome of individual requests, we can track down the root cause faster.

resultsobject

Map of obfuscated cards keyed by multi-use token

Example response

{
  "id": "example-response-trace-id",
  "results": {
    "3d967f3e-8710-4c2b-9828-28b9531617f1": {
      "cardType": "VISA",
      "nameOnCard": "John F Doe",
      "pan": "#### #### #### 1111",
      "expiryDate": "06-30",
      "startDate": "01-20",
      "issueNumber": 0,
      "customerId": "example-customer-id",
      "tokenType": "CARD",
      "metadata": {
        "metadataType": "cardMetaData",
        "cardBrand": "VISA",
        "issuer": "ACMEBANK",
        "type": "DEBIT",
        "category": "CLASSIC",
        "countryIsoA2": "GB",
        "commercial": true,
        "bin": "45678765"
      },
      "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
      "fingerprintExtended": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60630"
    },
    "example-token-2": {
      "cardType": "MASTERCARD",
      "nameOnCard": "Jane Doe",
      "pan": "#### #### #### 1234",
      "expiryDate": "07-31",
      "startDate": "09-21",
      "issueNumber": 2,
      "customerId": "example-customer-id",
      "tokenType": "CARD",
      "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
      "fingerprintExtended": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60731"
    },
    "4c5f1e1d-a8d4-403c-8199-e9705da98735": {
      "cardType": "MASTERCARD",
      "nameOnCard": "John F Doe",
      "pan": "#### #### #### 4321",
      "expiryDate": "02-29",
      "startDate": "10-20",
      "customerId": "example-customer-id",
      "tokenType": "CARD",
      "metadata": {
        "metadataType": "cardMetaData",
        "cardBrand": "MASTERCARD",
        "type": "DEBIT",
        "countryIsoA2": "GB",
        "bin": "45678765"
      },
      "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
      "fingerprintExtended": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c60229"
    }
  }
}