---
title: "Create a Card-on-File"
method: POST
path: "/payment-instruments"
tags: ["Payment Instrument Tokenization"]
---

# Create a Card-on-File

`POST /payment-instruments`

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.

## Request body

- union
  - object — Payment instrument that is a credit or debit card.
    - `type` string, required — Discriminator field. Please see the discriminator mapping for the PaymentInstrumentRequest schema.
    - `customerId` string — Identifier for the merchant's customer who owns the payment instrument to be tokenized.
    - `nameOnCard` string — Name on the credit or debit card. This may be required by the payment services provider (PSP).
    - `pan` string, required — PAN of the credit or debit card.
    - `expiryDate` string, required — Card expiry date in MM-YY format.
    - `startDate` string — Start date of the credit or debit card.
    - `issueNumber` integer — Issue number of the credit or debit card.
    - `cv2` string
    - `pspTokens` PspToken[] — A set of PSP tokens linked to this Card-on-File
      - `pspName` string — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations
      - `token` string — The token generated by the PSP
      - `pspCardFingerprint` string — The PSP fingerprint for the payment instrument (if available)
      - `tokenProvisioningStatus` 'UNPROVISIONED' | 'PROVISIONING' | 'FAILED' | 'PROVISIONED' — The status of the PSP token provisioning. It can be one of the following states: - `UNPROVISIONED`: A PSP token has not attempted to be provisioned for this payment instrument. - `PROVISIONING`: Provisioning has been triggered but is not completed. - `FAILED`: Provisioning has failed, and could not be completed. - `PROVISIONED`: Provisioning was successful, and a PSP token is available for use.
      - `additionalData` PspTokenAdditionalData — Additional fields which may be returned for a subset of PSPs when provisioning a PSP token.
        - `customerToken` string — A token which represents customer information stored with the PSP. This field is only returned if a `customerId` was provided when provisioning the BR-DGE Card-on-File.
        - `instrumentIdentifierToken` string — A token which represents a card number stored with the PSP.
    - `storedCredentialIndicator` 'USED' | 'UNUSED' — Indicates whether a card has been stored externally to our system, and if it has been used previously. Used for the situation where you have previously used and stored the card outside our system. This will override the value sent to the card networks, (e.g. Visa/Mastercard) on the *first* time the card is used within our systems. If your systems don't ever store card details *this field should be ignored*. When sent to us this affects the first time the tokenized card is used within our systems. In the case of a card that you never want tokenized with us, but is tokenized externally, we will require the correct value on every call. This is related to [Credential on file mandate compliance](https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance). ## Possible Values * UNUSED - The card has not been previously used in a transaction, this is used as a hint to the networks that the card will be stored from this point onward. * USED - The card has been previously used in a transaction on your systems, this lets the networks know that this is a previously stored card. *Usage Notes:* * Not sending a value for this implies that you have not stored the card for reuse within your systems. * If your company never stores cards for reuse then there is no need to ever send a value for this field. * This field is optional but *MUST* be filled when using a previously/externally stored card.
    - `networkTokenProvisioning` 'async' | 'networkToken' | 'networkTokenWithCryptogram' — Whether to synchronously or asynchronously enroll and provision a network token and optionally include the cryptogram in the response when creating a card-on-file. If unspecified and, if the retail channel is enabled for network tokenization, the `async` behaviour will be used by default. This field accepts the following values: - `async` - Asynchronously enrolls a card, a network token card number will be available once a cryptogram is provisioned. - `networkToken` - Synchronously enrolls a card and provisions a network token when creating the card-on-file. - `networkTokenWithCryptogram` - Synchronously enrolls a card and provisions a network token when creating the card-on-file, providing the resulting cryptogram in the same response.
  - object — An existing PSP token to be imported into BR-DGE.
    - `type` string, required — Discriminator field. Please see the discriminator mapping for the PaymentInstrumentRequest schema.
    - `customerId` string — Identifier for the merchant's customer who owns the payment instrument to be tokenized.
    - `token` string, required — The token that represents a payment instrument.
    - `pspId` string, required — The PSP associated with the token to be imported.

## Response `201`

Successful tokenization of payment instrument

