Token Format Create Recipe

📌 Purpose

Token formats define the structure of the codes generated for programmes and stored value vouchers — controlling character type, length, and whether a checksum digit is appended. This recipe walks you through creating a numeric, 10-digit token format with a checksum, suitable for use with voucher programmes and stored value accounts.

For full configuration options, see the Create Token Format API reference.

🖼 Recipe Overview

You will create a token format with the following configuration:

• Format: Digits only (0–9)
• Length: 10 digits total, with the final digit reserved as a checksum
• Checksum: Enabled — the last character is automatically calculated to validate the token's integrity and prevent fraudulent guessing
• Use case: Suitable for attaching to programmes and stored value voucher accounts

Once created, this token format can be referenced when configuring a programme or campaign to control the structure of any tokens it generates.

📋 Prerequisites

Ensure the following are ready before proceeding:

• Access to the Eagle Eye API platform with a valid clientId and secret
• An active company unit to attach the token format to
• A name for the token format
• Confirmed token length and character type requirements
• Confirmation that checksum validation is required

Note: Tokens cannot be between 13–19 digits in length, as this range is reserved to prevent clashes with BIN (Bank Identification Number) ranges.

📤 Outputs

📒 Steps

Step 1: Define Your Token Format

Before calling the API, confirm the following configuration choices:

• 1.1 Name: Choose a descriptive name for the token format that makes it easy to identify when selecting it during programme or campaign setup (e.g. "10-Digit Numeric with Checksum")
• 1.2 Format: Set details.format to ######### to restrict tokens to numeric characters (0–9). Note only nine # are needed, as the last digit will be the checksum value.
• 1.3 Length: Set details.length to 10 — this is the total token length including the checksum digit
• 1.4 Checksum: Set details.checksum to true — this appends a calculated check digit as the final character of the token, used to validate the code at point of redemption and prevent fraudulent code guessing
• 1.5 Prefix/Suffix: Leave as null if no prefix or suffix is required. These can be added if you need a fixed string prepended or appended to every generated token

Step 2: Call POST /tokenFormats

{
    "name": "10-Digit Numeric with Checksum",
    "details": {
        "format": "#########",
        "length": 10,
        "checksum": true
    }
}

{
    "id": 35541,
    "name": "10-Digit Numeric with Checksum",
    "safeName": "000035541",
    "details": {
        "checksum": true,
        "format": "#########",
        "length": 10
    }
}

✅ Business Readiness Checklist

• Retrieve the token format using GET /tokenFormats/{id} and confirm the tokenFormatId has been captured
• Confirm details.format is set to #########
• Confirm details.length is 10
• Confirm details.checksum is true
• Verify the token format name is descriptive and unambiguous for anyone configuring programmes and campaigns
• Attach the safeName to a programme and generate a test stored value account to confirm it produces a valid 10-digit numeric code with checksum POST /connect/account

🔧 Troubleshooting Tips