Integrations

Integration Recipes

The same four primitives — payment, checkout, webhook, payout — compose into very different businesses. Pick your shape; each recipe lists the exact endpoints and the gotchas that matter for that shape.

🏫 School — fee collection

Shape: known payers, invoice-like amounts, paid remotely by parents or at the bursar's desk.

• Partial payments: create a payment per instalment; sum paid payments per metadata.student_id for the outstanding balance.
• Reconciliation: filter GET /v1/payments?merchant_ref=… or export the CSV statement per term window.

🏥 Hospital / clinic — patient billing

Shape: amounts decided at the point of service, paid immediately at a counter, several counters in parallel.

• Each billing point creates payments with merchant_ref: "INV-<invoice>" and narration: "Consultation — Dr. …" (the narration shows on the customer's InnBucks side and your statement).
• Counter screens use the kiosk pattern; waiting rooms can use printed QR + payment-link SMS for settle-before-collection.
• Run one webhook receiver in the HIS; route on merchant_ref prefix to the right department's ledger.
• Idempotency keys = invoice numbers, so a double-clicked “bill” button can never double-charge.

🏪 Tuck shop / retail counter — till + cash point

Shape: small fast baskets, mixed cash/wallet, often doubling as the neighbourhood cash point.

• Basket → POST /v1/payments → show code/QR on the till (kiosk pattern). The 18-second sandbox auto-settle makes training demos painless.
• No coins? Bank change sends ≤ USD 5.00 change to the customer's wallet in seconds.
• Cash-out service: withdrawal codes — hand over cash only on redeemed.
• Sell airtime from the same balance with utility payments and keep the commission.
• End of day: dashboard → statement CSV; weekly POST /v1/payouts to move takings to the owner's wallet.

🚐 Fleet operator — fares & driver settlement

Shape: many small payments collected in the field by drivers/conductors, settled centrally.

• The operator's app (one merchant account, one key on the operator's server) creates a payment per fare; conductor shows the QR from their phone, passenger scans and pays.
• metadata: {vehicle, route, driver_id} on every fare → GET /v1/payments filters become per-vehicle takings reports.
• Driver settlement is internal bookkeeping over the ledger: sum paid fares per driver_id per day, pay drivers your way; the platform balance pays out to the operator's wallet.
• Field reality: codes expire in 10 minutes and create instantly — create the payment when the passenger boards, not in batches.

🛍️ Online store — e-commerce checkout

Shape: classic web checkout, customer remote, fulfilment after payment.

• Cart → server creates payment (Idempotency-Key: order-<id>) → redirect to checkout_url, or keep them on-page with pos.js.
• Fulfil only on payment.paid via verified webhook; treat the browser redirect as UX.
• Abandoned checkout = payment.expired webhook → send a “complete your order” email with a fresh payment link.
• Refund-ish flows: codes can't be reversed (InnBucks rule) — issue store credit or a manual InnBucks transfer, and track it as your own business process.

Which products each shape uses