Skip to content
Helpcentrum-gidsOnboardingfase 2
3 min leestijdGecontroleerd 2026-11-16

Cadeaukaarten & prepaidkaarten

Configureer opwaardeermechanieken voor cadeaukaarten met controleerbare saldotransacties.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Kiezer 'Add a Pass Mechanic' (Ingesneden)

Kies uit 6 ingebouwde mechanieken: Stempelkaart, Stempelverzilvering, Tegoed (Stored Value), Punten & niveaus, Validatie eenmaal per dag of Vervaldatum verlengen.

Overzicht

Met digitale cadeaukaarten en opwaardeerbare prepaidkaarten kunnen winkeliers, cafés, horecazaken en retailers kooptegoed in eigen huisstijl rechtstreeks uitgeven aan Apple Wallet en Google Wallet. Klanten hebben hun actuele saldo altijd bij de hand op hun smartphone, terwijl financiële teams beschikken over een onveranderlijk dubbelboekhoudkundig auditgrootboek voor financiële reconciliatie.

Backendarchitectuur & Stored Value-entiteiten

Opgeslagen-waardefunctionaliteit (Stored Value) in Passinstance wordt aangestuurd door specifieke financiële saldomodellen in het Passinstance database-schema:

  • Pastype (pass type): storeCard (toont live geldbedragen prominent in de primaire paszones).
  • Catalogus-demoblauwdruk: gift-card.
  • Mechaniektype (mechanic type): PREPAID_CARD.
  • Belangrijkste financiële modellen:

- prepaid account: Houdt het actieve geldsaldo bij met geheeltallige rekenkunde in kleinste valuta-eenheden (balanceMinor) en valutacodes (currency: "EUR" | "USD"). - prepaid ledger entry: Onveranderlijk auditgrootboek dat elke bijschrijving, afschrijving, opwaardering en correctie vastlegt met tijdstempels, medewerkers-ID's, POS-terminalreferenties en idempotenciesleutels.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
STORED VALUE-GROOTBOEKTRANSACTIE
DEELNEMENDE SYSTEEMACTOREN
P1 Kassalezer / E-commerce
P2 Passinstance Core API
P3 Passinstance database-database & grootboek
STAP 1 VERZOEK / ACTIE POST/api/v1/reader/redeem
STAP 2 VERZOEK / ACTIE Account ophalen
›
(Huidig saldo)
STAP 3 VERZOEK / ACTIE Invariantcontroles:
›
Status === ACTIVE
›
Saldo >= Afschrijving
STAP 4 VERZOEK / ACTIE Atomaire transactie
›
Update prepaid account
›
Voeg LedgerEntry toe
STAP 5 ANTWOORD 200 OK (resultingValue)
STAP 6 VERZOEK / ACTIE Stille APNs-push
›
(Apple toegangsscherm:
›
& Google REST PATCH
›
"Betaald € 12,50. Nieuw
›
saldo: € 37,50")

Regels van de mechaniekengine & boekhoudkundige waarborgen

De Pass Mechanics Engine dwingt strikte financiële invarianten af op Stored Value-bewerkingen:

  1. 1
    Weergave in kleinste valuta-eenheden: Saldi worden berekend in gehele subeenheden (bijv. 2500 staat voor $ 25,00 USD en 1550 staat voor € 15,50 EUR). Dit voorkomt afrondingsfouten met zwevendekommagetallen bij hoogfrequente winkeltransacties.
  2. 2
    Preventie van negatief saldo (disallowNegativeBalance: true): De server weigert strikt elk afschrijvingsverzoek waarbij currentBalanceMinor - debitAmountMinor < 0, en retourneert HTTP 400 met foutcode INSUFFICIENT_FUNDS.
  3. 3
    Waarborgen voor opwaarderen (disableAutoRecharge: true): Voorkomt geautomatiseerde herladingen tenzij uitdrukkelijk geautoriseerd via opgeslagen betaalmethoden van de klant.
  4. 4
    Idempotentiebescherming: Elk afschrijvings- of opwaardeerverzoek accepteert een unieke idempotencyKey. Dubbele POS-verzoeken door netwerkherpogingen retourneren veilig het oorspronkelijke succesvolle antwoord zonder de klant dubbel te belasten.

Atomaire POS-afschrijving & saldo-opwaardering

Kassamedewerkers, geïntegreerde POS-hardware en geautomatiseerde zelfscankassa's communiceren met de Reader Orchestration API of baliescan-endpoints:

HTTP-verzoek

POST /api/v1/reader/redeem
Headers
X-Reader-Secret <reader integration secret>
Content-Type application/json
JSON
{
  "customerId": "8f94d930-b302-4fc8-9f12-000000000001",
  "passId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "amount": "12.50",
  "idempotencyKey": "pos_tx_20261115_0091",
  "operatorId": "cashier_alex"
}

HTTP-respons (200 OK)

JSON
{
  "success": true,
  "resultingValue": "37.50"
}

Opmerking: Baliemedewerkers kunnen saldi ook debiteren of crediteren via POST /api/v1/scans (met x-scanner-key) of POST /api/v1/passes/:id/use / POST /api/v1/passes/:id/adjust-value (met Bearer-/API-sleutelauthenticatie), en transacties controleren via GET /api/v1/balance-changes?passId=<passId>. Stored Value-regels ondersteunen StoredValueOperation (NONE, ADD, SUBTRACT, SET) en StoredValueAmountSource (FIXED, OPERATOR, MECHANIC). Gebruik externalId bij aanmaak om wallet-passen te koppelen aan externe cadeaukaartnummers in uw kassasysteem.

Openbare opwaardeersessies voor klanten

Pashouders kunnen zelf hun saldo bekijken en online kooptegoed bijstorten:

  • Handelaren kunnen links voor zelf opwaarderen uitgeven die worden ondersteund door GET /api/v1/public/reload-sessions/:token en de betaalstatus pollen via GET /api/v1/public/reload-sessions/:sessionId/status.
  • De opwaardeersessie integreert met Stripe, PayPal, Paystack of Mobile Money (MTN MoMo, Orange Money) om betalingen te verwerken, de prepaid account direct te crediteren en het bijgewerkte saldo naar Apple Wallet en Google Wallet te pushen.

Belangrijk: Configureer altijd changeMessage: "Nieuw saldo: %@" op het saldoveld in de visuele sjablooneditor. Zodra een afschrijving of opwaardering plaatsvindt, licht de telefoon van de klant direct op met een native melding op het toegangsscherm met het nieuwe beschikbare saldo.

Ontdek meer in onze Use-case voor cadeaukaarten.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.