TukuPay Docs

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

AttributeValueDefault
data-paypointA paypoint's idOne of these two is required
data-merchantYour TukuPay username: all your public paypoints
data-primaryButton colour, hex (#0f6b3a)TukuPay green
data-backgroundBackground, hex or transparenttransparent (sits on your page)
data-textText colour, hexYour page's text colour
data-radiusCorner radius in pixels, 0 to 2812
data-fontA font your page already loads (letters, digits, spaces, commas, hyphens)Your page's font
data-google-fontA Google Fonts family to load, e.g. PoppinsNone
data-modelight or darklight
data-amountA 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

  1. On the page: when a payment completes, the form fires a tukupay:paid event (it bubbles up to document) with detail.reference and detail.amount. Use it to say thank you.
  2. 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 with status completed.
  3. 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.dev

Nothing 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.