Sales Payments (M-Pesa & Card)

Sales Payments exists to close the gap most businesses actually struggle with. Taking the money is rarely the hard part — a customer can already pay your till. The pain is reconciliation: a cashier squints at a confirmation SMS, finance re-keys the receipt into the ledger, and a half-paid invoice quietly drifts out of sync. AWRA's answer is to make the act of paying and the act of recording the same event, so a successful payment posts itself against the exact invoice or POS sale it settles.

The defining design choice is that it is non-custodial. Each business connects its own Safaricom Daraja and Paystack credentials, and money settles directly into that business's own till, paybill, and bank. AWRA never holds, pools, or routes your funds — it only triggers the request and records the outcome. This is deliberately separate from how you pay for your AWRA subscription (that is the platform billing you as a customer); sales payments are you billing your own customers, on your own rails. Confusing the two is the single most common misconception, so anchor on it: the subscription M-Pesa/Paystack config is the platform's; the sales config is the tenant's.

Because credentials are per-tenant and sensitive, they are encrypted at rest and entered under Payment Settings, where a one-click "Test connection" confirms the keys authenticate before you rely on them. Everything downstream — STK prompts, QR, card popups, reconciliation, refunds — runs on those stored credentials. The mental model to carry through the rest of this course is a four-step loop: connect your accounts once, charge the customer, receive a signed confirmation from the provider, and reconcile that confirmation onto the sale automatically.

M-Pesa offers four ways to collect, and choosing well is mostly about who starts the payment. With an STK push, the cashier enters the customer's phone number and AWRA sends a PIN prompt to that phone; the customer approves and the confirmation flows back. STK is the right tool when staff drive the transaction at a counter. A Dynamic QR is generated for the exact amount — shown on the register screen or printed on the invoice — and the customer scans it in their M-Pesa or My Safaricom app; it is ideal when you would rather the customer pay on their own device without you typing their number.

The third path is the customer-initiated one: the customer simply pays your Paybill or Till directly from M-Pesa, the way they always have. AWRA supports both Paybill (CustomerPayBillOnline) and Till / Buy Goods (CustomerBuyGoodsOnline) — for a Till you put the store/head-office number in Shortcode and the Till number in Party B. The crucial detail is that customer-initiated payments only auto-confirm after you register your C2B Confirmation/Validation URLs with Safaricom (the "Register payment URLs" button). Until you do, that money lands in your till but AWRA never hears about it; after you do, Safaricom posts every such payment to AWRA, which matches it to the invoice by the account reference the customer typed.

STK and customer-initiated payments differ in one operational way worth internalising: STK fires its own callback because AWRA started it, so it auto-confirms with no extra setup; customer-initiated and QR payments are started by the customer, so they rely on C2B registration to be heard. That is why a brand-new account can charge by STK immediately but should register C2B before leaning on Paybill/Till or QR for hands-off reconciliation. The account reference is the bridge for Paybill matching, which is why invoices instruct the customer to use the invoice number as the account.

Card acceptance runs through the tenant's own Paystack account and comes in two shapes chosen by context. On the POS register, AWRA uses Paystack's inline popup: the cashier selects card, a secure Paystack window opens over the page, and — critically — the cart is never abandoned because the page does not navigate away. On a successful charge the popup hands control back to AWRA, which fills the amount paid and completes the sale, so the receipt prints exactly as it would for cash. On an invoice (and on a saved POS sale), AWRA uses a hosted checkout link instead: the customer is taken to Paystack's page and returned to the relevant record afterward.

Whichever shape is used, the authoritative confirmation is the Paystack webhook, not the browser. After the charge, Paystack sends a server-to-server event that AWRA verifies by recomputing an HMAC SHA-512 signature with that tenant's secret key — a forged or tampered call fails the check and is ignored. Only a verified charge.success marks the transaction paid and posts it to the ledger. This is why a flaky network on the customer's phone does not lose a payment: even if the browser never returns, the webhook still arrives and reconciles.

The reason the register uses the inline popup rather than a redirect is practical: a redirect mid-sale would lose the in-progress cart, whereas the popup keeps the cashier on the register and lets AWRA finalize the sale on success. The hosted link suits invoices because the payable already exists and there is no fragile cart to preserve. In both cases the money settles to the tenant's Paystack balance and the recorded payment is tied to the invoice or sale, so card and M-Pesa reconcile through the same path.

Reconciliation is the point of the whole feature. When a provider confirms a payment, AWRA records it in a unified sales-payments ledger and matches it to the invoice or POS sale it settles — for a Paybill payment, by the account reference the customer typed; for STK, QR, and card, by the transaction the charge was raised against. On a match it posts the payment, reduces the balance, and updates the status. The matching and posting are idempotent: a provider that sends the same confirmation twice (they sometimes retry) will not double-credit the sale, and a payment already recorded by the checkout flow is flagged so a later webhook does not post it again.

The payments dashboard ("All Transactions") is where you supervise it. It lists every transaction across methods and statuses — received, pending, failed, reversed — with filters by date, method, and provider, and KPI tiles for totals. Two safety nets sit behind it. First, a background job periodically queries the provider for any STK left pending and resolves it to success or failed, so nothing sits "pending" forever because a callback was missed. Second, payments that genuinely cannot be matched to a sale — most often a customer who typed the wrong account number — are not lost; they are surfaced as unmatched receipts.

The unmatched-receipts screen is the manual escape hatch that keeps the books honest. It lists confirmed money that arrived without a home, and lets a clerk attach each receipt to the right invoice or POS sale in one click — at which point it posts to that record exactly as an auto-matched payment would, re-using the same idempotent posting so there is no double counting. The discipline to teach is simple: money is never silently dropped; if it is not on a sale, it is waiting in unmatched for someone to place it.

Refunds and reversals are deliberately treated as destructive actions. They are off by default; a business turns them on under Payment Settings, and only then do the Refund/Reverse buttons appear on invoices, POS sales, and the dashboard — and the server also blocks the action when the setting is off, so a hidden button is not the only guard. When enabled, triggering one opens a confirmation dialog that shows the method, receipt number, and amount before any money moves. A card refund goes through Paystack; an M-Pesa reversal goes through Daraja and is asynchronous — Safaricom accepts the request and posts the outcome back to a result URL. Either way, once it succeeds the customer is paid back and the balance on the linked invoice or sale re-opens, with the reversal shown in the records.

Receipts close the customer-facing loop. A business can opt in to automatically email or SMS the customer a branded receipt the moment a payment succeeds — reusing the same POS receipt template — and because SMS has a cost, this is an explicit per-tenant setting rather than an on-by-default surprise. Independently of auto-send, the payment method now appears on POS receipts and invoice PDFs, so a printed receipt reads "Paid (MPESA)" or "Paid (CARD)", and a refunded invoice shows the reversal line.

Going live is mostly credentials and registration. In sandbox you test with Safaricom's shared test shortcode and passkey; in production each tenant enters its real Daraja Go-Live keys and its own Paybill/Till, switches the environment to live, registers its C2B URLs, and adds the Paystack webhook URL in the Paystack dashboard. M-Pesa reversals additionally need the tenant's initiator credentials plus Safaricom's public certificate configured on the server, which is why reversal is realistically a production capability. As an optional hardening step, webhook endpoints can be locked to the providers' source IP ranges — platform-level, since those IPs belong to Safaricom and Paystack, not to any one tenant.