Network Tokenization API Overview

The Network Tokenization API allows you to either replace or augment your current vaulting strategy to begin using network tokens in the place of primary account numbers (PAN). Pagos makes it easy for you to access network services globally with all four major card networks (Visa, Mastercard, Amex, and Discover).

This guide outlines the following network tokenization processes, from provisioning tokens to requesting underlying account data:

1. Authenticating with the Network Tokenization API.

2. Set up webhooks to receive updates.

3. Provisioning a token from a primary account number (PAN)

4. Obtaining a cryptogram for transacting with the network token

5. Suspending an active token

6. Resuming a suspended token

7. Getting the status of a token

8. Requesting account data for the card underlying an existing network token

9. Requesting updated card art for the card underlying an existing network token

10. Deleting an existing token

​

Authenticating

To ensure only authorized entities access our services, we authenticate the identity of each client that submits requests to the Network Tokenization API. Learn more in our Authentication guide.

​

Set Up Webhooks

Webhooks are automated notifications that push information to your designated destination when important events occur. To create a webhook, click Network Tokens under Data Enrichment in the main navigation of your Pagos Service Panel, then click the Webhooks tab. You can return to this tab any time to review and edit existing webhooks.

You’ll receive webhook notifications from Pagos for the following events types:

​

Token Status Updates

When the status of a network token changes, you’ll receive a networkTokenStatusUpdated webhook containing the following information:

• Details about the token, including the token Ref ID, card brand, status (e.g. inactive, active, suspended, or deleted), and expiration date of the token (when the status is active). Keep in mind, this expiration date is the expiration date of the token, not the underlying PAN

• The date in UTC when the event was created, written in UNIX Epoch Timestamp format

• The reason for the event, provided the associated card brand included this detail

{
    "token_ref_id": "visa-cb9b0e653e5809db32caacc0205210ad",
    "card_network_name": "visa",
    "event_type": "networkTokenStatusUpdated",
    "date": 1661807833,
    "merchant_id": "c9a303b8-e812-4516-a0d2-cd90e56742b2"
    "status": "active",
    "expiration_date": {
      "year": "2023",
      "month": "12"
    },
    "reason": "",
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}

​

Lifecycle Management Updates

When a network token has a lifecycle management (LCM) update—meaning the issuer updated details of the underlying PAN (e.g. last four digits, expiry date)—you’ll receive a networkTokenCardUpdated webhook. This webhook will contain the token ID and card brand; you can then request the status of the impacted network token to get the full updated details.

{
    "token_ref_id": "visa-cb9b0e653e5809db32caacc0205210ad",
    "card_network_name": "visa",
    "event_type": "networkTokenCardUpdated",
    "date": 1661807833,
    "merchant_id": "c9a303b8-e812-4516-a0d2-cd90e56742b2"
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}

​

Provisioning a Network Token

You can provision a network token on POST: /tokenize. “Provisioning a network token” refers to the step you take to convert a PAN into a network token. This is the critical step that signals to an issuer that your company is establishing a relationship with a cardholder that will persist over time. Every time you use the network token for a transaction, that context is accessible to the issuer.

​

Transacting With a Network Token

Before you can process a transaction with a network token, you must first fetch a cryptogram for that token by calling the /transact API endpoint. A cryptogram is an issuer-generated value for the transaction you’re processing, and is a key mechanism to the additional trust issuing banks give network tokens.

​

Suspending a Token

At any time, you can call the /suspend endpoint to suspend an active token, effectively blocking your customer’s ability to initiate transactions with you. Suspending a token is useful when you suspect fraudulent activity.

​

Resuming a Suspended Token

You can resume a suspended token using /resume. This returns the token from a status of Suspended to Active.

​

Getting the Status of a Network Token

Once you’ve provisioned a network token there will be instances when you will want to check the token status and basic token information, such as network, last 4 digits of the token, or expiration date of the token. To do so, call the /status endpoint.

There are three possible statuses that a network token can be in:

1. Active - the token is active and can be used to transact with

2. Suspended - the token is temporarily suspended by the merchant

3. Deleted - the token has been deleted by the merchant

​

Requesting Account Data

Call the /account endpoint to request account data for the card underlying an existing network token. The response will include information you can share with the customer to help them identify the exact card saved on file and tokenized with your business (e.g. last four digits of the PAN, expiry date of the PAN, etc.). The response can include an assets array, indicating the card has card art you can request the file for.

​

Requesting Card Art

If the assets section of the /account response is populated, you can make a request for those assets from the /assets endpoint. For Visa cards, the response will be for the actual image data, presented as a base64 encoded string; for Mastercard cards, it will be a URL to the card image file.

​

Deleting a Token

You can delete a token permanently with /delete. Once you delete a token, you cannot resume it. To temporarily suspend a token, use /suspend.