Best practices

12.1 Money

Store money as integer cents in your database and convert only for display. Never send 4.50, "4.50" or 4.5 to InnBucks.
Keep the currency with every amount. A code, a deposit and its reversal must use the same currency.

Generate your own unique reference for every request that takes one, and save it before you send the request. Use short, plain values (letters, digits and hyphens, such as ORD-10045); InnBucks doesn’t publish a length limit.
Deposits: the reference is the only key for a deposit inquiry or a reversal. A deposit without your own reference can’t be traced reliably.
Reversals and inquiries need a new participantReference each; the original goes in originalParticipantReference.

One code inquiry every 30 seconds per code, starting 30 seconds after generating it.
Stop at Claimed, Paid, Expired or Timed Out.
Stop at about 11 minutes even without a final status, and mark the payment unknown for review, not failed. Re-check it once more later.
Run checks in a queue or scheduled job. Let the customer’s browser poll your server.

Make “mark as paid” idempotent: a repeated Claimed must never fulfil twice.
Never re-send a deposit, bank change or utility payment after a timeout. Look it up first (deposit inquiry), or check your statement and ask InnBucks with the X-Trace-Id.

Credentials and the access token live only on your server. A mobile app gets the code, QR and deep link from your server, never the API key.
Use HTTPS everywhere and keep your server’s clock right (token timing depends on it).
Don’t log secrets. Mask phone numbers and account numbers in logs where you can.
Agents: check the customer’s national ID against the linked account name before every deposit. It is a compliance requirement, not an option.

Put your reference in narration: it is what appears on your InnBucks merchant statement.
Save code, stan, authNumber and processedDateTime against each order.
Pull the account statement (7.11) daily, one calendar month at a time at most, and match it to your orders.

Show the amount, the code, the QR code, *569# and a 10-minute countdown together. Add the deep link on mobile.
Tell the customer to keep the page open until payment completes, and update it the moment your server sees Claimed.
When a code expires, offer a new one with one tap.

This page is generated from section 12 of the README in README.md. Spotted something wrong? Open an issue.