Web Client SDK

Integrate Atoa into your web checkout in minutes using our Web SDK. Whether you’re building a custom payment gateway or enhancing an existing one, the Atoa SDK makes it easy to embed a seamless bank payment flow.

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

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

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

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

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

(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

​

🧠 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 hello@paywithatoa.co.uk or talk to us from chat support from the dashboard.