- TokenResponse — Information about card payment instruments. This can be used to help cardholders identify which of their cars were used (without becoming PCI sensitive) in addition to the metadata providing useful insights for merchants.
  - `id` string, 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.
  - `token` string, required — Identifier for the tokenized Payment Instrument
  - `tokenType` string — Always `CARD`
  - `cardType` string — Please use `metadata`.`cardBrand` instead. This field is now deprecated and will be removed in a future update.
  - `nameOnCard` string — Name on the credit or debit card.
  - `pan` string — PAN of the credit or debit card in obfuscated form.
  - `expiryDate` string — Card expiry date in MM-YY format.
  - `startDate` string — Start date of the credit or debit card.
  - `issueNumber` integer — Issue number of the credit or debit card.
  - `customerId` string — ID of the merchant's customer who owns the payment instrument (if available)
  - `pspTokens` object[] — A set of PSP tokens linked to this Card-on-File
    - `pspName` string — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations
    - `token` string — The token generated by the PSP
    - `pspCardFingerprint` string — The PSP fingerprint for the payment instrument (if available)
    - `tokenProvisioningStatus` 'UNPROVISIONED' | 'PROVISIONING' | 'FAILED' | 'PROVISIONED' — The status of the PSP token provisioning. It can be one of the following states: - `UNPROVISIONED`: A PSP token has not attempted to be provisioned for this payment instrument. - `PROVISIONING`: Provisioning has been triggered but is not completed. - `FAILED`: Provisioning has failed, and could not be completed. - `PROVISIONED`: Provisioning was successful, and a PSP token is available for use.
    - `additionalData` PspTokenAdditionalData — Additional fields which may be returned for a subset of PSPs when provisioning a PSP token.
      - `customerToken` string — A token which represents customer information stored with the PSP. This field is only returned if a `customerId` was provided when provisioning the BR-DGE Card-on-File.
      - `instrumentIdentifierToken` string — A token which represents a card number stored with the PSP.
  - `fingerprint` string — A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument.
  - `fingerprintExtended` string — A fingerprint with card expiry date appended in MMYY format.
  - `cardArtUri` string, uri — URI to card art
  - `metadata` PaymentInstrumentMetadata — If a card payment instrument is used then BR-DGE may be able to provide metadata about the card **Please note: All text will be UPPERCASE and all fields can be null**
    - `metadataType` string — Discriminator field. Discriminator field. Please see the discriminator mapping for the PaymentInstrumentMetadata schema.
    - `cardBrand` string — MASTERCARD, VISA, etc
    - `issuer` string — Name of issuing bank
    - `type` 'DEBIT' | 'CREDIT' | 'CHARGE_CARD' | 'CHARGE' | 'DEFERRED_DEBIT' | 'PREPAID' | 'PREPAID_RELOADABLE' | 'UNKNOWN'
    - `category` string — CLASSIC, BUSINESS, MIXED_PRODUCT, etc
    - `countryIsoA2` string — ISO 3166 Alpha-2 Country code
    - `commercial` boolean — Indicates if the card is corporate or retail
    - `bin` string — The Bank Identification Number that identifies the bank or financial institution that issued the card
  - `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.
  - `networkToken` NetworkTokenWithCryptogram — Information about a Network Token.
    - `id` string, required — A unique identifier that represents the token associated with a card enrolled into the Card Network Service
    - `token` string — The unique token for the enrolled PAN which can be used in authorization as per ISO/IEC 7812 format. This will only be available once a cryptogram has been provisioned at least once.
    - `expiryDate` string, required — Expiration date of the token, noted in MM-YY format
    - `issuer` 'MASTERCARD' | 'VISA', required — The issuing card network of the Network Token
    - `status` 'ACTIVE' | 'DISABLED' | 'DELETED', required — The status of the Network Token. - `ACTIVE`: Can be used to provision Cryptograms for payments. - `DISABLED`: This can be due to card suspensions, fraud, or other temporary hold reasons and may be re-activated at a later date. - `DELETED`: The token is no longer valid and cannot be re-activated. This can be due to token expirations, lost card or other non-temporary reasons.
    - `tokenUniqueReference` string, required — Unique identifier for the Network Token provided by the Card Network
    - `paymentAccountReference` string, required — A non-financial reference assigned to each unique funding PAN (FPAN) that's used to link the payment account of that PAN to affiliated payment tokens. See our [dedicated PAR guide](https://docs.br-dge.io/docs/payment-account-reference) for more info.
    - `lastFour` string — Last four digits of the Network Token
    - `cardBin` string — BIN of the associated associated Card
    - `cardLastFour` string — Last four digits of the associated Card
    - `cardExpiryDate` string — Expiration date of the associated Card, noted in MM-YY Format
    - `cardIssuer` string — Name of the issuing bank
    - `cryptogram` NetworkTokenCryptogram
      - `cryptogram` string, required — The cryptogram value, from the provider of the Network Token. This value is one time use, for subsequent payments a new cryptogram should be retrieved.
      - `eci` string, required — The electronic commerce indicator (ECI).
    - `cryptogramProvisioningStatus` 'FAILED' | 'PROVISIONED' — A cryptogram provisioning status is only given when provisioning is attempted while synchronously provisioning a network token. As cryptogram provisioning is a synchronous operation, this status will never be `PROVISIONING`. The status of the network token cryptogram provisioning. It can be one of the following states: - `FAILED`: Provisioning has failed. The provisioning could not be completed. - `PROVISIONED`: Provisioning was successful, and a NT cryptogram is available for use.
  - `associatedMultiUseToken` string — Multi-use token associated with the card

## Other responses

- `400` — Unsuccessful tokenization of payment instrument - bad request
- `500` — An internal server error occurred upstream while processing the request. If you have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at <https://comcarde.atlassian.net/servicedesk/customer/portals> with the `id` from the response so we track down the individual requests on our end.

---

[API](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api.md) · [All operations](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/br-dge/br-dge-transaction-rest-api/revisions/a9c0feac5523/schema)