Enroll Network Token

To try it out today, email us at [email protected]

Enroll a Network Token

The Enrollment API invocation is a synchronous process, and should complete within a few seconds after the call is made. As soon as a response is received with state: ACTIVE you can use the Network Token to transact with a PSP.

Prerequisites:

You will need a valid bearer_token to issue Enrollment API calls. Please see the Authentication guide for how to create one.

Enroll Network Token

You can expand the below dropdown to view more information about the API specifications for an Enrollment request:

Request a network token for a card

post

Enrolls a vaulted card for a network token with the card network. The Enrollment API invocation is intended to occur when there is an acceptable time window for the enrollment to be completed with the network and card issuer. In a checkout flow, where a new card is being vaulted, it is not recommended to enroll into NT prior to authorizing payments as the calls to the network and issuers require asynchronous callbacks.

When there is an acceptable time window for the enrollment to be completed with the network and card issuer, hence customers will receive multiple responses - Synchronous and Asynchronous.The synchronous response is returned immediately upon posting the enroll request. This response does not provide the final state of the request. A webhook will be invoked as the final state of the enrollment request is completed or the user can GET the network token by its ID to get its current state.

A network token cannot be used within a transaction unless it is in the ACTIVE state.

Authorizations

OAuth2

Body

application/json

one ofOptional

or

or

Responses

200

Provision network token response

application/json

201

Provision network token response

application/json

400

Bad Request

application/json

404

Not Found. Possible error codes:

• declined

application/json

422

Unprocessable Entity. Possible error codes:

• card-not-allowed
• card-brand-not-supported
• required-fields-missing
• invalid-format
• rejected

application/json

500

Internal Server Error

application/json

default

Provision network token response

application/json

post

HTTPcURLJavaScriptPython

POST /network-tokens HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "pan_alias": "5573495XKjDP28V7312",
  "exp_month": 7,
  "exp_year": 24
}

Enroll a payment card for Network Tokens (minimal)Enroll a payment card (full)Enroll with a Mastercard Token connect PushAccountDataEnroll with a Mastercard Token connect PushAccountReceipt

{
  "pan_alias": "9914040119524512000",
  "network_token_last4": "2345",
  "expires_at": "2023-12",
  "state": "ACTIVE",
  "created_at": "2019-05-15T12:30:45Z",
  "updated_at": "2019-05-15T12:30:45Z",
  "card": {
    "last4": "0010",
    "bin": "489537",
    "expires_at": "2023-12",
    "holder_info": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "number": "[phone]",
      "billing_address": {
        "name": "John Doe",
        "company": "John Doe Company",
        "address1": "555 Unblock Us St",
        "address2": "M13 9PL",
        "city": "New York",
        "region": "CA",
        "country": "US",
        "postal_code": "12301",
        "phone": "[phone]"
      }
    }
  }
}

Request Body Fields

The below table contains more details on the request body fields, which are required, and which are optional.

Field	Field Type	Description
name	Optional	Name of the user on the card
pan_alias	Required	VGS alias representing the PAN
cvv_alias	Optional	VGS alias representing the CVV
exp_month	Required	Expiration month on the card
exp_year	Required	Expiration year on the card
billing_address	Optional	Billing address registered on the card
company	Optional	Company registered on the card
address1	Optional	Address1 of the user registered on the card
address2	Optional	Address2 of the user registered on the card
city	Optional	City of the user registered on the card
region	Optional	Region of the user registered on the card
country	Optional	Country of the user registered on the card
postal_code	Optional	Postal Code of the user registered on the card
phone	Optional	Phone Number of the user registered on the card

Enrollment request

Please see below for a sample enrollment request, and a walkthrough of the Network Token enrollment request lifecycle.

Sample request:

curl --location -X POST https://calm.<ENVIRONMENT>.verygoodsecurity.app/network-tokens \
    -H "Authorization: Bearer ${VGS_ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -x https://<CREDENTIALS>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 \
    --data-raw '{
       "name": "John Doe",
       "pan_alias": "557349eee1027312",
       "cvv_alias": "tok_sandbox_1218782dsds",
       "exp_month":12,
       "exp_year":23,
       "billing_address": {
           "name": "John Doe",
           "company": "John Doe Company",
           "address1": "555 Unblock Us St",
           "address2": "M13 9PL",
           "city": "New York",
           "region": "NY",
           "country": "US",
           "postal_code": 12301,
           "phone": "[phone]"
       }
    }'

A synchronous response is returned immediately upon posting the enrollment request. This response provides the final state of the request if enrollment is completed successfully:

{
  "pan_alias": "5573491171027312",
  "network_token_last4": "2345",
  "created_at": "2023-05-15T12:30:45Z",
  "updated_at": "2023-05-15T12:30:45Z",
  "state": "ACTIVE",
  "expires_at": "2023-12",
  "card": {
    "last4": "7312",
    "bin": "557349",
    "expires_at": "2024-07"
  }
}

In some circumstances, an error response might be returned by the Network. Below is a sample error response:

{
  "pan_alias": "5573491171027312",
  "created_at": "2023-05-15T12:30:45Z",
  "updated_at": "2023-05-15T12:30:45Z",
  "state": "FAILED",
  "error_code": "card_not_allowed",
  "description": "The requested action is not allowed for a given PAN. This card is valid but cannot be used for tokenization.",
  "additional_info": "Network: Visa. Error: cardNotEligible"
}

---

Network Token Provisioning Status

The network token provisioning process includes two primary states: Active and Failed.

• Active: This status indicates that the network token has been successfully provisioned and is ready for use.

• Failed: Indicates that the network token provisioning attempt was unsuccessful.

Network Token States

When a Network Token (NT) is successfully provisioned, it is initially assigned the status of "Active". Over time, the NT can transition between various states, such as "Suspended", "Deleted", and "Activated", based on its updates. Below is a description of each possible state:

• Suspended: The network token has been temporarily suspended by the issuing card network (e.g., Mastercard, Visa).

• Activated: The network token has been reactivated after being suspended or updated.

• Deleted: The network token has been removed via the API.

Descriptions of enrollment failure reasons can be found in the table below:

Status Code	Error Code	Description
400	card_not_allowed	The requested action is not allowed for a given PAN. This card is valid but cannot be used for tokenization.
400	declined	This card is not eligible for tokenization at this moment.
400	card_enrollment_failed	Invalid payment instrument or data associated with the payment instrument.
500	internal_server_error	Something went wrong while processing the request

What's next?

• GET a Network Token

• API docs