Quickstart

Introduction

This document is a comprehensive guide on how to set up the VGS Network Tokens integration, enabling you to retrieve Visa and Mastercard network tokens. A network token is a secure digital representation of a payment card, used to facilitate transactions between merchants and customers. It provides an additional security layer when transmitting sensitive payment information, as well as reducing the risk of fraud, and ensures a smooth and seamless transaction experience for your customers.

Before you start

Capture credit card data

If you’re an existing user and already have VGS tokens, please skip this step.

Before creating and using network tokens, you need to capture and tokenize card data. You can do this in a few ways:

• VGS Collect - one of the ways to start collecting sensitive data is to configure the VGS Collect form that will send requests to the VGS proxy, which is configured to redact the sensitive fields and store them in your vault. The form inputs themselves are VGS-hosted iFrames, so the web application is not interacting with the data as it is entered.

• Vault API - You can also use our Vault API to create test tokens.

Test Cards

The following test cards can be used to test out the network tokens enrollment.

Create Network Tokens

Adding Network Tokens to your Integration

You integrate directly with the VGS Network Tokens API. VGS integrates with the network tokenization service provider (like Visa or MasterCard) on your behalf and uses the network token (where available) to process the transaction.

Authentication and API Credentials

1. Generate Service Account

You can generate a service account in the dashboard or create one using the VGS Command Line Interface (CLI).

1. 1. Navigate to the Service Accounts section of your Dashboard, under Vault > Organization > Service Accounts, and click on the Create New button.

2. 2. Select your Vault and add the network-tokens:write scope to provide access to Network Tokens.

Execute the sample code below, which will create credentials.yaml a file:

vgs generate service-account -t calm --var vault_id=<VAULT_ID> > credentials.yaml

2. Generate Access Token

To Authenticate with the Network Tokens API, you should use the CLIENT_ID and CLIENT_SECRET generated in the previous step to create an access_token.

curl -X POST \
-d "client_id=<CLIENT_ID>" \
-d "client_secret=<CLIENT_SECRET>" \
-d "grant_type=client_credentials" \
"https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token"

The generated token can now be used with the Network Tokens API. Please note that the access_token is valid only for 5 minutes. After expiry, you can generate a new access token using the same process. refresh_token should not be used. Pass the created access_token as an Authorization: Bearer ${VGS_ACCESS_TOKEN} header in each API call.

3. Generate Access Credentials

To initiate a transaction to a PSP, you need an additional set of credentials that will allow requests through an outbound proxy.

To create access credentials, go to the Vault Settings > Access Credentials and press the Generate Credentials button. When Access Credentials are generated, you will be prompted to download them.

Note that access credential’s secrets can only be viewed at the time of generation. You can download them to keep them safe.

If you lose these credentials, you can generate a new pair following the same process. Read more

Create Network Tokens

1. Enable Network Tokens API

Go to Addons > VGS CALM and enable the Network Tokens addon. This will create an outbound route for the Network Tokens API.

2. Enroll a Network Token

The Enrollment API invocation is a synchronous process and should complete within a few seconds after the call is made. As soon as a response is received with state: ACTIVE you can use the Network Token to transact with a PSP.

curl -X POST https://calm.<ENVIRONMENT>.verygoodsecurity.app/network-tokens \
-x https://<CREDENTIALS>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 -k \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ${VGS_ACCESS_TOKEN}' \
-d '{
  "pan_alias":"tok_sandbox_mLCuQsa6bQUrsiZYYvzSC3",
  "exp_month":12,
  "exp_year":23
}'

You can explore all the fields that can be sent in an enrollment request here. Descriptions of enrollment failure reasons can be found here.

Initiate A Payment Transaction

Using Network Tokens to Transact

Performing a transaction with VGS Network Tokens is functionally the same as performing them with a VGS aliased PAN. You only need to include the header vgs-network-token: yes. VGS will populate the payload with all the data needed for a successful transaction with your Network Token.

1. Enable the integration for your PSP

To initiate a payment transaction you need to enable the integration with the desired PSP. Navigate to the Addons section under the Vault menu bar and find your desired PSP. Select the Network Tokens variant of their integration.

Note For some PSP's, the default and Network Tokens integration are the same integration.

Generally Test cards cannot be used to perform test transactions with real PSPs, while they may work with some PSP’s, the test cards are intended as test cards for Network Tokens only. PSP’s will need to add support for testing Network Tokens in their Sandbox environments. You can use our Demo PSP in the Addons sections to test transactions.

Prebuilt PSP Integrations:

• Stripe

• Cybersource

• JPM Orbital

• Adyen

• Demo PSP

If the PSP you want to work with isn’t on the list, reach out to [email protected] for help integrating with your PSP of choice.

2. Initiate the payment transaction to your PSP

After enabling the outbound route to your PSP, include the vgs-network-token: yes header, and send a regular request.

Here are some examples of requests sent to a specific PSP, showing the before, Network Token transformation, PAN fallback, and response.

Cybersource

