Web Client SDK for Atoa Payments

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.

If you encounter any issues or need help debugging, please refer to our public GitHub repository 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

npm install @atoapayments/atoa-web-client-sdk

b. Use via CDN (Script Tag)

<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:

POST https://api.atoa.me/api/payments/process-payment

To know more, follow the Getting Started 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

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

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: "[email protected]",
  }, // 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

<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 (Recommended) or polling (as a fallback). For full implementation details, refer to the Getting Started 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.

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.

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

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

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

(paymentRequestId: string)

Step 6: Cleanup the SDK

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

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”:

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

Refer to our Sandbox Guide 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
Design Guidelines: Refer to our official branding guide to correctly showcase “Pay by Bank” in your checkout. View Figma file
Custom Domain: Set your domain or subdomain (e.g., pay.yourbrandname.co.uk) from the Atoa Dashboard or mobile app. Whitelist your domain here

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. 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 for detailed setup instructions and troubleshooting steps. We’re here to help — email us at [email protected] or talk to us from chat support from the dashboard.

Overview

Payments

SDKs

Integration

Bank Feed

Developer Tools

Agentic Payments

Web Client SDK for Atoa Payments

Step 1: Install the SDK

a. Install via NPM

b. Use via CDN (Script Tag)

Step 2: Generate a Payment Request (Backend)

Step 3: Initialize and Launch the SDK

Example using Script Tag

Step 4: Handle Payment Status

Step 5: Handle Events

onPaymentStatusChange(data)

onError(error)

onClose(data)

onUserCancel(paymentRequestId)

Step 6: Cleanup the SDK

Step 7: Test in Sandbox

Step 8: Brand & Customize (Optional)

Apple Pay Setup

🧠 Tips & Best Practices

📩 Need Help?

​Step 1: Install the SDK

​a. Install via NPM

​b. Use via CDN (Script Tag)

​Step 2: Generate a Payment Request (Backend)

​Step 3: Initialize and Launch the SDK

​Example using Script Tag

​Step 4: Handle Payment Status

​Step 5: Handle Events

​onPaymentStatusChange(data)

​onError(error)

​onClose(data)

​onUserCancel(paymentRequestId)

​Step 6: Cleanup the SDK

​Step 7: Test in Sandbox

​Step 8: Brand & Customize (Optional)

​Apple Pay Setup

​🧠 Tips & Best Practices

​📩 Need Help?

Step 1: Install the SDK

a. Install via NPM

b. Use via CDN (Script Tag)

Step 2: Generate a Payment Request (Backend)

Step 3: Initialize and Launch the SDK

Example using Script Tag

Step 4: Handle Payment Status

Step 5: Handle Events

onPaymentStatusChange(data)

onError(error)

onClose(data)

onUserCancel(paymentRequestId)

Step 6: Cleanup the SDK

Step 7: Test in Sandbox

Step 8: Brand & Customize (Optional)

Apple Pay Setup

🧠 Tips & Best Practices

📩 Need Help?