Devalue Card

Accept Festivalcadeau giftcard payments in your checkout. Send us the customer's card details and ticket amount, and we handle the rest.

Endpoint

Live

Sandbox

Request Parameters

Success Response 200 OK

On success you receive amount_deducted (what was taken from the card), remaining_to_pay (what the customer still owes), and a cancel_token that can be used once to reverse the deduction via the Cancel Devalue endpoint.

Full payment

{
    "success": true,
    "amount_deducted": 2500,
    "remaining_to_pay": 0,
    "cancel_token": "a1b2c3d4e5f6..."
}

Partial payment: card balance too low

// Ticket = €75.00, card balance = €30.00 → deducted €30.00, remaining €45.00
{
    "success": true,
    "amount_deducted": 3000,
    "remaining_to_pay": 4500,
    "cancel_token": "a1b2c3d4e5f6..."
}

Partial payment: exceeds €50 max

// Ticket = €75.00, card balance = €100.00 → deducted €50.00 (max), remaining €25.00
{
    "success": true,
    "amount_deducted": 5000,
    "remaining_to_pay": 2500,
    "cancel_token": "a1b2c3d4e5f6..."
}

Error Responses

401 Authentication Failed

{
    "success": false,
    "error": "Authentication Failed"
}

422 Missing Fields

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

400 Invalid Card or PIN

{
    "success": false,
    "error": "Invalid card number or PIN"
}

400 Card Not Active

{
    "success": false,
    "error": "Card is not active",
    "card_status": "Blocked"
}

400 Card Expired

{
    "success": false,
    "error": "Card has expired",
    "card_status": "Expired"
}

400 No Balance

{
    "success": false,
    "error": "Card has no balance",
    "card_status": "No balance"
}

Example Usage (PHP)

<?php

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

$data = [
    'apikey'     => 'your-api-key',
    'company_id' => 123,
    'cardnumber' => '6064364918251828110',
    'pin'        => '968980',
    'amount'     => 4500  // €45.00 in cents
];

$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 ($result['success']) {
    echo "Deducted: €" . number_format($result['amount_deducted'] / 100, 2) . "\n";

    if ($result['remaining_to_pay'] > 0) {
        echo "Remaining: €" . number_format($result['remaining_to_pay'] / 100, 2) . "\n";
        // Collect the remaining amount via another payment method
    } else {
        echo "Fully paid with giftcard!\n";
    }
} else {
    echo "Failed: " . $result['error'] . "\n";
    if (isset($result['card_status'])) {
        echo "Card status: " . $result['card_status'] . "\n";
    }
}

Integration Flow

1. Customer selects payment
   Customer clicks "Pay with Festivalcadeau" in your checkout
2. Collect card details
   Customer enters their card number and PIN
3. Call the API
   Send the card details and ticket amount to /devalue
4. We process the payment
   We validate the card, check if it's active, and deduct up to €50.00
5. Handle the response
   Check remaining_to_pay: if 0, fully paid. If > 0, collect the rest via another payment method.