Paylink Widget

Embed a Palpluss payment link into any website as a modal overlay or inline iframe. The widget is pure browser-side — your backend language (Node.js, PHP, Python, Laravel, Django, etc.) does not matter.

@palpluss/paylink is a frontend-only browser package. It has no dependency on @palpluss/sdk and runs entirely in the visitor’s browser. Your server never handles raw payment credentials.

Getting Your Paylink ID

Every integration — whether you use the npm package, the CDN script, or a raw iframe — starts with a paylink ID. Here is how to generate one from the Palpluss Console.

Step 1 — Open Create Pay Link

Log in to the Palpluss Console and click Create Pay Link in the left sidebar under the SERVICES section. You will see the Generate Pay Link form with the following fields:

Field	Required	Description
Payment Channel	Optional	Select a Paybill or Till to receive the payment. Leave empty to use your tenant default channel.
Amount (KES)	Optional	Pre-fill the amount. If left empty the customer enters it themselves on the payment page.
Customer Phone	Optional	Pre-fill the customer’s M-PESA number so they don’t have to type it.
Customer Name	Optional	Pre-fill the customer’s name on the payment page.
Reference	Optional	An invoice number, order ID, or any internal reference you want attached to the transaction.

Click Advanced Options to set an expiry date or additional restrictions.

Step 2 — Generate the link

Once you have filled in the values you need, click the Generate Pay Link button at the bottom of the form. A modal will appear confirming the link was created:

PAY LINK URL
https://link.palpluss.com/1fbb7b69-ac0e-4439-a08d-40bfd9ee13de

Status   ACTIVE
Expires  Never

Step 3 — Copy only the ID

The full URL has this format:

https://link.palpluss.com/{paylink-id}

You only need the ID portion — the UUID that comes after the last /. In the example above that is:

1fbb7b69-ac0e-4439-a08d-40bfd9ee13de

This is the value you pass to pay(), the <PalplussPayment> component, or the src attribute of the raw iframe:

// ✅ correct — just the ID
await pay('1fbb7b69-ac0e-4439-a08d-40bfd9ee13de')

// ❌ wrong — do not pass the full URL
await pay('https://link.palpluss.com/1fbb7b69-ac0e-4439-a08d-40bfd9ee13de')

You can click Preview in the modal to open the payment page in a new tab and confirm it looks correct before sharing it with customers.

How It Works

Your page                          Palpluss
─────────────────────────────      ──────────────────────
pay('abc-123')
  │
  ▼
Creates full-screen overlay
Injects <iframe src="https://link.palpluss.com/abc-123?embed=1[&amount=…&phone=…]">
  │
  │  ◄──── postMessage: RESIZE ──────────────── iframe adjusts height
  │  ◄──── postMessage: PAYMENT_SUCCESS ─────── payment complete
  │
  ▼
cleanup() — removes overlay, resolves Promise

pay() creates a modal overlay and injects an <iframe> pointing to https://link.palpluss.com/{id}?embed=1.
The embedded page communicates back via window.postMessage.
On success the Promise resolves with { txId, amount, phone }. On close/cancel it rejects.

The iframe origin is https://link.palpluss.com — your page never handles raw M-PESA credentials or STK callbacks.

Installation (JavaScript / TypeScript only)

If you use PHP, Python, Ruby, or any other server-side language, skip this section and jump directly to Any Backend — Raw iframe. The npm package is only needed for JavaScript/TypeScript projects.

npm install @palpluss/paylink

pnpm add @palpluss/paylink

yarn add @palpluss/paylink

React peer dependencies are only needed if you import @palpluss/paylink/react:

npm install react react-dom

Quick Start

import { pay } from '@palpluss/paylink'

const result = await pay('your-paylink-id')
// result → { txId: 'TXN_...', amount: 500, phone: '2547...' }

Get your paylink ID from the Palpluss Console → Payment Links.

API Reference

`pay(paylinkId, options?)`

Opens a full-screen modal containing the payment iframe. Returns a Promise<PaymentResult> that:

resolves when the customer completes payment
rejects with Error('Payment modal closed by user') when the modal is dismissed

