Vault Interoperability
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