Guides

Vault Import via BR-DGE API

Suggest Edits

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

Once you have completed the steps in this guide your card data will have migrated from your existing Payment Service Provider (PSP) to BR-DGE.

This guide is applicable in scenarios where:

  • Your sensitive card data is stored in a PSP’s vault
  • The PSP has provided a token to you that represents the sensitive card data and is used to make payments through that 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.

Before initiating the migration, ensure you have the following:

  • Active BR-DGE Account: A prerequisite for utilizing 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 BR-DGE Customer Support team to add to your Retail Channel configuration. These credentials authorize BR-DGE to interact with your PSP on your behalf and are essential for successful token retrieval.

  • Understanding of API Calls and Rate Limits: Familiarity with making API requests, and knowledge of rate limits imposed by BR-DGE and your PSP.

Step-by-Step Migration Process

  1. Endpoint and Parameters:

The /payment-instruments endpoint is used to generate and store tokens. In this scenario, we'll use it with the IMPORTPSPTOKEN body parameter to import existing PSP tokens into the BR-DGE vault.

Method: POST

Body Parameters:

  • type: Must be set to IMPORTPSPTOKEN.
  • pspId: The identifier of your current PSP.
  • token: The unique identifier of the payment instrument token from your current PSP.

Currently, only Cybersource tokens are supported via this endpoint. Use CYBER in the pspId parameter

  1. Preparing the API Call:

  • Authentication: Ensure you include the necessary authentication headers in your API request. This might involve using API keys or tokens provided by BR-DGE.

  • Request Body: Construct the request body with the parameters as described above.

Example using cURL:

curl --request POST \
     --url https://sandbox.comcarde.com/v1/payment-instruments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer oatzjxsq8QsTgjWOAO...' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "importPspToken",
  "pspId": "CYBER",
  "token": "7040000000055884910"
}

  1. BR-DGE uses the provided token to retrieve the sensitive card details from your PSP. We will store them in our vault and generate and return a BR-DGE token.

  2. Handling the Response:

Successful Response (200 OK):

The response will contain a JSON object with the BR-DGE token identifier.

Example JSON:

{
  "id": "ea3a972d04a69005",
  "token": "4eced175-3d56-492d-ad38-230f90180ea1",
  "tokenType": "CARD",
  "cardType": "VISA",
  "nameOnCard": "John F Doe",
  "pan": "************1111",
  "expiryDate": "01-99"
}
  • Store the token securely. This is what you will use for future payment transactions through BR-DGE (See the tokenized payment instrument object in POST /payment).

Error Responses:

If there is an error, the response will include an error code and message.

Common errors include:

  • Invalid PSP token - check your data and formats match what your PSP is expecting

  • Authentication failure with the PSP - check your keys and config are correct

  • Internal server error - try again and raise with Customer Support if the error persists

Rate Limits:

  1. Repeat the Process:

Repeat steps 2 and 3 for each PSP token you need to migrate.

  1. Updating Your Systems:

Once you have migrated all your tokens, update your systems to use the new BR-DGE token identifiers for all future payment transactions.

Card data is now successfully stored in the BR-DGE vault and can be removed from your PSP vault if desired.

Important Considerations

  • Security: Ensure that you handle the BR-DGE token identifiers securely. Avoid storing them in plain text.

  • Testing: Thoroughly test the migration process in a staging or test environment before migrating production data.

  • Error handling: Implement robust error handling in your application to gracefully handle any issues during the migration process.

  • Customer Notification: Consider notifying your customers about the migration.

Rate Limit Management:

  • Carefully review the rate limits imposed by both BR-DGE and your PSP.

  • Consider migrating tokens in batches to avoid exceeding rate limits.

  • Implement retry logic with exponential backoff to handle 4290 errors.

  • Monitor your API usage to ensure you are staying within the rate limits.

Support

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

Updated 1 day ago