# Quickstart - V1 ## 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](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/create-a-card-using-vgs-collect) 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm/network-tokens-v1/broken-reference) to create test tokens. ### Test Cards The following test cards can be used to test out the network tokens enrollment. | Card Number | Expiry Date (MMYY) | CVV | Region | | ---------------- | ------------------ | ------------ | ------ | | 2222690420064590 | Any Future Date | Any 3 digits | Global | | 2222690420064574 | Any Future Date | Any 3 digits | Global | | 2222690420064582 | Any Future Date | Any 3 digits | Global | | 5120350100064594 | Any Future Date | Any 3 digits | Global | | 2223520127577835 | Any Future Date | Any 3 digits | India | ## 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 {% stepper %} {% step %} ### Generate Service Account You can generate a service account in the dashboard or create one using the VGS Command Line Interface (CLI). * Navigate to the Service Accounts section of your Dashboard, under Vault > Organization > Service Accounts, and click on the Create New button. * 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`: {% code title="CLI: generate service account" %} ```bash vgs generate service-account -t calm --var vault_id= > credentials.yaml ``` {% endcode %} {% endstep %} {% step %} ### Generate Access Token To authenticate with the Network Tokens API, use the `CLIENT_ID` and `CLIENT_SECRET` generated in the previous step to create an `access_token`. {% code title="cURL: obtain access token" %} ```bash curl -X POST \ -d "client_id=" \ -d "client_secret=" \ -d "grant_type=client_credentials" \ "https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token" ``` {% endcode %} The generated token can now be used with the Network Tokens API. The `access_token` is valid only for 5 minutes. After expiry, generate a new access token using the same process. Do not use `refresh_token`. Pass the created `access_token` as an Authorization: `Bearer ${VGS_ACCESS_TOKEN}` header in each API call. {% endstep %} {% step %} ### 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. * Go to Vault Settings > Access Credentials and press the Generate Credentials button. * When Access Credentials are generated, download them. Note that access credential secrets are visible only at generation time. If you lose these credentials, generate a new pair following the same process. Read more: [Access Credentials](https://docs.verygoodsecurity.com/cmp/platform/authentication#id-3-generate-access-credentials) {% endstep %} {% endstepper %} ### Create Network Tokens {% stepper %} {% step %} ### 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. {% endstep %} {% step %} ### Enroll a Network Token The Enrollment API invocation is synchronous and should complete within a few seconds. When you receive a response with `state: ACTIVE` you can use the Network Token to transact with a PSP. {% code title="cURL: enroll network token" %} ```bash curl -X POST https://calm..verygoodsecurity.app/network-tokens \ -x https://@..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 }' ``` {% endcode %} You can explore all the fields that can be sent in an enrollment request [here](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm/network-tokens-v1/network-tokens-api-v1/network-tokens-bulk-enrollment-v1). Descriptions of enrollment failure reasons can be found [here](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm/network-tokens-api-v1/network-tokens-bulk-enrollment-v1#enrollment-data-format). {% endstep %} {% endstepper %} ## Initiate A Payment Transaction ### Using Network Tokens to Transact Performing a transaction with VGS Network Tokens is functionally the same as performing one with a VGS aliased PAN. 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. {% stepper %} {% step %} ### 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 PSPs, the default and Network Tokens integration are the same integration. > Generally test cards cannot be used to perform test transactions with real PSPs. PSPs will need to add support for testing Network Tokens in their Sandbox environments. You can use our Demo PSP in the Addons section 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 . {% endstep %} {% step %} ### 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. Below are examples for Cybersource showing: original request, transformed Network Token request, PAN fallback, and a sample response. Original request: {% code title="Cybersource - Request (aliased PAN)" %} ```json { "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": "test@cybs.com" } } } ``` {% endcode %} Transformed Network Token request: {% code title="Cybersource - Tokenized Request" %} ```json { "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": "test@cybs.com" } } } ``` {% endcode %} PAN fallback request: {% code title="Cybersource - PAN Fallback" %} ```json { "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": "test@cybs.com" } } } ``` {% endcode %} Sample response: {% code title="Cybersource - Sample Response" %} ```json { "_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" } ``` {% endcode %} {% endstep %} {% endstepper %} ## Set up Notifications After a Network Token has been enrolled, there are 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. Set up a webhook to receive Network Token updates by following these [setup instructions](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/network-tokens-webhooks). ## 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” 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: [Migrations](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm). ### 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.), contact . 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 onboarding confirmation. Look for the confirmation email from VGS. Once you receive it, 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. The steps to set this up with VGS are detailed above: [Authentication and API Credentials](https://docs.verygoodsecurity.com/cmp/platform/authentication). ### Enable the Network Tokens API & your PSP integration in your Live Vault To promote your Sandbox integration from Sandbox to Live, use our [YAML](file:///3056465/platform-insights/dashboard/yaml.md) feature. ### Set up Notifications in Live Follow the same steps described [here](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/network-tokens-webhooks) 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 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. ## 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. --- # 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/cmp/developer-resources/api/card-management-v1-apis-calm/network-tokens-v1/quickstart-v1.md?ask= ``` 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.