Parameter	Type	Required	Description
`paylinkId`	`string`	Yes	The paylink ID from your Palpluss dashboard
`options`	`PayOptions`	No	Pre-fill values and callbacks

PayOptions

Option	Type	Description
`amount`	`number`	Pre-fill the amount in KES (must be ≥ 1). Ignored if the paylink already has a fixed amount.
`phone`	`string`	Pre-fill the customer’s M-PESA number, e.g. `0712345678` or `254712345678`. Ignored if the paylink already has a fixed phone.
`customerName`	`string`	Pre-fill the customer name / payment note (max 120 characters).
`lockPrefill`	`boolean`	Make the pre-filled fields read-only for the customer. Default `false`.
`onSuccess`	`(data: PaymentResult) => void`	Called immediately when payment succeeds, before the Promise resolves
`onClose`	`() => void`	Called when the user dismisses the modal without paying

const result = await pay('abc-123', {
  amount:       1500,
  phone:        '0712345678',
  customerName: 'Jane Wanjiku',
  onSuccess: (data) => console.log('paid', data),
  onClose:   ()     => console.log('modal closed'),
})

Pre-filling the payment form

Available from @palpluss/paylink 1.4.0.

Pass amount, phone and customerName to save your customer typing — for example when the amount comes from your cart and you already know their number.

Merchant-fixed values always win. If the paylink was created with a fixed amount or phone, that value is used and the pre-fill is ignored. The Palpluss API enforces this too, so a pre-fill can never change a merchant’s price.
Invalid values throw a TypeError (e.g. amount: 0, a name over 120 characters), so pay() rejects immediately and the mistake shows up during development.
A phone number that isn’t a valid Kenyan number is left blank so the customer can type it.

lockPrefill: true makes the pre-filled fields read-only, but it is a convenience, not a security control — the values travel in the iframe URL, which can be edited. If the amount must be guaranteed, create the paylink with a fixed amount (in the Console or via @palpluss/sdk), and always confirm the paid amount on your server before fulfilling an order.

`openModal(paylinkId, options, resolve, reject)`

Low-level function used internally by pay(). Exposed for advanced cases where you need direct control of the Promise lifecycle. Returns a cleanup() function that tears down the modal immediately.

import { openModal } from '@palpluss/paylink'

const cleanup = openModal(
  'abc-123',
  {},
  (result) => console.log('resolved', result),
  (err)    => console.log('rejected', err),
)

// Force-close from outside
cleanup()

`buildPaylinkUrl(paylinkId, prefill?, { embed? })`

Returns the URL of the hosted payment page with the same validated pre-fill — useful for raw iframes, server-rendered pages, or a shareable link.

import { buildPaylinkUrl } from '@palpluss/paylink'

buildPaylinkUrl('abc-123', { amount: 1500, phone: '0712345678' })
// → https://link.palpluss.com/abc-123?embed=1&amount=1500&phone=0712345678

buildPaylinkUrl('abc-123', { amount: 1500 }, { embed: false })
// → https://link.palpluss.com/abc-123?amount=1500   (plain link to share)

`<PalplussPayment>` (React)

Import from @palpluss/paylink/react. Renders the payment iframe inline — no overlay, no modal — so you control layout and placement.

import { PalplussPayment } from '@palpluss/paylink/react'

<PalplussPayment
  id="abc-123"
  amount={1500}
  phone="0712345678"
  onSuccess={({ txId, amount }) => console.log(txId, amount)}
  className="my-payment-frame"
/>

Prop	Type	Required	Description
`id`	`string`	Yes	Paylink ID
`amount`	`number`	No	Pre-fill the amount in KES (≥ 1)
`phone`	`string`	No	Pre-fill the customer’s M-PESA number
`customerName`	`string`	No	Pre-fill the customer name / note (max 120 chars)
`lockPrefill`	`boolean`	No	Make the pre-filled fields read-only
`onSuccess`	`(data: PaymentResult) => void`	No	Called on successful payment
`className`	`string`	No	CSS class applied to the `<iframe>`

Pre-fill props follow the same rules as pay() (merchant-fixed values win). The iframe only reloads when one of them changes. The iframe starts at minHeight: 560px and auto-resizes via RESIZE postMessage events.

