Ensure your Toucan integration works correctly by simulating network tokenization in the Toucan sandbox.

Step 1: Request Access to Toucan

📘

The Toucan sandbox is not available for self-signup at this time.

Complete our registration form if you’re interested in Toucan. The Pagos Accounts team will email you with an invitation to our Toucan Sandbox environment. Follow the link in the invitation to confirm your email address, create a Sandbox password, and complete your account setup.

Step 2: Generate Your Toucan Sandbox API Keys

To generate your API keys:

1. Log into your Sandbox.
2. Click your profile icon in the navigation bar, then click Manage API Keys.
3. Click Create API Key.
4. Save the Client Key and Private Key in your secrets for future reference.

🚧

Important

This is the only time you can view this Private Key!

These API Keys are universal across the sandbox and will be used for testing both Toucan and Loon.

Step 3: Test Toucan

You're ready to begin testing the full capabilities of Toucan. Follow the instructions in our Toucan Tokenization Overview to perform the following actions in the Sandbox using our test values below.

• Authenticating with Toucan
• Provisioning a token from a primary account number (PAN)
• Obtaining a cryptogram for transacting with the network token
• Suspending an active token
• Resuming a suspended token
• Getting the status of a token
• Requesting metadata on the card underlying an existing network token
• Requesting updated card art for the card underlying an existing network token
• Deleting an existing token

Toucan Test PANs

Testing Provisioning a Network Token

You can use the following test PANs to test provisioning a network token in the Toucan Sandbox. All test PANs will pass Luhn verification checks.

Testing Transacting With a Token

You can test fetching a cryptogram on the tokenRefId returned for a card you successfully tokenized. The response for your /transact call will include random token and cryptogram values, following the examples below:

Visa Response

{
    "cryptogram": "NDExMTExMDc1NjQxMTEwMA==",
    "token": "4111115847111100",
    "eci": "07"
}

Mastercard Response

{
    "cryptogram": "NTU1NTU1MDg2MzUxNDQwMA==",
    "token": "5555558674814400",
    "eci": ""
}

Testing Requesting Metadata

You can test requesting metadata on the tokenRefId returned for a card you successfully tokenized. The response for your /metadata call will include an assetId which you can then use to test the /asset call.

Visa Response

{
  "properties": {
    "cardNetworkName": {
      "type": "string"
    },
    "tokenAccount": {
      "type": "object",
      "properties": {
        "last4": {
          "type": "string"
        },
        "expirationMonth": {
          "type": "string"
        },
        "expirationYear": {
          "type": "string"
        },
        "par": {
          "type": "string"
        }
      },
      "required": [
        "last4",
        "expirationMonth",
        "expirationYear",
        "par"
      ]
    },
    "foregroundColor": "0x1af0f0",
    "backgroundColor": "0x009614",
    "labelColor": "0x19550a",
    "shortDescription": "Test-Card",
    "longDescription": "This is a test card.",
    "assets": [
        {
            "assetId": "00000000000000000000000000001011",
            "assetData": null
        },
        {
            "assetId": "00000000000000000000000000001012",
            "assetData": null
        }
      ]
    }
  }

Mastercard Response

{
  "properties": {
    "cardNetworkName": {
      "type": "string"
    },
    "tokenAccount": {
      "type": "object",
      "properties": {
        "last4": {
          "type": "string"
        },
        "expirationMonth": {
          "type": "string"
        },
        "expirationYear": {
          "type": "string"
        },
        "par": {
          "type": "string"
        }
      },
      "required": [
        "last4",
        "expirationMonth",
        "expirationYear",
        "par"
      ]
    },
    "foregroundColor": "0x1af0f0",
    "backgroundColor": "0x009614",
    "labelColor": "0x19550a",
    "shortDescription": "Test-Card",
    "longDescription": "This is a test card.",
    "assets": [
        {
            "assetId": "00000000000000000000000000001011",
            "assetData": null
        },
        {
            "assetId": "00000000000000000000000000001012",
            "assetData": null
        }
      ]
    }
  }

Testing Requesting Card Art

If the response when you request metadata includes an assetId, you can use that value to test requesting card art for the associated token. The response will include the card art image data presented as a base64 encoded string.

🚧

Note

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

Testing Requesting the Status of a Token

You can test requesting a token’s status using the tokenRefId returned for a card you successfully tokenized. The response for your /status call will include random year and month values, following the examples below:

Response for Visa account 4111111111111100

{
    "tokenRefId": "visa-8e9c3493ce9a2e299b7242b43254b625",
    "expirationDate": {
        "year": "2024",
        "month": "09"
    },
    "status": "active",
    "cardNetworkName": "visa",
    "panLast4": "1100"
}

Response for Visa account 4111111111111101

{
    "tokenRefId": "visa-fc3955f56233bd892f107a333bf280e6",
    "expirationDate": {
        "year": "2024",
        "month": "04"
    },
    "status": "active",
    "cardNetworkName": "visa",
    "panLast4": "1101"
}

Response for Mastercard account 5555555555554401

{
    "tokenRefId": "mastercard-d53183c0ae658f6a0123c4d68b081dd5",
    "expirationDate": {
        "year": "2024",
        "month": "07"
    },
    "status": "active",
    "cardNetworkName": "mastercard",
    "panLast4": "4400"
}

Response for Mastercard account 5555555555554400

{
    "tokenRefId": "mastercard-63ef64b93627ec44f2459febe873ee27",
    "expirationDate": {
        "year": "2024",
        "month": "06"
    },
    "status": "active",
    "cardNetworkName": "mastercard",
    "panLast4": "4401"
}

Testing Suspending a Token

You can test suspending a token using the tokenRefId returned for a card you successfully tokenized.

Keep in mind, the response will return a status of suspended, but that status won’t persist for the associated token, meaning if you then test requesting the status of that token, it will return a status of active.

Testing Resuming a Suspended Token

You can test resuming a suspended token using the tokenRefId returned for a card that received a success /tokenize response. The test response will always return a status of active.

Testing Deleting a Token

You can test deleting a token using the tokenRefId returned for a card that received a success /tokenize response.

Keep in mind, the response will return a status of deleted, but that status won’t persist for the associated token, meaning if you then test requesting the status of that token, it will return a status of active.