Embedded Checkout for Agent Pay

Show Atoa’s checkout inside your own product. Your server creates a payment and sends its nextAction to the browser. Your browser passes that to AtoaUI.mount() and gets a callback when the customer is done.

A chat thread drawn as grey placeholder bubbles, with the Atoa checkout rendered inside one of them and outlined as your checkout div. — Your thread, your container — the checkout is the only part Atoa draws.

Install

npm install @atoapayments/pay-embed
# Already using @atoapayments/agent-pay? Import from @atoapayments/agent-pay/ui
# instead — same API. It's an optional peer dependency, so install this too.

<script src="https://unpkg.com/@atoapayments/[email protected]/dist/index.global.js"></script>
<script>
  const { AtoaUI } = window.AtoaUI;
</script>

Pin an exact version in production. A payment surface should not change under you between deploys.

Create a payment

The API key creates payments, so it stays on your server and never reaches the browser. The embed needs a backend. If you don’t have one, send the customer a pay-link instead. Your server creates the payment and returns its nextAction:

import atoa_agent_pay

private_key_pem, _ = atoa_agent_pay.generate_es256_keypair()
atoa = atoa_agent_pay.init(environment="sandbox", private_key_pem=private_key_pem)
atoa.agent.register(name="Bookings assistant")   # required before any payment call

@app.post("/api/checkout")
def checkout(order_id: str):
    req = atoa.payment.collect(
        amount={"amount": 45.00},
        order_id=order_id,
    )
    return {"nextAction": req.next_action}   # this, and nothing else

import { createAgentPayClient } from "@atoapayments/agent-pay";

const atoa = createAgentPayClient({ environment: "sandbox" });   // reads ATOA_API_KEY
await atoa.agent.register({ name: "Bookings assistant" });       // required before any payment call

app.post("/api/checkout", async (req, res) => {
  const result = await atoa.payment.collect({
    amount: { amount: 45.00 },
    orderId: req.body.orderId,
  });

  res.json({ nextAction: result.nextAction });   // this, and nothing else
});

Send the nextAction, not the result. A full Agent Pay result carries beneficiary details, contact details and your own metadata — none of which the checkout reads.

Approval secrets travel in the URL fragment. Don’t copy them into query strings, logs, or your own code.

Mount the checkout

Fetch it and mount it. Set your container’s width — the iframe sets its own height.

import { AtoaUI } from "@atoapayments/pay-embed";

const { nextAction } = await fetch("/api/checkout", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ orderId: "booking-8812" }),
}).then((r) => r.json());

const handle = AtoaUI.mount(nextAction, {
  container: document.querySelector("#checkout"),
  environment: "sandbox",
  orderId: "booking-8812",                      // one live mount per order
  theme: { mode: "auto" },
  onPaymentCompleted: (e) => showReceipt(e),
  onError: (e) => console.error(e.kind, e.message),
});

<div id="checkout" style="max-width: 420px"></div>

<script src="https://unpkg.com/@atoapayments/[email protected]/dist/index.global.js"></script>
<script>
  const { AtoaUI } = window.AtoaUI;

  fetch("/api/checkout", { method: "POST" })
    .then((r) => r.json())
    .then(({ nextAction }) => {
      AtoaUI.mount(nextAction, {
        container: document.getElementById("checkout"),
        environment: "sandbox",
        onPaymentCompleted: (e) => console.log("completed", e.data),
        onError: (e) => console.error(e.kind, e.message),
      });
    });
</script>

import { useEffect, useRef } from "react";
import { AtoaUI } from "@atoapayments/pay-embed";

function Checkout({ nextAction, orderId }: { nextAction: unknown; orderId: string }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;

    const handle = AtoaUI.mount(nextAction, {
      container: ref.current,
      environment: "sandbox",
      orderId,
      onPaymentCompleted: (e) => console.log(e.data),
      onError: (e) => console.error(e.kind, e.message),
    });

    return () => handle.destroy();     // React 18 StrictMode remounts — destroy is idempotent
  }, [nextAction, orderId]);

  return <div ref={ref} style={{ maxWidth: 420 }} />;
}

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from "vue";
import { AtoaUI, type Handle } from "@atoapayments/pay-embed";

