Scenarios

Create a default voucher (POST)

Authorization is required

URL /merchants/${merchantId}/vouchers

Note

In this scenario we're create a simple money value based voucher.

Request with cURLRequest with PHP GuzzleResponse

curl --location 'http://localhost:3000/merchants/6543f1a747d45f218ed0071e/vouchers' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"amount": 23.12,
"type": "AMOUNT",
"name": "Stefans Vouchers",
"description": "Wir testen nur mal",
"codeGeneratorSettings": {
            "charset": "numerical",
            "length": 12,
            "pattern": "####-####-##",
            "prefix": "CODE-",
            "suffix": "",
            "uppercase": true
        }
}'

<?php
    $client = new Client();
    $headers = [
        'Content-Type' => 'application/json',
        'Authorization' => 'YOUR_API_KEY',
    ];
    $body = '{
        "amount": 23.12,
        "type": "AMOUNT",
        "name": "Stefans Vouchers",
        "description": "Wir testen nur mal",
            "codeGeneratorSettings": {
                "charset": "numerical",
                "length": 12,
                "pattern": "####-####-##",
                "prefix": "CODE-",
                "suffix": "",
                "uppercase": true
            }
    }';
    $request = new Request('POST', 'http://localhost:3000/merchants/6543f1a747d45f218ed0071e/vouchers', $headers, $body);
    $res = $client->sendAsync($request)->wait();
    echo $res->getBody();
?>

{
    "amount": 23.12,
    "type": "AMOUNT",
    "name": "Stefans Vouchers",
    "description": "Wir testen nur mal",
    "codeGeneratorSettings": {
        "charset": "numerical",
        "length": 12,
        "pattern": "####-####-###",
        "prefix": "CODE-",
        "suffix": "",
        "uppercase": true
    },
    "merchantId": "6543f1a747d45f218ed0071e",
    "validFrom": "2024-04-08T07:45:27.123Z",
    "validUntil": "2025-04-08T07:45:27.123Z",
    "code": "CODE-5270-3530-42",
    "id": "bd7b6bdc-f335-444a-8bbd-4d20a03ea846",
    "initialAmount": 0,
    "purpose": "MULTIPLE",
    "createdAt": "2024-04-08T05:45:27.227Z",
    "sessionCode": "",
    "paid": false,
    "usage": "CUSTOMER",
    "default": false,
    "deactivated": false,
    "quota": 0
}

Usage of Code Generator

Defines how the code should look like, when automatically generated.

Property	Type	Description	Default
charset	enum	Defines, which chars sould be used. Can be numerical, alphanumerical, alphabetical.	numerical
length	number	Length of code	8
pattern	string	You can define a patter by using #. Each # will be replaced by a char of the genrator code. All other than # will count as one character as well.	####-###
prefix	string	Use this to add something before the code.	empty
suffix	string	Use this to add someting to the end.	empty
uppercase	boolean	If using alphabetical or alphanumerical all chars will be uppercase if true - otherwise it could be a mix of upper- and lowercase characters.	abc

Create a volume of vouchers (POST)

Authorization is required

URL /merchants/${merchantId}/vouchers/quantity/${quantity}

We use the same base request as in Create default voucher.

BUT

..we have to add a reference to identity all vouchers related to this volume-generation.

If you don't provide a reference, you will end in an exception.

{
    "message": "REFERENCE_REQUIRED",
    "error": "Bad Request",
    "statusCode": 400
}

Limitations

Currently the maximum amount of vouchers you can create with one request is limited to 1000.

If you exceed the limit per request, you will end in an exception.

{
   "message": "QUANTITY_EXCEEDED",
    "error": "Bad Request",
    "statusCode": 400 
}

Deactivate vouchers (POST)

by id

Authorization is required

URL /merchants/${merchantId}/vouchers/deactivate

Deactivate a single voucher

{
    "id": "f85f3d36-0893-41e1-bbc3-8ee419e98107"
}

by reference

Authorization is required

URL /merchants/${merchantId}/vouchers/deactivate

Deactivate a single voucher

{
    "reference": "Marketing Spring 2024"
}

Get vouchers - with filter (GET)

Authorization is required

URL /merchants/${merchantId}/vouchers

by VoucherStatus (Query-Parameter voucherStatus)

Status	Description
COLLECT	If you have a default voucher, you will get all generated vouchers based on your default voucher.
REDEEM	You will receive all vouchers, that are redeemed while checkout.
CHECK	You will receive all vouchers, that were entered in the checkout process.

Redeem voucher (POST)

Authorization is required

URL /vouchers/${voucherCode}/redeem

{
    "amountToPay": 49.99,
    "merchantId": "the-id-of-the-merchant",
    "order": {
        "cart": [
            {
                "productId": "ABC-1",
                "productName": "Sandalen Gr. 42",
                "unitPrice": 12.99,
                "pieces": 2
            },
            {
                "productId": "SONC-1",
                "productName": "Sonnencreme LSF 'Nutella'",
                "unitPrice": 24.01,
                "pieces: 1
            }
        ]
    },
    "callback": {
        "url": "https://i-called-you.com/voucher/hook",
        "headerName": "X-API-KEY",
        "headerAuth": "mySecretApiKey"
    }
}

Property	Type	Description	Mandatory
amountToPay	number	The amount the cart has.	yes
merchantId	objectId	The Fanz Merchant-Id	yes
order	object	Your payload you want to proxy. It will be the body of callback	no
callback	object	Get notified, when a voucher is redeemed.	should

PERCENTAGE voucher

If it's a percentage voucher, the redemption is straight forward: The whole voucher code will marked as REDEEMED and is not available anymore.

AMOUNT voucher

If you reedem a voucher with an amount it's quiet different. Let's explain three possible scenarios:

Amount to pay is higher than amount of voucher

Straight forward: Voucher is completely REDEEMED.

Amount to pay is equal to amount of voucher

Straight forward: Voucher is completely REDEEMED.

Amount to pay is lower than amount of voucher

The only exception, BUT our system is designed to handle that.

Let's create an example.

You have a voucher with an amount of EUR 100.
Your cart have items for EUR 49.99.
If you redeem your voucher you have EUR 50.01 left.

You can use the voucher code until the amount is EUR 0 (Zero).

QUOTA voucher