API Reference
Go to Blog

Toucan Tokenization Overview

Toucan by Pagos allows you to either replace or augment your current vaulting strategy to begin using network tokens in the place of primary account numbers (PAN). With Toucan, we make it easy for you to access network services directly with your own dedicated account, and control how and where you deploy network tokenization.

This guide outlines the Toucan process to make network tokenization more accessible:

  1. Authenticating with Toucan
  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

📘

Note

Check out our Toucan Testing guide to get access to the Toucan Sandbox.

Authenticating

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

Set Up Webhooks

Webhooks are automated notifications that push information to your designated destination when important events occur. To set up webhooks, contact your Pagos account manager and provide a webhook endpoint URL.

Toucan sends webhooks for the following events types:

  • networkTokenStatusUpdated - The status of a network token has changed. This webhook will contain:
    • Details about the token, including the token Ref ID, card brand, status (e.g. inactive, active, suspended, or deleted), and expiration date (when the status is active). Keep in mind, this 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
{
    "tokenRefId": "visa-cb9b0e653e5809db32caacc0205210ad",
    "cardNetworkName": "visa",
    "eventType": "networkTokenStatusUpdated",
    "date": 1661807833,
    "status": "inactive/active/suspended/deleted",
    "expirationDate": { 
      "year": "2023", 
      "month": "12" 
    },
    "reason": "",
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}
  • networkTokenCardUpdated - 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). 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. 
{
    "tokenRefId": "visa-cb9b0e653e5809db32caacc0205210ad",
    "cardNetworkName": "visa",
    "eventType": "networkTokenCardUpdated",
    "date": 1661807833,
    "metadata": "e2318ac9-56d2-4835-9b7a-d72369cc0e1b"
}

Provisioning a Network Token

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

Using our Toucan test values, you can test provisioning a network token on POST: /tokenize

📘

Keep in Mind

While we only require the card PAN (accountNumber) and expiration date (expirationDate) to provision a network token, we recommend also providing the card's CVV2 value if possible, as this gives the issuer more context when authorizing the token's creation.

If your tokenization request includes your own metadata value for a PAN, that same value will be returned in the response for all API calls associated with that PAN's token.

Transacting With a Network Token

Before you can process a transaction with a network token, you must first fetch a cryptogram for that token. 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.

Using our Toucan test values, you can test this using the API on POST: /transact

📘

Keep in Mind

When you sell recurring subscriptions, you aren’t required to fetch a cryptogram at this time—you can use the details of the token and the expiration date.

Suspending a Token

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

You can test the /suspend command in Sandbox using our Toucan test values, but note that the status will not persist for the given token.

Resuming a Suspended Token

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

Note that because the status doesn’t persist after you suspend a token in the Toucan Sandbox, you won't have any suspended tokens to resume. That being said, you can still test the call using our test values, and the response will always return a status of 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 PAN, or expiration date for the underlying PAN.

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

Using our Toucan test values, you can test this using the API on GET: /status

Requesting Account Data

You can request account data for the card underlying an existing network token at any time. 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, expiry date, etc.). The response can include an assets array, indicating the card has card art you can request the file for.

Using our Toucan test values, you can test this using the API on GET: /account

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. The response will be the actual image data, presented as a base64 encoded string.

Using our Toucan test values, you can test this using the API on GET: /asset

🚧

Note

Discover cards don't support card art at this time.

Deleting a Token

You can test deleting a token permanently with /delete using our Toucan test values. Once you delete a token, you cannot resume it. To temporarily suspend a token, use [/suspend].