const props = defineProps<{ nextAction: unknown; orderId: string }>();
const host = ref<HTMLDivElement | null>(null);
let handle: Handle | null = null;

onMounted(() => {
  if (!host.value) return;

  handle = AtoaUI.mount(props.nextAction, {
    container: host.value,
    environment: "sandbox",
    orderId: props.orderId,
    onPaymentCompleted: (e) => console.log(e.data),
    onError: (e) => console.error(e.kind, e.message),
  });
});

onUnmounted(() => handle?.destroy());
</script>

<template>
  <div ref="host" style="max-width: 420px" />
</template>

import { AfterViewInit, Component, ElementRef, Input, OnDestroy, ViewChild } from "@angular/core";
import { AtoaUI, type Handle } from "@atoapayments/pay-embed";

@Component({
  selector: "atoa-checkout",
  standalone: true,
  template: `<div #host style="max-width: 420px"></div>`,
})
export class AtoaCheckoutComponent implements AfterViewInit, OnDestroy {
  @Input({ required: true }) nextAction!: unknown;
  @Input() orderId?: string;
  @ViewChild("host") host!: ElementRef<HTMLDivElement>;

  private handle?: Handle;

  ngAfterViewInit(): void {
    this.handle = AtoaUI.mount(this.nextAction, {
      container: this.host.nativeElement,
      environment: "sandbox",
      orderId: this.orderId,
      onPaymentCompleted: (e) => console.log(e.data),
      onError: (e) => console.error(e.kind, e.message),
    });
  }

  ngOnDestroy(): void {
    this.handle?.destroy();
  }
}

mount() returns a handle for unmounting and refreshing the surface. Destroy it when your component unmounts, or the iframe outlives the view that owned it. There is no method to create a payment from the browser, so re-rendering or reloading always shows the same payment rather than creating a second one.

Payment surfaces

mount() reads nextAction.type and shows the right screen — you don’t branch on it.

Four checkout screens in a grid: the bank picker, an approval with Face ID, contract setup with saved cards, and the add-a-card form. — The same mount call, four of the screens it can produce.

`nextAction.type`	Screen
`PAY`	Bank picker and checkout
`APPROVAL`	Approval — one-time code or passkey
`AUTHORIZE_CONTRACT`	Contract setup — `data.kind: 'cvrp'` shows the bank-consent page instead
`NONE`	Receipt
Anything else	The action’s `fallback` text and link

Those four are the whole set an Agent Pay call returns. Picking a card, entering card details and enrolling a passkey are steps inside those screens, on Atoa’s origin — they don’t come back to you as actions to render. The last row is the forward-compatibility rule: a type this version doesn’t know renders the action’s fallback, so Atoa can add one without breaking your build. See the nextAction reference.

Handle events

Domain events tell you what happened to the money. Every one arrives in the same envelope:

{
  specVersion: 1,                    // bumps only on a breaking shape change
  type: "payment.completed",         // resource.event — an open string, not an enum
  resource: "payment",               // always the segment before the dot
  resourceId: "prq_a81f…",           // the subject's id; null when the SDK holds none
  occurredAt: "2026-08-25T10:04:11.201Z",  // when the SDK saw it, not when money moved
  livemode: false,                   // true only against production
  data: { status: "COMPLETED" }      // per type, below
}

Which resource the event names follows from what you mounted: a payment surface emits payment.*, a contract surface contract.*, an approval surface approval.*. The subject’s id is always on the envelope as resourceId — read it there rather than out of data.

`type`	Callback	Emitted when	`data`
`payment.completed`	`onPaymentCompleted`	The payment settled.	`paymentRequestId`, `status`, `iso?`
`payment.cancelled`	`onPaymentCancelled`	The customer cancelled.	`status`, `reason`
`payment.expired`	`onPaymentExpired`	The payment request expired unpaid.	`status`, `reason`
`payment.failed`	`onPaymentFailed`	Only when the frame reports a failure with no specific reason. A declined payment normally stays on screen for a retry, so a real `FAILED` reaches you by polling, not here.	`status`
`contract.activated`	`onContractActivated`	The contract reached `ACTIVE`.	`status`, `iso?` — plus `contractId` on `resourceId`
`contract.declined`	`onContractDeclined`	The customer declined the contract.	`reason`
`approval.approved`	`onApprovalApproved`	The approver passed SCA. Approval is the first step — the payment can still fail afterwards.	`status`
`approval.declined`	`onApprovalDeclined`	The approver declined.	`reason`
`approval.expired`	`onApprovalExpired`	The approval window lapsed undecided.	`reason`

