# Atoa Developer Documentation
> Atoa is a UK payments platform for accepting Pay by Bank (open banking / account-to-account) and card payments through one API. These developer docs cover the REST API, SDKs (Web, Flutter, React Native), e-commerce plugins, the Atoa CLI, and the Model Context Protocol (MCP) server for AI agents. Base API URL: https://api.atoa.me. Dashboard: https://dashboard.paywithatoa.co.uk. Marketing site: https://paywithatoa.co.uk.
## Getting started
- [Getting started](https://docs.paywithatoa.co.uk/introduction): Sign up for developer access, generate an API token, and send your first payment request.
- [Sandbox guide](https://docs.paywithatoa.co.uk/atoa-sandbox): Test end to end in the sandbox environment before going live.
- [Go-live checklist](https://docs.paywithatoa.co.uk/go-live): Steps to move from sandbox to production.
- [Design guidelines](https://docs.paywithatoa.co.uk/design-system): Brand and UI guidance for building Atoa payment experiences.
## Authentication
- Authentication is HTTP Bearer with a JWT: send `Authorization: Bearer <token>`. Generate tokens in the [Atoa Dashboard](https://dashboard.paywithatoa.co.uk/my-account/settings/api-access).
- Sandbox and production tokens are separate and not interchangeable — use each only against its own environment.
## SDKs
- [Web Client SDK](https://docs.paywithatoa.co.uk/web-client-sdk): Drop Pay by Bank and card checkout into a web app.
- [Flutter SDK](https://docs.paywithatoa.co.uk/flutter-sdk): Accept payments in a Flutter mobile app.
- [React Native SDK](https://docs.paywithatoa.co.uk/react-native-sdk): Accept payments in a React Native mobile app.
## E-commerce integrations
- [Integration overview](https://docs.paywithatoa.co.uk/integration-overview): How Atoa plugs into e-commerce platforms.
- [WooCommerce](https://docs.paywithatoa.co.uk/woo-commerce): WooCommerce plugin setup.
- [Magento](https://docs.paywithatoa.co.uk/magento): Magento integration setup.
## Bank feed (Open Banking AIS)
- [Bank feed introduction](https://docs.paywithatoa.co.uk/accounts-introduction): Read account and transaction data via Open Banking.
- [Bank feed getting started](https://docs.paywithatoa.co.uk/accounts): Set up account authorization and start pulling account data.
## Agentic Payments (Agent Pay)
- [Agent Pay overview](https://docs.paywithatoa.co.uk/agent-pay/overview): Give AI agents a guarded way to move money within human-approved limits. Install `@atoapayments/agent-pay` (npm, Node 22+) or `atoa-agent-pay` (PyPI, Python 3.10+).
- [Embedded checkout](https://docs.paywithatoa.co.uk/agent-pay/embed): Render an existing payment inside your own page with `@atoapayments/pay-embed` — install, a container div, and one `AtoaUI.mount` call. Your server creates the payment; the API key never reaches the browser.
- [Collect (money in)](https://docs.paywithatoa.co.uk/agent-pay/collect): Pay-links, off-session charges under a COLLECT contract, charge-on-approval (`initialCharge`), SCA, refunds.
- [Send (money out)](https://docs.paywithatoa.co.uk/agent-pay/send): Payouts under a SEND contract the account owner authorises once; per-payment and period caps enforced server-side; SCA on every payout.
- [AI agents & tools](https://docs.paywithatoa.co.uk/agent-pay/ai-agents): `createAgentPayTools` turns the SDK into 23 self-describing tools for any model; approving is not a tool — a human decides on Atoa's page.
- [The nextAction contract](https://docs.paywithatoa.co.uk/agent-pay/next-action): The one action object on every result — type catalogue, `for: customer|owner|none`, and the `{text,url}` fallback every action carries.
- [Approvals SDK](https://docs.paywithatoa.co.uk/agent-pay/approvals): `@atoapayments/agentic-payment-approvals-js` embeds the hosted SCA approval page in your own web UI.
- [Agent Pay reference](https://docs.paywithatoa.co.uk/agent-pay/reference): Authentication (API key + ES256 signing), KMS/custom signers, every method, errors, sandbox, go-live.
## Developer tools
- [Atoa CLI](https://docs.paywithatoa.co.uk/cli): Command-line tool (`@atoapayments/atoa-cli`, Node 20+) to create payments, manage customers, test webhooks and inspect transactions from the terminal. Install with `npm install -g @atoapayments/atoa-cli`. Log in with `atoa login` (browser-based; no token copy-paste). Source: https://github.com/ATOAPaymentsLimited/Atoa-CLI.
- [Model Context Protocol (MCP) server](https://docs.paywithatoa.co.uk/mcp-server): Lets AI assistants call the Atoa API as tools (29 tools across payments, customers, cards, refunds, webhooks, bank feeds and institutions). HTTP mode endpoint: `https://mcp.atoa.me/mcp` (send `Authorization: Bearer <token>` and `X-Atoa-Env: sandbox|production` headers). Local mode: `npx @atoapayments/mcp` (set `ATOA_AUTH_TOKEN` and `ATOA_ENV` in the client's env block).
## API reference
- [API reference introduction](https://docs.paywithatoa.co.uk/api-reference/introduction): Auth scheme and Postman collection.
### Payments
- [Get stores](https://docs.paywithatoa.co.uk/api-reference/payment/get-stores): List active stores on the merchant account.
- [Process payment](https://docs.paywithatoa.co.uk/api-reference/payment/process-payment): Create a payment request; returns a payment link, QR code and `paymentRequestId`.
- [Cancel payment](https://docs.paywithatoa.co.uk/api-reference/payment/cancel-payment): Cancel a pending payment request.
- [Get payment status](https://docs.paywithatoa.co.uk/api-reference/payment/get-payment-status): Check the current status of a payment.
- [Get transactions](https://docs.paywithatoa.co.uk/api-reference/payment/get-transactions): Retrieve transaction history with filters.
### Customers
- [Create customer](https://docs.paywithatoa.co.uk/api-reference/customers/create-customer): Register a customer (requires email or phone number).
- [List customers](https://docs.paywithatoa.co.uk/api-reference/customers/list-customers): List customers with pagination.
- [Get customer](https://docs.paywithatoa.co.uk/api-reference/customers/get-customer): Get a single customer.
- [Update customer](https://docs.paywithatoa.co.uk/api-reference/customers/update-customer): Update customer details.
- [Delete customer](https://docs.paywithatoa.co.uk/api-reference/customers/delete-customer): Remove a customer record.
### Payment methods (saved cards)
- [List payment methods](https://docs.paywithatoa.co.uk/api-reference/payment-methods/list-payment-methods): List a customer's saved cards.
- [Get payment method](https://docs.paywithatoa.co.uk/api-reference/payment-methods/get-payment-method): Get a single saved card.
- [Delete payment method](https://docs.paywithatoa.co.uk/api-reference/payment-methods/delete-payment-method): Remove a saved card.
### Card on file
- [Card on file introduction](https://docs.paywithatoa.co.uk/api-reference/card-on-file/introduction): Charge a saved card off-session.
- [Charge saved card](https://docs.paywithatoa.co.uk/api-reference/card-on-file/charge-saved-card): Charge a previously saved card (supports AUTO_CAPTURE, MANUAL_CAPTURE, CAPTURE_BEFORE_EXPIRY).
- [Manual capture payment](https://docs.paywithatoa.co.uk/api-reference/card-on-file/capture-payment): Settle a pre-authorized card payment.
- [Manual cancel payment](https://docs.paywithatoa.co.uk/api-reference/card-on-file/cancel-payment): Void a pre-authorization or unsettled card payment.
### Refunds
- [Get refund payments](https://docs.paywithatoa.co.uk/api-reference/refund/get-refund-payments): List refunds for a payment.
- [Initiate refund](https://docs.paywithatoa.co.uk/api-reference/refund/initiate-refund): Start a full or partial refund of a COMPLETED payment.
- [Cancel refund](https://docs.paywithatoa.co.uk/api-reference/refund/cancel-refund): Cancel an INITIATED refund (production only).
### Bank feed (Account Initiation Services)
- [Initiate account authorization](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/initiate-account-authorization): Start the bank authorization flow.
- [Fetch all accounts](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/fetch-all-accounts): List authorized bank accounts.
- [Fetch account details](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/fetch-account-details): Get sort code, account number and bank name.
- [Fetch account balance](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/fetch-account-balance): Get the current balance for an account.
- [Fetch account transactions](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/fetch-account-transactions): Retrieve paginated transactions.
- [Revoke account access](https://docs.paywithatoa.co.uk/api-reference/account-initiation-services/revoke-account-access): Revoke access to accounts or a session.
### Institutions
- [List institutions](https://docs.paywithatoa.co.uk/api-reference/institutions/institutions-controller): List supported banking institutions.
### Webhooks
- [Webhook introduction](https://docs.paywithatoa.co.uk/api-reference/webhook/introduction): How Atoa notifies your server of payment and refund status changes.
- [Create webhook](https://docs.paywithatoa.co.uk/api-reference/webhook/create-webhook-event): Register a webhook endpoint (OAuth 2.0 or Basic Auth).
- [List merchant webhooks](https://docs.paywithatoa.co.uk/api-reference/webhook/get-all-merchant-webhooks): List registered webhook endpoints.
- [Delete webhook](https://docs.paywithatoa.co.uk/api-reference/webhook/delete-webhook-event): Remove a webhook endpoint.
- [Payment webhook payload](https://docs.paywithatoa.co.uk/api-reference/webhook/process-payment-webhook-response): Shape of the payment-status webhook body.
## Notes for AI agents
- Read the auth token from the environment as `ATOA_AUTH_TOKEN` (or send it as an `Authorization: Bearer` header for HTTP MCP). Never run `atoa login` in an automated or headless context and never request or store a raw token — a human creates keys once in the dashboard or via `atoa login` in a browser.
- Sandbox and production credentials are not interchangeable; match the token to `X-Atoa-Env` / `ATOA_ENV`.
- Amounts are in pounds (e.g. `10.50` = £10.50), not pence, on the typed API and CLI. `charge_saved_card` returns `AUTHORIZED` first; final settlement is asynchronous — use webhooks or poll get payment status.