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.
Regels van de mechaniekengine & boekhoudkundige waarborgen
De Pass Mechanics Engine dwingt strikte financiële invarianten af op Stored Value-bewerkingen:
-
1
Weergave in kleinste valuta-eenheden: Saldi worden berekend in gehele subeenheden (bijv.
2500staat voor $ 25,00 USD en1550staat voor € 15,50 EUR). Dit voorkomt afrondingsfouten met zwevendekommagetallen bij hoogfrequente winkeltransacties. -
2
Preventie van negatief saldo (
disallowNegativeBalance: true): De server weigert strikt elk afschrijvingsverzoek waarbijcurrentBalanceMinor - debitAmountMinor < 0, en retourneert HTTP 400 met foutcodeINSUFFICIENT_FUNDS. -
3
Waarborgen voor opwaarderen (
disableAutoRecharge: true): Voorkomt geautomatiseerde herladingen tenzij uitdrukkelijk geautoriseerd via opgeslagen betaalmethoden van de klant. -
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
/api/v1/reader/redeem
{
"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)
{
"success": true,
"resultingValue": "37.50"
}
Opmerking: Baliemedewerkers kunnen saldi ook debiteren of crediteren via
POST /api/v1/scans(metx-scanner-key) ofPOST /api/v1/passes/:id/use/POST /api/v1/passes/:id/adjust-value(met Bearer-/API-sleutelauthenticatie), en transacties controleren viaGET /api/v1/balance-changes?passId=<passId>. Stored Value-regels ondersteunenStoredValueOperation(NONE,ADD,SUBTRACT,SET) enStoredValueAmountSource(FIXED,OPERATOR,MECHANIC). GebruikexternalIdbij 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/:tokenen de betaalstatus pollen viaGET /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 accountdirect 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.
