> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payluk.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay with Payluk button

> Add a branded checkout button to your page with a script tag, a function call, or a React component.

The **Pay with Payluk** button shows the Payluk icon and the text "Pay with
Payluk". When the buyer clicks it, it creates a checkout session and
opens the escrow checkout widget. While the session is being created, the
button shows a spinner and ignores further clicks.

You can add it in three ways:

| Your site | Use |
| - | - |
| Plain HTML, no build step | The [script tag](#plain-html), served by the Payluk API. |
| JavaScript or TypeScript app | [`mountCheckoutButton()`](#javascript-or-typescript) from the SDK. |
| React or Next.js | [`<EscrowCheckoutButton>`](https://docs.payluk.ng/sdk/react#escrowcheckoutbutton) from the SDK. |

All three render the same button and accept the same checkout inputs as
[`pay()`](https://docs.payluk.ng/sdk/javascript#pay-parameters). Your backend still creates the
escrow and gives your page its payment token.

## Appearance

![Pay with Payluk buttons: purple default, hover, keyboard focus, loading, disabled and custom label on light backgrounds; white theme default, hover and loading on a dark background.](https://mintcdn.com/payluk-ef2ec5d5/_-z0nUUwoE9ylBBG/images/payment-button-states.svg?fit=max\&auto=format\&n=_-z0nUUwoE9ylBBG\&q=85\&s=bab7cea52f14665b8027edd6108ae3dc)

The button in both themes and every state.

| Theme | Use it on | Look |
| - | - | - |
| `purple` (default) | Light backgrounds | Payluk purple button, white icon and text. |
| `white` | Dark or busy backgrounds | White button, purple icon and text. |

The button is 44px tall with a minimum width of 220px. It has hover, pressed,
keyboard focus and disabled states. Screen readers announce it as "Pay with
Payluk", and the icon is hidden from them.

To change the text, set the label (`label` or `data-label`). The icon
stays. To add your own styles, target the `.payluk-btn` class, or pass a
`className` in React.

## Plain HTML

Add the script once, then put a `data-payluk-button` element where the button
should appear.

```html theme={null}
<script src="https://live.payluk.ng/v1/checkout/button.js" async></script>

<div data-payluk-button
     data-public-key="pk_live_..."
     data-payment-token="PY_8AB12C9D3045"
     data-reference="order_2026_0001"
     data-redirect-url="https://yourapp.com/checkout/complete"></div>
```

> [!NOTE]
>
> With a test key, load the script from staging:
> `https://staging.live.payluk.ng/v1/checkout/button.js`. The script opens
> checkout sessions on the server it was loaded from.

### Attributes

| Attribute | Required | Description |
| - | - | - |
| `data-public-key` | Yes | Your publishable key. |
| `data-payment-token` | Yes | The escrow's payment token. Separate several tokens with commas to fund them in one checkout. |
| `data-reference` | Yes | Your unique reference for this checkout. |
| `data-redirect-url` | Yes | Where the buyer goes after checkout. |
| `data-customer-id` | No | The merchant customer the payment acts for. |
| `data-brand` | No | Business name shown in the widget. |
| `data-logo-url` | No | Logo shown in the widget. |
| `data-theme` | No | `purple` (default) or `white`. |
| `data-label` | No | Button text. Defaults to `Pay with Payluk`. |

The button reads the attributes when it is clicked, so you can change them
after the page loads (for example, when the cart changes).

### Events

The element fires these events. They bubble, and the result is in
`event.detail`.

| Event | When |
| - | - |
| `payluk:success` | The widget reports a payment result. |
| `payluk:close` | The buyer closes the widget. |
| `payluk:error` | A required attribute is missing, or the session or widget fails to load. `event.detail` is the `Error`. |

```html theme={null}
<script>
  const el = document.querySelector('[data-payluk-button]');
  el.addEventListener('payluk:success', (e) => console.log('paid', e.detail));
  el.addEventListener('payluk:error', (e) => alert(e.detail.message));
</script>
```

### Buttons added later

The script mounts every `data-payluk-button` element on the page when it loads.
If you add one later (for example, in a single-page app), call:

```js theme={null}
window.PaylukButton.mount();
```

## JavaScript or TypeScript

After [`initEscrowCheckout()`](https://docs.payluk.ng/sdk/javascript#1-initialize), render the
button into an element or a CSS selector:

```ts theme={null}
import { initEscrowCheckout, mountCheckoutButton } from 'payluk-escrow-inline-checkout';

initEscrowCheckout({ publicKey: 'pk_live_...' });

const unmount = mountCheckoutButton('#payluk-button', {
  paymentToken: 'PY_8AB12C9D3045',
  reference: 'order_2026_0001',
  redirectUrl: 'https://yourapp.com/checkout/complete',
  theme: 'white',
  callback: (result) => console.log(result),
  onError: (error) => console.error(error.message),
});

// Later, to remove the button:
unmount();
```

`mountCheckoutButton(target, options)` takes every [`pay()`](https://docs.payluk.ng/sdk/javascript#pay-parameters)
input, plus these:

| Option | Type | Description |
| - | - | - |
| `theme` | `'purple' \| 'white'` | Button theme. Defaults to `purple`. |
| `label` | `string` | Button text. Defaults to `Pay with Payluk`. |
| `onError` | `(error: Error) => void` | Called when the session or widget fails. Defaults to `console.error`. |

It throws an `EscrowCheckoutError` with code `INVALID_INPUT` if the target
element does not exist, and `BROWSER_ONLY` if it runs on the server.

## React

Use [`<EscrowCheckoutButton>`](https://docs.payluk.ng/sdk/react#escrowcheckoutbutton). It renders
the same button by default.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.