Quickstart
Maak een bon aan zodra de klant heeft betaald. De API geeft een korte URL terug — codeer die op je puck (of laat ons de puck voor je leveren).
curl https://api.tapreceipt.com/v1/receipts \
-H "Authorization: Bearer sk_live_********" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "mer_018E7Q",
"currency": "EUR",
"total_minor": 940,
"lines": [
{ "name": "Filterkoffie", "qty": 1, "price_minor": 380 },
{ "name": "Kaneelbroodje", "qty": 1, "price_minor": 350 },
{ "name": "Bio sinaasappel","qty": 1, "price_minor": 210 }
]
}'Je krijgt een bon-object terug met een publieke url. Schrijf die URL één keer bij het inrichten op de puck — elke volgende tap roteert de handtekening automatisch.
Authenticatie
Alle aanvragen gebruiken een Bearer-token. Test-keys beginnen met sk_test_, live-keys met sk_live_. Je kunt op elk moment roteren vanuit het dashboard — de vorige key blijft tien minuten geldig.
Authorization: Bearer sk_live_5p9d2a...
Webhooks
Abonneer je op events op het moment dat ze plaatsvinden — taps, wallet-opslag, verwijderingen, sabotage-alerts. Elk event wordt ondertekend met HMAC-SHA256.
POST /your-handler
{
"id": "evt_01HZRY9C...",
"type": "receipt.tapped",
"created": 1746200400,
"data": {
"receipt_id": "rcp_018E7Q...",
"puck_id": "pck_LDN_03",
"country": "NL"
}
}Verifieer door de TapReceipt-Signature-header te vergelijken met een HMAC van de ruwe request body.
SDKs
Node / TypeScript
npm i tapreceipt
Python
pip install tapreceipt
Go
go get github.com/tapreceipt/go
Ruby
gem install tapreceipt
Fouten
De API gebruikt gangbare HTTP-statuscodes. De body bevat altijd een type en een leesbare message.
{
"error": {
"type": "validation_error",
"param": "total_minor",
"message": "must be a non-negative integer"
}
}