{
  "clientReferenceInformation": {
    "code": "PaymentReferenceCode"
  },
  "paymentInformation": {
    "card": {
      "number": "tok_sandbox_dklas09asdmasdfssd9",
      "expirationMonth": "08",
      "expirationYear": "24"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "1",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "548 Market St",
      "locality": "Los Angeles",
      "administrativeArea": "CA",
      "postalCode": "94104",
      "country": "US",
      "email": "[email protected]"
    }
  }
}

{
  "clientReferenceInformation": {
    "code": "PaymentReferenceCode"
  },
  "paymentInformation": {
    "tokenizedCard": {
      "assuranceLevel": "07",
      "cryptogram": "AAA1sshfgdDVdsAafgjdsax",
      "expirationMonth": "12",
      "expirationYear": "2027",
      "number" :"4444444444444444"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "1",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "548 Market St",
      "locality": "Los Angeles",
      "administrativeArea": "CA",
      "postalCode": "94104",
      "country": "US",
      "email": "[email protected]"
    }
  }
}

{
  "clientReferenceInformation": {
    "code": "PaymentReferenceCode"
  },
  "paymentInformation": {
    "card": {
      "number": "4242424242424242",
      "expirationMonth": "08",
      "expirationYear": "24"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "1",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "548 Market St",
      "locality": "Los Angeles",
      "administrativeArea": "CA",
      "postalCode": "94104",
      "country": "US",
      "email": "[email protected]"
    }
  }
}

{
    "_links": {
        "authReversal": {
            "method": "POST",
            "href": "/pts/v2/payments/123456789012345678901234567890/reversals"
        },
        "self": {
            "method": "GET",
            "href": "/pts/v2/payments/12345678901234567890"
        },
        "capture": {
            "method": "POST",
            "href": "/pts/v2/payments/123456789012345678901234567890/captures"
        }
    },
    "clientReferenceInformation": {
        "code": "YOURREFERENCE"
    },
    "id": "6920293736436626204988",
    "orderInformation": {
        "amountDetails": {
            "authorizedAmount": "1.00",
            "currency": "USD"
        }
    },
    "paymentAccountInformation": {
        "card": {
            "type": "001"
        }
    },
    "paymentInformation": {
        "tokenizedCard": {
            "type": "001"
        },
        "card": {
            "type": "001"
        }
    },
    "pointOfSaleInformation": {
        "terminalId": "0100123748"
    },
"processorInformation": {
        "approvalCode": "123455I",
        "networkTransactionId": "1234567890",
        "transactionId": "12345678901234567890",
        "responseCode": "100",
        "avs": {
            "code": "N",
            "codeRaw": "I8"
        }
    },
    "reconciliationId": "1234567890HP",
    "status": "AUTHORIZED",
    "submitTimeUtc": "2023-08-14T16:09:34Z"
}

Set up Notifications

After a Network Token has been enrolled, there are a few events that may occur to update the status of the Network Token. You may receive these status updates via our Webhook integration, or may notice them on the Usage Reports section of your organization's Dashboard. You can set up a webhook to receive Network Token updates by following these setup instructions.

Going Live Checklist

Activate your Organization

To activate an organization, click on the Activate Organization button next to your Organization name. Organization activation is a simple process: you fill out some basic personal profile information and your company information.

Create a Live Vault

Once you’ve activated your organization, you can create a Live Vault by hovering your cursor over your Vault list and clicking on “+ New” button, and then choosing “Live” as the environment.

Live cards migration optional

If you need to, you can migrate your existing live cards into the vault using the following process.

Obtain a Token Requester ID for your Live Vault

VGS has integrated directly with Visa and Mastercard to offer Network Token to its merchants. If you need a Network Token from other card networks (American Express, Discover etc.), don't hesitate to contact [email protected].

Go to the Network Tokens section in your Live Vault side menu bar, and press the Complete TRID form button. Follow the instructions and submit the necessary information about your business and contact details. Based on the card network, it might take up to 2 business days to receive the onboarding confirmation. Please look out for the confirmation email from VGS. Once you receive an email, you can proceed with the setup below.

Set up authentication and API Credentials for your Live Vault

The VGS Network Tokenization APIs use OAuth 2.0 Client Credentials flow for authentication. This API is intended for server-to-server communication, and no user is involved in the authentication process. The steps to set this up with VGS are detailed above: Authentication and API Credentials.

Enable the Network Tokens API & your PSP integration in your Live Vault

To promote your Sandbox integration from Sandbox to Live, you will need to use our YAML feature.

Set up Notifications in Live

Follow the same steps described here to set up notifications in the live environment.

Verify your live configurations

Perform test transactions using your company's internal cards, or reach out to Customer Support at [email protected] to verify your live configuration of network tokens.

Begin sending customer transactions through your integration!

Once you have completed the steps above, and verified your integration, you can begin processing live customer transactions through VGS Network Tokens! Congratulations!

Glossary

Tokenization is the act of securely redacting and storing sensitive information in your VGS Vault.

A token is a piece of information stored within the VGS Vault. You can store up to 20 tokens in one API call.

A network token is a secure digital representation of a payment card, used to facilitate transactions between merchants and customers.

Inbound routes handle the passing of data from end users to your application repository using the VGS proxy to tokenize the data.

Outbound routes handle the passing of data from your application repository to a third party, such as a card processor, using the VGS proxy to reveal the data.