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:
Goals
By the end of this walkthrough, you will be able to confidently achieve the following:
Collect New Cards with VGS
Perform Stripe Payment Intents and Subscriptions
Migrate Current Cards from Stripe to VGS
Below is a diagram explaining the entire workflow of what we will be accomplishing:
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.
Steps
Before loading your form, you will need to create an authorization token that is scoped to allow your client-side form to create cards.
The service account used to create cards in Collect should have the following scopes:
cards:writenetwork-tokens:write
The Auth token is loaded into the client-side form
The customer enters their details into the Collect form
The merchant UI code creates a card using the vgsCollectForm.createCard() and the authentication token from step 1.
2. Perform Stripe Payments and Subscriptions
2.a Create Stripe Payment Methods via VGS Outbound Proxy
Steps:
The client forwards the VGS Card ID and aliased card details to the Merchant server
The merchant generates a Stripe Payment Method by forwarding the aliased PAN details through the VGS Outbound Proxy
The merchant stores the Stripe Payment Method and VGS Card ID in their database for later use.
2.b Perform Payments and Subscriptions
Steps
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.
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.
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:
{
"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 cryptoram with the Stripe payment intents API using NodeJS.
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.
Steps
Stripe will provision an SFTP Server and access credentials.
Stripe will encrypt the access credentials for the new SFTP Server using VGS’s public PGP key (found here) and provide the encrypted credentials in an email to the VGS Operations team.
Stripe will encrypt the batch file (or files) using VGS’s public PGP key and upload the encrypted files to the Stripe SFTP Server.
VGS will download the batch file from Stripe's SFTP Server.
VGS will decrypt the batch file using the VGS PGP Private Key.
VGS will validate the data format to ensure it meets the expected input format for Stripe.
VGS will import each record into VGS, which will create Card IDs and PAN Aliases for each record.
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.
VGS will upload the results file to the VGS SFTP Delivery Server
The Customer will download the results file from the VGS SFTP Delivery Server using the Customer’s SSH key for authentication.
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.
customer_card_id
987654321
Customer-generated identifier for tracking the card.
stripe_token_id
pm_abcdef
The payment method or card ID from Stripe. This value can be used to process payments or enroll in subscriptions with Stripe
vgs_card_id
CRD12345
The VGS Card ID that can be used to access card-related services such as Account Updater and Network Tokens.
vgs_pan_alias
tok_live_abcdef
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.
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.
Last updated