Usage Examples (JavaScript / TypeScript)

Vanilla JS / TypeScript
Pre-filled checkout
React — modal
React — inline embed
CDN script tag

import { pay } from '@palpluss/paylink'

document.getElementById('pay-btn')!.addEventListener('click', async () => {
  try {
    const { txId, amount } = await pay('abc-123')
    window.location.href = `/thank-you?ref=${txId}&amount=${amount}`
  } catch {
    // user closed the modal — no action needed
  }
})

Pass the amount from your cart and the customer details you already have:

import { pay } from '@palpluss/paylink'

async function checkout(cart: { total: number }, customer: { phone: string; name: string }) {
  try {
    const { txId } = await pay('abc-123', {
      amount:       cart.total,
      phone:        customer.phone,
      customerName: customer.name,
      lockPrefill:  true,          // customer confirms, but can't edit the values
    })
    await fetch('/api/orders/confirm', { method: 'POST', body: JSON.stringify({ txId }) })
  } catch {
    // modal closed, or an invalid pre-fill (TypeError) during development
  }
}

Always confirm the amount on your server (webhook or transaction lookup) before fulfilling an order.

import { pay } from '@palpluss/paylink'

export function CheckoutButton({ paylinkId }: { paylinkId: string }) {
  async function handleClick() {
    try {
      const result = await pay(paylinkId)
      console.log('Paid', result.amount, 'KES — ref:', result.txId)
    } catch {
      // modal dismissed
    }
  }

  return <button onClick={handleClick}>Pay with M-PESA</button>
}

Use @palpluss/paylink/react when you want the payment form embedded directly in your page layout instead of a floating modal.

import { PalplussPayment } from '@palpluss/paylink/react'

export function CheckoutPage() {
  function handleSuccess({ txId, amount }: { txId: string; amount: number }) {
    console.log(`Payment complete — ${amount} KES, ref: ${txId}`)
  }

  return (
    <div className="checkout">
      <h1>Complete your payment</h1>
      <PalplussPayment id="abc-123" onSuccess={handleSuccess} />
    </div>
  )
}

No build step required. Drop this into any HTML page:

<script src="https://cdn.palpluss.com/paylink.min.js"></script>

<button onclick="Palpluss.pay('abc-123').then(r => alert('Paid! Ref: ' + r.txId))">
  Pay with M-PESA
</button>

Everything is available on the window.Palpluss global:

Palpluss.pay('abc-123', { amount: 1500, phone: '0712345678' })
  .then(result => console.log(result))
  .catch(() => console.log('cancelled'))

// Build a pre-filled URL for a raw iframe or a shareable link
Palpluss.buildPaylinkUrl('abc-123', { amount: 1500 })

Any Backend — Raw Iframe

This section is for PHP, Python, Ruby, Go, .NET, and any other server-side language. The @palpluss/paylink npm package is entirely optional — it is just a convenience wrapper around a standard <iframe>. You can embed the payment widget using plain HTML and a small <script> block in any templating engine, CMS, or static site.

How it works without the npm package

The paylink widget is an <iframe> hosted at https://link.palpluss.com/{paylink-id}?embed=1. The ?embed=1 query parameter tells the Palpluss page it is running inside an embedded context. Once loaded, the iframe sends two types of postMessage events back to your page:

Event type	Payload	Purpose
`RESIZE`	`{ height: number }`	Resize the iframe to fit its content — eliminates scrollbars
`PAYMENT_SUCCESS`	`{ txId, amount, phone }`	Payment was completed successfully

Your page listens for these messages and reacts accordingly. No SDK or npm package required.

Minimal HTML snippet

Replace abc-123 with your actual paylink ID from the Palpluss Console.

