No matching payment yet. Ask the customer to show the confirmation SMS, or check again in a moment.
) : null}
);
}
type SendResult = "confirmed" | "failed" | "timeout";
type CheckResult = "confirmed" | "unpaid";
/** STK push: send a payment prompt to the customer's phone, then follow it through MpesaStatus. */
function StkPush({
amount,
defaultPhone,
disabled,
onSendPrompt,
onCheckStatus,
onConfirmed,
}: {
amount: number;
defaultPhone?: string;
disabled?: boolean;
/** Card 012: `amount` is what this push asks for (the part being paid by M-Pesa in a split). */
onSendPrompt: (phone: string, amount: number) => Promise<{ state: SendResult; receiptNo?: string }>;
onCheckStatus: (phone: string, amount: number) => Promise<{ state: CheckResult; receiptNo?: string }>;
onConfirmed: (c: PaymentConfirmation) => void;
}) {
const [phone, setPhone] = React.useState((defaultPhone ?? "").replace(/\D/g, "").slice(-9));
const [state, setState] = React.useState(null);
const [receipt, setReceipt] = React.useState();
const run = React.useRef(0);
const display = `+254 ${phone.slice(0, 3)} ${phone.slice(3, 6)} ${phone.slice(6)}`;
const valid = /^[17]\d{8}$/.test(phone);
const send = async () => {
const id = ++run.current;
setState("waiting");
const r = await onSendPrompt(`254${phone}`, amount);
if (id !== run.current) return; // cancelled or resent meanwhile
setState(r.state);
if (r.state === "confirmed") {
setReceipt(r.receiptNo);
onConfirmed({ method: "M-Pesa", channel: "STK push", reference: r.receiptNo ?? "", phone: `+254${phone}` });
}
};
// After a timeout, ask M-Pesa before anything else: the customer may have paid late (IG-05).
const check = async () => {
const id = ++run.current;
setState("checking");
const r = await onCheckStatus(`254${phone}`, amount);
if (id !== run.current) return;
setState(r.state);
if (r.state === "confirmed") {
setReceipt(r.receiptNo);
onConfirmed({ method: "M-Pesa", channel: "STK push", reference: r.receiptNo ?? "", phone: `+254${phone}` });
}
};
if (state)
return (
{
run.current++;
setState(null);
}}
onResend={send}
onCheck={check}
onOtherMethod={() => setState(null)}
/>
);
return (
Customer phone
setPhone((e.target as HTMLInputElement).value.replace(/\D/g, "").slice(-9))}>
The customer gets a prompt for KES {amount.toFixed(2)} and enters their M-Pesa PIN.
);
}
/**
* M-Pesa tender: STK push (prompt on the customer's phone), Paybill (business number + account number) or
* Till (Buy Goods). Paybill and Till confirm with the customer's M-Pesa code or a lookup.
* `onSendPrompt` and `onVerify` are the API calls; the defaults simulate them for previews.
*/
export function MpesaPayment({
amount,
accountRef,
paybill = "174379",
till = "5123456",
defaultPhone = "712345678",
disabled,
// Previews: a number ending 0000 times out and turns out paid; ending 1111 times out unpaid.
onSendPrompt = async (phone) => {
await wait(2500);
return /(0000|1111)$/.test(phone) ? { state: "timeout" } : { state: "confirmed", receiptNo: fakeReceipt() };
},
onCheckStatus = async (phone) => {
await wait(1500);
return phone.endsWith("0000") ? { state: "confirmed", receiptNo: fakeReceipt() } : { state: "unpaid" };
},
onVerify = async ({ code }) => {
await wait(1200);
return code ?? fakeReceipt();
},
onConfirmed = () => {},
stkOnly = false,
}: {
amount: number;
/** Card 012: only the STK push tab, for a live till until Paybill and Till payments can be verified (M-Pesa C2B, Phase 2). */
stkOnly?: boolean;
/** Paybill account number: the sale's receipt number, so the payment matches the sale. */
accountRef: string;
paybill?: string;
till?: string;
defaultPhone?: string;
disabled?: boolean;
onSendPrompt?: (phone: string, amount: number) => Promise<{ state: SendResult; receiptNo?: string }>;
/** Queries the STK request status; called after a timeout, before any resend. */
onCheckStatus?: (phone: string, amount: number) => Promise<{ state: CheckResult; receiptNo?: string }>;
/** Plan F: `amount` is what this tab is collecting, so a payment can be checked against it (C2B). */
onVerify?: (q: { code?: string; accountRef: string; amount: number }) => Promise;
onConfirmed?: (c: PaymentConfirmation) => void;
}) {
return (
{stkOnly ? null : (
STK pushPaybillTill
)}
);
}
/* ======================================= Card ========================================= */
type Brand = "Visa" | "Mastercard" | "Amex" | "Card";
export function cardBrand(digits: string): Brand {
if (/^4/.test(digits)) return "Visa";
if (/^(5[1-5]|2(2[2-9]|[3-6]\d|7[01]|720))/.test(digits)) return "Mastercard";
if (/^3[47]/.test(digits)) return "Amex";
return "Card";
}
/** Luhn checksum: catches mistyped card numbers before they reach the gateway. */
export function luhn(digits: string) {
let sum = 0;
for (let i = 0; i < digits.length; i++) {
let d = Number(digits[digits.length - 1 - i]);
if (i % 2 === 1) {
d *= 2;
if (d > 9) d -= 9;
}
sum += d;
}
return digits.length > 0 && sum % 10 === 0;
}
const groupCard = (d: string, brand: Brand) =>
brand === "Amex" ? [d.slice(0, 4), d.slice(4, 10), d.slice(10, 15)].filter(Boolean).join(" ") : (d.match(/.{1,4}/g) ?? []).join(" ");
function expiryError(v: string) {
const m = /^(\d{2})\/(\d{2})$/.exec(v);
if (!m) return "Enter the expiry as MM/YY";
const month = Number(m[1]);
if (month < 1 || month > 12) return "Month must be 01 to 12";
const now = new Date();
const end = new Date(2000 + Number(m[2]), month, 1); // first day after the expiry month
return end <= now ? "This card has expired" : "";
}
/** Card terminal: the terminal takes the card; the cashier records what it printed. No card number in the app. */
function TerminalCard({ amount, disabled, onConfirmed }: { amount: number; disabled?: boolean; onConfirmed: (c: PaymentConfirmation) => void }) {
const [brand, setBrand] = React.useState("");
const [last4, setLast4] = React.useState("");
const [approval, setApproval] = React.useState("");
const [tried, setTried] = React.useState(false);
const [done, setDone] = React.useState(false);
const errs = {
brand: brand ? "" : "Choose the card type",
last4: /^\d{4}$/.test(last4) ? "" : "Enter the last 4 digits",
approval: /^[A-Z0-9]{6}$/.test(approval) ? "" : "Enter the 6-character approval code",
};
const ok = !errs.brand && !errs.last4 && !errs.approval;
if (done)
return (
Card payment recorded
{brand} ending {last4}, approval {approval}.
);
return (
Enter KES {amount.toFixed(2)} on the terminal and ask the customer to tap, insert or swipe. When it approves, record the
slip details below.