> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents & Tools with Atoa Agent Pay

> Turn the Atoa Agent Pay SDK into a tool surface any model can use. Wire up the tools, run the loop and keep every capability enforced server-side.

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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  import { createAgentPayClient, createAgentPayTools } from "@atoapayments/agent-pay";

  const atoa = createAgentPayClient({ environment: "sandbox" });   // reads ATOA_API_KEY
  await atoa.agent.register({ name: "Checkout copilot" });

  const tools = createAgentPayTools(atoa);
  tools.tools;                               // tool definitions — hand these to your model
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={null}
  # 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
  ```

  ```typescript TypeScript theme={null}
  // 1 — give the model tools.tools as its available tools
  // 2 — when it returns a tool call, execute it:
  const out = await tools.call(toolCall.name, toolCall.arguments);
  // out: { result, text, isError } — text is model-ready; errors come back in-band, not thrown
  // 3 — return out.text to the model and continue until it's done
  ```
</CodeGroup>

## The tools

Each tool maps to the SDK method of the same name — parameters and behaviour are identical, so the
[reference](/agent-pay/reference#methods) 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](/mcp-server) exposes Atoa's tools to Claude, Cursor, VS Code, and any other
MCP-compatible client — no SDK integration needed.