AI agents & tools
One call turns the SDK into a tool surface: definitions any model can use, plus a dispatcher that executes whatever it picks. The agent gets exactly the capabilities you have — no more — and every cap stays on the contract, enforced server-side, no matter what the model does.
Wire-up
from atoa_agent_pay import init, create_agent_pay_tools
atoa = init(environment="sandbox") # reads ATOA_API_KEY
atoa.agent.register(name="Checkout copilot")
tools = create_agent_pay_tools(atoa)
tools.specs # tool definitions — hand these to your model
The definitions carry the usage guidance a model needs — required fields, defaults, when to ask the user — so you don’t write tool prompts yourself.
The loop
Provider-agnostic: hand the model the definitions, execute what it calls, feed the result back.
# 1 — give the model tools.specs as its available tools
# 2 — when it returns a tool call, execute it:
out = tools.call(tool_call.name, tool_call.arguments)
# out: { "result", "text", "isError" } — text is model-ready; errors come back in-band, not raised
# 3 — return out["text"] to the model and continue until it's done
The tools
Each tool maps to the SDK method of the same name — parameters and behaviour are identical, so the reference covers both.
Setup & sandbox
| Tool | Purpose |
|---|---|
register_agent | Register / identify the agent (idempotent). |
check_availability | Health probe — never errors. |
get_sandbox_test_accounts | The sandbox SEND accounts and the outcome each forces. |
Contracts
| Tool | Purpose |
|---|---|
create_contract | Create a SEND or COLLECT contract — returns the authorizationUrl a human approves. |
get_contract | Read a contract, including live usage headroom. |
list_contracts | Filter by type, status, or customer. |
update_contract | Change limits — returns a new authorizationUrl to re-approve. |
revoke_contract | Revoke (terminal). |
Payments
| Tool | Purpose |
|---|---|
collect_payment | Money in — a pay-link, or an off-session charge with a contractId. |
send_payment | Money out under an ACTIVE SEND contract. |
get_payment | Read one payment. |
list_payments | Filter by type, status, contract, or customer. |
cancel_payment | Cancel an unpaid collect. |
Refunds
| Tool | Purpose |
|---|---|
refund_payment | Refund a COMPLETED collect, full or partial. |
list_refunds | All refunds on a payment. |
cancel_refund | Cancel a pending refund. |
Customers & stores
| Tool | Purpose |
|---|---|
create_customer · get_customer · list_customers · update_customer · delete_customer | Manage customers (page list_customers to find one by name/email). |
list_stores | Discover your business locations. Tool-driven payments always use the primary store. |
Approvals: the human stays in charge
Approving is deliberately not a tool. A send_payment or off-session collect_payment result carries a
nextAction — the agent’s job is to surface its approvalUrl to the right human (the business owner for a send,
the customer for a charge) and wait for the decision. The model never approves its own payment, and the credential
is only ever entered on Atoa’s page.
Every payment an agent makes is a normal Payment — list_payments and get_payment give it (and you) the full
audit trail.
No AI required
The tools are a thin layer over the SDK. Without a model in the loop, call the same operations directly —
atoa.payment.collect(...), atoa.payment.send(...) — for identical behaviour.
Prefer MCP?
The hosted Atoa MCP server exposes Atoa’s tools to Claude, Cursor, VS Code, and any other MCP-compatible client — no SDK integration needed.