Givacard / Cadeaukaart¶

Doel¶

De Zwerfkei cadeaukaart ("givacard") is een fysieke of digitale cadeaukaart waarmee klanten geheel of gedeeltelijk kunnen betalen in de webshop. Het systeem integreert met een externe dienst: Loyalty in a Box (loyaltyinabox.com) die het saldo en de transacties bijhoudt.

Huidige architectuur (legacy)¶

Er zijn twee lagen:

sequenceDiagram
    actor Klant
    participant Webshop as zwerfkei.nl
    participant GivacardApi as GivacardApi (server-side)
    participant LoyaltyBox as Loyalty in a Box API

    Note over Klant,Webshop: Saldo opvragen (saldocheck pagina)
    Klant->>Webshop: POST /saldocheck/get_saldo_info (kaartnummer + captcha)
    Webshop->>GivacardApi: login() + verifyCard(cardnumber)
    GivacardApi->>LoyaltyBox: POST VerifyCard
    LoyaltyBox-->>GivacardApi: { Balance, ResultCode, ... }
    GivacardApi-->>Webshop: saldo info
    Webshop-->>Klant: "Saldo: €XX,XX"

    Note over Klant,Webshop: Betalen met cadeaukaart (checkout)
    Klant->>Webshop: Kiest "Givacard" als betaalmethode
    Webshop->>GivacardApi: login() + verifyCard() + pay(amount)
    GivacardApi->>LoyaltyBox: POST Pay
    LoyaltyBox-->>GivacardApi: bevestiging
    GivacardApi-->>Webshop: success
    Webshop->>Webshop: Maak Payment record aan (type=givacard)

    Note over Klant,Webshop: Restant betalen
    Klant->>Webshop: Kiest tweede betaalmethode (iDEAL, etc.)
    Webshop->>Webshop: Verwerk gecombineerde betaling

API endpoint¶

GET /api/givacard¶

Server-side proxy voor de Loyalty in a Box API. Authenticatie via sessie-cookies die de backend onderhoudt.

Parameters:

Acties:

Relevante bestanden:

Checkout flow¶

Klanten kunnen de cadeaukaart als (deel)betaling gebruiken:

1. Klant kiest "Zwerfkei Givacard / Cadeaukaart" als betaalmethode op de betaalpagina
2. Klant voert het kaartnummer in (19 cijfers, verdeeld over 5 invoervelden)
3. Saldo wordt geverifieerd via GivacardApi::verifyCard()
4. Bij voldoende saldo: GivacardApi::pay() wordt aangeroepen
5. Er wordt een Payment-record aangemaakt met type = Payment_type::givacard (id: 10)
6. Als het orderbedrag groter is dan het kaartsaldo: klant kiest een extra betaalmethode voor het restant

Session handling:

Kaartgegevens worden tijdelijk in de sessie bewaard (giftcard session key) als JSON-array, geïndexeerd op kaart-ID:

$session['giftcard'][$cardId] = json_encode([
    'saldo' => ...,
    'number' => ...,
    'pin' => ...
]);

Relevante bestanden:

Cadeaukaart kopen (webshop)¶

Klanten kunnen ook zelf een cadeaukaart kopen in de webshop:

• Vaste artikel-ID: 30108, barcode: 2000000420585
• Klant voert een zelf te kiezen bedrag in (minimum €10,00, maximum €500,00)
• Het bedrag wordt meegegeven als quantity (in centen) bij het toevoegen aan de winkelwagen
• Na betaling wordt de kaart opgewaardeerd via GivacardApi::reload() / activate()

Rapportage¶

Maandelijks wordt automatisch een CSV-rapport gegenereerd van afgewaardeerde kaarten en givacard-betalingen:

• Givacard_item::report() — rapport van oude/uitgegeven kaarten → administratie@zwerfkei.nl
• Givacard_item::reportPayByGivacard() — rapport van givacard-betalingen via Payment-tabel

Knelpunten huidige implementatie¶

• Session-scraping login: GivacardApi logt in op de Loyalty in a Box webinterface via cURL + HTML scraping + cookie-beheer — fragiel en afhankelijk van de paginastructuur
• Geen echte REST API: de externe dienst biedt een .aspx endpoint aan (WebTerminal2/Index.aspx/...) — dit is niet de standaard REST API die moderne diensten aanbieden
• Gecombineerde betaling: de flow voor deelbetaling + tweede betaalmethode is complex en verspreid over meerdere componenten
• Dubbele registratie: zowel in Payment-tabel (Pay.nl givacard type V662) als in de legacy giveacard-tabel

Target situatie¶

Milestone: Givacard v2