Connect to VISA DPS

This guide explains how to create a new card ID for VISA DPS using a primary account number (PAN). By the end of this guide, you’ll have successfully used Skyflow’s API to create an outbound connection with VISA DPS.

Before you start,

Log in to your Skyflow account. If you don’t have an account, you can sign up for a free trial account.
For trial accounts, log in to try.skyflow.com. For production accounts, log in to your dedicated sign in URL.
Select a vault that you have the Vault Owner role for. This vault must also have a compatible schema:
A simple vault schema with a table named “cards” and two columns named “pan” and “card_id” will work. The assumption is that you have previously stored an API bearer token in the vault and have access to the token that references this number.
The Vault Owner role (only Vault Owners can create connections)A new project on developer.visa.com that includes the
Corresponding mTLS private key and public key that are required to sign all REST requests to VISA DPS APIs.Basic Authorization header credentials from VISA. Learn more here.

The image below demonstrates the full process for how a new card ID for VISA DPS is created using a PAN:

Card issuer initiates the request: The card issuer requests a new debit card by sending a token that corresponds to a PAN to Skyflow.Skyflow requests a new debit card: Skyflow detokenizes the PAN token to get a plain-text PAN and then sends it to the Visa DPS service as part of a request to create a new card.Visa issues a card ID to Skyflow: Visa DPS service sends the card ID to Skyflow.Skyflow provides a card ID token to the issuer: Skyflow tokenizes the card ID, stores it in the card issuer’s Skyflow vault, and sends the token to the card issuer.

To create an outbound connection with VISA DPS, follow the steps below.

In Skyflow Studio, select the vault you want to create a connection for and click the Settings tab in the top menu > the Vault tab in the left menu > Service Accounts.



Click New Service Account.

Name the service account, assign it the Vault Owner role, and click Create.

Store the credentials.json file that downloads onto your local machine. Keep this file secure, as you'll need it in the next steps.

Generate an API bearer token using your service account credentials.

For more information on how to generate an API bearer token, check out API Authentication. Because you’ve already created a service account, you’ll skip to Step 2 of that guide.

For this example, you’ll create a new card ID associated with a specific PAN. It uses the create card ID API provided by VISA DPS here. This API endpoint requires the PAN number in the request body and responds with the newly created card ID in the response body.

Use the Create Outbound Connection API shown below to detokenize the PAN from the Skyflow vault before sending it over to the VISA DPS endpoint:

bash
curl -i -X POST 'https://manage.skyflowapis.com/v1/gateway/outboundRoutes' \
-H 'X-SKYFLOW-ACCOUNT-ID: $SKYFLOW_ACCOUNT_ID' \
-H 'Authorization: $BEARER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "baseURL": "https://sandbox.api.visa.com",
    "vaultID": "$VAULT_ID",
    "routes": [
        {
            "path": "/dcas/cardservices/v2/cards",
            "method": "POST",
            "requestBody": [
                {
                    "action": "DETOKENIZATION",
                    "fieldName": "primaryAccountNumber",
                }
            ],
            "responseBody": [
                {
                    "action": "TOKENIZATION",
                    "fieldName": "resource.cardId",
                    "table": "cards",
                    "column": "card_id"
                }
            ]
        }       
    ],
    "authMode": "MTLS"
}'

Replace the SKYFLOW_ACCOUNT_ID, BEARER_TOKEN, and VAULT_ID parameters.

To find the SKYFLOW_ACCOUNT_ID and VAULT_ID parameters, use Skyflow Studio to go to the Vault Dashboard. Click the three-dot menu for the vault, select Edit Vault Details. For help generating an API bearer token, check out API Authentication.

Send the request.

You should receive a response that looks similar to:

http code 200 OK
{"gatewayURL":"https://sb.area51.gateway.skyflowapis.dev/v1/outboundConnections/db884a16-6b33-42f6-b32d-861ed88d12b7","ID":"db884a16-6b33-42f6-b32d-861ed88d12b8"}

You just created a new connection to your vault!

This connection has a relative path defined as “/dcas/cardservices/v2/cards”, which expects a token that represents "primaryAccountNumber" (the PAN) in the request body.

The instruction given to the connection is to detokenize the token representing "primaryAccountNumber", replace it with the actual PAN number from the vault, and then forward the request to the VISA DPS endpoint “https://sandbox.api.visa.com/dcas/cardservices/v2/cards”.

In order for the connection to make an outbound call to VISA DPS, it must meet the request signature requirements defined by VISA DPS. VISA DPS supports mTLS and shared secret as the two modes for signing requests.

For this example, you’ll use the mTLS authentication mode to upload the private key and the public key using the connection ID returned in Step 2.

Before continuing to the next steps, you’ll need to create a project with VISA DPS, which will provide access to the mTLS private key and public key.

Make the following call to upload the keys and associate them with the connection:

