Toucan Tokenization Overview

📘

PRIVATE BETA

This product is in private beta. Contact us if you’re interested in participating!

Toucan by Pagos allows you to either replace or augment your current vaulting strategy to begin using network tokens in the place of personal account numbers (PAN). With Toucan, we make it easy for you to access network services directly, and control how and where you deploy network tokenization. This guide outlines the three processes Toucan simplifies to make network tokenization more accessible:

  1. Provisioning a token from a primary account number (PAN)
  2. Obtaining a cryptogram for transacting with the network token
  3. Handling a lifecycle management event for a token.

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.

After you onboard with Toucan, you’ll have access to our Sandbox environment–here we allow you to perform network tokenization via the UI for testing purposes, and get details around the actual API calls.

To provision a network token in the Sandbox:

  1. In the Toucan dashboard, click Tokenize.
  2. Input test card details.
  3. Click Tokenize.
  4. Click the JSON tab in this form to reveal the actual JSON object for the call.
  5. Click Tokens in the top menu to locate a list of the cards you’ve already tokenized. Here, you’ll find the details you need for the token, including a Pagos reference ID to use in subsequent Toucan calls and the token details to use when processing on any payment service provider or acquirer.

You can use the JSON text to try the API directly. Visit our /tokenize reference guide to learn more about making a call from the command line with cURL or another server-side programming language.

Here's an example using cURL for reference:

[email protected] % curl --request POST \
     --url https://toucan.sandbox.pagosapi.com/tokenize \ 
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <your key>' \
     --data '
  {
    "accountNumber": "<card number here>",
    "cvv2": "859",
    "name": "Ramona Chase",
    "expirationDate": {
      "month": "12",
      "year": "2023"
    }
  }'

{"statusCode":"OK","error":{"status":"OK","code":"200","reason":null,"message":"OK: The request was successfully completed."},"body":{"tokenRefID":"adca1a32-e073-4af2-a008-e3bc7eec5593","last4":"9193","expirationDate":{"year":"2023","month":"12"}}}
%

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.

To generate a cryptogram in the Sandbox:

  1. In the Toucan dashboard, click Tokens.
  2. Locate the token you want to transact with, and click cryptogram.
  3. Under Cryptogram Details, you’ll find the data you’ll need to combine with the Token to create a transaction with your acquirer or payment service provider (PSP).

To test this using the API, visit our /transact reference guide.

📘

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.