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

# Checkout SDK and button

> Open Pasteaza hosted checkout in a responsive modal using the browser SDK.

Use the Pasteaza browser SDK when you want customers to pay without leaving your website. The SDK works with the same checkout session returned by `POST /v1/checkout/sessions`.

<Info>
  Create checkout sessions from your backend with your secret key. The browser SDK renders a native Pasteaza modal on your page using only your public key and the returned checkout `reference`.
</Info>

## Install

Add the SDK script to your checkout page.

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

## Open checkout

Create the checkout session on your backend, then pass the returned `reference` to the SDK.

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

<script>
  PasteAZA.init("pk_live_xxxxxxxxxxxxxxxxx");

  PasteAZA.checkout("ch_Fb8z7rX8r9w2");
</script>
```

You can also pass callbacks.

```html theme={null}
<script>
  PasteAZA.checkout({
    publicKey: "pk_live_xxxxxxxxxxxxxxxxx",
    checkout: "ch_Fb8z7rX8r9w2",
    onLoad: function (session) {
      console.log("Checkout loaded", session);
    },
    onSuccess: function (payment) {
      console.log("Payment successful", payment.reference);
    },
    onFailed: function (event) {
      console.log("Checkout failed", event.status);
    },
    onClose: function (event) {
      console.log("Checkout closed", event.reference);
    },
    onError: function (error) {
      console.error(error.message);
    }
  });
</script>
```

## Pay button

Use `button.js` when you want Pasteaza to render a ready-made button.

```html theme={null}
<script
  src="https://js.oyapasteaza.com/v1/button.js"
  data-public-key="pk_live_xxxxxxxxxxxxxxxxx"
  data-checkout="ch_Fb8z7rX8r9w2">
</script>
```

You can customize the button text.

```html theme={null}
<script
  src="https://js.oyapasteaza.com/v1/button.js"
  data-public-key="pk_live_xxxxxxxxxxxxxxxxx"
  data-checkout="ch_Fb8z7rX8r9w2"
  data-label="Pay now">
</script>
```

## How it works

<Steps>
  <Step title="Create session">
    Your backend creates a checkout session using your Pasteaza secret key.
  </Step>

  <Step title="Pass reference">
    Your frontend passes the returned `reference` to `PasteAZA.checkout`.
  </Step>

  <Step title="Confirm checkout">
    The SDK retrieves the public checkout session and confirms the merchant, amount, currency, and status.
  </Step>

  <Step title="Open modal">
    The SDK renders a responsive Pasteaza modal on your page. Desktop uses a centered modal. Mobile uses a bottom sheet.
  </Step>

  <Step title="Receive event">
    The SDK calls your `onSuccess`, `onFailed`, `onClose`, or `onError` callback.
  </Step>
</Steps>

## Full example

```html theme={null}
<button id="pay-button">Pay with Pasteaza</button>

<script src="https://js.oyapasteaza.com/v1/pasteaza.js"></script>
<script>
  PasteAZA.init("pk_live_xxxxxxxxxxxxxxxxx");

  document.getElementById("pay-button").addEventListener("click", async function () {
    const response = await fetch("/api/create-pasteaza-checkout", {
      method: "POST",
      headers: { "Content-Type": "application/json" }
    });
    const payload = await response.json();

    PasteAZA.checkout({
      checkout: payload.data.reference,
      onSuccess: function (payment) {
        window.location.href = "/payment-success?reference=" + payment.reference;
      },
      onClose: function () {
        console.log("Customer closed checkout");
      }
    });
  });
</script>
```

## Events

| Callback             | When it runs                                              |
| -------------------- | --------------------------------------------------------- |
| `onLoad(session)`    | The SDK has retrieved the checkout session.               |
| `onSuccess(payment)` | Payment has been confirmed.                               |
| `onFailed(event)`    | Checkout expired, was cancelled, or is no longer payable. |
| `onClose(event)`     | Customer closed the modal.                                |
| `onError(error)`     | The SDK could not load or open checkout.                  |

## Options

| Option       | Type     | Description                                                                  |
| ------------ | -------- | ---------------------------------------------------------------------------- |
| `publicKey`  | string   | Your Pasteaza public key. You can also set it once with `PasteAZA.init`.     |
| `checkout`   | string   | Checkout session reference, such as `ch_Fb8z7rX8r9w2`.                       |
| `onSuccess`  | function | Called after payment confirmation.                                           |
| `onFailed`   | function | Called when checkout reaches a failed terminal state.                        |
| `onClose`    | function | Called when the customer closes the modal.                                   |
| `onError`    | function | Called when the SDK cannot fetch or open checkout.                           |
| `autoClose`  | boolean  | Defaults to `true`. Automatically closes the modal shortly after success.    |
| `closeDelay` | number   | Delay in milliseconds before auto-closing after success. Defaults to `1200`. |

## Notes

* `PasteAZA.checkout("ch_...")` and `PasteAZA.checkout({ checkout: "ch_..." })` both open the same hosted checkout session.
* Never expose your secret key in browser code.
* Use webhooks as your source of truth for order fulfillment. SDK callbacks are for user experience.