Transactions with Network Tokens

Performing transaction with VGS Network Tokens is functionally the same as performing them with a VGS aliased PAN.

Below we will go through the requirements, and logic that occurrs in the process of making a payment request with a VGS Network Token.

Requirements:

• You must have a valid VGS alias which points to the PAN of the card

• The underlying card PAN must have been successfully enrolled as a Network Token

• A configured VGS outbound route to your 3rd party PSP to authorize the payment

1. The vgs-network-token header:

Whether or not a Network Token is used for a request, is determined by the vgs-network-token header on the request that is sent to VGS.

Set the header value as shown below:

vgs-network-token	Result
yes	NT used
any other value	NT not used

2. Token cryptogram and PANs

VGS will determine whether to use a token cryptogram or PAN based on the configured 3rd parties support for Network Tokens.

Brand	NT Provision Status	PSP that supports cryptogram	PSP that does not support cryptogram
Visa	Not Provisioned	VGS will use the PAN+CVV (if available) or PAN only for the transaction	VGS use the PAN+CVV (if available) or PAN only for the transaction
	Provisioned	VGS will dynamically use shorter or longer form of cryptogram based on PSP readiness, and fallback to PAN+CVV (if available) or PAN only for the transaction	VGS will use shorter form of cryptogram based on PSP readiness, and fallback to PAN+CVV (if available) or PAN only for the transaction
Mastercard	Not Provisioned	VGS will use the PAN+CVV (if available) or PAN only for the transaction	VGS use the PAN+CVV (if available) or PAN only for the transaction
	Provisioned	VGS will use longer form of cryptogram based on PSP readiness, and fallback to PAN+CVV (if available) or PAN only for the transaction	VGS use the PAN+CVV (if available) or PAN only for the transaction
Visa/Mastercard/Other	N/A, Inactive, Suspended or Deleted	VGS will use the PAN+CVV (if available) or PAN only for the transaction	VGS use the PAN+CVV (if available) or PAN only for the transaction

If a Network Token is provisioned, and your PSP supports Network Tokens, but an error occurrs in fetching the cryptogram, we will use the PAN.

3. Sending a Request to your PSP

Customers can initiate transactions using VGS Network Tokens by generating a unique cryptogram, commonly referred to as TAVV (Token Authentication Verification Value). This cryptogram is specific to the network token and can be up to 32 characters long. When submitting transactions, networks may require merchants to specify the transaction type explicitly during cryptogram generation. VGS supports two primary transaction types:

1. Ecommerce (ECOM): This is the default type for most transactions.

2. Account Funding Transaction (AFT): This type is specifically for account funding transactions.

Important Note:

• Visa-Specific Requirement: For Visa transactions, it's mandatory to specify the AFT transaction type when fetching the cryptogram for account funding transactions.

• Other Networks: Other networks typically default to the ECOM type unless explicitly specified.

VGS Network Token Usage

Sending a payment request using VGS Network Tokens functions similarly to using a VGS-aliased PAN. The same transaction type considerations apply when generating cryptograms.

Example Requests:

1. Default Transaction Type: ECOM

Below is an example of a cURL request to post a payment request to Adyen with the default ECOM transaction type:

 curl --location -X POST PSP_URL \
     -H "Authorization: Bearer ${VGS_ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -x https://<USERNAME>:<PASSWORD>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 \
     --data-raw '{
        "amount": {
           "currency": "USD",
           "value": 1000
        },
        "reference": "Your order number",
        "paymentMethod": {
           "number": "VGS_ALIAS",
        },
        "returnUrl": "https://your-company.com/...",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
     }'

2. Specifying the Transaction Type: AFT

To initiate an AFT transaction, include the header vgs-cryptogram-txn-type with the value AFT in your request:

curl --location -X POST PSP_URL \
     -H "Authorization: Bearer ${VGS_ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "vgs-cryptogram-txn-type: AFT" \
     -x https://<USERNAME>:<PASSWORD>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 \
     --data-raw '{
        "amount": {
           "currency": "USD",
           "value": 1000
        },
        "reference": "Your order number",
        "paymentMethod": {
           "number": "VGS_ALIAS"
        },
        "returnUrl": "https://your-company.com/...",
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
     }'

Note: Enabling the AFT transaction type requires a custom Larky configuration. For assistance with setting this up, please reach out to [email protected].

VGS will populate the payload with all the data needed for a successful transaction with your Network Tokens. For example, the following will be utilized for Adyen’s payment with Network Tokens:

"paymentMethod": {
  "type": "networkToken",
  "brand": "visa",
  "expiryMonth": "08",
  "expiryYear": "2020",
  "holderName": "CARDHOLDER_NAME",
  "number": "666666xxxxxx6666",
},
"mpiData": {
  "directoryResponse": "Y",
  "authenticationResponse": "Y",
  "cavv": "AAEBAwQjSQAAXXXXXXXJYe0BbQA=",
  "eci": "05"
}      

"paymentMethod": {
  "type": "networkToken",
  "brand": "visa",
  "expiryMonth": "08",
  "expiryYear": "2020",
  "holderName": "CARDHOLDER_NAME",
  "number": "666666xxxxxx6666",
  "networkPaymentReference": "MCC123456789012"
}

Example PSP response (Adyen):

{
  "additionalData": {
    "cardBin": "489537",
    "cardSummary": "3416",
    "PaymentAccountReference": "123456",
    "recurringProcessingModel": "CardOnFile",
    "paymentMethod": "visa",
    "networkTxReference": "393657085380164"
  },
  "pspReference": "NN8W2T8XCVTFWR82",
  "resultCode": "Authorised",
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "merchantReference": "afd8c4d3-c0c2-4737-a8c9-ade8229771d5",
  "paymentMethod": {
    "brand": "visa",
    "type": "networkToken"
  }
}

{
  "additionalData": {
    "cardBin": "489537",
    "cardSummary": "0010",
    "PaymentAccountReference": "123456",
    "recurringProcessingModel": "CardOnFile",
    "paymentMethod": "visa"
  },
  "pspReference": "DM2GW4RSLV5X8N82",
  "refusalReason": "Refused",
  "resultCode": "Refused",
  "refusalReasonCode": "2",
  "merchantReference": "bf4ef8c1-a0b5-477c-8d0d-e851646c8564"
}

Note: Successful and failed responses may look different if you are using a different PSP.

What's next?

• API docs