Payment link widget

Embed a Fortpesa payment link into any website as a modal overlay or an inline iframe. The widget is pure browser-side, so your backend language does not matter — plain HTML, WordPress, React, Laravel, Django or a static site. The payment page is hosted at https://fortpesa.co.ke/pay/{uuid}; the widget just frames it and tells your page when the payment succeeds.

Before you start

Create a payment link in the dashboard (sidebar Payment links) — fixed amount or open amount.
Copy its UUID from the link detail page. The shared URL looks like https://fortpesa.co.ke/pay/9k3f2x....
Make sure the link is active and your merchant account has an approved channel.

The script is a single static file — no build step, no npm.

<script src="https://fortpesa.co.ke/paylink.js"></script>

<button onclick="Fortpesa.pay('YOUR-LINK-UUID')">Pay with M-PESA</button>

Fortpesa.pay() opens the payment in a modal, returns a Promise, and rejects with Payment modal closed by user if the customer dismisses it.

Fortpesa.pay('YOUR-LINK-UUID', {
  amount: 1500,                 // whole KES — open-amount links only
  phone: '0712345678',          // prefills the phone field
  customerName: 'Jane Wanjiru', // prefills the description field
  lockPrefill: true             // make the prefilled values read-only
})
  .then(function (result) {
    // result = { txId: '...', amount: 1500, phone: '254712345678' }
    return fetch('/order/paid', { method: 'POST', body: JSON.stringify(result) });
  })
  .catch(function () { /* modal closed — no payment made */ });

All options are optional. A fixed-amount link always charges its own amount, whatever you pass.

Inline iframe

No script needed:

<iframe
  src="https://fortpesa.co.ke/pay/YOUR-LINK-UUID?embed=1"
  style="width:100%;max-width:440px;height:700px;border:0"
  title="Pay with M-PESA"></iframe>

For a full checkout page where you want to prefill the customer’s details:

<iframe
  src="https://fortpesa.co.ke/pay/YOUR-LINK-UUID?embed=1&amount=1500&phone=0712345678&customer_name=Jane&lock=1"
  style="width:100%;max-width:440px;height:700px;border:0"
  title="Pay with M-PESA"></iframe>

Embed parameters

Parameter	Type	Notes
`embed`	flag	Render the payment card only — no site header or footer. Also sends the postMessage events below.
`amount`	integer	Whole KES. Open-amount links only — ignored on fixed-amount links.
`phone`	string	Kenyan mobile in `07…`, `2547…` or `+2547…` form. Invalid values are dropped, not rejected.
`customer_name`	string	Prefills the description field (max 120 characters).
`lock`	flag	Makes the prefilled phone / name / amount read-only.

Events (embed mode)

In embed mode the payment page posts messages to the parent window:

Message	When	Payload
`RESIZE`	On load and whenever the card changes height	`{ type: 'RESIZE', height: 640 }`
`PAYMENT_SUCCESS`	The payment confirmed as successful	`{ type: 'PAYMENT_SUCCESS', txId, amount, phone }`

window.addEventListener('message', function (e) {
  if (e.origin !== 'https://fortpesa.co.ke') return;
  if (e.data && e.data.type === 'PAYMENT_SUCCESS') {
    // verify server-side before fulfilling — see below
  }
});

In embed mode the iframe stays on the success card instead of redirecting to the receipt page — your page decides what happens next.

Verify the payment server-side

The success message is a UI hint, not proof. Before you deliver goods or mark an order paid, confirm the transaction with the API (GET /api/v1/transactions/{uuid}) or wait for the signed webhook. Both are covered in Transaction status and Webhooks.

Notes

The widget needs no API key in the browser — the UUID is the only identifier.
X-Frame-Options is removed on /pay/* and frame-ancestors * is sent, so framing works on any site. Everything else in the app stays unframeable.
The hosted link without ?embed=1 remains available as a plain page you can share on WhatsApp or by SMS.

Get started

API reference

Guides

Libraries & SDKs

AI agents

Payment link widget

Before you start

Inline iframe

Embed parameters

Events (embed mode)

Verify the payment server-side

Notes

​Before you start

​Modal button

​Inline iframe

​Embed parameters

​Events (embed mode)

​Verify the payment server-side

​Notes

Before you start

Modal button

Inline iframe

Embed parameters

Events (embed mode)

Verify the payment server-side

Notes