{"_id":"@agentaos/pay","_rev":"6-6a88479975f178d3c37c7018a3bce739","name":"@agentaos/pay","dist-tags":{"latest":"2.3.0"},"versions":{"1.0.0":{"name":"@agentaos/pay","version":"1.0.0","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","_id":"@agentaos/pay@1.0.0","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"homepage":"https://github.com/AgentaOS/agentaos#readme","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"7a8894c880321772be754ef559737c7e35ad3dc2","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-1.0.0.tgz","fileCount":51,"integrity":"sha512-awkJIPDO346VGSHOQ7rw/OvrmUhK0FAlZ+w3u1ZvYsl/tQ9bZg554RrZLwC+kZQE36BYCIlvuCpoKuZBrwxDSg==","signatures":[{"sig":"MEUCIA1mFzdkb0MMw3B4gDFuyCt6f16KucMWnSWnKcwH2yj3AiEAhJGM0xfDwvRytgSwyqG/rLUmf3BipYDnLz8M5JWgHXM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93023},"main":"./dist/index.js","type":"module","_from":"file:agentaos-pay-1.0.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"_resolved":"/tmp/6a00063574485fab0dc3e1df8c80cf7a/agentaos-pay-1.0.0.tgz","_integrity":"sha512-awkJIPDO346VGSHOQ7rw/OvrmUhK0FAlZ+w3u1ZvYsl/tQ9bZg554RrZLwC+kZQE36BYCIlvuCpoKuZBrwxDSg==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.4","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pay_1.0.0_1773833588892_0.15308008281607077","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@agentaos/pay","version":"1.0.1","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","_id":"@agentaos/pay@1.0.1","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"homepage":"https://github.com/AgentaOS/agentaos#readme","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"cc5e68b6807667a09fe35507fb0613a9c53fd34d","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-1.0.1.tgz","fileCount":51,"integrity":"sha512-9fdjNpwT0iXSjyAGkpqY5F7iEG2E0hID1Dy9U0N7OipSPSetGr1hYuzP6HKrZTOXitHDB9HD4vc6QAqKwHaKkw==","signatures":[{"sig":"MEUCIBgEbTwR05Wj+eZO9DRQ5EwT5o6is0LbAirfEj+ZZxd8AiEA4DjXN2f/qC/thNrssK6s6+VAmKKAGz9Wmubawx3m+iM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95079},"main":"./dist/index.js","type":"module","_from":"file:agentaos-pay-1.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"_resolved":"/tmp/d9fff4959fb2d56f16b87544a5d07cb6/agentaos-pay-1.0.1.tgz","_integrity":"sha512-9fdjNpwT0iXSjyAGkpqY5F7iEG2E0hID1Dy9U0N7OipSPSetGr1hYuzP6HKrZTOXitHDB9HD4vc6QAqKwHaKkw==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.4","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pay_1.0.1_1774482546568_0.920337620492121","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@agentaos/pay","version":"2.0.0","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","_id":"@agentaos/pay@2.0.0","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"homepage":"https://github.com/AgentaOS/agentaos#readme","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"c4ffc4dbd51768a92ddff393ee75a0a4a4f70ceb","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-2.0.0.tgz","fileCount":59,"integrity":"sha512-xnp7mpUzD3PUGTyb35Fgoc+xWZgLZQZpwELd1am1RBm9OaaQwyyhnzFNb+N6P5rP/HdmgMlV8CQJGRcYrjZWEQ==","signatures":[{"sig":"MEUCIGRPpQsJw2QQZBtWaAQaNMnyXYaRY1Svb0J1Tl2Cl+47AiEAzzPKckla492Ge9gWa3Xt5w4u+Omvcluz4Xg0QuEZLnM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111996},"main":"./dist/index.js","type":"module","_from":"file:agentaos-pay-2.0.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"_resolved":"/tmp/1eee8eb0f0fb889c815b1ec70da1fbfc/agentaos-pay-2.0.0.tgz","_integrity":"sha512-xnp7mpUzD3PUGTyb35Fgoc+xWZgLZQZpwELd1am1RBm9OaaQwyyhnzFNb+N6P5rP/HdmgMlV8CQJGRcYrjZWEQ==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.8","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pay_2.0.0_1786455858372_0.2966269137631252","host":"s3://npm-registry-packages-npm-production"}},"2.1.0":{"name":"@agentaos/pay","version":"2.1.0","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","_id":"@agentaos/pay@2.1.0","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"homepage":"https://github.com/AgentaOS/agentaos#readme","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"e5b40a64050debdb2392c7216530e98439a000ef","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-2.1.0.tgz","fileCount":59,"integrity":"sha512-4ezZ/GhW707AxYSIjFOWeVXbrbB2vesF4HlJCuRGHvzesuY0nJEoFSjD7PmCesVgsTT8DhL7avrSC7E/AGRgdQ==","signatures":[{"sig":"MEUCIGjHJxg8Qm5iadDJm19jxAMtVnCPZfi2kju/hOuLjhhvAiEAqmIMb6ORloSBunin9JaWfK7jrv2vBwWdfc3TzJQmvg4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113008},"main":"./dist/index.js","type":"module","_from":"file:agentaos-pay-2.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"_resolved":"/tmp/9a5e4fb19c97ca577deeb2bfaa12ef29/agentaos-pay-2.1.0.tgz","_integrity":"sha512-4ezZ/GhW707AxYSIjFOWeVXbrbB2vesF4HlJCuRGHvzesuY0nJEoFSjD7PmCesVgsTT8DhL7avrSC7E/AGRgdQ==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.8","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pay_2.1.0_1786551212017_0.6380681054044868","host":"s3://npm-registry-packages-npm-production"}},"2.2.0":{"name":"@agentaos/pay","version":"2.2.0","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","_id":"@agentaos/pay@2.2.0","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"homepage":"https://github.com/AgentaOS/agentaos#readme","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"d415b8e547f2486ec7bd99a31be48df648894fd0","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-2.2.0.tgz","fileCount":59,"integrity":"sha512-DbTSTyIjPYMwYKhS97lH68iCoSHDuFLMLX8ULxqWz1nb6Pev2ftLQxJaYwcLrGciM23wes0FhiwcuPN/IwHrcg==","signatures":[{"sig":"MEUCIE36rR/ngKiP+OpX9wakeUE8ND0fumskCrKAyNmRaorBAiEA32U1hBRUuDJTNu03Izszpe8HCph6GncQx7HE6UzFYhU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIExBT+oMXt4dazu+94ehPE5hZHyAPMwZqQ4cBpExm9KyAiAtv0nE/tAs5kAjRrJLrVO4dexrxKqFSz+PUKYDDPTZVw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125275},"main":"./dist/index.js","type":"module","_from":"file:agentaos-pay-2.2.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"_resolved":"/tmp/eea8746af27532dfaf8706e14766889f/agentaos-pay-2.2.0.tgz","_integrity":"sha512-DbTSTyIjPYMwYKhS97lH68iCoSHDuFLMLX8ULxqWz1nb6Pev2ftLQxJaYwcLrGciM23wes0FhiwcuPN/IwHrcg==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.8","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pay_2.2.0_1788968222012_0.5549428566055847","host":"s3://npm-registry-packages-npm-production"}},"2.3.0":{"_id":"@agentaos/pay@2.3.0","bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"dist":{"shasum":"c3b4b723a539eab963f6bbfe18f70c4d178221fd","tarball":"https://registry.npmjs.org/@agentaos/pay/-/pay-2.3.0.tgz","fileCount":67,"integrity":"sha512-HgcnJR+j9NDzeZIxi02f5mGen0m+ClMBB2y6llQ1MQ/3VzAXy0MKeKcHHQVUTNlytRJl0Ntq7ksloFeoAQlojQ==","signatures":[{"sig":"MEUCIQCeUIdcpiGVBBC/LS4CbPN1abFvvc52BDwIyjoX6Gs3+wIgKHOnu6UfLsDR9dgjw7FfShjlQMDjP/0NHFCUHGgnj8k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHtvsrEFTKS+cc7kUThm3ht3H6jcTqvmj1VVjE44g7BlAiEAj5eqp/p7zaFC6p5GYvq9IOQu/hyCCk17JzdMbKm9j/8="}],"unpackedSize":144312},"main":"./dist/index.js","name":"@agentaos/pay","type":"module","_from":"file:agentaos-pay-2.3.0.tgz","types":"./dist/index.d.ts","author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"license":"Apache-2.0","scripts":{"lint":"biome check src/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"version":"2.3.0","_npmUser":{"name":"panche","email":"panche@agentokratia.com"},"homepage":"https://github.com/AgentaOS/agentaos#readme","_resolved":"/tmp/256cf2c1598d61df8ecfcca6c8064359/agentaos-pay-2.3.0.tgz","_integrity":"sha512-HgcnJR+j9NDzeZIxi02f5mGen0m+ClMBB2y6llQ1MQ/3VzAXy0MKeKcHHQVUTNlytRJl0Ntq7ksloFeoAQlojQ==","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"_npmVersion":"10.9.8","description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","directories":{},"maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/node":"^20.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pay_2.3.0_1788975643039_0.9575957976906686"}}},"time":{"created":"2026-03-18T11:33:08.743Z","modified":"2026-09-09T17:40:43.478Z","1.0.0":"2026-03-18T11:33:09.064Z","1.0.1":"2026-03-25T23:49:06.720Z","2.0.0":"2026-08-11T13:44:18.527Z","2.1.0":"2026-08-12T16:13:32.194Z","2.2.0":"2026-09-09T15:37:02.126Z","2.3.0":"2026-09-09T17:40:43.117Z"},"bugs":{"url":"https://github.com/AgentaOS/agentaos/issues"},"author":{"name":"AgentaOS","email":"hello@agentaos.ai"},"license":"Apache-2.0","homepage":"https://github.com/AgentaOS/agentaos#readme","repository":{"url":"git+https://github.com/AgentaOS/agentaos.git","type":"git","directory":"packages/pay"},"description":"AgentaOS Payment SDK — accept regulated stablecoin payments programmatically","maintainers":[{"name":"panche","email":"panche@agentokratia.com"}],"readme":"# @agentaos/pay\n\nAccept regulated stablecoin payments from your Node.js backend. Server-side SDK for the AgentaOS Payment API.\n\n## Install\n\n```bash\nnpm install @agentaos/pay\n```\n\n## Quick Start\n\n```typescript\nimport { AgentaOS } from '@agentaos/pay';\n\nconst agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!);\n\nconst checkout = await agentaos.checkouts.create({\n  amount: 49.99,\n  currency: 'EUR',\n  description: 'Pro Plan — Monthly',\n  successUrl: 'https://myshop.com/success',\n  cancelUrl: 'https://myshop.com/cart',\n  webhookUrl: 'https://myshop.com/webhooks',\n});\n\nconsole.log(checkout.checkoutUrl);\n// → https://app.agentaos.ai/checkout/mZrESFyR7RC9RPsJfZCVkg\n```\n\n## Authentication\n\nGet your API key from [app.agentaos.ai](https://app.agentaos.ai) → Developer → API Keys.\n\n```typescript\nconst agentaos = new AgentaOS('sk_live_...', {\n  baseUrl: 'https://api.agentaos.ai', // default\n  timeout: 30000,                      // ms, default\n  maxRetries: 2,                       // on 5xx, default\n  debug: false,                        // log requests to stderr\n});\n```\n\n> **Backend only** — never use this SDK in browser code. Your API key grants full access to all payments.\n\n---\n\n## Checkouts\n\nCreate a checkout session to collect a payment. The customer visits the `checkoutUrl` to pay.\n\n### `checkouts.create(params)`\n\n```typescript\nconst checkout = await agentaos.checkouts.create({\n  // --- Required (if no linkId) ---\n  amount: 100.00,           // Amount in currency units\n  currency: 'EUR',          // 'EUR' or 'USD'\n\n  // --- Optional: from a payment link template ---\n  linkId: 'uuid',           // Create session from existing link (inherits amount/currency)\n\n  // --- Optional: checkout config ---\n  description: 'Order #123',\n  successUrl: 'https://shop.com/success',    // Redirect after payment (HTTPS)\n  cancelUrl: 'https://shop.com/cart',        // \"Cancel\" link on checkout (HTTPS)\n  webhookUrl: 'https://shop.com/webhooks',   // Server notification on payment (HTTPS)\n  expiresIn: 1800,                           // Seconds until expiry (300-86400, default 1800)\n  taxRateId: 'uuid',                         // Pre-created tax rate UUID\n  dueDate: '2026-09-30',                     // Invoice due date (YYYY-MM-DD), presentation only\n\n  // --- Optional: pre-populate buyer info ---\n  buyerEmail: 'john@example.com',\n  buyerName: 'John Doe',\n  buyerCompany: 'Acme Corp',\n  buyerCountry: 'DE',                        // ISO 3166-1 alpha-2\n  buyerAddress: '123 Main St, Berlin',\n  buyerVat: 'DE123456789',\n\n  // --- Optional: custom data ---\n  metadata: { orderId: '12345', plan: 'pro' },\n});\n```\n\n**Response:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Session UUID |\n| `sessionId` | `string` | Public session ID (used in checkout URL) |\n| `checkoutUrl` | `string` | URL to send your human customer to |\n| `x402Url` | `string` | x402 protocol URL for AI agent payments |\n| `status` | `'open' \\| 'completed' \\| 'expired' \\| 'cancelled'` | Current status |\n| `sellerMode` | `'mor' \\| 'crypto'` | How this session settles |\n| `amountOverride` | `number \\| null` | Amount for this session |\n| `currency` | `string` | Settlement currency |\n| `invoiceId` | `string \\| null` | Issued invoice UUID (null until an invoice exists) |\n| `invoiceNumber` | `string \\| null` | Human-readable invoice number |\n| `expiresAt` | `string` | ISO 8601 expiration time |\n| `createdAt` | `string` | ISO 8601 creation time |\n\n### `checkouts.retrieve(sessionId)`\n\n```typescript\nconst checkout = await agentaos.checkouts.retrieve('mZrESFyR7RC9RPsJfZCVkg');\nconsole.log(checkout.status); // 'open' | 'completed' | 'expired' | 'cancelled'\n```\n\n### `checkouts.list(params?)`\n\n```typescript\nconst checkouts = await agentaos.checkouts.list({\n  status: 'completed',  // Filter: 'open' | 'completed' | 'expired' | 'cancelled'\n  limit: 10,\n  offset: 0,\n});\n```\n\n### `checkouts.cancel(sessionId)`\n\n```typescript\nawait agentaos.checkouts.cancel('mZrESFyR7RC9RPsJfZCVkg');\n```\n\n---\n\n## Payment Links\n\nReusable payment templates. Share the `checkoutUrl` — each visitor gets a new session.\n\n> **Seller mode is derived from your account — it is not a parameter.** Once your business is verified you accept card + bank via Merchant of Record; otherwise payments settle on-chain to the wallet on file. You never pass it; the server resolves it and returns it as `sellerMode` on the response (a `checkouts.create` with `linkId` inherits the link's mode).\n\n### `paymentLinks.create(params)`\n\n```typescript\nconst link = await agentaos.paymentLinks.create({\n  amount: 29.99,\n  currency: 'EUR',\n  description: 'Pro plan',\n  name: 'Pro Plan',             // shown in the dashboard's Products grid; defaults from `description` if omitted\n  successUrl: 'https://shop.com/success',\n  cancelUrl: 'https://shop.com/cancel',\n  webhookUrl: 'https://shop.com/webhooks',\n  taxRateId: 'uuid',\n  metadata: { plan: 'basic' },\n  expiresAt: '2026-12-31T23:59:59Z',\n  checkoutFields: [\n    { key: 'email', label: 'Email', type: 'email', required: true },\n    { key: 'company', label: 'Company', type: 'text', required: false },\n  ],\n});\n\nconsole.log(link.checkoutUrl);\n// → https://app.agentaos.ai/pay/7rr6S9ml4BMp829wV5WeAA\n```\n\n**Recurring (subscription) link** — set `type: 'subscription'` and a `billingInterval` (requires a verified account, since subscriptions bill card/bank via Merchant of Record):\n\n```typescript\nconst subscription = await agentaos.paymentLinks.create({\n  amount: 29.99,\n  currency: 'EUR',\n  description: 'Pro plan — monthly',\n  type: 'subscription',\n  billingInterval: 'month',     // 'month' | 'year' — REQUIRED for subscriptions\n});\n```\n\n**Response:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Link UUID |\n| `checkoutUrl` | `string` | Shareable payment URL |\n| `amount` | `number` | Payment amount |\n| `currency` | `string` | Settlement currency |\n| `name` | `string \\| null` | Product name shown in the dashboard's Products grid |\n| `imageUrl` | `string \\| null` | Product thumbnail shown in the dashboard's Products grid |\n| `status` | `'active' \\| 'cancelled'` | Link status |\n| `sellerMode` | `'mor' \\| 'crypto'` | How this link settles |\n| `type` | `'one_time' \\| 'subscription'` | Link type |\n| `billingInterval` | `'month' \\| 'year' \\| null` | Cadence for subscriptions; null for one-time |\n| `paymentCount` | `number` | Times this link has been paid |\n| `createdAt` | `string` | ISO 8601 |\n\n### `paymentLinks.retrieve(id)`\n\n```typescript\nconst link = await agentaos.paymentLinks.retrieve('uuid');\n```\n\n### `paymentLinks.list(params?)`\n\n```typescript\nconst links = await agentaos.paymentLinks.list({ limit: 20, offset: 0 });\n```\n\n### `paymentLinks.cancel(id)`\n\n```typescript\nawait agentaos.paymentLinks.cancel('uuid');\n```\n\n---\n\n## Subscriptions\n\nRead + manage subscriptions. Subscriptions are **created by buyers** on the hosted checkout (paying a payment link with `type: 'subscription'`) — this resource is the merchant-side management surface (list, cancel), mirroring the dashboard. There is no `create` here by design.\n\n### `subscriptions.list(params?)`\n\nPaginated — returns `{ items, total, hasMore }` (`total` is the full count, `hasMore` tells you whether another page remains).\n\n```typescript\nconst page = await agentaos.subscriptions.list({\n  limit: 20,   // 1-100, default 20\n  offset: 0,\n});\nconsole.log(page.total, page.hasMore);\n```\n\n**Each item in `page.items`:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Subscription UUID |\n| `customerEmail` | `string \\| null` | Subscriber email |\n| `customerName` | `string \\| null` | Subscriber name |\n| `planName` | `string \\| null` | The plan (subscription payment link) name or description |\n| `billingInterval` | `'month' \\| 'year' \\| null` | Billing cadence |\n| `status` | `'incomplete' \\| 'incomplete_expired' \\| 'trialing' \\| 'active' \\| 'past_due' \\| 'canceled' \\| 'unpaid' \\| 'paused'` | Current status |\n| `unitAmountMinor` | `number` | Per-cycle amount in integer minor units (e.g. `1999` = €19.99) |\n| `currency` | `string` | Settlement currency |\n| `currentPeriodEnd` | `string \\| null` | ISO 8601 end of the current paid period; null before the first cycle books |\n| `stripeSubscriptionId` | `string \\| null` | Underlying Stripe subscription ID |\n\n### `subscriptions.cancel(id, params?)`\n\nDefaults to cancel-at-period-end — the subscriber keeps the current paid period, no refund. Pass `{ atPeriodEnd: false }` to cancel immediately. Idempotent on an already-canceled subscription.\n\n```typescript\n// Cancel at period end (default) — subscriber keeps access until currentPeriodEnd\nawait agentaos.subscriptions.cancel('uuid');\n\n// Cancel immediately — access revoked now, no refund\nawait agentaos.subscriptions.cancel('uuid', { atPeriodEnd: false });\n```\n\n**Response:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `status` | `SubscriptionStatus` | Status after the cancellation |\n| `currentPeriodEnd` | `string \\| null` | ISO 8601 end of the current paid period |\n| `cancelAtPeriodEnd` | `boolean` | Whether the subscription is scheduled to cancel at period end |\n| `effectiveCancelDate` | `string \\| null` | ISO 8601 date the cancellation takes effect |\n\n---\n\n## Customers\n\nRead the customers who have paid you (mirrors the dashboard Customers list).\n\n### `customers.list(params?)`\n\nPaginated — returns `{ items, total, hasMore }` (`total` is the full count, `hasMore` tells you whether another page remains).\n\n```typescript\nconst page = await agentaos.customers.list({\n  limit: 20,   // 1-100, default 20\n  offset: 0,\n});\nconsole.log(page.total, page.hasMore);\n```\n\n**Each item in `page.items`:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Customer UUID |\n| `email` | `string` | Customer email |\n| `name` | `string \\| null` | Customer name |\n| `country` | `string \\| null` | ISO 3166-1 alpha-2 country code |\n| `vatNumber` | `string \\| null` | VAT number on file |\n| `stripeCustomerId` | `string \\| null` | Underlying Stripe customer ID |\n| `createdAt` | `string` | ISO 8601 |\n\n---\n\n## Transactions\n\nUnified ledger of all confirmed inbound (received) and outbound (sent) payments.\n\n### `transactions.list(params?)`\n\n```typescript\nconst txs = await agentaos.transactions.list({\n  direction: 'inbound',   // 'all' | 'inbound' | 'outbound'\n  from: '2026-03-01',     // ISO 8601 date\n  to: '2026-03-31',       // ISO 8601 date\n  limit: 50,\n  offset: 0,\n});\n```\n\n**Response item:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Transaction UUID |\n| `direction` | `'inbound' \\| 'outbound'` | Payment direction |\n| `amount` | `number` | Amount in settlement token |\n| `paymentToken` | `string` | Token used (e.g. 'USDC') |\n| `txHash` | `string \\| null` | On-chain transaction hash |\n| `network` | `string` | CAIP-2 network (e.g. 'eip155:8453') |\n| `payerAddress` | `string` | Sender wallet address |\n| `toAddress` | `string \\| null` | Recipient (outbound only) |\n| `status` | `'confirmed' \\| 'pending' \\| 'failed'` | Transaction status |\n| `createdAt` | `string` | ISO 8601 |\n\n---\n\n## Invoices\n\nTax-compliant invoice records generated from confirmed payments.\n\n### `invoices.list(params?)`\n\n```typescript\nconst invoices = await agentaos.invoices.list({\n  from: '2026-03-01',\n  to: '2026-03-31',\n  status: 'issued',        // 'all' | 'issued' | 'voided'\n  limit: 50,\n});\n```\n\n### `invoices.retrieve(id)`\n\n```typescript\nconst invoice = await agentaos.invoices.retrieve('uuid');\n```\n\n**Response:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `invoiceNumber` | `string` | e.g. 'INV-2026-0001' |\n| `amount` | `number` | Crypto amount |\n| `fiatAmount` | `number \\| null` | EUR/USD equivalent |\n| `fiatCurrency` | `string \\| null` | 'EUR' or 'USD' |\n| `exchangeRate` | `number \\| null` | Rate at settlement time |\n| `taxRate` | `number \\| null` | Applied tax rate (e.g. 19) |\n| `taxAmount` | `number \\| null` | Tax amount |\n| `taxName` | `string \\| null` | e.g. 'DE VAT' |\n| `merchantName` | `string \\| null` | Your business name |\n| `buyerEmail` | `string \\| null` | Customer email |\n| `status` | `'issued' \\| 'voided'` | Invoice status |\n\n### `invoices.void(id)`\n\n```typescript\nawait agentaos.invoices.void('uuid');\n```\n\n### `invoices.downloadPdf(id)`\n\n```typescript\nconst pdf = await agentaos.invoices.downloadPdf('uuid');\nfs.writeFileSync('invoice.pdf', pdf);\n```\n\n### `invoices.downloadStatement(params)`\n\nMonthly statement PDF (Wise-style) with balance reconciliation, VAT summary, and transaction ledger.\n\n```typescript\nconst statement = await agentaos.invoices.downloadStatement({\n  from: '2026-03-01',\n  to: '2026-03-31',\n});\nfs.writeFileSync('march-statement.pdf', statement);\n```\n\n### `invoices.exportCsv(params?)`\n\n```typescript\nconst csv = await agentaos.invoices.exportCsv({\n  from: '2026-03-01',\n  to: '2026-03-31',\n  status: 'issued',\n});\nfs.writeFileSync('invoices.csv', csv);\n```\n\n### `invoices.getReceipt(id)`\n\nDownload the receipt PDF for a paid invoice. Falls back to the invoice PDF for invoices issued before receipts existed.\n\n```typescript\nconst receipt = await agentaos.invoices.getReceipt('uuid');\nfs.writeFileSync('receipt.pdf', receipt);\n```\n\n### `invoices.sendReceipt(id)`\n\nRe-send the receipt email to the buyer on file. Paid invoices only.\n\n```typescript\nconst result = await agentaos.invoices.sendReceipt('uuid');\nconsole.log(result.sentTo); // buyer email the receipt was sent to\n```\n\n---\n\n## Webhooks\n\nVerify incoming webhook signatures. Uses HMAC-SHA256 with timing-safe comparison.\n\n### `webhooks.verify(payload, signature, secret)`\n\n```typescript\nimport express from 'express';\n\napp.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {\n  try {\n    const event = agentaos.webhooks.verify(\n      req.body,                                    // raw body (string or Buffer)\n      req.headers['x-agentaos-signature'] as string, // signature header\n      process.env.AGENTAOS_WEBHOOK_SECRET!,        // your webhook secret\n    );\n\n    switch (event.type) {\n      case 'checkout.session.completed':\n        // Payment received\n        console.log('Paid:', event.data.amount, event.data.currency);\n        console.log('Tx:', event.data.txHash);\n        console.log('Session:', event.data.sessionId);\n        break;\n\n      case 'send.completed':\n        // Outbound send confirmed\n        console.log('Sent:', event.data.amount, event.data.token);\n        break;\n\n      case 'send.failed':\n        // Outbound send failed\n        console.log('Failed:', event.data.transactionId);\n        break;\n    }\n\n    res.sendStatus(200);\n  } catch (err) {\n    res.status(400).send('Invalid signature');\n  }\n});\n```\n\n**Signature format:** `t=<unix_timestamp>,v1=<hmac_hex>`\n\n**Webhook events:**\n\n| Event | When |\n|-------|------|\n| `checkout.session.completed` | Payment confirmed on-chain |\n| `send.completed` | Outbound send broadcast succeeded |\n| `send.failed` | Outbound send broadcast failed |\n\n### `checkout.session.completed` data\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `linkId` | `string` | Payment link secure ID |\n| `sessionId` | `string` | Session ID |\n| `amount` | `string` | Amount paid |\n| `currency` | `string` | Settlement currency |\n| `txHash` | `string` | On-chain transaction hash |\n| `payer` | `string` | Payer wallet address |\n| `payerType` | `'human' \\| 'agent'` | Who paid |\n| `network` | `string` | CAIP-2 network |\n| `metadata` | `object` | Custom metadata from session |\n\n---\n\n## Error Handling\n\n```typescript\nimport {\n  AgentaOSError,\n  AuthenticationError,\n  NotFoundError,\n  RateLimitError,\n  ValidationError,\n} from '@agentaos/pay';\n\ntry {\n  await agentaos.checkouts.create({ amount: -1 });\n} catch (err) {\n  if (err instanceof ValidationError) {\n    console.log('Invalid params:', err.message);\n  } else if (err instanceof AuthenticationError) {\n    console.log('Bad API key:', err.message);\n  } else if (err instanceof RateLimitError) {\n    console.log('Rate limited, retry after:', err.retryAfter, 'ms');\n  } else if (err instanceof NotFoundError) {\n    console.log('Not found:', err.message);\n  } else if (err instanceof AgentaOSError) {\n    console.log('API error:', err.status, err.message);\n  }\n}\n```\n\n| Error | HTTP Status | When |\n|-------|-------------|------|\n| `AuthenticationError` | 401 | Invalid or expired API key |\n| `PermissionError` | 403 | Key can't access this resource |\n| `NotFoundError` | 404 | Resource doesn't exist |\n| `ValidationError` | 400 | Invalid request params |\n| `RateLimitError` | 429 | Too many requests |\n| `IdempotencyError` | 409 | Duplicate idempotency key |\n| `TimeoutError` | — | Request timed out |\n| `ApiError` | 5xx | Server error (auto-retried) |\n| `WebhookVerificationError` | — | Invalid webhook signature |\n\n---\n\n## Checkout Flow (Web Shop)\n\n```\nYour Server                    AgentaOS                     Customer\n──────────                     ────────                     ────────\n1. POST checkouts.create()  →\n   { amount, successUrl,\n     cancelUrl, webhookUrl }\n                            ←  { checkoutUrl, sessionId }\n2. Redirect customer       →                            →  Opens checkoutUrl\n                                                           Connects wallet\n                                                           Pays on-chain\n                            ←  Webhook: checkout.session.completed\n3. Verify webhook\n4. Fulfill order\n                                                        ←  Redirects to successUrl\n```\n\n## Requirements\n\n- Node.js 20+\n- ESM only (`\"type\": \"module\"`)\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}