VGS Integration

Lynx utilizes VGS for card details visualization. We provide a client-side component that your users will interact with in order for your users to view their card details.

At a high level, VGS works as a secure proxy and vault:

• Your application sends card data to a "Lynx VGS Proxy" (Lynx provides a Javascript iframe that you embed in your UI that abstracts this communication)
  • To the Lynx script, you will pass the VAULT_ID (explained below) and the environment ("sandbox" for non-production, "live" for production.
  • VGS will return to your UI, the un-redacted card information

VGS Integration Flow Overview

1. Register your inbound route with Lynx. This is service that the client implements; this 'backend-service' will make a machine-to-machine call to our API to retrieve the card details.
   1. To register an inbound route, contact the client success manager
2. A VAULT_ID will be provided to you when your inbound route is registered. This VAULT_ID will be used to communicate with the VGS integration. One VAULT_ID is assigned to only one domain/subdomain. This VAULT_ID will be provided to you by your client success manager.
   1. Note that the VAULT_ID becomes a part of the URL used to 'talk' to VGS.
      1. For example: if the VAULT_ID is: tnttaottxl4-6fbddc0e-bc95-4bf1-8cd2-a41d9d89d4f441d9d89d4f4, VGS automatically gives a base URL like: "https://tnttaottxl4-6fbddc0e-bc95-4bf1-8cd2-a41d9d89d4f441d9d89d4f4.sandbox.verygoodvault.com". In this example, 'sandbox' is the environment, and verygoodvault.com is the VGS domain.
   2. Therefore, each vault gets its own dedicated subdomain.
   3. In a sandbox environment, please ensure that your environment for this purpose is set to "sandbox"
3. Configure your UI using the _LynxVGs.js _script below to call your backend which in turn calls our View Card Info API.
4. Please note that at the moment only TLS1.2 is supported for transport layer security; so please ensure that you are on this version of TLS.

Configuration

Add LynxVGS.js script to your page:

LynxVGS.js

window.LynxVGS={create:function(e){this.instance=window.VGSShow.create(e.vaultId,()=>{}).setEnvironment(e.env)},show:function(e){let t={name:e.name,method:e.method,path:e.path,htmlWrapper:"text",headers:e.headers,jsonPathSelector:e.json};e.payload&&(t.payload=e.payload),e.replace&&(t.serializers=[this.instance.SERIALIZERS.replace(e.replace[0],e.replace[1])]);let s=e.elementId,a=e.css,r=this.instance.request(t);if(r.render(s,a),r.on("revealSuccess",e.success),r.on("requestFail",e.error),e.copy){let c=this.instance.copyFrom(r,{text:e.copy.text},e.copy.onCopy);c.render(e.copy.id,e.copy.css)}}},(script=document.createElement("script")).src="https://js.verygoodvault.com/vgs-show/2.1.0/show.js",script.type="text/javascript",script.defer=!0,document.getElementsByTagName("head").item(0).appendChild(script);

In your HTML create an empty wrapper element and assign it your own unique identifier. This element defines the location where the VGS iframe will be inserted:

Example:

<div id="lynx-vgs-secret"></div>

Initialize LynxVGS.js

window.LynxVGS.create({
  vaultId: <VAULT_ID>,
  env: <ENVIRONMENT>
});

Call LynxVGS.js

Execute a HTTP request to your server by calling the show method.

Example:

window.LynxVGS.show({  
  headers: headers,  
  name: 'data-code',  
  method: 'GET',  
  path: '/card/details?cardProxy=' + cardProxy + '&clientMemberId=' + clientMemberId,  
  json: 'data.cvc',  
  elementId: '#secret-cvc',
  replace: ['(\\d{4})(\\d{4})(\\d{4})(\\d{4})', '$1 $2 $3 $4'],
  css: {
    '@font-face': {  
      'font-family': 'Maven Pro',  
      'font-style': 'normal',  
      'font-weight': '400',  
      'font-display': 'swap',  
      'src': 'url(<https://fonts.gstatic.com/s/mavenpro/v33/7Au9p_AqnyWWAxW2Wk3GzWQI.woff2>) format("woff2")',  
      'unicode-range': 'U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116'  
    },
    'font-family': '"Maven Pro", monospace',  
    'color': '#fff',  
    'font-size': '18px',  
    'font-weight': '400'  
  },
  success: () => console.log('success'),  
  error: (e) => alert(e.message),
  copy: {
    id: '#copy-number-btn',
    text: 'Copy Card Number',
    css: {
      'color': '#000',
      'backgroundColor': '#fff'
    },
    onCopy: (status) => {
      console.log('copy status:', status);
    }
  }
});

Backend Call

Your registered route should call the Lynx API for retrieving the redacted card info via a GET request:

"https://sandbox.lynx-fh.co/cards/info"

Please note that this is specifically a "GET" API. This API is not available for reference in the "API Reference" section on Readme because it only returns redacted card number. Other APIs such as https://docs.lynx-fh.com/reference/getcard return other pertinent details about a card such as the card proxy, last four, issue date, expiration month/year etc.

***** In order to register your route and have a VAULT_ID generated, please contact a member of our Customer Success team.