{"_id":"@atoapayments/agent-pay","_rev":"4-f6f32bfbebb5ab6d3b0e0da50f67b3fb","name":"@atoapayments/agent-pay","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@atoapayments/agent-pay","version":"0.0.1","keywords":["agent-pay","agentic-payments","ai-agents","payments","sdk","mcp","ap2","jws","fintech"],"author":{"name":"Atoa and contributors"},"license":"UNLICENSED","_id":"@atoapayments/agent-pay@0.0.1","maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"homepage":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/tree/main/packages/agent-pay/typescript#readme","bugs":{"url":"https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework/issues"},"dist":{"shasum":"0fa940573bf00d21388e7d63b166b87e2d326f53","tarball":"https://registry.npmjs.org/@atoapayments/agent-pay/-/agent-pay-0.0.1.tgz","fileCount":7,"integrity":"sha512-gwbcY5OPHEzUzcMy5Gk3VLZ0CTQtMw5q/gWla9YM/sJA06kZQZ34FuKfHbw3YLVV9nkpCV5YhQJZVi6JrvCcSw==","signatures":[{"sig":"MEQCIBIsRGMQXlA9mwcIQANiHeBbwOs5GRB2D+0yIJZnDmSiAiBd+YaGtcYnf7X2aKIwwnAkpzcNhlgL+1YJ50h0NNzhmQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":290070},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"ce0e27b75a7564f2f37842bfc9612623e7bebf0d","private":false,"scripts":{"test":"node --test test/*.test.ts","build":"tsup","typecheck":"tsc --noEmit","conformance:gen":"npx tsx ../conformance/generate-vectors.ts","conformance:verify-py":"npx tsx ../conformance/verify-python-sigs.ts"},"_npmUser":{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},"repository":{"url":"git+https://github.com/ATOAPaymentsLimited/AtoaAgenticFramework.git","type":"git","directory":"packages/agent-pay/typescript"},"_npmVersion":"11.16.0","description":"The ergonomic, standalone SDK for agentic payments: embed payments in your product, or give your AI agent a payment tool, under a signed, capped, payee-scoped contract over HTTP. Three nouns — agent, contract, payment.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^7.0.2","zod":"^4.4.3","@ai-sdk/openai":"^4.0.0","@ai-sdk/anthropic":"^4.0.0","@anthropic-ai/claude-agent-sdk":"^0.3.193"},"_npmOperationalInternal":{"tmp":"tmp/agent-pay_0.0.1_1785245790813_0.12888276802732235","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@atoapayments/agent-pay","version":"0.0.2","keywords":["agent-pay","agentic-payments","ai-agents","payments","sdk","mcp","ap2","jws","fintech"],"author":{"name":"Atoa Payments Limited"},"license":"MIT","_id":"@atoapayments/agent-pay@0.0.2","maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"homepage":"https://docs.paywithatoa.co.uk/agent-pay/overview","dist":{"shasum":"92b970dbae5bfc1c0a0258bb2b1648faa743817a","tarball":"https://registry.npmjs.org/@atoapayments/agent-pay/-/agent-pay-0.0.2.tgz","fileCount":9,"integrity":"sha512-pk2LSqsRCn+/XHZ62diklB3SgAbBNMl1Rtdt2oSNf+FmtxBlbY32efV0R/y6myDBFLTIUFbBknVnp8Qk/mHvQg==","signatures":[{"sig":"MEQCIHcfBZbt8fOXiP+nRpeiO6zyZWAQUgHX87i8tgtjgYUwAiANqXYFbknisOAN8WjI6ZaHpxNbs7JGwPMhMPVWXYBKTA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":294033},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"6d992b974e4c6903cbe5258028f75c5236d9ef47","private":false,"scripts":{"test":"node --test test/*.test.ts","build":"tsup","typecheck":"tsc --noEmit","conformance:gen":"npx tsx ../conformance/generate-vectors.ts","conformance:verify-py":"npx tsx ../conformance/verify-python-sigs.ts"},"_npmUser":{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},"_npmVersion":"11.16.0","description":"The ergonomic, standalone SDK for agentic payments: embed payments in your product, or give your AI agent a payment tool, under a signed, capped, payee-scoped contract over HTTP. Three nouns — agent, contract, payment.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^7.0.2","zod":"^4.4.3","@ai-sdk/openai":"^4.0.0","@ai-sdk/anthropic":"^4.0.0","@anthropic-ai/claude-agent-sdk":"^0.3.193"},"_npmOperationalInternal":{"tmp":"tmp/agent-pay_0.0.2_1785902618757_0.4814380469470054","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@atoapayments/agent-pay","version":"0.0.3","keywords":["agent-pay","agentic-payments","ai-agents","payments","sdk","mcp","ap2","jws","fintech"],"author":{"name":"Atoa Payments Limited"},"license":"MIT","_id":"@atoapayments/agent-pay@0.0.3","maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"homepage":"https://docs.paywithatoa.co.uk/agent-pay/overview","dist":{"shasum":"6bd051014e4ad61119b7c9b77d573734d6657c18","tarball":"https://registry.npmjs.org/@atoapayments/agent-pay/-/agent-pay-0.0.3.tgz","fileCount":9,"integrity":"sha512-mmLUuYm9ihkoC+QO1DMjhbKGViDaKc8lpjtGc7yS+xCiTSX2vIN6ogV3Da2ipMBgYhVnNohgG9wm7rd4Z9KEFw==","signatures":[{"sig":"MEUCIQCkbZVaAn+FW360Qc7sE7DszlJdXuFwRS25pC0621GuTwIgLOGigoFi4V3jYtGAHH/ES3baB+KD1FQCIYwaqD+Kt88=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":308546},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"a2226a49ec577365013453ed6f79feea5ba5ab1f","private":false,"scripts":{"test":"node --test test/*.test.ts","build":"tsup","typecheck":"tsc --noEmit","conformance:gen":"npx tsx ../conformance/generate-vectors.ts","conformance:verify-py":"npx tsx ../conformance/verify-python-sigs.ts"},"_npmUser":{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},"_npmVersion":"11.16.0","description":"The ergonomic, standalone SDK for agentic payments: embed payments in your product, or give your AI agent a payment tool, under a signed, capped, payee-scoped contract over HTTP. Three nouns — agent, contract, payment.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^7.0.2","zod":"^4.4.3","@ai-sdk/openai":"^4.0.0","@ai-sdk/anthropic":"^4.0.0","@anthropic-ai/claude-agent-sdk":"^0.3.193"},"_npmOperationalInternal":{"tmp":"tmp/agent-pay_0.0.3_1786077177020_0.032028038064500164","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@atoapayments/agent-pay","version":"0.0.4","private":false,"type":"module","description":"The ergonomic, standalone SDK for agentic payments: embed payments in your product, or give your AI agent a payment tool, under a signed, capped, payee-scoped contract over HTTP. Three nouns — agent, contract, payment.","keywords":["agent-pay","agentic-payments","ai-agents","payments","sdk","mcp","ap2","jws","fintech"],"homepage":"https://docs.paywithatoa.co.uk/agent-pay/overview","author":{"name":"Atoa Payments Limited"},"license":"MIT","engines":{"node":">=22"},"sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./ui":{"types":"./dist/ui.d.ts","import":"./dist/ui.js","require":"./dist/ui.cjs"},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","test":"node --test test/*.test.ts","typecheck":"tsc --noEmit","conformance:gen":"npx tsx ../conformance/generate-vectors.ts","conformance:verify-py":"npx tsx ../conformance/verify-python-sigs.ts"},"devDependencies":{"@ai-sdk/anthropic":"^4.0.0","@ai-sdk/openai":"^4.0.0","@anthropic-ai/claude-agent-sdk":"^0.3.193","ai":"^7.0.2","zod":"^4.4.3","@atoapayments/pay-embed":"*"},"peerDependencies":{"@atoapayments/pay-embed":">=0.0.1 <0.2.0"},"peerDependenciesMeta":{"@atoapayments/pay-embed":{"optional":true}},"gitHead":"7b2d5d12976b92eea65eb45932badc2729ed5936","_id":"@atoapayments/agent-pay@0.0.4","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-LGO+gfuBwxo8gf3X6cJpCqswGuwp4vYBiSzasS9apak1vSjMjCnZQqi3BJgg2kzOyDVELh3fuwlG5o80wVjdWA==","shasum":"c20828cd35798f3847d2c7493b8999b093901b84","tarball":"https://registry.npmjs.org/@atoapayments/agent-pay/-/agent-pay-0.0.4.tgz","fileCount":13,"unpackedSize":364933,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDWGZmBzhFguP7IYgXJz+O99OokyhRZ//gm+E0zBdPp7QIgGdQj5fMvky3aDaUcj+TYu5FVe1U7sDg/uwKGTFaDMcc="}]},"_npmUser":{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},"directories":{},"maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-pay_0.0.4_1787653777981_0.9182649019625826"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T13:36:30.668Z","modified":"2026-08-25T10:29:38.313Z","0.0.1":"2026-07-28T13:36:30.976Z","0.0.2":"2026-08-05T04:03:38.924Z","0.0.3":"2026-08-07T04:32:57.194Z","0.0.4":"2026-08-25T10:29:38.149Z"},"author":{"name":"Atoa Payments Limited"},"license":"MIT","homepage":"https://docs.paywithatoa.co.uk/agent-pay/overview","keywords":["agent-pay","agentic-payments","ai-agents","payments","sdk","mcp","ap2","jws","fintech"],"description":"The ergonomic, standalone SDK for agentic payments: embed payments in your product, or give your AI agent a payment tool, under a signed, capped, payee-scoped contract over HTTP. Three nouns — agent, contract, payment.","maintainers":[{"name":"shariqueatoa","email":"sharique@paywithatoa.co.uk"},{"name":"rvkrish","email":"vamsi@paywithatoa.co.uk"},{"name":"tushargupta224","email":"tushar@paywithatoa.co.uk"},{"name":"atoalicence","email":"licence@paywithatoa.co.uk"},{"name":"anandtanu","email":"tanushree@paywithatoa.co.uk"}],"readme":"# @atoapayments/agent-pay\n\n**The ergonomic, standalone SDK for agentic payments — move money in both directions from your backend or your AI agent, over HTTP, in a few lines.** Collect from your customers (a pay-link/QR, or an off-session charge under a contract they authorized) and send to bank accounts under signed, capped contracts that Atoa enforces server-side. Every request is signed for you.\n\n[![npm version](https://img.shields.io/npm/v/@atoapayments/agent-pay.svg)](https://www.npmjs.com/package/@atoapayments/agent-pay)\n[![node](https://img.shields.io/node/v/@atoapayments/agent-pay.svg)](https://www.npmjs.com/package/@atoapayments/agent-pay)\n[![types](https://img.shields.io/badge/types-included-blue.svg)](https://www.npmjs.com/package/@atoapayments/agent-pay)\n![license](https://img.shields.io/badge/license-MIT-green.svg)\n\n`@atoapayments/agent-pay` is a small client for [Atoa](https://paywithatoa.co.uk) that lets a program — an AI agent, or an ordinary backend job — collect and send real money. It is HTTP-only, has **zero runtime dependencies** (the crypto is `node:crypto`), ships full TypeScript types, and signs every request with a per-request ES256 signature. A business outcome (a payment that fails or is rejected) comes back as a returned value you branch on; only operational faults throw. A byte-compatible [Python sibling](https://pypi.org/project/atoa-agent-pay/) exists — both produce byte-identical signed wire artifacts and hit the same backend interchangeably.\n\n## Install\n\n```bash\nnpm install @atoapayments/agent-pay\n```\n\nRequires Node 22+ (see the badge for the exact floor). ESM + CJS builds and `.d.ts` are included.\n\n## Quickstart\n\nYou need an API key from the [Atoa dashboard](https://dashboard.paywithatoa.co.uk/) (the key selects the environment; it defaults to the `ATOA_API_KEY` env var). `apiUrl` is optional — the SDK targets the right host for the `environment`.\n\n```ts\nimport { createAgentPayClient, generateEs256KeyPair } from '@atoapayments/agent-pay';\n\nconst { privateKeyPem } = generateEs256KeyPair();       // prod: load a PEM from your secrets manager, or sign in your KMS\nconst atoa = createAgentPayClient({ environment: 'sandbox', privateKeyPem });\nawait atoa.agent.register({ name: 'Bookings assistant' }); // idempotent; name required\n\n// ── collect — money IN (customer present, no contract) ──\nconst req = await atoa.payment.collect({ amount: { amount: 45.0 }, orderId: 'booking-8812' });\nconsole.log(req.paymentUrl);                             // give the customer this link (or req.qrCodeUrl)\nconsole.log((await atoa.payment.awaitSettled(req.paymentRequestId)).status); // 'COMPLETED'\n\n// ── send — money OUT (under a capped contract) ──\nconst contract = await atoa.contract.create({\n  name: 'Supplier payouts',\n  limits: { maxPerPayment: 50.0, periodLimits: [{ amount: 500.0, period: 'MONTH' }], validTo: '2026-12-31T23:59:59Z' },\n});\nawait atoa.contract.awaitActive(contract.contractId);    // resolves once the account holder authorizes at their bank (sandbox: the Atoa Test Bank)\nconst [payment] = await atoa.payment.send({\n  contractId: contract.contractId,                       // contract once; payments is always an array\n  payments: [{ amount: { amount: 12.5 }, beneficiary: { name: 'ACME LTD', sortCode: '040004', accountNumber: '12345678' }, orderId: 'order-9281' }],\n});\nif (payment.paymentIdempotencyId) {\n  console.log((await atoa.payment.awaitSettled(payment.paymentIdempotencyId)).status); // 'COMPLETED'\n} else {\n  console.log('refused:', payment.failureReason, '-', payment.failureReasonDescription);\n}\n```\n\nMoney in is a grouped `Amount` in **DECIMAL major units** (`{ amount: 12.50, currency: 'GBP' }`, never `1250`; `currency` defaults to GBP). Money you read back on a `Payment` is flat (`paidAmount` + `currency`). There are no webhooks — you poll (`get` / `list` / `awaitSettled`).\n\n## Documentation\n\nThe public docs are the source of truth for naming and behaviour:\n\n- **Overview** — https://docs.paywithatoa.co.uk/agent-pay/overview\n- **Collect (money in)** — https://docs.paywithatoa.co.uk/agent-pay/collect · [off-session charges](https://docs.paywithatoa.co.uk/agent-pay/collect#off-session) · [SCA on a charge](https://docs.paywithatoa.co.uk/agent-pay/collect#sca-on-a-charge)\n- **Send (money out)** — https://docs.paywithatoa.co.uk/agent-pay/send · [SCA on a payout](https://docs.paywithatoa.co.uk/agent-pay/send#sca-on-a-payout)\n- **AI agents & tools** — https://docs.paywithatoa.co.uk/agent-pay/ai-agents\n- **Reference** (methods, types, errors, auth) — https://docs.paywithatoa.co.uk/agent-pay/reference · [Authentication](https://docs.paywithatoa.co.uk/agent-pay/reference#authentication) · [KMS / custom signer](https://docs.paywithatoa.co.uk/agent-pay/reference#kms-custom-signer)\n- **Sandbox guide** — https://docs.paywithatoa.co.uk/atoa-sandbox · **Go-live checklist** — https://docs.paywithatoa.co.uk/go-live\n- **Runnable notebook** — https://atoa-pdf.s3.eu-west-2.amazonaws.com/developer-guide.ipynb\n\n## Core concepts\n\nThree routes cover everything ([Overview](https://docs.paywithatoa.co.uk/agent-pay/overview)):\n\n- **Customer present** — `payment.collect({ amount, orderId })` returns a `paymentUrl` + `qrCodeUrl`; the customer picks their bank or card on Atoa's page. No contract.\n- **Customer not present** — `payment.collect({ amount, orderId, contractId, atoaCustomerId })` charges a **COLLECT** contract the customer authorized earlier. See [off-session charges](https://docs.paywithatoa.co.uk/agent-pay/collect#off-session).\n- **Paying out** — `payment.send({ contractId, payments })` moves money under a **SEND** contract the account holder authorized once at their bank. See [Send](https://docs.paywithatoa.co.uk/agent-pay/send).\n\nA **contract** is a limited, revocable authority bounded by a per-payment cap, one or more period caps, and an end date (`validTo`); Atoa enforces the caps server-side. Contracts are AP2-aligned mandates. A gated `send` or off-session `collect` can pause for **Strong Customer Authentication (SCA)** — see the SCA gate below. The full mental model (the five nouns, who approves what, keys & signing) is in the [monorepo overview](https://docs.paywithatoa.co.uk/agent-pay/overview) and [CONCEPTS](https://docs.paywithatoa.co.uk/agent-pay/overview).\n\n## API reference\n\n`createAgentPayClient(config) → AgentPayClient`, where `config` is `{ environment, apiUrl?, apiKey?, privateKeyPem? | keyStore? | signer?, clock?, fetchImpl? }`. Client members: `atoa.agentId`, `atoa.environment`, `atoa.apiUrl`, `atoa.checkAvailability()`, `atoa.sandboxTestAccounts()`.\n\nFive namespaces:\n\n| Namespace | Methods |\n|---|---|\n| `atoa.agent` | `register({ name, description?, agentId?, publicKeyPem? })` (idempotent; `name` required) · `me()` |\n| `atoa.contract` | `create({ type?, atoaCustomerId?, name, description?, limits, initialCharge? })` · `get(id)` · `list(opts?)` · `listAll(opts?)` · `awaitActive(id, opts?)` · `update(id, input)` · `revoke(id)` |\n| `atoa.payment` | `collect(input)` · `send(input)` · `get(id)` · `list(opts?)` · `listAll(opts?)` · `awaitSettled(id, opts?)` · `cancel(paymentRequestId)` · `refund(paymentRequestId, input)` · `listRefunds(paymentRequestId)` · `cancelRefund(refundId)` · `awaitDecision(approvalId, opts?)` · `cancelApproval(contractId, approvalId)` |\n| `atoa.customer` | `create(input)` · `get(id)` · `list(opts?)` · `update(id, input)` · `delete(id)` |\n| `atoa.store` | `list(opts?)` |\n\nNotes worth knowing before the [full reference](https://docs.paywithatoa.co.uk/agent-pay/reference):\n\n- **`collect(input) → PaymentRequest`.** Default (no `contractId`): a `paymentUrl` + `qrCodeUrl`. With `contractId` (+ `atoaCustomerId`): an off-session charge against a COLLECT contract. Not idempotent — the `paymentRequestId` is the source of truth.\n- **`send(input) → SendResult`.** `input` is `{ contractId, payments: [...] }`; `payments` is **always an array** (1–20 per call). `SendResult` is a `Payment[]` (destructure it, `Array.isArray` works) with an optional `.nextAction` attached when the SCA gate is on.\n- **`contract.revoke(id) → ContractRevokeResult`** returns a confirmation `{ ... }`, not `void`. Later sends/charges against a revoked contract are rejected.\n- **`awaitActive` / `awaitSettled` / `awaitDecision`** poll (no webhooks) and throw `AuthorizationTimeoutError` / `SettlementTimeoutError` on timeout.\n\n### The one `Payment` shape (both directions)\n\n```ts\ninterface Payment {\n  type: 'DEBIT' | 'CREDIT';            // money out (send) | money in (collect) — a collect flips to DEBIT once REFUNDED/PARTIALLY_REFUNDED or disputed\n  status: 'AWAITING_AUTHORIZATION' | 'PENDING' | 'AUTHORIZED' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'EXPIRED'\n        | 'REFUNDED' | 'PARTIALLY_REFUNDED' | 'DISPUTE_RAISED' | 'DISPUTE_WON' | 'DISPUTE_LOST';\n  paidAmount: number;                  // money is FLAT on reads (inputs are grouped Amounts)\n  currency: string;\n  orderId: string;\n  createdAt: string;\n  paymentIdempotencyId: string | null; // the settlement-attempt id (ATOA...); null until an attempt exists\n  agentId: string;\n  businessId: string;\n  failureReason?: PaymentFailureReason;   // on a terminal FAILED/CANCELLED\n  failureReasonDescription?: string;      // always-present human detail\n  contractId?: string;                    // DEBIT (send) only\n  beneficiary?: PartyAccount;             // DEBIT only, masked\n  paymentRequestId?: string;              // CREDIT (collect) only\n  customerId?: string;                    // CREDIT only\n}\n```\n\n`COMPLETED` is the settled terminal (there is no `SETTLED`). Branch on `status`, then on `failureReason`. Full status + reason tables and retry rules: [ERRORS](https://docs.paywithatoa.co.uk/agent-pay/reference).\n\n### The SCA gate (`nextAction`)\n\nA gated `send` or off-session `collect` returns a `nextAction` of shape `{ approvalId, clientSecret, approvalUrl }`. A human approves on Atoa's hosted page. Either hand them the `approvalUrl`, or embed the page in your own web UI with the browser companion [`@atoapayments/agentic-payment-approvals-js`](https://www.npmjs.com/package/@atoapayments/agentic-payment-approvals-js) using `clientSecret`. Then poll `atoa.payment.awaitDecision(nextAction.approvalId)` (or `atoa.payment.cancelApproval(contractId, approvalId)`). See [SCA on a payout](https://docs.paywithatoa.co.uk/agent-pay/send#sca-on-a-payout) and [SCA on a charge](https://docs.paywithatoa.co.uk/agent-pay/collect#sca-on-a-charge).\n\n### Charge on approval (COLLECT)\n\nA COLLECT contract can bundle a **first charge into the customer's single approval** — one page both activates the contract *and* takes that payment, so you don't call `collect` separately for charge #1 (a deposit, a first bill). Pass `initialCharge` to `contract.create`:\n\n```ts\nconst contract = await atoa.contract.create({\n  type: 'COLLECT',\n  atoaCustomerId,                                        // from atoa.customer.create(...)\n  name: 'Gym membership',\n  limits: { maxPerPayment: 50.0, periodLimits: [{ amount: 50.0, period: 'MONTH' }], validTo: '2027-01-31T23:59:59Z' },\n  initialCharge: {\n    amount: 25.0,            // plain decimal, ≥ £1 and ≤ maxPerPayment\n    orderId: 'joining-1001', // your reference (≤ 50 chars)\n    notes: 'Joining fee',    // optional (≤ 30 chars)\n    // storeId?: '…'          // optional — attribute to a store (defaults to your primary); its name/logo shows on the customer's page\n  },\n});\n\n// The customer approves ONCE at contract.authorizationUrl — that approval activates the contract AND takes the charge.\nawait atoa.contract.awaitActive(contract.contractId);\nconst c = await atoa.contract.get(contract.contractId);\nc.initialCharge?.status; // AWAITING_APPROVAL → PENDING → COMPLETED | FAILED | INITIATION_FAILED\n```\n\nThe outcome rides the contract view as `initialCharge` (with a pollable `paymentRequestId` → `payment.get`). Only fall back to `collect` for the first charge when the contract was created **without** an `initialCharge`.\n\n## Give the tools to an AI agent\n\n`createAgentPayTools(client)` returns the canonical, self-describing tool definitions (the 23-tool `AGENT_PAY_TOOLS` set) plus a `call` dispatcher. Hand `tools` to any LLM runtime and route each tool call to `await call(name, args)`:\n\n```ts\nimport { createAgentPayClient, createAgentPayTools } from '@atoapayments/agent-pay';\n\nconst atoa = createAgentPayClient({ environment: 'sandbox', privateKeyPem });\nconst { tools, call } = createAgentPayTools(atoa);\n// advertise `tools` to your model; route each tool call to `await call(name, args)`\n```\n\nPrefer zero code? Atoa ships a hosted MCP server (a superset of these tools) for Claude Desktop / Cursor — see [AI agents & tools](https://docs.paywithatoa.co.uk/agent-pay/ai-agents) and the [MCP server docs](https://docs.paywithatoa.co.uk/mcp-server).\n\n## Errors\n\nEvery **operational** fault is a typed `AgentPayError` subclass with a stable `code` — branch on `err.code` or `instanceof`, never on the message. **Business** outcomes (name mismatch, cap exceeded, settlement failed, customer cancelled) come back as a `FAILED`/`CANCELLED` `Payment` with a `failureReason` instead.\n\n| Class | When |\n|---|---|\n| `AuthError` | 401/403 from the service |\n| `ValidationError` | 400/422 invalid request (missing `name`/`validTo`, bad amount, empty `payments`, incompatible options) |\n| `NotFoundError` | 404 unknown/not-owned id |\n| `ConflictError` | 409 re-registering an agent id with a different key/env/business |\n| `RateLimitError` | 429 rate limited |\n| `NetworkError` | transport / non-mapped HTTP fault |\n| `RegistrationError` | register handshake failure (e.g. signing before register) |\n| `AuthorizationTimeoutError` / `AuthorizationFailedError` | `contract.awaitActive` timed out / user declined |\n| `SettlementTimeoutError` | `payment.awaitSettled` / `awaitDecision` timed out |\n| `KeyNotFoundError` | no signing key for the id |\n\nThere is also a first-class contract-charge \"ladder\" (`ContractNotActiveError`, `CapExceededError`, `NoPaymentMethodError`, …). Full model, tables, and retry rules: [Reference](https://docs.paywithatoa.co.uk/agent-pay/reference) and [ERRORS](https://docs.paywithatoa.co.uk/agent-pay/reference).\n\n## Authentication, keys & sandbox\n\nTwo credentials ride on every request: your **API key** (from the [dashboard](https://dashboard.paywithatoa.co.uk/); pins the environment) and a per-request **ES256 signature** from your agent's key. The client never touches a raw private key unless you hand one in — pass a `privateKeyPem`, a `keyStore` (e.g. `createInMemoryKeyStore()` for dev), or a `signer` you supply so the key never enters your process (KMS/HSM). `createHttpTransport` is exported for advanced integrators who want the wire contract directly.\n\n- **Auth & signing:** https://docs.paywithatoa.co.uk/agent-pay/reference#authentication\n- **KMS / custom signer:** https://docs.paywithatoa.co.uk/agent-pay/reference#kms-custom-signer\n- **Sandbox (test accounts, forcing outcomes):** https://docs.paywithatoa.co.uk/atoa-sandbox\n\n## Related packages\n\n- **Python sibling** — same SDK, byte-identical wire artifacts: [`atoa-agent-pay`](https://pypi.org/project/atoa-agent-pay/) (`pip install atoa-agent-pay`).\n- **Browser approvals** — embed the hosted SCA approval page in your own web UI: [`@atoapayments/agentic-payment-approvals-js`](https://www.npmjs.com/package/@atoapayments/agentic-payment-approvals-js).\n- **Monorepo & guides** — https://docs.paywithatoa.co.uk/agent-pay/overview\n\n## License\n\n**License.** MIT. This covers the code in this package.\n\n**Service terms.** Use of the Atoa API is governed by the Atoa Services Agreement: https://paywithatoa.co.uk/terms/. The MIT license applies to this SDK only and grants no rights to the Atoa service.\n\n**Trademarks.** \"Atoa\" and the Atoa logo are trademarks of Atoa Payments Limited. The MIT license grants rights in the code, not in our names or marks — a modified or redistributed copy must not be presented as an Atoa product.\n\n**Security.** Report vulnerabilities to hello@paywithatoa.co.uk — please do not open a public issue.\n","readmeFilename":"README.md"}