<!-- Palpluss Payment Widget -->
<iframe
  id="palpluss-pay"
  src="https://link.palpluss.com/abc-123?embed=1"
  style="width: 100%; border: none; min-height: 600px; display: block;"
  allow="payment"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (!e.data || typeof e.data !== 'object') return;

    // Auto-resize the iframe to fit its content
    if (e.data.type === 'RESIZE') {
      document.getElementById('palpluss-pay').style.height = e.data.height + 'px';
    }

    // Payment completed successfully
    if (e.data.type === 'PAYMENT_SUCCESS') {
      console.log('Payment confirmed!', {
        txId:   e.data.txId,
        amount: e.data.amount,
        phone:  e.data.phone,
      });

      // Examples — uncomment what fits your use case:
      // window.location.href = '/thank-you?ref=' + e.data.txId;
      // document.getElementById('download-btn').disabled = false;
    }
  });
</script>

The allow="payment" attribute grants the iframe access to the Payment Request API in supporting browsers. It does not affect functionality in environments that don’t support it.

Pre-filling the form with URL parameters

Add query parameters to the iframe src to pre-fill the payment form — no npm package needed. These are the same parameters pay() sends.

Parameter	Example	Meaning
`embed`	`1`	Page runs inside an iframe and sends `postMessage` events
`amount`	`1500`	Pre-filled amount in KES (≥ 1)
`phone`	`0712345678`	Pre-filled M-PESA number
`customer_name`	`Jane%20Wanjiku`	Pre-filled customer name / note (URL-encoded, max 120 chars)
`lock`	`1`	Make the pre-filled fields read-only

<iframe
  id="palpluss-pay"
  src="https://link.palpluss.com/abc-123?embed=1&amount=1500&phone=0712345678&customer_name=Jane%20Wanjiku&lock=1"
  style="width: 100%; border: none; min-height: 600px; display: block;"
  allow="payment"
></iframe>

Build the URL server-side with proper encoding — for example in PHP:

$src = 'https://link.palpluss.com/' . rawurlencode($paylinkId) . '?' . http_build_query([
    'embed'         => 1,
    'amount'        => $order->total,
    'phone'         => $customer->phone,
    'customer_name' => $customer->name,
    'lock'          => 1,
]);

or in Python:

from urllib.parse import urlencode, quote

src = f"https://link.palpluss.com/{quote(paylink_id)}?" + urlencode({
    "embed": 1,
    "amount": order.total,
    "phone": customer.phone,
    "customer_name": customer.name,
    "lock": 1,
})

Invalid values (an amount below 1, an unrecognised phone number) are ignored and the customer fills that field themselves. Merchant-fixed values on the paylink always take precedence, and lock is a convenience only — see the warning under Pre-filling the payment form.

Framework examples

PHP / Laravel Blade
Python / Django
Python / Flask
Static HTML / No framework

In your Blade template, output the paylink ID from your controller or config. Everything else is plain HTML:

{{-- resources/views/checkout.blade.php --}}
<iframe
  id="palpluss-pay"
  src="https://link.palpluss.com/{{ $paylinkId }}?embed=1"
  style="width: 100%; border: none; min-height: 600px; display: block;"
  allow="payment"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (!e.data || typeof e.data !== 'object') return;

    if (e.data.type === 'RESIZE') {
      document.getElementById('palpluss-pay').style.height = e.data.height + 'px';
    }

    if (e.data.type === 'PAYMENT_SUCCESS') {
      // Redirect to a thank-you page with the transaction reference
      window.location.href = '/thank-you?ref=' + e.data.txId + '&amount=' + e.data.amount;
    }
  });
</script>

Pass $paylinkId from your controller:

// app/Http/Controllers/CheckoutController.php
public function show()
{
    return view('checkout', [
        'paylinkId' => config('services.palpluss.paylink_id'),
    ]);
}

Render the paylink ID from your Django view into the template:

# views.py
from django.shortcuts import render

def checkout(request):
    return render(request, 'checkout.html', {
        'paylink_id': 'abc-123',   # or load from settings / DB
    })

{# templates/checkout.html #}
<iframe
  id="palpluss-pay"
  src="https://link.palpluss.com/{{ paylink_id }}?embed=1"
  style="width: 100%; border: none; min-height: 600px; display: block;"
  allow="payment"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (!e.data || typeof e.data !== 'object') return;

    if (e.data.type === 'RESIZE') {
      document.getElementById('palpluss-pay').style.height = e.data.height + 'px';
    }

    if (e.data.type === 'PAYMENT_SUCCESS') {
      window.location.href = '/thank-you/?ref=' + e.data.txId;
    }
  });
