---
title: "Create a single-use token"
method: POST
path: "/payment-instruments/single-use"
tags: ["Payment Instrument Tokenization"]
---

# Create a single-use token

`POST /payment-instruments/single-use`

For one off payments you can exchange cardholder data for a single-use token that can be used as a payment instrument via the [Tokenized Payment Flow]

Card on File multi-use tokens can also be exchanged for single-use tokens. This can be useful if you wish to include CVV values in your payments as this data cannot be stored with Card on File.

[Tokenized Payment Flow]: https://docs.br-dge.io/docs/payment-flows#tokenized-payment-flow

## 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 — For use by BR-DGE SDK
    - `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 — Whether to synchronously enroll and provision a network token when creating this card-on-file.
    - `digitalWalletType` 'APPLE_PAY' | 'GOOGLE_PAY' | 'CLICK_TO_PAY' — The type of digital wallet, currently supports Apple Pay and Google Pay.
  - object — For use by BR-DGE SDK
    - `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.
    - `cv2` string — CV2 of the Tokenized payment instrument.
    - `updateStoredCredentialIndicator` 'USED' — When provided this updates the indicator of whether a card has been stored externally to our system, and if it has been used previously. Used for the situation where you have registered a card with our system, but used it externally before returning to our system to make a subsequent payment. 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 you do not use the card outside of the payment flow in our system before the first payment event, this feature can be ignored, as the standard used functionality will track this. This will effectively update the payment instrument's used status before creating the single use token, as such, if an update is needed it is only required on the first payment request in our system. This is related to [Credential on file mandate compliance]. ## Possible Values * 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 no updates are needed, and so the existing status will be used from our system. * The update value is only needed on the first payment on our system, subsequent calls will just result in extra processing. * This field is optional but *MUST* be filled when a card has been used outside our system before making a first payment inside our system. [Credential on file mandate compliance]: https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance
  - object — For use by BR-DGE SDK
    - `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.
    - `cv2` string — CV2 of the Tokenized payment instrument.
    - `updateStoredCredentialIndicator` 'USED' — When provided this updates the indicator of whether a card has been stored externally to our system, and if it has been used previously. Used for the situation where you have registered a card with our system, but used it externally before returning to our system to make a subsequent payment. 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 you do not use the card outside of the payment flow in our system before the first payment event, this feature can be ignored, as the standard used functionality will track this. This will effectively update the payment instrument's used status before creating the single use token, as such, if an update is needed it is only required on the first payment request in our system. This is related to [Credential on file mandate compliance]. ## Possible Values * 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 no updates are needed, and so the existing status will be used from our system. * The update value is only needed on the first payment on our system, subsequent calls will just result in extra processing. * This field is optional but *MUST* be filled when a card has been used outside our system before making a first payment inside our system. [Credential on file mandate compliance]: https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance
    - `apmProvider` 'VIS', required — An APM provider ID
    - `data` VisaInstallmentsApmData, required — For use by BR-DGE SDK
      - `planId` string — Visa-generated identifier for an Installment plan
      - `termsAndConditionsVersionNumber` integer — Version number of the Terms and Conditions accepted by the user

## 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)