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

# JavaScript / TypeScript

> Initialize the SDK once, then call pay() to open the checkout widget.

## 1. Initialize

Call `initEscrowCheckout` **once**, as early as possible (e.g. at your app's
entry point). This registers your publishable key and prepares the widget
script.

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

initEscrowCheckout({
  publicKey: '<YOUR_PUBLISHABLE_KEY>',
});
```

`initEscrowCheckout(config: InitConfig)` accepts:

| Option              | Type                                     | Required | Description                                                               |
| ------------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `publicKey`         | `string`                                 | Yes      | Your publishable key.                                                     |
| `scriptUrlOverride` | `string`                                 | No       | Override the widget script URL (advanced/self-hosted).                    |
| `globalName`        | `string`                                 | No       | Window global the widget attaches to. Defaults to `EscrowCheckout`.       |
| `crossOrigin`       | `'' \| 'anonymous' \| 'use-credentials'` | No       | `crossorigin` attribute for the injected script. Defaults to `anonymous`. |

## 2. Collect payment

`pay()` opens the checkout widget for one or more payment tokens. It returns a
`Promise<void>` that resolves once the session has been created and the widget
launched.

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

await pay({
  paymentToken: 'PY_8AB12C9D3045',
  reference: 'order_2026_0001',
  redirectUrl: 'https://yourapp.com/checkout/complete',
  brand: 'Acme Store',
  logoUrl: 'https://yourapp.com/logo.png',
  callback: (result) => {
    console.log('Payment result', result);
  },
  onClose: () => {
    console.log('Checkout closed');
  },
});
```

### `pay()` parameters

| Parameter      | Type                      | Required | Description                                                     |
| -------------- | ------------------------- | -------- | --------------------------------------------------------------- |
| `paymentToken` | `string \| string[]`      | Yes      | One token, or an array to fund multiple escrows in one session. |
| `reference`    | `string`                  | Yes      | Your unique reference for this checkout.                        |
| `redirectUrl`  | `string`                  | Yes      | Where the buyer is redirected after completion.                 |
| `logoUrl`      | `string`                  | No       | Logo shown in the widget.                                       |
| `brand`        | `string`                  | No       | Brand/business name shown in the widget.                        |
| `customerId`   | `string`                  | No       | The merchant customer the payment acts on behalf of.            |
| `extra`        | `Record<string, unknown>` | No       | Arbitrary key/values forwarded to the widget.                   |
| `callback`     | `(result: any) => void`   | No       | Invoked with the payment result.                                |
| `onClose`      | `() => void`              | No       | Invoked when the buyer closes the widget.                       |

<Note>
  `pay()` must run in a browser. Calling it during server-side rendering throws an
  `EscrowCheckoutError` with code `BROWSER_ONLY`. Calling it before
  `initEscrowCheckout()` throws `NOT_INITIALIZED`.
</Note>

## Multi-escrow checkout

Pass an array of tokens to settle several escrows in a single session:

```ts theme={null}
await pay({
  paymentToken: ['PY_8AB12C9D3045', 'PY_77F0A1B2C3D4'],
  reference: 'cart_2026_0042',
  redirectUrl: 'https://yourapp.com/checkout/complete',
});
```

<Warning>
  All tokens in a multi-escrow checkout must belong to the **same merchant** and
  each escrow must still be in **`PENDING`** status (not yet funded).
</Warning>

## TypeScript

The SDK is written in TypeScript and ships its own types; no `@types` package
needed. Import the types directly when you need them:

```ts theme={null}
import {
  initEscrowCheckout,
  pay,
  type InitConfig,
  type PayInput,
} from 'payluk-escrow-inline-checkout';
```

See the full [SDK reference](/sdk/reference) for every exported type.