Take payments
Embed a paypoint on your website
One script tag puts a TukuPay payment form on any website or web app. No keys, no server code.
What it does
The script puts a small payment form (in an iframe) where you paste it. The payer types their phone and the amount, then pays by M-Pesa prompt or with their TukuPay wallet (confirmed with a 6-digit SMS code). The money lands in the paypoint's wallet, as with its QR code or link. When the paypoint's wallet has the payer pay the Bank & App charges, a small line under the amount shows them before the M-Pesa prompt, as on TukuPay's own checkout. The form follows your page's font and text colour by itself.
1. Get the paypoint's id
In TukuPay open Paypoints → a paypoint → Embed: the code is there ready to copy, with a live preview where you pick the colour, corners and light or dark. Or take the id from GET /v1/paypoints.
2. Paste the code
<!-- Paste where the payment form should show. No keys: this is safe in a public page. -->
<script src="https://api.tukupay.dev/api/v1/embed/tukupay.js"
data-paypoint="PAYPOINT_ID"
data-primary="#0f6b3a"
data-radius="12"
async></script>
<script>
// A hint for the page (show a thank-you). Not proof of payment: check it on your server.
document.addEventListener("tukupay:paid", (e) => {
console.log("Paid", e.detail.reference, e.detail.amount);
});
</script>Use data-paypoint for one paypoint, or data-merchant with your TukuPay username for a list of all your public paypoints (each opens its own form).
Options
| Attribute | Value | Default |
|---|---|---|
data-paypoint | A paypoint's id | One of these two is required |
data-merchant | Your TukuPay username: all your public paypoints | |
data-primary | Button colour, hex (#0f6b3a) | TukuPay green |
data-background | Background, hex or transparent | transparent (sits on your page) |
data-text | Text colour, hex | Your page's text colour |
data-radius | Corner radius in pixels, 0 to 28 | 12 |
data-font | A font your page already loads (letters, digits, spaces, commas, hyphens) | Your page's font |
data-google-font | A Google Fonts family to load, e.g. Poppins | None |
data-mode | light or dark | light |
data-amount | A starting amount in KES (the payer can change it unless the paypoint is fixed) | Empty |
Bad values are ignored and the default is used, so a typo never breaks the form.
How you know someone paid
- On the page: when a payment completes, the form fires a
tukupay:paidevent (it bubbles up todocument) withdetail.referenceanddetail.amount. Use it to say thank you. - On your server, before you hand anything over: look the payment up on your statement with a signed call:
GET /v1/statement?paypoint_id=PAYPOINT_ID&search=REFERENCE. It is paid when the row is there withstatuscompleted. - In TukuPay: every payment shows on the paypoint's statement and your notifications, as any paypoint payment does.
Treat tukupay:paid as a hint, never as proof: anyone can fire an event on their own copy of your page. Only TukuPay's answer to a signed call proves a payment.
// Your server: is this embed payment really paid?
import { TukuPay } from "@tukupay/sdk";
const tukupay = new TukuPay();
export async function embedPaymentIsPaid(paypointId, reference) {
const { rows } = await tukupay.statement({ paypoint_id: paypointId, search: reference });
return rows.some((r) => r.reference === reference && r.status === "completed");
}Your site's Content-Security-Policy
If your site sends a Content-Security-Policy header, allow TukuPay's script and frame:
Content-Security-Policy: script-src 'self' https://api.tukupay.dev; frame-src https://api.tukupay.devNothing to register on TukuPay's side: any website may show a paypoint's form (it only ever pays you). The form talks to TukuPay itself, so your connect-src needs nothing.
Safety
- No keys on the page. The embed uses only the paypoint's public id; never put a key secret in a web page.
- No PIN inside your page. A wallet payment that needs the payer's TukuPay PIN opens TukuPay's own checkout in a new tab instead.
- Messages from the form are checked: the script only listens to TukuPay's own origin and its own frame.
- Always real money. The embed has no sandbox. Test with a small amount (KES 10) on a paypoint you own.