data is a passthrough of what the frame reported, so a settled payment carries its id, status and timestamp, while a failure carries only the reason. resourceId is populated on every event except an approval’s, where the mount holds the client secret and never the id.

Events with no named callback

These are emitted today and reach onEvent only — there is no on… option for them. If any matter to you, handle them there: contract.expired · contract.revoked · contract.suspended · contract.ended · contract.invalid · contract.failed · approval.superseded · approval.cancelled

onEvent: (e) => {
  if (e.type === "approval.superseded") replaceApprovalUi();
  if (e.type === "contract.revoked") stopChargingThisCustomer();
}

type is an open string, so onEvent is also where types added after your installed version arrive. Treat data as additive — read the keys you know, ignore the rest. On an approval surface resourceId is null: the mount holds the client secret, never the approval’s id.

These fire on a real status change recorded by Atoa, not on an optimistic UI guess — but they reach you through the customer’s browser, which can close, lose signal, or never send them. Confirm on your own backend before you fulfil an order, with payment.get or awaitSettled. Webhooks don’t fire for contract payments in this phase, so polling is the path.

UI callbacks [#ui-callbacks]

Separate from the events above, and these can fire many times. They describe the frame, never the money, so never branch on them to decide an order is paid.

Callback	Fires when	Argument
`onReady`	The frame connected and is ready to render.	—
`onUiState`	The frame’s phase changed.	`'BOOT'` · `'PICKER'` · `'RESOLVING'` · `'HANDOFF'` · `'WAITING'` · `'SETTLING'` · `'CARD'` · `'APPROVAL'` · `'CONTRACT'` · `'PAID'` · `'FAILED'` · `'EXPIRED'` · `'CANCELLED'`
`onStatusChange`	The frame re-read the payment’s status.	`{ status: string, iso?: string }`
`onHandoff`	The customer is being sent to their bank.	`{ href: string, bank: string }`
`onExit`	The customer left the surface.	`{ reason: string }`
`onError`	A request failed.	`ApiFailure` — see Errors

Options and theming

AtoaUI.mount(nextAction, options) → Handle.

Option	Default	Notes
`container`	— (required)	An `HTMLElement` — not a selector. Set its width; the frame reports its own height and the loader applies it, clamped to 2000px. Throws synchronously if it isn’t an element.
`environment`	— (required)	`'sandbox'` or `'production'`. Anything else throws before an iframe is created. Must match the key that created the payment.
`paymentRequestId`	from the action	Only needed if you have an id but no `nextAction`. There is no create verb here — mount shows a payment that already exists.
`orderId`	—	De-duplication key. A second `mount` with the same `orderId` returns the first handle and renders nothing new, so a re-render or double-tap can’t produce two surfaces.
`theme`	`{ mode: 'auto' }`	Bounded tokens, validated below.
`layout`	`'inline'`	`'inline'` or `'sheet'`.
`device`	UA detection	`'desktop'` or `'mobile'`. Believed verbatim — you know your surface better than a UA string does. Drives the QR affordance: a phone is never offered a QR to scan with itself.
`locale`	frame default	Locale hint, e.g. `'en-GB'`.
`gridColumns`	`4`	`3` or `4`. The bank grid’s width.
`gridRows`	`2`	`1` or `2`. Tile count is `gridColumns × gridRows − 1`, the last cell being View all — so `gridRows: 1` gives a chat a single-row picker.
`method`	`'unknown'`	`'bank'` · `'card'` · `'unknown'`. Which method you expect, so the loading skeleton paints the right shape. A hint only — a wrong one costs one repaint, never a wrong surface.
`relay`	`false`	`true` when your page is itself inside an iframe, so applied heights re-emit to the page above. Resolves the parent origin from `ancestorOrigins`/referrer and stays off if neither is readable — it never posts to `*`. Pass `{ targetOrigin }` to state it explicitly.
`handoff`	`'auto'`	`'auto'` renders the bank link inside the frame. `'native'` hands the URL out to `onHop` so your host opens it its own way.
`onHop`	—	`(e: { href, bank?, reason: 'handoff' \| 'escalate' }) => boolean`. For hosts that open links through a platform API rather than an anchor. Return `true` to mean “handled”; anything else falls through to the in-frame anchor. Consulted for the bank hop only when `handoff: 'native'`.

Four wireframe hosts: a chat thread, an in-app assistant panel, a mobile sheet, and a plain inline card, each with the checkout slot marked. — One mount call, whatever container you give it.

Theming

theme: { mode: "auto" }     // "auto" | "light" | "dark"

That is the whole theme surface. Anything unrecognised normalises to "auto". Colours, fonts, corner radius and density are deliberately not settable. A checkout a host can restyle is a checkout a host can make look like something it is not, and the trust the frame carries is what you are embedding. Brand treatment, when it ships, will be issued to your business from Atoa’s side — not accepted from the page.

Don’t modify the iframe’s allow or sandbox attributes. Removing them breaks passkeys, one-time-code autofill, and the redirect to the customer’s bank. The loader warns in the console if it detects either was altered.

The handle

Member	Type	Notes
`destroy()`	`void`	Removes the iframe, leaves your container’s styles as it found them, and releases the `orderId`. Idempotent — calling it twice does nothing.
`refresh()`	`void`	Ask the surface to re-check its money. Status watches are capped — the frame stops polling after a few minutes — so call this when your server learns something changed. Safe any time; a settled surface ignores it.
`getState()`	`PhaseName`	The current UI phase.
`kind`	`'payment'` · `'contract'` · `'approval'` · `'fallback'`	What was mounted. `'fallback'` means no frame exists — the action’s text and link were rendered instead.
`id`	`string`	The subject: a `paymentRequestId`, `contractId`, or the approval’s id.
`paymentRequestId`	`string`	Set on payment surfaces, empty on contract and approval surfaces.

Errors

mount() throws straight away — before any iframe exists — if container isn’t an HTMLElement, or if environment isn’t 'sandbox' or 'production'. Everything after that reaches onError as an ApiFailure:

Field	Type	Notes
`kind`	`'network'` · `'http'` · `'domain'` · `'abort'` · `'unknown'`	What class of failure.
`message`	`string`	Human-readable.
`statusCode`	`number?`	Present on `'http'`.
`name`	`string?`	The server’s error name, on `'domain'`.
`referenceId`	`string?`	Quote this to support.

An onError doesn’t end the surface — the frame may recover. Call destroy() yourself if you want to stop. If the container stays blank, check the console. AtoaUI.mount: the embed frame at <origin> never connected within <n>ms means the iframe loaded but never answered — usually a frame-src content-security policy on your own page, or a network path that can’t reach Atoa. If nothing is logged at all, container probably resolved to null.

Test in sandbox

Create the payment with a sandbox API key and pass environment: 'sandbox'. Choose Atoa Test Bank in the checkout and pick the outcome you want. No money moves — see Sandbox. To go live, switch to a production API key and pass environment: 'production'. Nothing else changes.

Approvals SDK

Show just the human sign-off step, without the whole checkout.

The nextAction contract

What mount() reads — for anyone rendering their own UI.

Overview

Payments

SDKs

Integration

Bank Feed

Developer Tools

Agentic Payments

Embedded Checkout for Agent Pay

Install

Create a payment

Mount the checkout

Payment surfaces

Handle events

Events with no named callback

UI callbacks [#ui-callbacks]

Options and theming

Theming

The handle

Errors

Test in sandbox

Next

Approvals SDK

The nextAction contract

​Install

​Create a payment

​Mount the checkout

​Payment surfaces

​Handle events

​Events with no named callback

​UI callbacks [#ui-callbacks]

​Options and theming

​Theming

​The handle

​Errors

​Test in sandbox

​Next

Approvals SDK

The nextAction contract

Install

Create a payment

Mount the checkout

Payment surfaces

Handle events

Events with no named callback

UI callbacks [#ui-callbacks]

Options and theming

Theming

The handle

Errors

Test in sandbox

Next