# Adding VGS to a Stripe Payments Environment

## Overview

This guide provides step-by-step instructions on how to move from a Stripe-managed checkout experience to a PSP-neutral card vault using the VGS suite. We will explain step-by-step how merchants can continue to work with Stripe for payments while collecting and managing cards with VGS. With the strategies included in this document, merchants can achieve a no-downtime cutover to the payments flow.

If you would like code samples for this project, please see the complementary GitHub repo:

* [github.com/vgs-samples/vgs-with-stripe](https://github.com/vgs-samples/vgs-with-stripe/tree/main)

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FDGyRR6izdErvFC7zcxDt%2Fimage.png?alt=media&#x26;token=6ada567d-18e5-4111-85b5-be253ecbfa91" alt=""><figcaption></figcaption></figure>

## Goals

By the end of this walkthrough, you will be able to confidently achieve the following:

1. **Collect New Cards with VGS**
2. **Perform Stripe Payment Intents and Subscriptions**
3. **Migrate Current Cards from Stripe to VGS**

Below is a diagram explaining the entire workflow of what we will be accomplishing:

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FjsZ2FTyV72X4HehCyDWV%2Fimage.png?alt=media&#x26;token=84b5f4e2-57d6-4d9c-b676-e09dfd4f26c9" alt=""><figcaption></figcaption></figure>

## 1. Collect New Cards with VGS

This section will explain how VGS can be used to replace Stripe Hosted Checkout for capturing new card details.

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FR2a1lCBEr0uvhRmi0ROY%2Fimage.png?alt=media&#x26;token=072787a0-ac49-4298-b3db-d045c293324f" alt=""><figcaption></figcaption></figure>

**Steps**

1. Before loading your form, you will need to create an authorization token that is scoped to allow your client-side form to create cards.
   1. [How to generate service accounts](https://app.gitbook.com/s/zbOVGj5YTirkppRKlOP9/access-management/service-accounts-for-programmatic-access)
   2. The service account used to create cards in Collect should have the following scopes: `cards:write`  `network-tokens:write`
   3. [How to authenticate with VGS](https://app.gitbook.com/s/g1pA9re6lCmtaiQAnvjh/platform/authentication)
2. The Auth token is loaded into the client-side form
3. The customer enters their details into the Collect form
   1. [Code sample for building Collect form](https://github.com/vgs-samples/vgs-with-stripe/blob/main/client/src/components/VGSCollectCheckout.jsx)
4. The merchant UI code creates a card using the [vgsCollectForm.createCard()](https://app.gitbook.com/s/g1pA9re6lCmtaiQAnvjh/developer-resources/guides/create-a-card-using-vgs-collect) and the authentication token from step 1.

## 2. Perform Stripe Payments and Subscriptions

### 2.a Create Stripe Payment Methods via VGS Outbound Proxy

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FJjtsWFVJ6Wqj5iMy5EO4%2Fimage.png?alt=media&#x26;token=2742940c-2a96-4fbc-8792-1edb2adaa325" alt=""><figcaption></figcaption></figure>

**Steps:**

5. The client forwards the VGS Card ID and aliased card details to the Merchant server
6. The merchant generates a Stripe Payment Method by forwarding the aliased PAN details through the VGS Outbound Proxy
   1. [VGS Outbound Proxy](https://docs.verygoodsecurity.com/vault/http-proxy/outbound-connection)
   2. [How to add pre-built integrations to your proxy configuration](https://docs.verygoodsecurity.com/vault/http-proxy/integration-templates)
7. The merchant stores the Stripe Payment Method and VGS Card ID in their database for later use.

### 2.b Perform Payments and Subscriptions

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FPTI0P76nQFT5yyZRiOeF%2Fimage.png?alt=media&#x26;token=89aec925-aaae-4e72-b500-c866fdadc401" alt=""><figcaption></figcaption></figure>

#### Steps

8. Now that the Stripe payment method is created, it can be used directly with Stripe's API or SDK to create a payment\_intent for performing a payment or to create a Stripe subscription.
9. After the payment or subscription is complete, the merchant can present the landing page to the customer.

### 2.c Perform Payments with Network Tokens & Cryptograms

In addition to being able to provision Stripe Payment Methods to perform payment\_intents, Stripe allows merchants to provide Network Tokens and cryptograms that have been generated by VGS.&#x20;

The details required in order to perform payments with Network Tokens and Cryptograms is returned by the VGS `/cards/{card_id}/cryptogram` endpoint. See the docs and sample response from this request below:

```json
{
  "data": {
    "id": "NTK6j75fBx46Lzd3G3aVkfGQF",
    "type": "network_tokens",
    "attributes": {
      "bin": "411321",
      "created_at": "2025-01-17T12:53:17.94829",
      "cryptogram": {
        "eci": "07",
        "type": "TAVV",
        "value": "JWrMYLqNQjmEHQDAZbSx+A=="
      },
      "exp_month": 9,
      "exp_year": 27,
      "last4": "2304",
      "network_token": "4113216317012304",
      "payment_account_reference": "V4243058293132582787411225618",
      "state": "active",
      "updated_at": "2025-01-17T12:53:17.948293"
    }
  },
  "metadata": {
    "observability": {
      "client_id": "ACoKRUTV7-config-ci-5I76w",
      "fingerprint": "4GqVMr6PvdWHn5qfb66TquParUHsTiFsjJCFaDpVed8KbAmz4bSftQeNQBb",
      "account_id": "37199757-3a4f-418f-bcf4-4119d1dbd39e",
      "trace_id": "f2046b6548e7dbe5793adee1f4a13c63",
      "vault_id": "tntipby064g"
    }
  }
}
```

Below is a code sample of how to utilize the VGS-issued cryptogram with the Stripe payment intents API using NodeJS.

```javascript
async function createPaymentIntentWithNetworkToken() {
  try {
    const response = await axios.post('https://api.stripe.com/v1/payment_intents', 
      new URLSearchParams({
        'amount': '1000',
        'currency': 'usd',
        'payment_method_types[]': 'card',
        'confirm': 'true',
        'payment_method_data[type]': 'card',
        'payment_method_data[card][exp_month]': '4',
        'payment_method_data[card][exp_year]': '2023',
        'payment_method_data[card][last4]': '4242',
        'payment_method_data[card][network_token][number]': '4000000000000001', // returned from VGS /cards/{card_id}/cryptogram
        'payment_method_data[card][network_token][exp_month]': '1', // returned from VGS /cards/{card_id}/cryptogram
        'payment_method_data[card][network_token][exp_year]': '2024', // returned from VGS /cards/{card_id}/cryptogram
        'payment_method_options[card][network_token][cryptogram]': 'AAEB....e0BbQ', // returned from VGS /cards/{card_id}/cryptogram
        'payment_method_options[card][network_token][electronic_commerce_indicator]': '05' // returned from VGS /cards/{card_id}/cryptogram
      }),
      {
        auth: {
          username: process.env.STRIPE_SECRET_KEY,
          password: ''
        },
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        }
      }
    );

    console.log('Payment Intent created:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error creating payment intent:', error.response?.data || error.message);
    throw error;
  }
}
```

## 3. Migrate Current Cards from Stripe to VGS

VGS regularly works with Stripe to migrate cards on file from Stripe to a VGS Card Management Account. This process requires the Merchant to instruct Stripe to export cards on file to an SFTP server so that VGS can import each record and deliver a results file.

Stripe documentation on how to export card details can be found [here](https://docs.stripe.com/get-started/data-migrations/pan-export).

**Steps**

<figure><img src="https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2FIKfMI7R9c7ystXmgkHxi%2FOpen%20AI%20Solutions%20Architecture%20-%20Card%20Collection%20(5).png?alt=media&#x26;token=b944051d-97c1-496e-b754-4a5cd81f3487" alt=""><figcaption></figcaption></figure>

1. Stripe will provision an SFTP Server and access credentials.
2. Stripe will encrypt the access credentials for the new SFTP Server using VGS’s public PGP key (found [here](https://www.verygoodsecurity.com/keys/vgs.pgp.txt)) and provide the encrypted credentials in an email to the VGS Operations team.
3. Stripe will encrypt the batch file (or files) using VGS’s public PGP key and upload the encrypted files to the Stripe SFTP Server.
4. VGS will download the batch file from Stripe's SFTP Server.
5. VGS will decrypt the batch file using the VGS PGP Private Key.
6. VGS will validate the data format to ensure it meets the expected input format for Stripe.
7. VGS will import each record into VGS, which will create Card IDs and PAN Aliases for each record.
8. VGS will generate a results file that maps Stripe Tokens to VGS Card IDs and PAN Aliases. Details on this results file can be found here.
9. VGS will upload the results file to the VGS SFTP Delivery Server
10. The Customer will download the results file from the VGS SFTP Delivery Server using the Customer’s SSH key for authentication.
11. The Customer will import the VGS Card records into their database. Below is a sample database schema that can be used to track the data in the VGS results file with data previously in the database.

<table><thead><tr><th width="160.17578125">Column</th><th width="145.99609375">Example</th><th>Description</th></tr></thead><tbody><tr><td>customer_card_id</td><td>987654321</td><td>Customer-generated identifier for tracking the card.</td></tr><tr><td>stripe_token_id</td><td>pm_abcdef</td><td>The payment method or card ID from Stripe. This value can be used to process payments or enroll in subscriptions  with Stripe</td></tr><tr><td>vgs_card_id</td><td>CRD12345</td><td>The VGS Card ID that can be used to access card-related services such as Account Updater and Network Tokens. </td></tr><tr><td>vgs_pan_alias</td><td>tok_live_abcdef</td><td><p>The VGS PAN alias that is a direct mapping to the PAN. This value can be used in the VGS Proxy to reveal the PAN details to new third parties other than Stripe.</p><p></p><p>Note that if the VGS Account Updater service is being used, this value will be updated when a new PAN is provided by the issuer.</p></td></tr></tbody></table>

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verygoodsecurity.com/vault/guides/adding-vgs-to-a-stripe-payments-environment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.