bash
curl -i -X POST 'https://manage.skyflowapis.com/v1/gateway/outboundRoutes/$CONNECTION_ID/secret' \
-H 'Authorization: $BEARER_TOKEN' \
-H 'X-SKYFLOW-ACCOUNT-ID: $SKYFLOW_ACCOUNT_ID' \
-H 'Content-Type: application/json' \
-d '{
    "routeSecret": {
        "sharedKey": "$SHARED_KEY",
        "publicKey": "-----BEGIN CERTIFICATE-----\$PUBLIC_KEY\n-----END CERTIFICATE-----",
        "privateKey": "-----BEGIN RSA PRIVATE KEY-----\$PRIVATE_KEY\n-----END RSA PRIVATE KEY-----\n"
    },
    "authMode": "MTLS"
}'

Replace the WORKSPACE_URL, VAULT_URL, VAULT_ID, BEARER_TOKEN, and SKYFLOW_ACCOUNT_ID parameters.

Replace the SHARED_KEY, PUBLIC_KEY, and PRIVATE_KEY parameters.

Send the request.

You should receive the following response:

http code 200 OK
{}

You have completed the connection configuration! Next, you'll create a connection-level service account and invoke the connection.

Using the bearer token of the Vault Owner who created the connection, run the following command to create a service account for the connection:

bash
curl -i -X POST 'https://manage.skyflowapis.com/v1/serviceAccounts' \
-H 'X-SKYFLOW-ACCOUNT-ID: $SKYFLOW_ACCOUNT_ID' \
-H 'Authorization: $BEARER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "resource": {
        "ID": "$CONNECTION_ID",
        "type": "CONNECTION"
    },
    "serviceAccount": {
        "name": "Connection SA",
        "displayName": "Connection Invoker SA",
        "description": "SA for invoking Connection"
    }
}'

Replace the SKYFLOW_ACCOUNT_ID, BEARER_TOKEN, and CONNECTION_ID parameters.

Send the request.

The credentials are returned in the response. Keep these credentials secure, as you'll need them for step 4.3.

Make the following call to get the Role ID for the Connection Invoker role associated with the connection ID:

bash
curl -i -X GET 'https://manage.skyflowapis.com/v1/roles?name=CONNECTION_INVOKER&resource.ID=$CONNECTION_ID&resource.type=CONNECTION'
-H 'Authorization: $BEARER_TOKEN'
-H 'X-SKYFLOW-ACCOUNT-ID: $SKYFLOW_ACCOUNT_ID'

Replace the CONNECTION_ID, BEARER_TOKEN, and SKYFLOW_ACCOUNT_ID parameters.

Assign the service account as a member of the Connection Invoker Role:

bash
curl -i -X POST 'https://manage.skyflowapis.com/v1/roles/assign' \
-H 'Authorization: Bearer $BEARER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "ID": "$CONNECTION_INVOKER_ROLE_ID",
    "members": [
        {
            "ID": "$SERVICE_ACCOUNT_ID",
            "type": "SERVICE_ACCOUNT"
        }
    ]
}'

Send the request.

Use the credentials file from Step 4.1 to generate an API bearer token.

For this step, you’ll need the

Bearer token from step 4 Connection ID and relative path generated in Step 2Token referencing the PAN

Use the data above to make the following request to the connection endpoint:

bash
curl -i -X POST '$WORKSPACE_URL/v1/gateway/outboundRoutes/$CONNECTION_ID/dcas/cardservices/v2/cards' \
-H 'X-SKYFLOW-ACCOUNT-ID: $SKYFLOW_ACCOUNT_ID' \
-H 'X-Skyflow-Authorization: $BEARER_TOKEN' \
-H 'Authorization: Basic OU5LVjFPOTZaVDJ...UdDY=' \
-H 'Content-Type: application/json' \
-d '{
    "primaryAccountNumber": "$TOKEN_REFERENCING_PAN"
}'

curl -i -X POST 'https://manage.skyflowapis.com/v1/serviceAccounts' \
-H 'Authorization: Bearer $BEARER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "resource": {
        "ID": "$CONNECTION_ID",
        "type": "CONNECTION"
    },
    "serviceAccount": {
        "name": "Connection SA",
        "displayName": "Connection Invoker SA",
        "description": "SA for invoking Connection"
    }
}'

Replace the VAULT_URL, CONNECTION_ID, SKYFLOW_ACCOUNT_ID, BEARER_TOKEN, and TOKEN_REFERENCING_PAN parameters.

Send the request.

When the connection endpoint receives the request, it validates the credentials, extracts the token referencing the primary account number, and retrieves the corresponding PAN from the Skyflow vault. The connection then replaces the token with the actual PAN and forwards the request to the appropriate Visa endpoint.

VISA DPS validates the mTLS connection and Authorization header, and then processes the request to generate a new card ID. This new card ID is returned to the connection.

The connection tokenizes the card ID and returns the token referencing the card ID in the response as follows:

{
    "receivedTimestamp": "2020-12-31T16:51:29.426Z",
    "resource": {
    "cardId": "5457a4e1-ec71-499f-ba1f-e8554g596195"
},
    "processingTimeinMs": 19222
}

You’re ready to connect your Skyflow vault with VISA DPS!

Check out the other Data APIs or one of the articles below:

Creating a Custom VaultTokenization OverviewData Governance Overview