Vault Introduction

Card on Files can be created using the POST /v1/payment-instruments endpoint.

Example request:

{
  "type": "card",
  "pan": "4444 3333 2222 1111",
  ...
}

Example response:

{
  "token": "01ed22f0-5f16-47ba-945f-abfacc59777c",
  ...
}

Alternatively, if making payments using the Card Payment Flow you can set a flag in calls to POST /v1/payments which will result in multi-use tokens (Card on File) being generated.

Example request:

{
  "paymentInstrument": {
    "type": "card",
    ...
    "tokenize": true // flag to create Card on File
  },
  ...
}

Example response:

{
  "token": "e2379d46-4fff-4e6f-b9af-6dab64877d60",
  ...
}

Please see the Payment with Card Payment Instrument and Create Card on File example request in POST /v1/payments.

🚧

Tokenizing card details directly via the BR-DGE REST API requires merchants to handle cardholder data and therefore be PCI DSS SAQ D compliant. Merchants who wish to avoid handling cardholder data please use the Payment Page or Web SDK.

Merchants who choose to fully outsource their payment page to BR-DGE using our customizable Hosted Payment Page can also use it to create Card on Files. For more information please see BR-DGE Hosted Payment Page - Creating new Card on Files.

Merchants who use the BR-DGE Hosted Fields Module to outsource cardholder data collection can configure the module to create Card on Files.

hostedFieldsInstance.tokenize(
  {
    customerAgreedToSaveCard: true,
    customerId: 123, // optionally associated Card on File to a customer ID
  },
  function (tokenizeErr, payload) {
    // payload.savedCard.token contains a multi-use token for Card on File
  }
)

Please see BR-DGE Hosted Fields Module for more information.

Card on File multi-use tokens can be directly used as payment instruments via the POST /v1/payments endpoint.

{
  "paymentInstrument": {
    "type": "tokenized",
    "token": "5caa5a2a-be0b-4160-ae21-1bbbf2267f4c", // multi-use token
  }
  ...
}

If you are PCI DSS SAQ D compliant then you can also pass a CVV value.

{
  "paymentInstrument": {
    "type": "tokenized",
    "token": "5caa5a2a-be0b-4160-ae21-1bbbf2267f4c", // multi-use token
    "cv2": 123
  }
  ...
}

If you are not PCI DSS SAQ D compliant it is still possible to collect CVV data via the Web SDK or Payment Page

Orders can be configured to offer the ability to pay with new or existing Card on Files

When creating an order via the POST /v1/orders endpoint you can specify a set of Card on File multi-use tokens which will result in the Card on Files being offered as payment methods when your customer views the payment page.

{
  "tokens": "multi-use-token-1,multi-use-token-2"
  ...
}

Alternatively you can associate an order with a customer identifier which will result in any Card on Files associated with that customer being offered as payment methods.

{
  "customerId": "example-customer-id",
  ...
}

You will be able to see whether a successful CIT was performed and retrieve a multi-use token for use in MITs when you query the status of the order via the GET /v1/orders/{orderId}/status endpoint.

{
  "cardOnFileTokenCreated": "12ac7fb1-f2b0-47bd-bf8b-d4853ad45851",
  ...
}

Please see BR-DGE Hosted Payment Page - Card on File for more information.

Merchants who wish to avoid directly collecting cardholder data in order to minimize PCI compliance costs can use BR-DGE Hosted Fields convert a Card on File multi-use token into a single-use token while collecting a CVV.

hostedFieldsInstance.tokenizeSavedCard(
  {
    token: 'multi-use-token', // for selected saved card
  },
  function (tokenizeErr, payload) {
    // send payload.token to your server to be used as a tokenized payment
    // instrument in a payment request.
  }
)

Please see BR-DGE Hosted Fields - Using a Card on File for more information.

Make a call to POST /v1/payments using the Card-on-File you wish to use for the MIT agreement while also flagging the transaction as an initial payment for MIT and enabling 3-D Secure
authentication.

{
  "paymentInstrument": {
    "type": "tokenized",
    "token": "8545ef1e-1464-40e3-b605-2e0d5bda792e"
  },
  "merchantInitiated": "unscheduled",
  "merchantInitiatedDetails": {
    "initialPayment": true
  },
  "threeDSecureRequired": true,
  ...
}

Please see the Initial payment with Tokenized Card Payment Instrument for MIT agreement example request in POST /v1/payments.

Hosted Payment Page orders can be configured to act as an initial payment for an MIT agreement by

1. Flagging the order as an MIT via the merchantInitiated field.
2. Enabling 3-D Secure authentication via the threeDSecureRequired field.
3. Ensuring that your customer uses a Card-on-File using the BR-DGE Hosted Payment Page - Vault features.

Using an existing Card-on-File

If you already know which Card-on-File you wish to use for an MIT agreement then set it as the only entry in the tokens field:

{
  "merchantInitiated": "unscheduled",
  "allowedPaymentInstruments": [
    "card"
  ],
  "tokens": "da000a2c-da85-4aed-843e-679dd6c7376f",
  "threeDSecureRequired": true,
  ...
}

Please see the Initial payment for an MIT agreement with an existing Card-on-File example request in POST /v1/orders and the BR-DGE Hosted Payment Page - Specifying a set of multi-use tokens section of the Hosted Payments Page guide.

Letting your customer create a new Card-on-File

If you want to give your customer the option of creating a new Card-on-File for use with the MIT agreement you can use the customerAgreedToSaveCard, cardOnFileSaveEnabled, and cardOnFileTermsAndConditionsUrl fields.

cardOnFileSaveEnabled: This field is necessary to control whether the Card-on-File option is enabled or not. If set to true, the system will allow the customer to save their card details for future use.

customerAgreedToSaveCard: This field determines how the Card-on-File option is presented to the customer. If enabled, it will prompt the customer to explicitly agree to save their card details. If not enabled, it will simply inform the customer that their card will be saved automatically.

cardOnFileTermsAndConditionsUrl: This optional field allows you to provide a link to the terms and conditions related to saving the card. It’s a good practice to include this to ensure transparency and compliance with legal requirements.

{
  "merchantInitiated": "unscheduled",
  "allowedPaymentInstruments": [
    "card"
  ],
  "cardOnFileSaveEnabled": true,
  "customerAgreedToSaveCard": true,
  "cardOnFileTermsAndConditionsUrl": "https://url/to-terms",
  "threeDSecureRequired": true,
  ...
}

Please see the Initial payment for an MIT agreement and create new Card-on-File example request in POST /v1/orders and the BR-DGE Hosted Payment Page - Creating a new Card-on-File section.

The multi-use token for the new Card-on-File will be included in the order status response:

{
  "cardOnFileTokenCreated": "12ac7fb1-f2b0-47bd-bf8b-d4853ad45851",
  ...
}

Please see the Card on File created example response in GET /v1/orders/{orderId}/status.

Please see the BR-DGE Hosted Fields - Web SDK Card on File section for information on how the BR-DGE Web SDK can assist in creating BR-DGE Card-on-Files for use in MITs, and the REST API tab for information on how to
use the Card-on-File to perform an initial payment.