Guides

Vault Interoperability

Suggest Edits

BR-DGE provides Vault Interoperability by providing you with PSP tokens during the BR-DGE tokenization flow. This allows you to have contingencies in place in case you wish to process payments directly with PSPs.

You can use BR-DGE’s Vault Interoperability feature to create Payment Service Provider (PSP) tokens for your Card-on-Files. When this feature is enabled, every time you create a BR-DGE Card-on-File the platform will asynchronously tokenize the card at PSPs you have nominated, and provide you with the relevant token you can use in direct payments via those PSPs. To enable this feature on your retail channels get in contact with support.

Once provisioned the PSP tokens will be visible when you query the associated BR-DGE Card-on-Files via our GET /v1/payment-instruments API endpoint. You can also subscribe to be notified via webhooks. Please see the Notifications section for more information.

You can use the below endpoints to trigger the creation of a PSP token:

If any PSP tokens fail to be created, the next time you query the status or make a payment with the Card-on-File, we will asynchronously retry the creation of any unprovisioned or failed PSP tokens. If you are configured to receive notifications, you will receive a "PSP Provisioning Failed" notification when a PSP token fails to be created. For more information, please see the Notifications section.

In the event of interruption of BR-DGE services, you can process transactions directly with a PSP. During such times, a new Card-on-File information can be tokenized directly with the PSP, but BR-DGE will not have access to these tokens. Once BR-DGE services are recovered, you can process payments and payouts using the PSP tokens on the BR-DGE platform. We recommend that you migrate the tokenized instruments into the BR-DGE Vault once services are recovered and not continue to make payments using PSP tokens for an extended period of time.

To use BR-DGE’s Vault Interoperability feature, it will need to be enabled on your retail channel(s). Please get in contact with support for more information.

POST /v1/payment-instruments

PSP tokens will be created when you create a new Card-on-File using POST /v1/payment-instruments. For more information, please look at the pspTokens object in the example response “token with PSP Tokens”.

GET /v1/payment-instruments

PSP tokens will be created when you query the status of a Card-on-File using GET /v1/payment-instruments. For more information, please look at the pspTokens object in the example response “BR-DGE Card-on-File with PSP tokens”.

POST /v1/payments

PSP tokens will be created when you create a payment using a saved Card-on-File via POST /v1/payments.

Tokens created with the PSP can be used to make a payment via POST /v1/payments by using a PspTokenInstrument Payment Instrument.

POST /v1/payouts

Tokens created with the PSP can be used to make a payout via POST /v1/payouts by using a PspTokenInstrument Payment Instrument.

Token Provisioning Status Flow

Notifications

If you are configured to receive notifications then you will receive one at the end of the provisioning process. This means that every time there is an attempt to create a PSP Token, you will be notified with "PSP Token Status Change" or "PSP Provisioning Failed" events. You can navigate to these callbacks in the callbacks section at the bottom of the POST /v1/payments page.

Please get in contact with support to get set up with Notifications.

"PSP Token Status Change" Example

When BR-DGE provisions a PSP token it will generally enter an ACTIVE state indicating that it can be used in transactions with the PSP.

This change notification will contain:-

  • a response code of 1000
  • the associated multi use token
  • a psp object including
    • the PSP
    • the PSP Token ID
    • the card fingerprint (if the PSP returns that info)
    • the status of the token; ACTIVE

📘

To see an example, please go to POST /v1/payments and navigate to the "PSP Token Status Change Event" in the callbacks section at the bottom of the page.

"PSP Provisioning Failed" Example

The failure notification will contain:-

  • the PSP the attempt was for
  • the related BR-DGE multi-use token
  • the response code mapped from the PSP’s response

📘

To see an example, please go to POST /v1/payments and navigate to the "PSP Token Provisioning Failed Event" in the callbacks section at the bottom of the page.

Updated about 1 month ago