Check Card Balance

Check the balance of a Festivalcadeau giftcard before processing a payment. Use this to verify sufficient funds before calling /devalue.

---

Endpoint

---

Request Parameters

Parameter	Type	Required	Description
apikey	string	Yes	Your API key (obtained via authentication)
company_id	integer	Yes	Your company ID (obtained via authentication)
cardnumber	string	Yes	The giftcard number
pin	string	Yes	The giftcard PIN code

---

Success Response 200 OK

{
    "success": true,
    "balance": 5000,
    "currency": "EUR",
    "card_status": "Active",
    "expiry_date": "2027-06-15"
}

Note: Balance is returned in cents (5000 = €50.00)

Error Responses

401 Authentication Failed

{
    "error": "Authentication Failed"
}

422 Missing Fields

{
    "error": "Missing required fields",
    "required": ["cardnumber", "pin", "apikey", "company_id"]
}

400 Invalid Card

{
    "error": "Card validation failed",
    "result_code": 5,
    "message": "Invalid card number or PIN"
}

---

Example Usage (PHP)

<?php

$url = 'https://business.festivalcadeau.com/api/endpoint/v1/balance';

$data = [
    'apikey'     => 'your-api-key',
    'company_id' => 123,
    'cardnumber' => '6064364918251828110',
    'pin'        => '968980'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['success']) {
    $balanceEuros = $result['balance'] / 100;
    echo "Card balance: €" . number_format($balanceEuros, 2) . "\n";
    echo "Status: " . $result['card_status'] . "\n";
    echo "Expires: " . $result['expiry_date'] . "\n";
} else {
    echo "Error: " . $result['error'] . "\n";
}