Vault

The BR-DGE Vault allows you to save your customers from having to re-enter card details while also increasing approval rates.

For a list of PSPs that support BR-DGE Vault please get in contact with support.

Creating Card on Files

Card on Files can be created via our REST API, Hosted Payment Page or Web SDK.

Things to note when creating Card on Files:

• It is the merchant's responsibility to meet the Credentials On File Mandate requirements around gaining informed consent prior to saving card details.
• Some Issuing Banks will automatically return a 3-D Secure challenge the first time a Card on File is used in a payment. Therefore, please ensure your integration supports the 3-D Secure Payment Flow if not using the Hosted Payment Page.

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

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

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

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

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

Making Cardholder-Initiated-Transactions (CITs) using Card on File

CITs are transactions made with the active participation of cardholders.

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

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

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

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

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

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.
  }
)

Making Merchant-Initiated-Transactions (MITs) using Card on File

Merchant Initiated Transactions (MITs) are transactions initiated by a merchant without the active participation of a cardholder. This can be useful for recurring payments such as subscriptions or for taking automated payments for services.

To maximize transaction approvals we recommend the following best practices:

Step 1: Enter into MIT agreement with a cardholder

Merchants are required to enter into an appropriate agreement with cardholders before performing transactions without their active participation.

Step 2: Perform an initial payment

The first payment for an MIT agreement must occur with the cardholder present. This transaction should be flagged as MIT and have 3-D Secure authentication enabled.

You can either use an existing Card-on-File or create a new one (see Creating Card-on-Files). The process for performing an initial payment for an MIT agreement varies depending on how you choose to integrate with BR-DGE. Please note that you can use the same BR-DGE Card-on-File for multiple MIT agreements.

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

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

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

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

Step 3: Performing subsequent MITs

Subsequent MITs should be made via the POST /v1/payments endpoint and in accordance with your agreement with the cardholder. These transactions should be linked back to the payment ID, and use the same Card-on-File, as the initial payment.

{
  "merchantInitiated": "recurring",
  "merchantInitiatedDetails": {
    "previousPaymentId": "22669f90-5bf0-45df-ba8c-ea6d4235a5da"
  },
  "paymentInstrument": {
    "type": "tokenized",
    "token": "5caa5a2a-be0b-4160-ae21-1bbbf2267f4c"
  },
  ...
}

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

Helping Cardholders Identify Their Card on File

Cardholders will need some way of identifying which credit/debit card is represented by a BR-DGE Card on File. In order to help with this, while still complying with PCI-DSS SAQ-A, obfuscated card details are
provided when creating Card on Files and also when querying [v1/payment-instruments]. This gives you the option of letting BR-DGE keep track of who owns each card, or you can maintain your own database.

Example obfuscated card data returned by GET /v1/payment-instruments:

"example-token-1": {
   "cardType": "VISA",
   "nameOnCard": "John F Doe",
   "pan": "#### #### #### 1111",
   "expiryDate": "06-30",
   "startDate": "01-20",
   "issueNumber": 0,
   "customerId": "example-customer-id"
},

Deleting Card on Files

Card on Files can be deleted via the DELETE /v1/payment-instruments endpoint.

Credentials on File Mandate Compliance

Card payment networks such as Visa and Mastercard have introduced Credential on File (CoF) requirements to provide greater visibility for all parties into transaction processing. This makes it easier to identify initial storage and
subsequent usage of stored credentials to determine the risk level. Providing these details will increase the approval rate and improve the cardholder experience. If you offer cardholders the option to store their credentials for future use or for recurring payments, it’s required to have cardholder consent.

BR-DGE automates compliance with most CoF requirements, but as merchants your responsibilities include:

• Obtaining cardholders’ consent to store the credentials,
• Disclosing to cardholders how those credentials will be used,
• Notifying cardholders when any changes are made to the terms of use.

For more information please refer to the "Consent Agreement Provision" section of Visa's "Stored Credential Transaction Framework" and the "Credential-on-File Transactions" section of "MasterCard Transaction Processing Rules".

Vault Interoperability

BR-DGE provides vault interoperability by providing you with PSP tokens during BR-DGE payment flows. This allows you to have contingencies in place in case you wish to process payments directly with PSPs.

The PSP token shall be returned as part of the payment response when a BR-DGE Card-on-File is first used with each PSP connected to your retail channel. It can also be retrieved by querying the BR-DGE Card On File itself and, finally, it will also be available via webhooks.

This feature needs to be enabled on your retail channel(s).