Provisioning PSP Tokens for Payments

PSP tokens (Payment Service Provider tokens) are secure, provider-specific and merchant-specific representations of payment credentials, such as credit or debit cards, that can be stored and reused without exposing the original sensitive data.

When you provision a PSP token, you're asking a payment provider like Stripe, Adyen, or Braintree to create a unique identifier for a card. This unique identifier can then be used for card-on-file and recurring payments.

As an enterprise grows and becomes more sophisticated with its payment stack, it is common to limit risk by adding additional PSPs. Using this model, enterprises can provision tokens from multiple PSPs, allowing the enterprise the highest level of flexibility and redundancy.

Introduction to the VGS Outbound Proxy

The Outbound Proxy allows users to reveal the pan_alias and cvc_alias values to any third-party payment processor.

The Outbound Proxy is used by configuring the Outbound Route URL on HTTPS requests that require sensitive data to be exchanged and configuring your Vault Routes to allow requests to be sent from your server to a third-party domain.

Example Architecture

In the architecture below, you can see how the Agentic Provider Server sends the aliased data through the VGS Outbound Proxy, which in turn converts the aliased data to the original PAN and CVC before forwarding to the final destinations.

Reference Documentation

• VGS Outbound Proxy

Step 1: Find your Outbound Route URL

The Outbound Route URL can be found in your VGS Dashboard. It is in the following format: USERNAME:PASSWORD@<vault_id>.<environment>.verygoodproxy.com:8443

The "USERNAME" and "PASSWORD" are placeholders for the Vault Access Credentials that are generated in Step 2.

Step 2: Generate Vault Access Credentials

Access Credentials are required to authenticate to the VGS Outbound Proxy. The Username and Password should be stored securely in your environment.

Step 3: Configure Allowed Outbound Routes

In order for the Outbound Proxy to be allowed to reveal data to a third-party API, you need to create an Outbound Route. These routes can be configured manually, or you can easily select one of our templated integrations by navigating to the Addons -> Route Templates section in the dashboard.

Step 4: Add Proxy to Server-side HTTPS Requests

In your server-side code, configure the Outbound Proxy as the HTTPS forward proxy for the requests.

// NodeJS sample of configuring a proxy 
function getProxyAgent() {
    const vgs_outbound_url = `${VAULT_ID}.sandbox.verygoodproxy.com`
    console.log(`Sending request through outbund Route: ${vgs_outbound_url}`);
    return tunnel.httpsOverHttps({
        proxy: {
            servername: vgs_outbound_url,
            host: vgs_outbound_url,
            port: 8443,
            proxyAuth: `${VGS_USERNAME}:${VGS_PASSWORD}`
        },
    });
}

let buff = new Buffer(STRIPE_KEY+":");
let base64Auth = buff.toString('base64');

const instance = axios.create({
    baseURL: 'https://api.stripe.com',
    headers: {'authorization': `Basic ${base64Auth}`},
    httpsAgent: agent,
});

Step 5: Configuring the VGS Proxy Certificate

In order to make requests securely from your server to the VGS Outbound Proxy, you will need to attach the certificate for the VGS environment to your certificate chain.

The certificates for the VGS sandbox and live environments can be found here.

Below is the package.json of our sample app that automatically adds the certificate to the cert chain.

{
  "name": "sample-agentic-app",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": {
    "//": "The NODE_EXTRA_CA_CERTS environment variable needs to be set before starting the server to allow NodeJS to proxy requests through the VGS outbound route",
    "start": "NODE_EXTRA_CA_CERTS=$(pwd)/outbound-route-sandbox.pem node server"
  },
  "dependencies": {
    "axios": "^1.6.7",
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.18.2",    
    "body-parser": "^1.20.1",
    "qs": "^6.11.0",
    "tunnel": "^0.0.6"
  }
}

Step 6: Share Cards with PSPs To Provision PSP Token

Now that we have the VGS Vault configured to allow outbound requests to PSP APIs and set up the proxy in your app, we can make requests to third-party PSP endpoints.

Below is a sample integration with Stripe's Payment Methods endpoint. In this sample, the pan_alias and cvc_alias are used in place of the actual card number and CVC. When the request arrives at VGS, the alias values will be replaced with the original PAN and CVC values.

async function createStripeToken(cardObject) {
    let agent = getProxyAgent();
    let buff = new Buffer(STRIPE_KEY+":");
    let base64Auth = buff.toString('base64');

    const instance = axios.create({
        baseURL: 'https://api.stripe.com',
        headers: {'authorization': `Basic ${base64Auth}`},
        httpsAgent: agent,
    });

    try {
        let pm_response = await instance.post('/v1/payment_methods', qs.stringify({
            type: 'card',
            card: {
                number: cardObject.attributes.pan_alias,
                cvc: cardObject.attributes.cvc_alias,
                exp_month: cardObject.attributes.exp_month,
                exp_year: cardObject.attributes.exp_year,
            }
        }));

        return {
            success: true,
            psp_token: pm_response.data.id
        }
    }
    catch(error) {
        return { success: false, error: error }
    }
}

Step 7: Save PSP Token

After the PSP Token is provisioned, you can save it and link to the end-customer to be used for card-on-file or recurring subscription payments.