Transaction with Network Token - V1

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

Below we go through the requirements and the logic that occurs 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 party's 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 occurs 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.

Example: Default Transaction Type: ECOM

cURL (ECOM example)
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

Account Funding Transaction (AFT)

This type is specifically for account funding transactions.

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

cURL (AFT example)
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"
  }'

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 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.

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:

Example payload (Adyen 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"
}
Additional paymentMethod example
"paymentMethod": {
  "type": "networkToken",
  "brand": "visa",
  "expiryMonth": "08",
  "expiryYear": "2020",
  "holderName": "CARDHOLDER_NAME",
  "number": "666666xxxxxx6666",
  "networkPaymentReference": "MCC123456789012"
}

Example PSP response (Adyen)

Adyen - Authorised response
{
  "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"
  }
}
Adyen - Refused response
{
  "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

PreviousNetwork Tokens Bulk Enrollment - V1NextAccount Updater - V1