{ "openapi": "3.1.0", "info": { "title": "Animica Pay Merchant API", "version": "10.1.0", "summary": "Accept ANM payments: payment intents, refunds, balance, hosted checkout and HMAC-signed webhooks.", "description": "The merchant REST API behind https://pay.animica.dev — hosted checkout, payment links, invoices and POS for the Animica chain (L1 chain id 1, addresses bech32m `anim1…`, signatures ML-DSA-65).\n\n## Money\n- 1 ANM = 10^9 base units (nano-ANM, `nANM`). API responses report `anm_amount`, `merchant_amount` and `protocol_fee` as **integer nANM decimal strings**, plus `*_formatted` display strings.\n- **All amounts are JSON strings, never JSON numbers.** A JSON number loses precision before it reaches the server and is refused with `amount_must_be_string`.\n- `amount` is a human quantity of the stated `currency` (`\"100\"` with currency `ANM` means 100 ANM, `\"49.99\"` with `USD` means dollars). To specify base units exactly, send `amount_nanm` instead. Sending both is a 400.\n- Fee: **2.00% (200 bps)** per successful payment, floored, with `merchant_amount + protocol_fee == anm_amount` exactly. The fee is not refundable.\n\n## Authentication\nEvery `/api/v1` route requires a **secret** API key (`ask_live_…` / `ask_test_…`) as `Authorization: Bearer `. Publishable keys (`apk_…`) are refused. Keys are never accepted from cookies. Test-mode keys never move real ANM.\n\n## Idempotency\n`Idempotency-Key` is **required** on payment-intent creation. A retry with the same key and body replays the original response (with header `idempotent-replay: true`); the same key with a different body is a 409 `idempotency_key_reused`.\n\n## Settlement\nA payment is `PAID` only after a successful execution receipt at the required confirmation depth (currently 12). Inclusion in a block is not settlement on this chain, and a reorg can return a settled intent to `AWAITING_PAYMENT` (webhook `payment.reorged`). Fulfil orders from webhooks, not from anything observable in the browser.\n\n## Rate limits\nPer key: 100 requests/min (burst 100). Per IP: 300 requests/min. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; a 429 carries `Retry-After` (seconds).\n\n## Webhooks\nDeliveries are HMAC-SHA256 signed. The signed string is `v1:::` under your endpoint secret (`whsec_…`, shown once). Verify against the **raw** request body, compare in constant time, and reject timestamps older than 300 s. See the top-level `webhooks` section.\n\nHuman docs: https://pay.animica.dev/docs — machine index: https://pay.animica.dev/llms.txt", "contact": { "name": "Animica", "email": "ai@3vdc.com", "url": "https://animica.org" }, "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [{ "url": "https://pay.animica.dev" }], "security": [{ "bearerApiKey": [] }], "tags": [ { "name": "payment-intents", "description": "Create, list, fetch and cancel payment intents. One intent is satisfied by exactly one on-chain transaction, matched by payment reference + recipient — never by amount." }, { "name": "refunds", "description": "A refund on this chain is a NEW merchant-signed transfer, never a reversal. Cap = captured gross; the 2% protocol fee is not refundable. Refused in test mode." }, { "name": "balance", "description": "Settled vs pending merchant balance in nANM." }, { "name": "public", "description": "Unauthenticated surfaces: health probe, hosted checkout pages and the embeddable widget. Checkout pages are documented for reference only — they serve HTML to customers, not JSON to integrations." } ], "paths": { "/api/v1/payment-intents": { "post": { "tags": ["payment-intents"], "operationId": "createPaymentIntent", "summary": "Create a payment intent", "description": "Server-priced: you state what to charge in your currency; the server decides the nANM amount, the 2.00% fee split, the payment address and the payment reference. Client-supplied `merchant_address`, `treasury_address`, `protocol_fee`, `merchant_amount` or `protocol_fee_bps` are refused with `field_not_settable`.\n\nWith `currency: \"USD\"` (or another fiat currency) the server locks an exchange-rate quote; if no rate source is configured the request is refused with `currency_unsupported` rather than priced by guesswork — send `currency: \"ANM\"` with an exact amount instead.\n\nRedirect the customer to `checkout_url` from the response. Default intent expiry is 30 minutes.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentIntentRequest" }, "examples": { "anm": { "summary": "Charge 25 ANM", "value": { "amount": "25", "currency": "ANM", "merchant_order_id": "19482", "description": "Order #19482" } }, "usd": { "summary": "Charge $49.99 (server locks the ANM rate)", "value": { "amount": "49.99", "currency": "USD", "merchant_order_id": "19482", "description": "WooCommerce Order #19482", "metadata": { "platform": "woocommerce" } } }, "base_units": { "summary": "Charge exactly 25,000,000,000 nANM", "value": { "amount_nanm": "25000000000", "currency": "ANM" } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "200": { "description": "Idempotent replay — the same `Idempotency-Key` and body were seen before; this is the original response.", "headers": { "idempotent-replay": { "description": "`true` when this response is a replay of the first attempt.", "schema": { "type": "string", "enum": ["true"] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "`idempotency_key_reused` — this `Idempotency-Key` was already used with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": ["payment-intents"], "operationId": "listPaymentIntents", "summary": "List payment intents", "description": "Tenant- and mode-scoped to the API key. Cursor pagination via `starting_after`.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/PaymentIntentStatus" } }, { "name": "starting_after", "in": "query", "description": "Intent id to page after.", "schema": { "type": "string" } }, { "name": "merchant_order_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of payment intents.", "content": { "application/json": { "schema": { "type": "object", "required": ["object", "has_more", "data"], "properties": { "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntent" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/payment-intents/{id}": { "get": { "tags": ["payment-intents"], "operationId": "getPaymentIntent", "summary": "Fetch a payment intent", "description": "Another merchant's id returns 404 (never 403), so ids cannot be enumerated.", "parameters": [{ "$ref": "#/components/parameters/IntentId" }], "responses": { "200": { "description": "The payment intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/payment-intents/{id}/cancel": { "post": { "tags": ["payment-intents"], "operationId": "cancelPaymentIntent", "summary": "Cancel a payment intent", "description": "Only intents that have not reached a terminal or in-flight-settlement state can be cancelled; otherwise 409 `not_cancellable`.", "parameters": [{ "$ref": "#/components/parameters/IntentId" }], "responses": { "200": { "description": "The cancelled intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`not_cancellable` — the intent is in a state that cannot be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/refunds": { "post": { "tags": ["refunds"], "operationId": "createRefund", "summary": "Create a refund", "description": "Refundable states: `PAID` or `PARTIALLY_REFUNDED`; anything else is 409 `not_refundable`. Omit `amount`/`amount_nanm` to refund the full `merchant_amount` (what you received — the 2% fee is not refundable). A refund is a **new** transfer that you sign: the response carries `requires_merchant_signature` and an `unsigned_transfer` to sign from your payout address. Test mode is refused outright — a refund moves real value.", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyOptional" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" }, "examples": { "full": { "summary": "Full refund of the merchant amount", "value": { "payment_intent": "pay_X9m2ABC", "reason": "customer request" } }, "partial": { "summary": "Partial refund of 5 ANM", "value": { "payment_intent": "pay_X9m2ABC", "amount": "5" } } } } } }, "responses": { "201": { "description": "Refund created; signature may still be required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`not_refundable` (intent state) or `refund_refused` (e.g. over the refundable cap).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/refunds/{id}": { "get": { "tags": ["refunds"], "operationId": "getRefund", "summary": "Fetch a refund", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "The refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/balance": { "get": { "tags": ["balance"], "operationId": "getBalance", "summary": "Fetch merchant balance", "description": "Scoped to the key's mode. `settled` has confirmed on chain; `pending` is detected but not yet at the required depth — reported separately because treating pending as spendable is how a merchant over-ships.", "responses": { "200": { "description": "The balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/healthz": { "get": { "tags": ["public"], "operationId": "healthz", "summary": "Health probe", "description": "Unauthenticated routing probe. Says only whether to send traffic here — no internal detail.", "security": [], "responses": { "200": { "description": "Healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } }, "503": { "description": "Degraded — do not route traffic here." } } } }, "/c/{id}": { "get": { "tags": ["public"], "operationId": "checkoutPage", "summary": "Hosted checkout page (documentation only)", "description": "**Not a JSON API.** The customer-facing HTML checkout for a payment intent — this is the `checkout_url` returned by intent creation. Send customers here; do not scrape it. Live payment state is pushed to the open page over SSE at `/c/{id}/events`. With `?embed=1` it runs inside the widget iframe under a merchant-scoped `frame-ancestors` CSP.", "security": [], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment intent id." }], "responses": { "200": { "description": "HTML checkout page.", "content": { "text/html": {} } }, "404": { "description": "Unknown intent." } } } }, "/c/{id}/events": { "get": { "tags": ["public"], "operationId": "checkoutEvents", "summary": "Checkout status stream (documentation only)", "description": "**Server-Sent Events** stream consumed by the hosted checkout page itself. Not a merchant integration surface — fulfil orders from signed webhooks, never from anything observable in a browser.", "security": [], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "SSE stream of intent state changes.", "content": { "text/event-stream": {} } } } } }, "/widget.js": { "get": { "tags": ["public"], "operationId": "widgetJs", "summary": "Embeddable checkout widget (documentation only)", "description": "The `