v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB

Payment Instrument Tokenization

Create a Card-on-File

Further streamline your checkout experience by securely storing customer card details in BR-DGE to save them having to re-enter cardholder details in future.

A Network Token may be asynchronously provisioned if enabled on your Retail Channel. Merchants can track the status of Network Tokens via webhook callbacks or by querying the Card-on-Files via GET /payment-instruments.

Please see https://docs.br-dge.io/docs/vault for more information.

post/payment-instruments

Request body

Example request

{
  "type": "card",
  "nameOnCard": "John F Doe",
  "pan": "4444 3333 2222 1111",
  "expiryDate": "05-25",
  "startDate": "01-00",
  "issueNumber": 1,
  "pspTokens": [
    {
      "pspName": "Checkout.com",
      "tokenProvisioningStatus": "PROVISIONED",
      "additionalData": {
        "customerToken": "20C17E0D04D14D26E063A2598D0A4024",
        "instrumentIdentifierToken": "7010000000016241111"
      }
    }
  ]
}

Response

Successful tokenization of payment instrument

idstring required

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.

tokenstring required

Identifier for the tokenized Payment Instrument

tokenTypestring

Always CARD

cardTypestring

Please use metadata.cardBrand instead.

This field is now deprecated and will be removed in a future update.

nameOnCardstring

Name on the credit or debit card.

panstring

PAN of the credit or debit card in obfuscated form.

expiryDatestring

Card expiry date in MM-YY format.

startDatestring

Start date of the credit or debit card.

issueNumberinteger

Issue number of the credit or debit card.

customerIdstring

ID of the merchant's customer who owns the payment instrument (if available)

fingerprintstring

A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument.

fingerprintExtendedstring

A fingerprint with card expiry date appended in MMYY format.

cardArtUristring uri

URI to card art

networkTokenProvisioningStatus'UNPROVISIONED' | 'PROVISIONING' | 'FAILED' | 'PROVISIONED'

The status of the Network Token provisioning. It can be one of the following states:

UNPROVISIONED: A Network Token has not attempted to be provisioned, is not enabled or not valid for this payment instrument.
PROVISIONING: Provisioning has been triggered but is not completed.
FAILED: Provisioning has failed. The provisioning could not be completed.
PROVISIONED: Provisioning was successful, and a Network Token is available for use.

associatedMultiUseTokenstring

Multi-use token associated with the card

Example response

{
  "tokenType": "CARD",
  "cardType": "VISA",
  "nameOnCard": "John F Doe",
  "pan": "#### #### #### 1111",
  "expiryDate": "05-25",
  "startDate": "01-20",
  "customerId": "example-customer-id",
  "pspTokens": [
    {
      "pspName": "Checkout.com",
      "tokenProvisioningStatus": "PROVISIONED",
      "additionalData": {
        "customerToken": "20C17E0D04D14D26E063A2598D0A4024",
        "instrumentIdentifierToken": "7010000000016241111"
      }
    }
  ],
  "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
  "cardArtUri": "https://example.com/card-art/09a29968-f53f-4bdb-9744-6033996ee55f",
  "metadata": {
    "cardBrand": "MASTERCARD",
    "category": "CLASSIC",
    "countryIsoA2": "GB",
    "commercial": true,
    "bin": "48321456"
  },
  "networkTokenProvisioningStatus": "PROVISIONED",
  "networkToken": {
    "id": "WXdfRANqUrBalltlBKaaWHVGrFoWrIHsZAK",
    "token": "5186151969968300",
    "expiryDate": "08-26",
    "issuer": "MASTERCARD",
    "status": "ACTIVE",
    "tokenUniqueReference": "DM4MMC0000000001cd2826c715b7475bb089b7622366ebe4",
    "paymentAccountReference": "5001EUMYTT3AESCZGUEC77KPCLETI",
    "lastFour": "1234",
    "cardBin": "00123456",
    "cardLastFour": "1234",
    "cardExpiryDate": "08-26",
    "cardIssuer": "Bank of BR-DGE",
    "cryptogram": {
      "cryptogram": "Qwertyuio0987654321asdfghjklpois",
      "eci": "07"
    },
    "cryptogramProvisioningStatus": "PROVISIONED"
  },
  "associatedMultiUseToken": "4fg0498a-98cb-42ha-9g6a-06c7e63uc38f"
}