</script>

# app.py
from flask import Flask, render_template
import os

app = Flask(__name__)

@app.route('/checkout')
def checkout():
    return render_template('checkout.html', paylink_id=os.getenv('PALPLUSS_PAYLINK_ID'))

{# templates/checkout.html #}
<iframe
  id="palpluss-pay"
  src="https://link.palpluss.com/{{ paylink_id }}?embed=1"
  style="width: 100%; border: none; min-height: 600px; display: block;"
  allow="payment"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (!e.data || typeof e.data !== 'object') return;

    if (e.data.type === 'RESIZE') {
      document.getElementById('palpluss-pay').style.height = e.data.height + 'px';
    }

    if (e.data.type === 'PAYMENT_SUCCESS') {
      window.location.href = '/thank-you?ref=' + e.data.txId;
    }
  });
</script>

If you have no server-side framework at all, hard-code the paylink ID directly. This works on any static site, CDN, or HTML file:

<!DOCTYPE html>
<html>
<head>
  <title>Checkout</title>
</head>
<body>
  <h1>Complete your payment</h1>

  <iframe
    id="palpluss-pay"
    src="https://link.palpluss.com/abc-123?embed=1"
    style="width: 100%; border: none; min-height: 600px; display: block;"
    allow="payment"
  ></iframe>

  <script>
    window.addEventListener('message', function(e) {
      if (!e.data || typeof e.data !== 'object') return;

      if (e.data.type === 'RESIZE') {
        document.getElementById('palpluss-pay').style.height = e.data.height + 'px';
      }

      if (e.data.type === 'PAYMENT_SUCCESS') {
        alert('Payment confirmed! Reference: ' + e.data.txId);
      }
    });
  </script>
</body>
</html>

postMessage event reference

Your message event listener receives event.data with the following shapes:

// Auto-resize event — fired as the payment form grows or shrinks
{
  type: 'RESIZE',
  height: 640       // new iframe height in pixels
}

// Payment success event — fired once the customer completes payment
{
  type: 'PAYMENT_SUCCESS',
  txId:   'TXN_01J8ABC123',   // transaction reference — store this
  amount: 500,                // amount paid in KES
  phone:  '254712345678'      // M-PESA number used
}

Always check e.data.type before acting on a message. Other libraries on your page (analytics, chat widgets, etc.) also use postMessage and your listener will receive those events too.

Security note on postMessage

The iframe is served from https://link.palpluss.com. For production applications, validate the message origin before trusting the payload:

window.addEventListener('message', function(e) {
  // Only trust messages from the Palpluss iframe origin
  if (e.origin !== 'https://link.palpluss.com') return;

  if (e.data.type === 'PAYMENT_SUCCESS') {
    // safe to act on
  }
});

TypeScript Types

import type { PaymentResult, PayOptions, PaylinkPrefill, IframeEvent } from '@palpluss/paylink'

type PaymentResult = {
  txId:   string   // transaction reference
  amount: number   // amount paid in KES
  phone:  string   // M-PESA number used
}

type PaylinkPrefill = {
  amount?:       number   // KES, ≥ 1
  phone?:        string   // e.g. '0712345678' or '254712345678'
  customerName?: string   // max 120 characters
  lockPrefill?:  boolean  // make pre-filled fields read-only
}

type PayOptions = PaylinkPrefill & {
  onSuccess?: (data: PaymentResult) => void
  onClose?:   () => void
}

// postMessage events sent by the embedded iframe
type IframeEvent =
  | { type: 'RESIZE';          height: number }
  | { type: 'PAYMENT_SUCCESS'; txId: string; amount: number; phone: string }

When pay() is called:

