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

# Hosted checkout and embed

> Send buyers to pay.xenarch.com, turn any element into a pay button with the v1.js embed script, or render checkout in React with @xenarch/react.

Every pay link has a hosted checkout page at `https://pay.xenarch.com/l/<link_id>`. You can share that URL as it is, open it from a button with the embed script, or render it inside a React app.

## Hosted checkout

The buyer connects a wallet on the checkout page and pays in USDC on Base. By default the buyer pays by signature: an EIP-3009 authorization that a third-party x402 facilitator submits on Base, paying the gas. If no facilitator is healthy, or the buyer chooses it, the buyer sends a standard USDC transfer and pays about \$0.001 of gas.

### Return to your site

Add a `return_url` query parameter to the checkout URL, or set `return_url` in the link's params. After a confirmed payment the checkout sends the buyer to that URL with three query parameters added:

| Parameter | Value |
| - | - |
| `xenarch_paid` | `1` |
| `link_id` | The link that was paid |
| `tx_hash` | The Base transaction hash |

```
https://example.com/thanks?xenarch_paid=1&link_id=JJjIwDyV4N1CG9g8AHMxfdJ9&tx_hash=0x...
```

> [!WARNING]
>
> The return parameters are for your thank-you screen only. Anyone can type them into a URL. Fulfill orders from a verified [webhook](https://docs.xenarch.com/payments/webhooks.md) or from the payment record in your dashboard.

## Embed script

The embed script turns any element with a `data-xenarch-link` attribute into a pay button. It has no dependencies and needs no build step.

```html theme={null}
<script src="https://cdn.xenarch.dev/pay/v1.js" defer></script>

<button data-xenarch-link="JJjIwDyV4N1CG9g8AHMxfdJ9">
  Pay 25 USDC
</button>
```

A click sends the buyer to the hosted checkout with `return_url` set to the current page. After payment the buyer comes back with the query parameters above.

| Attribute | Required | Description |
| - | - | - |
| `data-xenarch-link` | Yes | The pay link id, the part after `pay.xenarch.com/l/` |
| `data-xenarch-return-url` | No | Return URL. Defaults to the current page. |

Two script URLs are published:

* `https://cdn.xenarch.dev/pay/v1.js` follows non-breaking fixes.
* `https://cdn.xenarch.dev/pay/v1.0.0.js` never changes. Pin it if you need byte-stable behavior.

The same code is on npm as `@xenarch/embed` 1.0.0.

## React component

```bash theme={null}
npm install @xenarch/react
```

`@xenarch/react` 1.0.0 exports `XenarchCheckout`. It needs `react` and `react-dom` 18 or later.

```tsx Redirect (default) theme={null}
import { XenarchCheckout } from "@xenarch/react";

export function PayButton() {
  return (
    <XenarchCheckout linkId="JJjIwDyV4N1CG9g8AHMxfdJ9">
      Pay 25 USDC
    </XenarchCheckout>
  );
}
```

```tsx Modal theme={null}
import { XenarchCheckout } from "@xenarch/react";

export function PayButton() {
  return (
    <XenarchCheckout
      linkId="JJjIwDyV4N1CG9g8AHMxfdJ9"
      mode="modal"
      onPaid={({ linkId, txHash }) => console.log("paid", linkId, txHash)}
      onClose={() => console.log("closed without paying")}
    >
      Pay 25 USDC
    </XenarchCheckout>
  );
}
```

```tsx Inline theme={null}
import { XenarchCheckout } from "@xenarch/react";

export function CheckoutPanel() {
  return (
    <XenarchCheckout
      linkId="JJjIwDyV4N1CG9g8AHMxfdJ9"
      mode="inline"
      inlineHeight="720px"
      onPaid={({ txHash }) => console.log("paid", txHash)}
    />
  );
}
```

Redirect mode renders a link styled as a button and sends the buyer to the hosted checkout. Modal mode renders a button that opens the checkout in an iframe overlay and closes it when the payment confirms. Inline mode renders the checkout iframe in place.

### Props

| Prop | Type | Default | Description |
| - | - | - | - |
| `linkId` | `string` | required | The pay link id |
| `mode` | `"redirect" \| "modal" \| "inline"` | `"redirect"` | Which surface to render |
| `returnUrl` | `string` | current page | Return URL in redirect mode. Modal and inline ignore it. |
| `onPaid` | `(event) => void` | none | Fires when the payment is paid or confirmed |
| `onTerminal` | `(event) => void` | none | Fires on underpaid, overpaid, expired or revoked |
| `onClose` | `() => void` | none | Modal only. Fires when the buyer closes it without paying. |
| `inlineHeight` | `string \| number` | `"min(900px, 80vh)"` | Inline only. Iframe height. |
| `className`, `style` | | | Passed to the rendered element |
| `children` | `ReactNode` | `"Pay"` | Button label in redirect and modal modes |

Each event is `{ type, linkId, txHash? }`, where `type` is one of `xenarch:paid`, `xenarch:underpaid`, `xenarch:overpaid`, `xenarch:expired`, `xenarch:revoked` or `xenarch:close`.

The component acts only on `postMessage` events from `https://pay.xenarch.com` whose `linkId` matches its own prop, and it passes on `txHash` only when it is a well-formed transaction hash. As with the return parameters, use a verified webhook to fulfill orders.

The package also exports `buildHostedUrl`, `attachXenarchListener`, `isValidLinkId` and `HOSTED_ORIGIN` for custom integrations.


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