Skip to main content
The embedded checkout is the AgentaOS checkout on your own page: inline in a spot you choose, or as an overlay over the page. Card, bank transfer, trials, discount codes, VAT and 3D Secure work exactly as on the hosted checkout. AgentaOS stays the merchant of record. It runs in the browser only. For server work, such as creating checkouts or reading subscriptions, use @agentaos/pay.

Before you start

1

Approve your site

In the dashboard, Settings → Developers → Approved sites, add each site you’ll embed on, e.g. https://acme.com. The browser refuses to show your checkout anywhere else. Test products also work on localhost without adding it.
2

Set your look

Settings → Business → Checkout appearance: button color, font, corners, background. It applies to the hosted and the embedded checkout alike.
3

Get the product's buyer link

The checkoutUrl from agenta products create, the SDK, or the product page. Embed on your site on the product page has a ready snippet.

Script tag

No build step:

npm

loadAgentaOS() adds the script once, however many times it’s called (the first call’s origin wins). While developing against a local AgentaOS, pass loadAgentaOS({ origin: 'http://localhost:3000' }). If the script can’t load, the promise rejects with a plain sentence and a later call tries again. <AgentaOSCheckout> reports it to onEvent as checkout.error not_loaded.

React

Options

The product’s buyer link.
string
Instead of link: the sessionId of a checkout your server created with checkouts.create. Use it for logged-in users, with your own metadata. Create the checkout when the buyer clicks Buy, not on every page view: checkout creation is rate-limited to 60 per minute from your server’s IP address, shared by all your buyers.
string | HTMLElement
Selector or element for inline. Leave it out for the overlay.
string
Prefill the buyer’s email. Sent to the checkout directly, never in a URL.
string
Prefill the buyer’s country, ISO code. Sent to the checkout directly, never in a URL.
string | false
Where the whole page goes after payment, with sessionId added (https only). Defaults to the checkout’s success URL: the one given to checkouts.create, else the product’s. false keeps the page where it is.
(event) => void
Receives the events below.
open() returns { update({ link | session }), close() }. Prefill and successUrl are read when the checkout opens; update() switches only the product or checkout.

Events

amountMinor is what was charged today in minor units (0 for a free trial), or what the buyer was asked to send for a bank transfer. A bank transfer never moves the page: the buyer needs the bank details on screen.
An event is never proof of payment. Unlock access from the webhook or checkouts.retrieve(sessionId), and handle checkout.completed once per sessionId: a reload of a finished checkout sends it again.
not_loaded after 10 seconds usually means the page’s site is not on the business’s approved sites.

Payment methods in a frame

Cards with 3D Secure work everywhere. On EUR sales the checkout also offers bank transfer. Apple Pay and Google Pay appear on devices that support them.

Next steps

Checkouts

Create a checkout on your server for a logged-in user.

Webhooks

Unlock access when the payment is confirmed.