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

# JavaScript (Inline Widget)

> Drop-in checkout widget for any website

A lightweight, dependency-free script for adding a Payracle checkout popup to any website — no build step, no framework required.

## Installation

Add the script tag anywhere on your page:

```html theme={null}
<script src="https://api.payracle.com/js/v1/payracle.js"></script>
```

## Usage

```html theme={null}
<button onclick="pay()">Pay ₦1,500</button>

<script src="https://api.payracle.com/js/v1/payracle.js"></script>
<script>
  function pay() {
    const handler = Payracle.setup({
      key: 'pk_live_your_public_key',
      businessId: 'biz_your_business_id',
      amount: 1500,
      email: 'customer@example.com',
      title: 'Order #9928',
      description: 'Payment for running shoes',
      onSuccess: function (response) {
        console.log('Payment complete:', response.reference);
      },
      onClose: function () {
        console.log('Checkout closed');
      },
    });

    handler.open();
  }
</script>
```

<Warning>
  Only ever use your public key (`pk_live_...` / `pk_test_...`) in this widget — it runs entirely in the browser, visible to anyone who views your page source. Your secret key must never appear in client-side code.
</Warning>

## Options reference

| Option        | Type     | Required | Description                                                           |
| ------------- | -------- | -------- | --------------------------------------------------------------------- |
| `key`         | string   | Yes      | Your public key (`pk_live_...` or `pk_test_...`)                      |
| `businessId`  | string   | Yes      | Your business ID, sent as the `X-Business-ID` header                  |
| `amount`      | number   | Yes      | Amount in Naira (e.g. `1500` = ₦1,500)                                |
| `email`       | string   | No       | Customer's email address                                              |
| `title`       | string   | No       | Payment title shown on the checkout page                              |
| `description` | string   | No       | Payment description shown on the checkout page                        |
| `onSuccess`   | function | No       | Called with `{ status: 'success', reference }` when payment completes |
| `onClose`     | function | No       | Called when the customer closes the checkout modal                    |

## How it works

Calling `.open()` does three things:

1. Shows a loading overlay while it calls `POST /api/v1/checkout/initialize` with your public key.
2. Opens a centered modal with a blurred backdrop, loading the returned `checkout_url` in an iframe — this is a [dynamic virtual account](/checkout/overview) generated for this exact payment.
3. Listens for a `postMessage` event from the checkout page when payment succeeds, fires `onSuccess`, then auto-closes the modal after a short delay.

The widget resolves its own API base URL from the `<script>` tag's own `src`, so it works identically whether loaded from `api.payracle.com` or a self-hosted mirror.