Vault Import via BR-DGE API

This guide outlines the process of migrating existing payment tokens from another provider to the BR-DGE token vault using the /v1/payment-instruments endpoint with the importPspToken body parameter.

This guide is applicable in scenarios where:

• Your sensitive card data is stored in a PSP's vault.
• The PSP has provided you with a token that represents the sensitive card data and is used to make payments through the PSP (referred to as a PSP token in this guide).
• The PSP supports API migration to BR-DGE.

Prerequisites

• Consult BR-DGE: It is highly recommended that you speak with BR-DGE or discuss any specific requirements before using the API for token migration. This will help ensure a smooth and successful integration.
• Active BR-DGE Account: A prerequisite for utilising BR-DGE services.
• PSP Token Identifiers: Unique identifiers representing the card details you wish to migrate from your current provider.
• Secure Credentials: Secure credentials, such as API keys or authentication tokens, must be provided to the BR-DGE Customer Support team to add to your Retail Channel configuration. These credentials authorise BR-DGE to interact with your PSP on your behalf and are essential for successful token retrieval.

PSP-Specific Prerequisites

Worldpay (WPG)

• Functionality Enablement: You must explicitly enable the detokenisation functionality with Worldpay on your account.
• Encryption Keys: BR-DGE requires an RSA key pair to decrypt the PAN received in the response from Worldpay. BR-DGE will generate these keys, and you will need to provide Worldpay with the public key per account.

Cybersource (CYBER)

• Message-Level Encryption (MLE): PAN data is securely encoded within a JSON Web Token (JWT) sent by Cybersource. BR-DGE will provide you with a public key to configure the Token Management Service Onboarding (Message-Level Encryption Keys) on your Cybersource account. BR-DGE uses the corresponding private key to decode the encrypted JWT and extract the PAN, Expiry Date, and Name on Card.

Step-by-Step Migration Process

Endpoint and Parameters

The /v1/payment-instruments endpoint is used to generate and store tokens. In this scenario, we use it to import existing PSP tokens into the BR-DGE vault, creating a multi-use token.

Method: POST

Body Parameters

Example Request — Cybersource

{
  "type": "importPspToken",
  "pspId": "CYBER",
  "token": "7030000000055884910"
}

Example Request — Worldpay

{
  "type": "importPspToken",
  "pspId": "WPG",
  "token": "7040000000055884910",
  "customerId": "unique-shopper-id-123"
}

📘

Worldpay: customerId is required

For Worldpay, customerId maps to the authenticatedShopperID at Worldpay. This field is required — requests will fail if it is missing or does not match the token.

Handling the Response

BR-DGE uses the provided payload to fetch the required data from your PSP's API (e.g., retrieving the encrypted PAN). We will decrypt and store the sensitive details in our vault, generating and returning a BR-DGE token.

Successful Response — 200 OK: The response will contain a JSON object with the BR-DGE multi-use token identifier and the associated card details.

Example Response

{
  "id": "ea3a972d04a69005",
  "token": "4eced175-3d56-492d-ad38-230f90180ea1",
  "tokenType": "CARD",
  "cardType": "VISA",
  "nameOnCard": "John F Doe",
  "pan": "************1111",
  "expiryDate": "01-99",
  "networkTokenProvisioningStatus": "PROVISIONING",
  "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6",
  "pspTokens": [
    {
      "pspName": "Cybersource",
      "tokenProvisioningStatus": "PROVISIONING"
    }
  ]
}

🚧

Store the token value securely

The token field in the response is your BR-DGE multi-use token. This is what you will use for all future payment transactions through BR-DGE.

Important Considerations for Cybersource Migrations

Cybersource's Token Management Service (TMS) utilises a multi-token architecture. It is vital to understand the distinction between these tokens to avoid breaking existing flows:

📘

Speak to your Technical Solutions Engineer

Please speak to your Technical Solutions Engineer at BR-DGE to ensure that the process can support your use case.

Troubleshooting & Rate Limits

Common Errors

Rate Limit Management

HTTP 429 — Rate Limit Exceeded: This indicates that you have exceeded the PSP's specific rate limit. BR-DGE maps the PSP's rate limit response directly to an HTTP 429 response code from our API.

Cybersource Constraints: Cybersource enforces a strict 100 requests-per-second rate limit per endpoint. Note that this limit applies independently, meaning endpoints used by your live payment flows will remain unaffected by the vault import process.

Best Practices:

• Migrate tokens in controlled batches to avoid exceeding rate limits.
• Implement a retry mechanism with exponential backoff to handle 429 errors smoothly without overloading the system.
• Monitor your API usage to ensure you are staying within the prescribed limits.

Support

If you encounter any issues or have questions, please contact BR-DGE support for assistance.