Core concepts

Transaction ID — the source of truth#

Every MoMo transfer has a Transaction ID chosen by the network (MTN, Telecel or AirtelTigo). LokiPay stores one record per (network, Transaction ID), and a Transaction ID can verify at most one payment, enforced by a unique constraint in the database. Re-sent SMS, duplicate claims and double clicks can never credit twice.

Payments (intents)#

A payment — called an intent in the API — is something you expect to be paid for: an order, an invoice, or one payer on a payment link. It has your reference (for example an order ID), an expected amount, an amount policy, and a LokiPay short reference the customer types when paying.

Short references#

References are 8 characters from an alphabet without look-alikes (no 0 O 1 I) and contain the marker LP at a random position — 4KLP7QMX, Q7MX2DLP, LP4GH3W2. The marker lets LokiPay find the reference anywhere in an SMS; the varying position avoids a fixed prefix on every transfer, which networks may flag.

Payment links#

A payment link is a reusable page with a fixed amount, like /pay/football-jersey. Every payer who presses Pay gets their own payment and reference, so payments never collide.

Claims (“I have paid”)#

If a customer forgot the reference or the SMS is late, they submit the Transaction ID from their MoMo confirmation. When the matching SMS arrives — or if it already has — LokiPay verifies the payment. See claims.

Relay phones#

The phone with the MoMo SIM runs the LokiPay Relay app. Each phone is paired once with a QR code and gets its own signing key; every request it sends is signed (HMAC-SHA256) and checked for replay. Revoking a phone in the dashboard disconnects it immediately.

Money#

All amounts are integers in pesewas (GHS 1.00 = 100) to avoid rounding errors. Currency is GHS.

Glossary