Validation — pre-fill values are checked and the iframe URL is built (buildPaylinkUrl). Invalid values throw before anything is drawn.
Native <dialog> — a <dialog> element (max-width: 860px, full-screen on phones) is opened with showModal(). It sits in the browser’s top layer, so no z-index is needed and page scroll is locked automatically.
Iframe — src is https://link.palpluss.com/{id}?embed=1 plus any pre-fill parameters. ?embed=1 tells the Palpluss page it is running inside an SDK modal.
Styles — injected once per page and shared by every modal.
postMessage listener — listens for two event types from the iframe origin:
- RESIZE — adjusts iframe.style.height for seamless auto-height.
- PAYMENT_SUCCESS — extracts { txId, amount, phone }, calls onSuccess, removes the modal, resolves the Promise.
Close handlers — the modal closes (and the Promise rejects) on:
- Clicking the ✕ button
- Clicking outside the dialog on the backdrop
- Pressing Escape
Cleanup — closes and removes the dialog and removes the message listener.

Relation to @palpluss/sdk

Package	Runtime	Who uses it	What it does
`@palpluss/sdk`	Node.js	Backend developers	Server-side API calls — create paylinks, STK push, webhooks
`@palpluss/paylink`	Browser	Frontend developers	Embed a payment link modal or inline iframe on any site
Raw `<iframe>`	Any browser	All languages	Same as `@palpluss/paylink` but without npm — for PHP, Python, etc.

These are completely independent. A typical full-stack integration uses @palpluss/sdk on the server to create the paylink, and then the paylink widget (or raw iframe) on the frontend to collect payment:

Backend (Node.js / PHP / Python / ...)    Frontend (Browser)
─────────────────────────────────────     ────────────────────────────────
@palpluss/sdk  OR  REST API               @palpluss/paylink  OR  raw iframe
  └─ createPaylink()  ─────────────►        └─ pay(id)  /  <iframe src="...">
  └─ handleWebhook()  ◄─────────────              resolves on PAYMENT_SUCCESS

Get Started

Guides

SDKs

STK Push

Transactions

B2C Payouts

Service Wallet

Payment Channels

Paylink Widget (`@palpluss/paylink`)

Getting Your Paylink ID

Step 1 — Open Create Pay Link

Step 2 — Generate the link

Step 3 — Copy only the ID

How It Works

Installation (JavaScript / TypeScript only)

Quick Start

API Reference

`pay(paylinkId, options?)`

Pre-filling the payment form

`openModal(paylinkId, options, resolve, reject)`

`buildPaylinkUrl(paylinkId, prefill?, { embed? })`

`<PalplussPayment>` (React)

Usage Examples (JavaScript / TypeScript)

Any Backend — Raw Iframe

How it works without the npm package

Minimal HTML snippet

Pre-filling the form with URL parameters

Framework examples

postMessage event reference

Security note on postMessage

TypeScript Types

Relation to @palpluss/sdk

​Paylink Widget (@palpluss/paylink)

​Getting Your Paylink ID

​Step 1 — Open Create Pay Link

​Step 2 — Generate the link

​Step 3 — Copy only the ID

​How It Works

​Installation (JavaScript / TypeScript only)

​Quick Start

​API Reference

​pay(paylinkId, options?)

​Pre-filling the payment form

​openModal(paylinkId, options, resolve, reject)

​buildPaylinkUrl(paylinkId, prefill?, { embed? })

​<PalplussPayment> (React)

​Usage Examples (JavaScript / TypeScript)

​Any Backend — Raw Iframe

​How it works without the npm package

​Minimal HTML snippet

​Pre-filling the form with URL parameters

​Framework examples

​postMessage event reference

​Security note on postMessage

​TypeScript Types

​How the Modal Works Internally

​Relation to @palpluss/sdk

Paylink Widget (`@palpluss/paylink`)

Getting Your Paylink ID

Step 1 — Open Create Pay Link

Step 2 — Generate the link

Step 3 — Copy only the ID

How It Works

Installation (JavaScript / TypeScript only)

Quick Start

API Reference

`pay(paylinkId, options?)`

Pre-filling the payment form

`openModal(paylinkId, options, resolve, reject)`

`buildPaylinkUrl(paylinkId, prefill?, { embed? })`

`<PalplussPayment>` (React)

Usage Examples (JavaScript / TypeScript)

Any Backend — Raw Iframe

How it works without the npm package

Minimal HTML snippet

Pre-filling the form with URL parameters

Framework examples

postMessage event reference

Security note on postMessage

TypeScript Types

How the Modal Works Internally

Relation to @palpluss/sdk