📌 Purpose

Stored value vouchers are a powerful tool to reward customers with monetary value they can use on future purchases. This recipe walks you through creating a programme that can issue a multi-use stored value card that carries a variable balance, valid for a specific promotional period. See the Create Programmes API for additional options that can be configured against programmes.

🖼 Recipe Overview

In this recipe, you will create a new debit card programme that generates multi-use stored value vouchers. Each voucher will have a flexible balance, a validity period (start and end date) and multi-use logic to ensure the voucher can be redeemed as many times as needed. At the end of this setup, you will have a fully configured stored value programme that can issue multi-use cards. The vouchers issued with this setup can only be topped up and redeemed unlimited times.

📋 Prerequisites

Ensure you have:

Access to Eagle Eye APIs
Name for your voucher
Minimum and maximum voucher and load values (e.g. £5 min, £50 max)
Voucher validity dates (start and end)
Token provider and format values

📤 Outputs

As you complete each step, note these outputs for future API calls and validation:

Output Name	Purpose
programmeId	Used to create stored value accounts or retrieve programme details

📒 Steps

Step 1: Define Voucher Details

Start by defining the required values to create a new voucher. You will define the name, type, balance rules, and expiry window.

1.1 Choose a name for the voucher
1.2 Set the type to VOUCHER
1.3 Define a 6-digit bin and 2-digit scheme in the settings.cardNumber object
1.4 Define the balance rules:
- Values are in the currency's lowest denomination (e.g. pence or cents)
- maxBalance: the maximum value a voucher can hold
- minLoadAmount: the minimum load amount for a voucher
- maxLoadAmount: the maximum load amount for a voucher
- maxDebitAmount: the maximum amount a customer can spend at once
1.5 Set a start and end date for the programme
1.6 Select a currency value (e.g. GBP or USD)

Note: If the programme should be restricted for use in one or more banners, the rules.storeRestrictions object can be added to the request payload, else the resulting stored value accounts can be managed at any banner within the company.

    "rules": {
        "storeRestrictions": {
            "{bannerIdentifier}": {
                "included": {
                    "locationIdentifiers": null
                }
            }
        }
    }

Step 2: Call POST /programmes

{
    "type": "VOUCHER",
    "status": "ACTIVE",
    "details": {
        "name": "Debit Card Programme",
        "description": "",
        "startDate": "2025-08-01 00:00:00",
        "endDate": "2050-06-30 23:59:59",
        "tags": []
    },
    "settings": {
        "tokenProvider": "StoredValue",
        "tokenFormat": "000030325",
        "cardNumber": {
            "bin": 123456,
            "scheme": 12
        },
        "accountClientType": "VOUCHER",
        "defaultAccountClientState": "LOADED",
        "passphrase": false,
        "refreshToken": true,
        "currency": "GBP"
    },
    "partners": {
        "creation": [],
        "redemption": []
    },
    "rules": {
        "expiry": {
            "type": "NEVER",
            "date": null,
            "value": null
        },
        "balances": {
            "maxBalance": 500000,
            "minLoadAmount": 100,
            "maxLoadAmount": 500000,
            "maxDebitAmount": 100000
        },
        "redemption": {
            "couponLimit": 0
        }
    }
}

{
    "id": "101451325",
    "type": "VOUCHER",
    "status": "ACTIVE",
    "reference": "101451325",
    "details": {
        "name": "Debit Card Programme",
        "description": "",
        "startDate": "2025-08-01 00:00:00",
        "endDate": "2050-06-30 23:59:59",
        "tags": []
    },
    "settings": {
        "tokenProvider": "StoredValue",
        "tokenFormat": "000030325",
        "cardNumber": {
            "bin": 123456,
            "scheme": 12
        },
        "accountClientType": "VOUCHER",
        "defaultAccountClientState": "LOADED",
        "passphrase": false,
        "refreshToken": true,
        "currency": "GBP"
    },
    "partners": {
        "creation": [],
        "redemption": []
    },
    "rules": {
        "expiry": {
            "type": "NEVER",
            "date": null,
            "value": null
        },
        "balances": {
            "maxBalance": 500000,
            "minLoadAmount": 100,
            "maxLoadAmount": 500000,
            "maxDebitAmount": 100000
        },
        "redemption": {
            "couponLimit": 0
        },
        "storeRestrictions": []
    },
    "dateCreated": "2025-08-08 12:53:20",
    "lastUpdated": "2025-08-08 12:53:20"
}

✅ Business Readiness Checklist

Use these checks to confirm programme is set up correctly:

Retrieve the programme using Create Programmes API to confirm the setup
Create a voucher in a wallet using Create Programme Account

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
accountClientType is invalid (ISF Error)	Ensure the settings.accountClientType is correct
Bad Request (400)	The request payload is missing a required field: type: VOUCHER, status or details object