API Reference

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
Body
one ofOptional
or
or
Responses
200

Provision network token response

application/json
post
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
}
{
  "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": "+1415-123-4567",
      "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": "+14842634673"
      }
    }
  }
}

Retrieve network tokens information associated with a card

get

Getting the network token will fetch the data for the provisioned network token and the card information.

Authorizations
Path parameters
pan_aliasstringRequired

VGS alias representing the PAN

Example: 9914040119524512000
Responses
200

Retrieve network token response

application/json
get
GET /network-tokens/{pan_alias} HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "pan_alias": "9914040119524512000",
  "network_token_last4": "2345",
  "expires_at": "2023-12",
  "created_at": "2019-05-15T12:30:45Z",
  "updated_at": "2019-05-15T12:30:45Z",
  "state": "ACTIVE",
  "card": {
    "last4": "0010",
    "bin": "489537",
    "expires_at": "2023-12",
    "holder_info": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "number": "+1415-123-4567",
      "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": "+14842634673"
      }
    }
  }
}

Delete a network tokens associated with a card

delete

Invoking the delete API will delete a provisioned network token. The result of this operation leads to a token status update.

Authorizations
Path parameters
pan_aliasstringRequired

VGS alias representing the PAN

Example: 9914040119524512000
Responses
200

OK

application/json
delete
DELETE /network-tokens/{pan_alias} HTTP/1.1
Host: calm.sandbox.verygoodsecurity.app
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "pan_alias": "9914040119524512000",
  "created_at": "2019-05-15T12:30:45Z",
  "updated_at": "2019-05-15T12:30:45Z",
  "network_token_last4": "2345",
  "state": "DELETED",
  "expires_at": "2027-01",
  "card": {
    "last4": "1234",
    "bin": "123456",
    "expires_at": "2027-01"
  }
}
PreviousTransactions with Network TokensNextNetwork Token Events

Last updated