> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Client SDK for Atoa Payments

> Add Atoa Pay by Bank and card payments to your website with the Web Client SDK. Install, initialise and launch checkout, with examples.

The Atoa Web Client SDK lets you embed a seamless payment experience into your web checkout in minutes. It provides a simple interface for a payment dialog supporting both pay-by-bank and card payments (Visa, Mastercard, Apple Pay and Google Pay), handling the entire flow securely and efficiently — whether you're building a custom payment gateway or enhancing an existing one.

<video controls className="w-full aspect-video" src="https://mintcdn.com/atoa-payments-limited/KEZXxpd7888D-dlX/videos/atoa-web-sdk-walkthrough.mp4?fit=max&auto=format&n=KEZXxpd7888D-dlX&q=85&s=302b69471531361394db4bdbed5ee540" data-path="videos/atoa-web-sdk-walkthrough.mp4" />

If you encounter any issues or need help debugging, please refer to our public [GitHub repository](https://github.com/ATOAPaymentsLimited/AtoaWebClientSDK) for detailed setup instructions and troubleshooting steps.

## Step 1: Install the SDK

Choose one of two ways to use the SDK:

### a. Install via NPM

```bash theme={null}
npm install @atoapayments/atoa-web-client-sdk
```

### b. Use via CDN (Script Tag)

```html theme={null}
<script type="module">
  import { AtoaWebSdk } from "https://unpkg.com/@atoapayments/atoa-web-client-sdk";
</script>
```

## Step 2: Generate a Payment Request (Backend)

You must first create a payment request from your backend using the following [API](/api-reference/Payment/process-payment):

```http theme={null}
POST https://api.atoa.me/api/payments/process-payment
```

To know more, follow the [Getting Started](/introduction#step-1-sign-up-for-developer-access) guide for backend integration, which includes payment request generation, webhook handling, and signature verification.

## Step 3: Initialize and Launch the SDK

> **Note:** To use the Atoa Web Client SDK, you must first whitelist your domain. Set your domain or subdomain (e.g. `https://pay.yourbrandname.co.uk`) via the Atoa Dashboard or mobile app: [Whitelist your domain here](https://dashboard.paywithatoa.co.uk/my-account/settings/api-access)

Here's how to launch the SDK on a button click after generating the paymentRequestId:

```typescript theme={null}
import { AtoaWebSdk } from "@atoapayments/atoa-web-client-sdk";

const sdk = new AtoaWebSdk({
  environment: "PRODUCTION", // Use 'SANDBOX' for testing
  paymentRequestId: "ad90e280-5e42-4917-9237-aa1cb2b829sd", // Required
  customerDetails: {
    phoneCountryCode: "44",
    phoneNumber: "1234567890",
    email: "test@mail.com",
  }, // Optional – enables one-click payments for return users
  onClose: (data) => {
    // Triggered when the payment dialog is closed
  },
  onUserCancel: (paymentRequestId) => {
    // Triggered when user cancels before completing the payment
  },
  onPaymentStatusChange: (data) => {
    if (data.status === "COMPLETED") {
      // Redirect to success page
    } else if (data.status === "PENDING") {
      // Show pending state until COMPLETED
    }
  },
  onError: (error) => {
    // Handle errors in SDK loading or runtime
  },
});

// Launch the checkout flow
sdk.showPaymentDialog();
```

### Example using Script Tag

```html theme={null}
<script type="module">
  import { AtoaWebSdk } from "https://unpkg.com/@atoapayments/atoa-web-client-sdk";

  const sdk = new AtoaWebSdk({
    environment: "PRODUCTION", // Use 'SANDBOX' for testing
    paymentRequestId: "ad90e280-5e42-4917-9237-aa1cb2b829sd",
    ...options,
  });

  document.getElementById("pay-btn").addEventListener("click", () => {
    sdk.showPaymentDialog();
  });
</script>
```

## Step 4: Handle Payment Status

The Web SDK notifies you of real-time payment updates via the onPaymentStatusChange callback. You can display your order summary page when the payment status is `COMPLETED`.

⚠️ Important: If the payment status is PENDING, display an intermediate state in your UI and continue showing it until a COMPLETED update is received.

To track the final payment outcome beyond the client, we recommend implementing [webhooks](/api-reference/Webhook/CreateWebhookEvent) (Recommended) or [polling](/api-reference/Payment/getPaymentStatus) (as a fallback). For full implementation details, refer to the [Getting Started](/introduction#step-1-sign-up-for-developer-access) Guide.

## Step 5: Handle Events

Here's what each event callback does:

| Event                   | Fires when                                                                  | Description                                                                                |
| ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `onClose`               | When the payment dialog is closed, either after payment or by user.         | Redirect to thank-you page or refresh cart summary.                                        |
| `onUserCancel`          | When the user manually closes the payment dialog before completing payment. | Log the event, notify the user, or offer retry.                                            |
| `onPaymentStatusChange` | When payment status updates (COMPLETED, PENDING, FAILED)                    | Handle COMPLETED and PENDING in your UI. You may show an intermediate confirmation screen. |
| `onError`               | If the SDK fails to load, initialize, or encounters any internal error      | Display a toast or fallback UI. Consider retry logic.                                      |

<Accordion title="Callback Payload Reference">
  Below are the payload structures you can expect inside each callback:

  #### onPaymentStatusChange(data)

  Triggered when the payment status updates. Handle `COMPLETED`, `PENDING` and `FAILED` statuses.

  ```typescript theme={null}
  {
    status: "COMPLETED" | "PENDING" | "FAILED",
    paymentRequestId: string,
    paymentIdempotencyId?: string,
    atoaSignature?: string,
    atoaSignatureHash?: string,
    callbackParams?: Record<string, string>
  }
  ```

  #### onError(error)

  Fired when there’s an issue with SDK initialization, config, or runtime.

  ```typescript theme={null}
  {
    name: "AtoaPayWebSDKError",
    message: string,
    details?: any, // Any additional metadata or context
    componentName?: string // Example: "PaymentDetailsView"
  }
  ```

  #### onClose(data)

  Called when the user closes the payment dialog after any action.

  ```typescript theme={null}
  {
    status: string, // e.g., "COMPLETED", "FAILED"
    paymentRequestId: string,
    paymentIdempotencyId?: string,
    callbackParams?: Record<string, string>,
    atoaSignature?: string,
    atoaSignatureHash?: string
  }
  ```

  #### onUserCancel(paymentRequestId)

  Triggered when the user closes the widget without making a payment.

  ```typescript theme={null}
  (paymentRequestId: string)
  ```
</Accordion>

## Step 6: Cleanup the SDK

Use dispose() to clear the SDK from memory and DOM.

```javascript theme={null}
sdk.dispose();
```

* Disposes the payment widget.
* Removes listeners and internal state.
* Recommended after every completed or cancelled session.

## Step 7: Test in Sandbox

To use sandbox mode, change the environment to "SANDBOX":

```javascript theme={null}
const sdk = new AtoaWebSdk({
  environment: "SANDBOX",
  paymentRequestId: "ad90e280-5e42-4917-9237-aa1cb2b829sd",
  // ...other config properties
});
```

Refer to our [Sandbox Guide](/atoa-sandbox) to simulate **`COMPLETED`**, **`FAILED`** and **`PENDING`** payments before going live.

## Step 8: Brand & Customize (Optional)

* **Theme Color:** Choose your brand's hex color in the dashboard. The widget will automatically reflect your theme color. [Update your theme color here](https://dashboard.paywithatoa.co.uk/add-ons/custom-branding)

* **Design Guidelines:** Refer to our official branding guide to correctly showcase "Pay by Bank" in your checkout. [View Figma file](/design-system)

* **Custom Domain:** Set your domain or subdomain (e.g., pay.yourbrandname.co.uk) from the Atoa Dashboard or mobile app. [Whitelist your domain here](https://dashboard.paywithatoa.co.uk/my-account/settings/api-access)

> **Note:** You do **not** need to pass the domain or theme color in the SDK. Simply configure these once from your Dashboard or Atoa Business App

### Apple Pay Setup

To use Apple Pay with the Web SDK, please [contact Support](https://help.paywithatoa.co.uk). We'll verify your domain ownership with Apple and get everything set up for you. This won't impact your payments.

## 🧠 Tips & Best Practices

✅ To enable **faster checkout**, Atoa uses the customer's email and mobile number to pre-select the previously used bank within our network. We recommend passing customer details in the Web SDK to support **one-click checkout** for returning users.

✅ Always validate the payment status using webhooks or polling.

✅ Do not display the payment widget before your backend has successfully created a valid **paymentRequestId**.

✅ Before going **LIVE**, ensure to use the production access secret generated from your Business App or Web Dashboard.

✅ Tipping is disabled when using the Web SDK. If tipping is part of your experience, we recommend implementing it on your end.

## 📩 Need Help?

If you encounter any issues or need help debugging, please refer to our public [GitHub repository](https://github.com/ATOAPaymentsLimited/AtoaWebClientSDK) for detailed setup instructions and troubleshooting steps.

We're here to help — email us at [hello@paywithatoa.co.uk](mailto:hello@paywithatoa.co.uk) or talk to us from chat support from the dashboard.