{ "openapi": "3.1.0", "info": { "title": "GoBTC Pay Merchant Account API", "version": "v1.2", "x-logo": { "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/GoMining_Logo_%28Black%29.png" }, "description": "# GoBTC Pay — Merchant Account API\n\nBackwards compatibility is preserved across published versions. Found an error in the docs? Email [support@gomining.com](mailto:support@gomining.com).\n\nThis is the **Merchant dashboard** surface of the GoBTC Pay API.\n\nEndpoints for the merchant personal cabinet (stores, POS terminals, team,\nreports, and webhooks). See the operation reference below.\n\n## Webhooks\n\nConfigure outbound webhook endpoints so your backend is notified when a\npayment's status changes — an alternative to polling the POS **Get payment**\nendpoint.\n\n- **Scope** — an endpoint can cover the whole account (`merchant`) or be\n narrowed to a single `store` or `pos` terminal.\n- **Delivery** — the `payment.status.updated` event is `POST`ed as a thin\n envelope `{ eventId, type, createdAt, data }`, where `data` matches the POS\n **Get payment** response. Delivery is at-least-once — de-duplicate on\n `eventId`.\n- **Signing** — each endpoint has its own `signingSecret` (returned once on\n create / rotate-secret). Verify the `X-GoBTCPay-Signature: t=,v1=`\n header, where `v1 = HMAC-SHA256(signingSecret, \"{t}.{rawBody}\")`, and\n reject deliveries outside a small time window.\n\nUse **Send test event** to verify your receiver and signature validation." }, "components": { "securitySchemes": { "merchantAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer `. Refresh it via `/merchant/auth/refresh` when it expires." } } }, "servers": [ { "url": "https://api.gobtcpay.com/public/api/v1.2" } ], "paths": { "/pos/transaction/create-payment": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create payment", "description": "Creates a payment request for a POS terminal. Specify the `amount` and `currency`; the response includes the satoshi amount, the BTC price snapshot, an `expiresAt` deadline, and a `qrString` to present to the payer. `signature` and `ts` may be supplied for request signing.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posTerminalId": { "type": "string", "description": "POS terminal that accepts the payment (from **Create POS terminal**).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amount": { "type": "number", "description": "Amount to charge, in the selected fiat `currency`.", "example": 10 }, "description": { "type": "string", "description": "Optional description shown to the payer.", "example": "Order #1024" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "ttlSeconds": { "type": "number", "description": "Optional lifetime of the payment in seconds; after this it expires.", "example": 900 }, "externalId": { "type": "string", "description": "Merchant's own correlation id (e.g. order / invoice id). Unique per merchant, so reusing it makes create-payment idempotent. Echoed back in payment responses and webhook deliveries.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signature": { "type": "string", "description": "Optional HMAC-SHA256 signature of the request (hex), authenticating the POS terminal with its `apiKey`.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "ts": { "type": "number", "description": "Request timestamp in milliseconds, used together with `signature` for replay protection.", "example": 1718012345000 } }, "required": [ "posTerminalId", "currency", "signature", "ts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Unique id of the created payment.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Payment status. One of `initiated`, `detected`, `paid`, `failed`, `expired`, `canceled`, `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "storeId": { "type": "string", "description": "Identifier of the store the payment belongs to (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "POS terminal that accepts the payment (from **Create POS terminal**).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ], "description": "Merchant's own correlation id (e.g. order / invoice id). Unique per merchant, so reusing it makes create-payment idempotent. Echoed back in payment responses and webhook deliveries." }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount to pay in satoshis (converted from `amount` at `btcPriceInCurrency`).", "example": "string" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount to charge, in the selected fiat `currency`.", "example": 10 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "checkoutUrl": { "type": "string", "example": "string" }, "version": { "type": "integer", "minimum": 0, "example": 0 }, "btcAddress": { "type": "string", "description": "Bitcoin address bound to this payment; the payer sends funds here. Can be used to look the payment up later.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" } }, "required": [ "paymentId", "status", "merchantId", "merchantName", "storeId", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "externalId", "amountSats", "currency", "amount", "expiresAt", "btcPriceInUsd", "btcPriceInCurrency", "checkoutUrl", "version", "btcAddress", "qrString" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Optional description shown to the payer.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/pos/transaction/create-payment\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"posTerminalId\": \"pos_…\",\n \"amount\": 10,\n \"currency\": \"USD\",\n \"metadata\": {}\n}'" } ] } }, "/pos/transaction/get-payment": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get payment", "description": "Returns the current state of a payment by `paymentId`, including its `status`, amounts, merchant / POS details, and `qrString`. Poll this to track a payment until it is paid or expired.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Transaction (payment) identifier — the `paymentId` returned by **Create payment**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signature": { "type": "string", "description": "Signature in hex format sha 256", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "ts": { "type": "number", "description": "Timestamp in milliseconds", "example": 1718012345000 } }, "required": [ "paymentId", "signature", "ts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Transaction (payment) identifier — the `paymentId` returned by **Create payment**.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Payment status. One of `initiated`, `detected`, `paid`, `failed`, `expired`, `canceled`, `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "storeId": { "type": "string", "description": "Identifier of the store the payment belongs to (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ], "description": "Merchant's own correlation id (e.g. order / invoice id), echoed back from create-payment. Null when none was supplied." }, "description": { "type": "string", "description": "Description shown to the payer (optional).", "example": "Order #1024" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount to pay, in satoshis.", "example": "string" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" }, "version": { "type": "integer", "minimum": 0, "example": 0 }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex) of this receipt. Look it up in any block explorer to show the payer their transaction.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "What this transaction paid into **this payment's** address, in satoshis — not the transaction's total, which may pay other outputs as well.", "example": "string" }, "blockHeight": { "anyOf": [ { "type": "number", "example": 845000 }, { "type": "null", "example": null } ], "description": "Height of the block that included the transaction; `null` while it is still in the mempool." }, "blockTime": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Timestamp of that block, Unix seconds; `null` while the transaction is still in the mempool. Historical payments confirmed before this field existed report `null` permanently." }, "confirmations": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 0 }, { "type": "null", "example": null } ], "description": "Confirmations as of **now**, not as of the moment the payment was paid, so the value keeps growing. `0` — seen but not in a block yet. `null` — the current chain tip is not known to us right now, so the count cannot be stated; do not render it as zero, the transaction may well be deeply confirmed. The remaining fields are unaffected." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "example": "string" }, { "type": "null", "example": null } ], "description": "Network fee the payer paid for this transaction, in satoshis; `null` when it is not known to us." } }, "required": [ "txid", "amountSats", "blockHeight", "blockTime", "confirmations", "feeSats" ], "additionalProperties": false }, "default": [], "description": "On-chain transactions observed paying this payment, freshest first. Empty until something is seen — and empty is a normal state for a payment in `initiated`. More than one element means the payer sent more than one transaction (an overpayment or a top-up); sum `amountSats` across the list to get what actually arrived. Identical for both payment routes: an in-app payment reports its single transaction here just like one paid from an external wallet." }, "paidAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "default": null, "description": "When the payment was paid, Unix timestamp (seconds); `null` until then. This is the payment's settlement time — for when a single transaction was mined see `transactions[].blockTime`." } }, "required": [ "paymentId", "status", "merchantId", "currency", "merchantName", "storeId", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "externalId", "amountSats", "btcPriceInUsd", "btcPriceInCurrency", "amount", "expiresAt", "qrString", "version" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Description shown to the payer (optional).", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/pos/transaction/get-payment\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\"\n}'" } ] } }, "/pos/transaction/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List payments", "description": "Returns a paginated list of payment transactions with optional `dateRange` and `status` filters. Each item carries merchant / POS context, fiat and BTC amounts, and on-chain settlement data when available. `totalCount` reflects the filtered total.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of items to return (1–100, default 20).", "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "description": "Number of items to skip — offset for pagination (default 0).", "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "Filter from this creation time, Unix timestamp (seconds).", "example": 0 }, "end": { "type": "integer", "minimum": 0, "description": "Filter up to this creation time, Unix timestamp (seconds).", "example": 0 } }, "required": [ "start", "end" ], "additionalProperties": false }, "status": { "type": "array", "items": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "example": "initiated" }, "description": "Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`." } }, "additionalProperties": false }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signature": { "type": "string", "description": "Signature in hex format sha 256", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "ts": { "type": "number", "description": "Timestamp in milliseconds", "example": 1718012345000 } }, "required": [ "posTerminalId", "signature", "ts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Filter by payment transaction status. Values: `success`, `failed`, `pending`, `cleared`.", "example": "initiated" }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount in satoshis.", "example": "string" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "description": { "type": [ "string", "null" ], "description": "Description shown to the payer (may be null).", "example": "Order #1024" }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "network": { "type": "string", "enum": [ "mainnet", "testnet" ], "example": "mainnet" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "btcAddress": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" } }, "required": [ "paymentId", "status", "amount", "amountSats", "currency", "description", "network", "btcPriceInUsd", "btcPriceInCurrency", "externalId", "createdAt", "expiresAt", "btcAddress", "merchantId", "merchantName", "merchantDisplayName", "posTerminalId", "posTerminalLabel", "posTerminalLocation" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Description shown to the payer (may be null).", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/login": { "post": { "security": [], "summary": "Log in", "description": "Authenticates with `email` and `password`. Returns either an authenticated session (`tokens`, `user`, `memberships`) when `$case` is `authenticated`, or an `mfaToken` to complete via 2FA when `$case` is `mfa_required`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" }, "password": { "type": "string", "example": "string" } }, "required": [ "email", "password" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "anyOf": [ { "type": "object", "properties": { "$case": { "type": "string", "const": "authenticated", "example": "authenticated" }, "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] } }, "required": [ "$case", "tokens", "user", "memberships", "activeMerchantId" ], "additionalProperties": false }, { "type": "object", "properties": { "$case": { "type": "string", "const": "mfa_required", "example": "mfa_required" }, "mfaToken": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "$case", "mfaToken" ], "additionalProperties": false } ] } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/register": { "post": { "security": [], "summary": "Register", "description": "Creates a new merchant user from `email` and `password`, with optional `displayName` and `merchantName` (bootstraps the first merchant with the user as admin). Returns the new `userId` and `status`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" }, "password": { "type": "string", "example": "string" }, "displayName": { "type": "string", "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "referralCode": { "type": "string", "example": "string" } }, "required": [ "email", "password" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "userId", "status" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/refresh": { "post": { "security": [], "summary": "Refresh tokens", "description": "Exchanges a valid `refreshToken` for a fresh `tokens` bundle (`accessToken`, `refreshToken`, `expiresAt`).", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "refreshToken" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/logout": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Log out", "description": "Revokes the given `refreshToken`, or the current session if omitted. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/me": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Current user", "description": "Returns the authenticated `user` profile and the list of `memberships` linking the user to merchants with a role.", "tags": [ "Merchant Auth" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "walletLinked": { "type": "boolean", "description": "Whether a receiving wallet is linked to the active merchant. The UI uses this to gate onboarding.", "example": true }, "walletAddress": { "type": [ "string", "null" ], "description": "The linked receiving wallet address, or null when none is linked.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "hasReferralAttribution": { "type": "boolean", "example": true } }, "required": [ "user", "memberships", "activeMerchantId", "walletLinked", "walletAddress" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/verify-email": { "post": { "security": [], "summary": "Verify email", "description": "Confirms an email address using the `email` and the emailed `code`. On success the user is signed in: returns the full auth bundle (`tokens`, `user`, `memberships`) so the client can log straight into the merchant cabinet without a separate login.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" }, "code": { "type": "string", "example": "string" } }, "required": [ "email", "code" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] } }, "required": [ "tokens", "user", "memberships", "activeMerchantId" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/oauth/login": { "post": { "security": [], "summary": "OAuth login", "description": "Logs in via an OAuth `provider` using `authCode` or `idToken` (with optional `redirectUri`); `merchantName` bootstraps the first merchant for new accounts. Returns an authenticated session or an `mfaToken` challenge.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "apple", "google" ], "example": "apple" }, "authCode": { "type": "string", "example": "string" }, "idToken": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "redirectUri": { "type": "string", "example": "string" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" } }, "required": [ "provider" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "anyOf": [ { "type": "object", "properties": { "$case": { "type": "string", "const": "authenticated", "example": "authenticated" }, "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] } }, "required": [ "$case", "tokens", "user", "memberships", "activeMerchantId" ], "additionalProperties": false }, { "type": "object", "properties": { "$case": { "type": "string", "const": "mfa_required", "example": "mfa_required" }, "mfaToken": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "$case", "mfaToken" ], "additionalProperties": false } ] } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/password/change": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Change password", "description": "Sets `newPassword` for the current user; `oldPassword` is required unless setting a password for the first time. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "oldPassword": { "type": "string", "example": "string" }, "newPassword": { "type": "string", "example": "string" } }, "required": [ "newPassword" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/password/forgot": { "post": { "security": [], "summary": "Forgot password", "description": "Triggers a password-reset email for the given `email`. Always returns `{ ok }` to avoid account enumeration.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" } }, "required": [ "email" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/password/reset": { "post": { "security": [], "summary": "Reset password", "description": "Sets `newPassword` using a reset `token` from the password-reset email. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "newPassword": { "type": "string", "example": "string" } }, "required": [ "token", "newPassword" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/2fa/verify": { "post": { "security": [], "summary": "Verify 2FA", "description": "Completes an MFA login challenge with the `mfaToken` and a TOTP or recovery `code`. Returns an authenticated session (`tokens`, `user`, `memberships`).", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mfaToken": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "code": { "type": "string", "example": "string" } }, "required": [ "mfaToken", "code" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] } }, "required": [ "tokens", "user", "memberships", "activeMerchantId" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/2fa/totp/setup": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Set up TOTP", "description": "Begins TOTP enrollment, returning the `secret`, `otpauthUri`, and a `qr` data URI for the authenticator app. TOTP is not active until confirmed via enable.", "tags": [ "Merchant Auth" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "secret": { "type": "string", "example": "string" }, "otpauthUri": { "type": "string", "example": "string" }, "qr": { "type": "string", "description": "QR code as a data URI", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" } }, "required": [ "secret", "otpauthUri", "qr" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/2fa/totp/enable": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Enable TOTP", "description": "Activates TOTP by confirming a `code` from the authenticator. Returns one-time `recoveryCodes` shown only once.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "string" } }, "required": [ "code" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "recoveryCodes" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/2fa/totp/disable": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Disable TOTP", "description": "Disables TOTP after re-authenticating with a current TOTP `code` or the account `password`. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "password": { "type": "string", "example": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/register/options": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Passkey register options", "description": "Returns WebAuthn `publicKeyOptions` (PublicKeyCredentialCreationOptions incl. challenge) to pass to `navigator.credentials.create()` for registering a new passkey.", "tags": [ "Merchant Auth" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "publicKeyOptions": { "description": "PublicKeyCredentialCreationOptions JSON, including challenge", "example": {} } }, "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/register/verify": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Passkey register verify", "description": "Verifies the authenticator attestation `credential` (with optional `deviceLabel`) and stores the passkey. Returns the created `credential` descriptor.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "description": "PublicKeyCredential attestation JSON from the authenticator", "example": {} }, "deviceLabel": { "type": "string", "example": "Front desk" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "deviceLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "lastUsedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "deviceLabel", "createdAt", "lastUsedAt" ], "additionalProperties": false } }, "required": [ "credential" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/login/options": { "post": { "security": [], "summary": "Passkey login options", "description": "Returns WebAuthn `publicKeyOptions` (PublicKeyCredentialRequestOptions incl. challenge) for `navigator.credentials.get()`. Pass `email` for a specific user, or omit for discoverable (usernameless) login.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "publicKeyOptions": { "description": "PublicKeyCredentialRequestOptions JSON, including challenge", "example": {} } }, "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/login/verify": { "post": { "security": [], "summary": "Passkey login verify", "description": "Verifies the authenticator assertion `credential` and signs the user in (single-step, no extra MFA). Returns an authenticated session (`tokens`, `user`, `memberships`).", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "description": "PublicKeyCredential assertion JSON from the authenticator", "example": {} } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "emailVerified": { "type": "boolean", "example": true }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "avatarUrl": { "type": [ "string", "null" ], "example": "string" }, "twoFactorEnabled": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "id", "email", "emailVerified", "displayName", "avatarUrl", "twoFactorEnabled", "status" ], "additionalProperties": false }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "isCustodial": { "type": "boolean", "example": true }, "isDemo": { "type": "boolean", "example": true }, "actionsBlocked": { "type": "boolean", "example": true } }, "required": [ "id", "merchantId", "merchantName", "role", "status", "isCustodial", "isDemo" ], "additionalProperties": false } }, "activeMerchantId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] } }, "required": [ "tokens", "user", "memberships", "activeMerchantId" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List passkeys", "description": "Returns the current user's registered passkeys as `items`, each with `id`, `deviceLabel`, `createdAt`, and `lastUsedAt`.", "tags": [ "Merchant Auth" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "deviceLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "lastUsedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "deviceLabel", "createdAt", "lastUsedAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/passkey/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete passkey", "description": "Removes the passkey identified by `credentialId` from the current user. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "credentialId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/sessions/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List sessions", "description": "Lists the current user's active sessions as `items` (with `userAgent`, `ip`, timestamps, and `current` flag) plus `totalCount`. Accepts optional `pagination`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "userAgent": { "type": [ "string", "null" ], "example": "string" }, "ip": { "type": [ "string", "null" ], "example": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 }, "current": { "type": "boolean", "example": true } }, "required": [ "id", "userAgent", "ip", "createdAt", "expiresAt", "current" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/sessions/revoke": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Revoke session", "description": "Revokes the session identified by `sessionId`. Returns `{ ok }`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "sessionId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/context/switch": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Switch merchant", "description": "Switches the active merchant context to `merchantId`, returning fresh `tokens` carrying the new merchantId/role claims.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "merchantId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived JWT access token. Send it as `Authorization: Bearer ` on authenticated requests.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "refreshToken": { "type": "string", "description": "Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "accessToken", "refreshToken", "expiresAt" ], "additionalProperties": false } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/xpub/link": { "post": { "security": [], "summary": "Link xpub key (via link token)", "description": "Links a BIP32 extended public key (`xpub`) to the merchant account, authorized by the one-time `linkToken` from **Start wallet link** (read from the scanned QR) — no bearer auth required. Receiving addresses are later derived from this key along its `derivationPath`. Optionally pass the `masterFingerprint` (for PSBT key origins) and a `label`. Returns the stored key record with its `keyId`. For the signed-in dashboard flow, use **Link xpub key (authorized)**.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkToken": { "type": "string", "description": "One-time link token from **Start wallet link**, read from the scanned QR. Scopes the call to the merchant's link session (no bearer auth needed).", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "xpub": { "type": "string", "description": "BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.", "example": "string" }, "derivationPath": { "type": "string", "description": "Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it.", "example": "string" }, "masterFingerprint": { "type": "string", "description": "Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs.", "example": "string" }, "label": { "type": "string", "description": "Optional human-readable label for the linked key.", "example": "Front desk" } }, "required": [ "linkToken", "xpub" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "keyId": { "type": "string", "description": "Id of the stored linked-key record.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "xpub": { "type": "string", "description": "BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.", "example": "string" }, "derivationPath": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ], "description": "Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it." }, "masterFingerprint": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ], "description": "Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs." }, "label": { "type": [ "string", "null" ], "description": "Optional human-readable label for the linked key.", "example": "Front desk" }, "linkedAt": { "type": "integer", "minimum": 0, "description": "When the key was linked, Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "keyId", "xpub", "derivationPath", "masterFingerprint", "label", "linkedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/auth/xpub/link-authorized": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Link xpub key (authorized)", "description": "Authenticated counterpart of **Link xpub key (via link token)**: links an `xpub` to the active merchant identified by the bearer token, so no `linkToken` is needed. Same `derivationPath`, `masterFingerprint`, and `label` options; returns the stored key record with its `keyId`.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "xpub": { "type": "string", "description": "BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.", "example": "string" }, "derivationPath": { "type": "string", "description": "Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it.", "example": "string" }, "masterFingerprint": { "type": "string", "description": "Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs.", "example": "string" }, "label": { "type": "string", "description": "Optional human-readable label for the linked key.", "example": "Front desk" } }, "required": [ "xpub" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "keyId": { "type": "string", "description": "Id of the stored linked-key record.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "xpub": { "type": "string", "description": "BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account.", "example": "string" }, "derivationPath": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ], "description": "Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it." }, "masterFingerprint": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ], "description": "Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs." }, "label": { "type": [ "string", "null" ], "description": "Optional human-readable label for the linked key.", "example": "Front desk" }, "linkedAt": { "type": "integer", "minimum": 0, "description": "When the key was linked, Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "keyId", "xpub", "derivationPath", "masterFingerprint", "label", "linkedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/auth/register": { "post": { "security": [], "summary": "Register (custodial)", "description": "Custodial counterpart of **Register**: creates the cabinet user and a custodial merchant, then creates that merchant's Uphold business user and its BTC account. Alongside `email` / `password` it takes the legal entity details Uphold requires — `businessEmail`, `country`, `subdivision`, `legalEntityType` — and the accepted `termsOfService` code, which is recorded together with the time and the caller's IP. Returns the new `userId` and `status`. The Uphold half is best-effort: if it fails the registration still stands, and the entities are replayed by **Create Uphold entities**.", "tags": [ "Merchant Auth" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" }, "businessEmail": { "type": "string", "example": "string" }, "password": { "type": "string", "example": "string" }, "displayName": { "type": "string", "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "country": { "type": "string", "example": "string" }, "subdivision": { "type": "string", "example": "string" }, "legalEntityType": { "type": "string", "enum": [ "government-entity", "non-profit", "partnership", "private-limited-company", "public-company", "sole-proprietor" ], "example": "government-entity" }, "termsOfService": { "type": "string", "enum": [ "general-us-hq", "general-gb-fca", "general-pt-bop", "general-lt-fcs", "general-bs-scb" ], "example": "general-us-hq" }, "userIp": { "type": "string", "example": "string" } }, "required": [ "email", "businessEmail", "password", "country", "subdivision", "legalEntityType", "termsOfService" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "active", "blocked", "pending" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "userId", "status" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/create-uphold-entities": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create Uphold entities", "description": "Replays the creation of the signed-in custodial merchant's Uphold business user and BTC account for the case where that step did not go through during **Register (custodial)**. Takes no parameters — everything it needs, including the recorded Terms of Service acceptance, was stored at registration. Idempotent: once the entities exist the call is a no-op and never creates a second pair.", "tags": [ "Merchant Auth" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/get-balance": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Custodial balance", "description": "Custodial merchants only — a non-custodial merchant gets an error rather than zeroes. Returns the merchant's money as three non-overlapping levels in satoshi, so every satoshi is counted exactly once: `inTransitSats` (paid by the buyer, not yet credited to the platform Treasury, gross), `pendingPayoutSats` (credited but not yet paid out — net of the platform fee, and including amounts held by a blocked payout), and `availableSats` (on the merchant's own Uphold account and free to dispose of: the balance Uphold reports as available, minus `reservedSats`). `reservedSats` covers withdrawals the merchant has started that Uphold has not debited yet, and is `0` until withdrawals exist. `balanceAsOf` is the unix second the figures are current as of. `balanceStale` is true when the Uphold balance could not be refreshed: `availableSats` is then the last value seen and must not be shown as current — it is never replaced by a figure computed from our own data. `upholdAccountReady` is false while the merchant's Uphold account has not been created yet, which is why `availableSats` is `0`. `payoutBlocked` is present only while something holds the payout back, carrying a machine-readable `reason` and a `message` for the merchant.", "tags": [ "Dashboard" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "inTransitSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "pendingPayoutSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "availableSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "reservedSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "balanceAsOf": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "balanceStale": { "type": "boolean", "example": true }, "upholdAccountReady": { "type": "boolean", "example": true }, "payoutBlocked": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "uphold_account_missing", "uphold_verification_required", "other" ], "example": "uphold_account_missing" }, "message": { "type": "string", "example": "string" } }, "required": [ "reason", "message" ], "additionalProperties": false } }, "required": [ "inTransitSats", "pendingPayoutSats", "availableSats", "reservedSats", "balanceAsOf", "balanceStale", "upholdAccountReady" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/capabilities": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Custodial capabilities", "description": "Custodial merchants only — a non-custodial merchant gets an error rather than an empty list. Returns what Uphold currently allows the merchant's account to do, taken from the stored snapshot: the call never queries Uphold itself. Each entry of `capabilities` carries Uphold's `code` and `name`, whether it is `enabled`, the `requirements` still **missing** (a non-empty list means the capability does not pass even when `enabled` is true), the `restrictions` in force, and `required` — whether the platform needs it for the merchant to operate. `checkedAt` is the unix second of the last successful check, `null` when none ever succeeded; `capabilities` is then empty because the state is unknown, not because nothing is required. `stale` is true when the last refresh attempt failed, with the reason in `lastError` — the state shown is the last good one and may be out of date, which on its own does not block anything. `actionsBlocked` says whether the merchant's actions (creating payments, sending the payout) are being refused, and `blockingCodes` lists the required capabilities that do not pass. Requirement and restriction codes are free-form strings: Uphold introduces new ones without notice, so show a code you do not recognize as it is.", "tags": [ "Dashboard" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "checkedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "stale": { "type": "boolean", "example": true }, "lastError": { "type": [ "string", "null" ], "example": "string" }, "actionsBlocked": { "type": "boolean", "example": true }, "blockingCodes": { "type": "array", "items": { "type": "string", "example": "string" } }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "string" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "enabled": { "type": "boolean", "example": true }, "requirements": { "type": "array", "items": { "type": "string", "example": "string" } }, "restrictions": { "type": "array", "items": { "type": "string", "example": "string" } }, "required": { "type": "boolean", "example": true } }, "required": [ "code", "name", "enabled", "requirements", "restrictions", "required" ], "additionalProperties": false } } }, "required": [ "checkedAt", "stale", "lastError", "actionsBlocked", "blockingCodes", "capabilities" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/wallet/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Add destination wallet", "description": "Custodial merchants only. Saves a BTC wallet the merchant can later withdraw to. Takes the `address`, an optional `label`, and a `totpCode` — adding a destination is a sensitive action and is gated by the merchant's TOTP. Returns the saved wallet: its `id`, `merchantId`, `address`, `label`, `network`, and `createdAt`. There is no asset field — a custodial merchant only ever holds bitcoin.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "totpCode": { "type": "string", "example": "string" } }, "required": [ "address", "totpCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "merchantId", "address", "label", "network", "createdAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/wallet/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List destination wallets", "description": "Custodial merchants only. Returns the merchant's saved BTC destination wallets as `items`, each with its `id`, `merchantId`, `address`, `label`, `network`, and `createdAt`. Takes no parameters — the merchant comes from the auth context.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "merchantId", "address", "label", "network", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create withdrawal", "description": "Custodial merchants only. Starts a withdrawal of `amountSats` (before fees, in satoshi) from the merchant's Uphold balance to a saved wallet (`walletId`), gated by `totpCode`. Returns the created withdrawal with the quote it was accepted under in `feeSummary` (`amountSats`, `feeSats`, `receivedSats` and Uphold's `feeBreakdown` line items, all in satoshi). `status` is `pending`, or `awaiting_travel_rule` when Uphold requires Travel Rule information first. Typed failures include `insufficient_available_balance`, `amount_below_minimum`, `pending_withdrawal_exists`, `fee_exceeds_amount`, `wallet_not_found`, the address checks (`address_validation_failed`, `address_wrong_network`, `address_not_btc`), the TOTP checks (`totp_required`, `totp_invalid`, `totp_not_configured`), and the eligibility checks (`not_custodial_merchant`, `no_uphold_account`, `withdraw_not_configured`).", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "totpCode": { "type": "string", "example": "string" } }, "required": [ "walletId", "amountSats", "totpCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "walletLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSummary": { "type": "object", "properties": { "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "receivedSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "feeBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 10 } ], "description": "Amount in the payment's fiat `currency`." }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } } }, "required": [ "amountSats", "feeSats", "receivedSats", "feeBreakdown" ], "additionalProperties": false }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "status", "walletId", "address", "walletLabel", "network", "amountSats", "feeSummary", "travelRuleRequired", "createdAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List withdrawals", "description": "Custodial merchants only. Returns the merchant's withdrawals, newest first, as `items` with a `totalCount`. Every filter is optional: `status` narrows to one lifecycle state, `from` / `to` bound the creation time (inclusive unix seconds), and `limit` / `skip` page the result.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "from": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "to": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "example": 20 }, "skip": { "type": "integer", "minimum": 0, "example": 0 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "quotedFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedReceivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "receivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeBreakdown": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 10 } ], "description": "Amount in the payment's fiat `currency`." }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } }, { "type": "null", "example": null } ] }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "walletLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "onchainTxid": { "type": [ "string", "null" ], "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_balance", "capability_failure", "rejected", "fee_changed", "fee_exceeds_amount", "travel_rule_verification_failed", "unknown" ], "example": "insufficient_balance" }, { "type": "null", "example": null } ] }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "status", "walletId", "amountSats", "quotedFeeSats", "quotedReceivedSats", "feeSats", "receivedSats", "feeBreakdown", "address", "walletLabel", "network", "onchainTxid", "failureReason", "travelRuleRequired", "createdAt", "submittedAt", "completedAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get withdrawal", "description": "Custodial merchants only. Fetches one withdrawal by `withdrawalId`. The withdrawal must belong to the authenticated merchant. Returns the full withdrawal item, including its quote (`quotedFeeSats`, `quotedReceivedSats`), the actual fee once settled (`feeSats`, `receivedSats`, `feeBreakdown` — `null` until then), `onchainTxid`, and the lifecycle timestamps.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "withdrawalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "quotedFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedReceivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "receivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeBreakdown": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 10 } ], "description": "Amount in the payment's fiat `currency`." }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } }, { "type": "null", "example": null } ] }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "walletLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "onchainTxid": { "type": [ "string", "null" ], "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_balance", "capability_failure", "rejected", "fee_changed", "fee_exceeds_amount", "travel_rule_verification_failed", "unknown" ], "example": "insufficient_balance" }, { "type": "null", "example": null } ] }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "status", "walletId", "amountSats", "quotedFeeSats", "quotedReceivedSats", "feeSats", "receivedSats", "feeBreakdown", "address", "walletLabel", "network", "onchainTxid", "failureReason", "travelRuleRequired", "createdAt", "submittedAt", "completedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/cancel": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Cancel withdrawal", "description": "Custodial merchants only. Cancels a withdrawal that has not been handed to Uphold yet, releasing the reserved funds and moving it to `canceled`. Returns `{ ok: true }` — the outcome is single-valued, so a failure arrives as a typed error rather than as a withdrawal in another state. An already submitted withdrawal returns `withdrawal_already_submitted`, and one past submission returns `withdrawal_not_cancellable`.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "withdrawalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/travel-rule/session": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Open Travel Rule session", "description": "Custodial merchants only. Opens an Uphold Travel Rule verification session for a withdrawal Uphold is holding (`awaiting_travel_rule`). Returns what Uphold's embedded widget needs to mount, relayed verbatim: `flow`, the widget `url`, a short-lived `token`, and provider-specific `data`. Safe to call repeatedly — nothing about the session is stored, and an expired one is replaced by asking again.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "withdrawalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "flow": { "type": "string", "enum": [ "withdrawal-form" ], "example": "withdrawal-form" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "token": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "data": { "type": "object", "additionalProperties": {}, "example": "string" } }, "required": [ "flow", "url", "token", "data" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/withdraw/travel-rule/submit": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Submit Travel Rule info", "description": "Custodial merchants only. Submits the Travel Rule information the merchant completed in Uphold's widget for a held withdrawal. `payload` is the widget's `complete` result **whole**, including its nested `value` — Uphold requires the envelope intact, so it is required and forwarded verbatim; its inner shape is Uphold's. On success the withdrawal leaves `awaiting_travel_rule` and returns to `pending` for re-evaluation, which is the item returned.", "tags": [ "Custodial Withdrawal" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "payload": { "type": "object", "additionalProperties": {}, "example": "string" } }, "required": [ "withdrawalId", "payload" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "walletId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "quotedFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedReceivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "receivedSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "feeBreakdown": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 10 } ], "description": "Amount in the payment's fiat `currency`." }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } }, { "type": "null", "example": null } ] }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "walletLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "network": { "type": "string", "example": "string" }, "onchainTxid": { "type": [ "string", "null" ], "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_balance", "capability_failure", "rejected", "fee_changed", "fee_exceeds_amount", "travel_rule_verification_failed", "unknown" ], "example": "insufficient_balance" }, { "type": "null", "example": null } ] }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "status", "walletId", "amountSats", "quotedFeeSats", "quotedReceivedSats", "feeSats", "receivedSats", "feeBreakdown", "address", "walletLabel", "network", "onchainTxid", "failureReason", "travelRuleRequired", "createdAt", "submittedAt", "completedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/bank-account/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Add bank account", "description": "Registers an ACH bank account as an Uphold External Account. Full routing/account numbers are sent to Uphold only — we store the last 4 digits. Gated by 2FA (`totpCode`). The account starts in `processing` and transitions to `ok` once Uphold verifies it.", "tags": [ "Custodial Bank Accounts" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "routingNumber": { "type": "string", "example": "string" }, "accountNumber": { "type": "string", "example": "string" }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "example": "checking" }, "holderAddress": { "type": "object", "properties": { "line1": { "type": "string", "example": "string" }, "line2": { "type": "string", "example": "string" }, "city": { "type": "string", "example": "string" }, "state": { "type": "string", "example": "string" }, "zipCode": { "type": "string", "example": "string" }, "country": { "type": "string", "example": "string" } }, "required": [ "line1", "city", "state", "zipCode", "country" ], "additionalProperties": false }, "totpCode": { "type": "string", "example": "string" } }, "required": [ "routingNumber", "accountNumber", "accountType", "holderAddress", "totpCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "routingNumberLast4": { "type": "string", "example": "string" }, "accountNumberLast4": { "type": "string", "example": "string" }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "example": "checking" }, "status": { "type": "string", "enum": [ "processing", "ok", "failed", "expired", "restricted", "blocked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "processing" }, "upholdExternalAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "label", "routingNumberLast4", "accountNumberLast4", "accountType", "status", "upholdExternalAccountId", "createdAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/bank-account/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List bank accounts", "description": "Returns all of the merchant's registered bank accounts as `accounts`, each with masked routing/account numbers, Uphold EA status, and label.", "tags": [ "Custodial Bank Accounts" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "routingNumberLast4": { "type": "string", "example": "string" }, "accountNumberLast4": { "type": "string", "example": "string" }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "example": "checking" }, "status": { "type": "string", "enum": [ "processing", "ok", "failed", "expired", "restricted", "blocked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "processing" }, "upholdExternalAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "label", "routingNumberLast4", "accountNumberLast4", "accountType", "status", "upholdExternalAccountId", "createdAt" ], "additionalProperties": false } } }, "required": [ "accounts" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/bank-account/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get bank account", "description": "Returns a single bank account by `bankAccountId` with up-to-date Uphold status.", "tags": [ "Custodial Bank Accounts" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "bankAccountId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "routingNumberLast4": { "type": "string", "example": "string" }, "accountNumberLast4": { "type": "string", "example": "string" }, "accountType": { "type": "string", "enum": [ "checking", "savings" ], "example": "checking" }, "status": { "type": "string", "enum": [ "processing", "ok", "failed", "expired", "restricted", "blocked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "processing" }, "upholdExternalAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "label", "routingNumberLast4", "accountNumberLast4", "accountType", "status", "upholdExternalAccountId", "createdAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/bank-account/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete bank account", "description": "Soft-deletes the bank account. Fails with `bank_account_has_pending_offramp` if there is an in-flight off-ramp using it. Gated by 2FA (`totpCode`). Returns `{ ok }`.", "tags": [ "Custodial Bank Accounts" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "totpCode": { "type": "string", "example": "string" } }, "required": [ "bankAccountId", "totpCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/quote": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Preview off-ramp quote", "description": "Prices an off-ramp without starting one: what `amountSats` BTC becomes in USD on the bank account identified by `bankAccountId`, what the conversion costs, and how long that price holds. `amountSats` must be a whole number of satoshi greater than zero. Returns an `approvedQuote` — the signed terms `offramp/create` executes on (`terms` with `merchantId`, `quoteId`, `amountSats`, `feeSats`, `netSats`, `bankAccountId`, `destinationAmount`, `destinationAsset`, `exchangeRate`, `expiresAt` and `travelRuleWillBeRequired`, plus a `signature` over them) — and a `feeBreakdown` for display. Satoshi values inside `terms` are decimal strings, which is what they are on the wire in both directions. Render every figure from `terms`: it is the only copy, so there is no second one to disagree with it. Store the `approvedQuote` exactly as received and send it back unmodified; read the countdown from `approvedQuote.terms.expiresAt`. Fails with `quote_failed` when the provider would not price it — never with a zero fee or a zero rate standing in for a price. Creates no off-ramp, reserves no balance and needs no 2FA — nothing moves until the merchant approves the quote by passing the whole `approvedQuote` to `offramp/create`.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]*$", "example": "string" }, { "type": "integer", "exclusiveMinimum": 0, "example": 50000 } ], "description": "Amount in satoshis." } }, "required": [ "bankAccountId", "amountSats" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "approvedQuote": { "type": "object", "properties": { "terms": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "The merchant these terms were issued to. Terms presented by anyone else are refused even though their signature is genuine.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "quoteId": { "type": "string", "description": "Uphold's identifier for this exact price.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Gross BTC debited from the merchant's Uphold account, in satoshis, as a decimal string. A string because that is what satoshi values are on the wire in both directions, and because a signed value must have exactly one representation — send it back character for character.", "example": "string" }, "feeSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Cost of the conversion as quoted, in satoshis, as a decimal string — Uphold's fee for this transfer, not a Bitcoin network fee. Zero is a legitimate quote.", "example": "string" }, "netSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "What is left of `amountSats` after `feeSats`, in satoshis, as a decimal string — the BTC actually converted.", "example": "string" }, "bankAccountId": { "type": "string", "description": "The registered bank account the USD is paid out to.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "destinationAmount": { "type": "string", "minLength": 1, "description": "What arrives at the bank, in `destinationAsset`, as quoted.", "example": "string" }, "destinationAsset": { "type": "string", "minLength": 1, "description": "Currency the payout arrives in, e.g. `USD`.", "example": "string" }, "exchangeRate": { "type": "string", "minLength": 1, "description": "Rate this quote converts at. Signed rather than merely displayed: `offramp/create` rebuilds its answer from these terms and cannot ask the provider again.", "example": "string" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "When this price stops holding, Unix timestamp (seconds). Confirming after it fails with `quote_expired`; request a fresh quote and have the merchant approve that one. Show the countdown from here — this is the value `offramp/create` enforces.", "example": 1718012345 }, "travelRuleWillBeRequired": { "type": "boolean", "description": "Whether Uphold will demand Travel Rule information for this transfer. Signed because it decides the state the off-ramp starts in — `awaiting_travel_rule` rather than `pending` — so it is not a warning a client may adjust. Distinct from the record's `travelRuleRequired`, which means the off-ramp is waiting for that data right now.", "example": true } }, "required": [ "merchantId", "quoteId", "amountSats", "feeSats", "netSats", "bankAccountId", "destinationAmount", "destinationAsset", "exchangeRate", "expiresAt", "travelRuleWillBeRequired" ], "additionalProperties": false, "description": "The terms being approved. This is exactly what the `signature` covers." }, "signature": { "type": "string", "minLength": 1, "description": "The platform's signature over `terms`. Opaque to clients: pass it back unchanged, do not parse it and do not attempt to produce one.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" } }, "required": [ "terms", "signature" ], "additionalProperties": false, "description": "The quote the merchant approved, signed by the platform. Store it exactly as received and send it back to `offramp/create` whole — the amount, the bank account and the fee are read from it rather than from request fields, and any edit invalidates the `signature`." }, "feeBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "type": "string", "description": "Amount in the payment's fiat `currency`.", "example": "string" }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } } }, "required": [ "approvedQuote", "feeBreakdown" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create off-ramp", "description": "Executes an off-ramp the merchant has already approved: send back the `approvedQuote` returned by `offramp/quote` **whole and unmodified** — byte for byte, including the decimal-string satoshi values — together with a 2FA code (`totpCode`). The amount, the bank account, the fee and the whole quoted price are **not** sent as fields — they are taken from `approvedQuote.terms`, whose `signature` the platform verifies before using them, so what executes is the price that was shown, and the `feeSummary` in the answer is rebuilt from those same terms. Fails with `quote_not_found` when the terms do not verify for this merchant — a forged signature, an edited term and terms issued to someone else all answer the same way — and `quote_expired` when `terms.expiresAt` has passed, in which case the merchant approves a fresh quote; the platform never re-prices silently. Returns the created off-ramp with the `feeSummary` that was executed. When `travelRuleRequired` is true the off-ramp starts in `awaiting_travel_rule`.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvedQuote": { "type": "object", "properties": { "terms": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "The merchant these terms were issued to. Terms presented by anyone else are refused even though their signature is genuine.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "quoteId": { "type": "string", "description": "Uphold's identifier for this exact price.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Gross BTC debited from the merchant's Uphold account, in satoshis, as a decimal string. A string because that is what satoshi values are on the wire in both directions, and because a signed value must have exactly one representation — send it back character for character.", "example": "string" }, "feeSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Cost of the conversion as quoted, in satoshis, as a decimal string — Uphold's fee for this transfer, not a Bitcoin network fee. Zero is a legitimate quote.", "example": "string" }, "netSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "What is left of `amountSats` after `feeSats`, in satoshis, as a decimal string — the BTC actually converted.", "example": "string" }, "bankAccountId": { "type": "string", "description": "The registered bank account the USD is paid out to.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "destinationAmount": { "type": "string", "minLength": 1, "description": "What arrives at the bank, in `destinationAsset`, as quoted.", "example": "string" }, "destinationAsset": { "type": "string", "minLength": 1, "description": "Currency the payout arrives in, e.g. `USD`.", "example": "string" }, "exchangeRate": { "type": "string", "minLength": 1, "description": "Rate this quote converts at. Signed rather than merely displayed: `offramp/create` rebuilds its answer from these terms and cannot ask the provider again.", "example": "string" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "When this price stops holding, Unix timestamp (seconds). Confirming after it fails with `quote_expired`; request a fresh quote and have the merchant approve that one. Show the countdown from here — this is the value `offramp/create` enforces.", "example": 1718012345 }, "travelRuleWillBeRequired": { "type": "boolean", "description": "Whether Uphold will demand Travel Rule information for this transfer. Signed because it decides the state the off-ramp starts in — `awaiting_travel_rule` rather than `pending` — so it is not a warning a client may adjust. Distinct from the record's `travelRuleRequired`, which means the off-ramp is waiting for that data right now.", "example": true } }, "required": [ "merchantId", "quoteId", "amountSats", "feeSats", "netSats", "bankAccountId", "destinationAmount", "destinationAsset", "exchangeRate", "expiresAt", "travelRuleWillBeRequired" ], "additionalProperties": false, "description": "The terms being approved. This is exactly what the `signature` covers." }, "signature": { "type": "string", "minLength": 1, "description": "The platform's signature over `terms`. Opaque to clients: pass it back unchanged, do not parse it and do not attempt to produce one.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" } }, "required": [ "terms", "signature" ], "additionalProperties": false, "description": "The quote the merchant approved, signed by the platform. Store it exactly as received and send it back to `offramp/create` whole — the amount, the bank account and the fee are read from it rather than from request fields, and any edit invalidates the `signature`." }, "totpCode": { "type": "string", "example": "string" } }, "required": [ "approvedQuote", "totpCode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "bankAccountId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSummary": { "type": "object", "properties": { "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "netSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "destinationAmount": { "type": "string", "example": "string" }, "destinationAsset": { "type": "string", "example": "string" }, "exchangeRate": { "type": "string", "example": "string" }, "feeBreakdown": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "type": "string", "description": "Amount in the payment's fiat `currency`.", "example": "string" }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } } }, "required": [ "amountSats", "feeSats", "netSats", "destinationAmount", "destinationAsset", "exchangeRate", "feeBreakdown" ], "additionalProperties": false }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "status", "bankAccountId", "amountSats", "feeSummary", "travelRuleRequired", "createdAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List off-ramps", "description": "Lists the merchant's off-ramp operations, newest first. Optionally filter by `status` and an inclusive `from` / `to` unix-second range; `limit` / `skip` paginate. Returns `items` and `totalCount`.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "from": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "to": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "example": 20 }, "skip": { "type": "number", "minimum": 0, "example": 0 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "bankAccountId": { "type": [ "string", "null" ], "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "bankAccountLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "routingNumberLast4": { "type": "string", "example": "string" }, "accountNumberLast4": { "type": "string", "example": "string" }, "accountType": { "type": "string", "example": "string" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "quotedFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedNetSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedDestinationAmount": { "type": [ "string", "null" ], "example": "string" }, "quotedExchangeRate": { "type": [ "string", "null" ], "example": "string" }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "netSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "destinationAmount": { "type": [ "string", "null" ], "example": "string" }, "exchangeRate": { "type": [ "string", "null" ], "example": "string" }, "feeBreakdown": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "type": "string", "description": "Amount in the payment's fiat `currency`.", "example": "string" }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } }, { "type": "null", "example": null } ] }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_balance", "capability_failure", "rejected", "fee_changed", "fee_exceeds_amount", "max_attempts_exceeded", "travel_rule_verification_failed", "bank_account_invalid", "unknown" ], "example": "insufficient_balance" }, { "type": "null", "example": null } ] }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "status", "bankAccountId", "bankAccountLabel", "routingNumberLast4", "accountNumberLast4", "accountType", "amountSats", "quotedFeeSats", "quotedNetSats", "quotedDestinationAmount", "quotedExchangeRate", "feeSats", "netSats", "destinationAmount", "exchangeRate", "feeBreakdown", "failureReason", "travelRuleRequired", "createdAt", "submittedAt", "completedAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get off-ramp", "description": "Returns the full off-ramp record for `offrampId`, including quoted vs. settled fee figures, exchange rate, USD destination amount, `feeBreakdown`, `failureReason`, and lifecycle timestamps.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offrampId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "offrampId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "awaiting_travel_rule", "submitting", "processing", "on_hold", "completed", "failed", "canceled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "bankAccountId": { "type": [ "string", "null" ], "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "bankAccountLabel": { "type": [ "string", "null" ], "example": "Front desk" }, "routingNumberLast4": { "type": "string", "example": "string" }, "accountNumberLast4": { "type": "string", "example": "string" }, "accountType": { "type": "string", "example": "string" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "quotedFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedNetSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "quotedDestinationAmount": { "type": [ "string", "null" ], "example": "string" }, "quotedExchangeRate": { "type": [ "string", "null" ], "example": "string" }, "feeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Network fee for the transaction, in satoshis." }, "netSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] }, "destinationAmount": { "type": [ "string", "null" ], "example": "string" }, "exchangeRate": { "type": [ "string", "null" ], "example": "string" }, "feeBreakdown": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "withdraw" }, "code": { "type": "string", "example": "string" }, "asset": { "type": "string", "example": "string" }, "amount": { "type": "string", "description": "Amount in the payment's fiat `currency`.", "example": "string" }, "percentage": { "type": "number", "example": 0 } }, "required": [ "type", "code", "asset", "amount" ], "additionalProperties": false } }, { "type": "null", "example": null } ] }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_balance", "capability_failure", "rejected", "fee_changed", "fee_exceeds_amount", "max_attempts_exceeded", "travel_rule_verification_failed", "bank_account_invalid", "unknown" ], "example": "insufficient_balance" }, { "type": "null", "example": null } ] }, "travelRuleRequired": { "type": "boolean", "example": true }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "id", "status", "bankAccountId", "bankAccountLabel", "routingNumberLast4", "accountNumberLast4", "accountType", "amountSats", "quotedFeeSats", "quotedNetSats", "quotedDestinationAmount", "quotedExchangeRate", "feeSats", "netSats", "destinationAmount", "exchangeRate", "feeBreakdown", "failureReason", "travelRuleRequired", "createdAt", "submittedAt", "completedAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/cancel": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Cancel off-ramp", "description": "Cancels the off-ramp identified by `offrampId` while it has not yet been submitted to Uphold. Fails with `offramp_already_submitted` once it has left the platform. Returns `{ ok }`.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offrampId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "offrampId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/travel-rule/session": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Open Travel Rule session", "description": "Opens an Uphold Travel Rule widget session for the off-ramp identified by `offrampId`, bound to its quote. Returns the session Uphold issued, relayed verbatim: `flow`, the `url` the widget mounts, a short-lived `token` and provider-specific `data` forwarded unchanged. Mount the widget with it and let the merchant complete the form there — the personal details go to the provider, never to this API. There is no expiry to compare against: the session is short-lived and single-use, so call this again to replace a stale one.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offrampId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "offrampId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "flow": { "type": "string", "enum": [ "withdrawal-form" ], "description": "Which Uphold widget form to mount.", "example": "withdrawal-form" }, "url": { "type": "string", "description": "Base URL the Uphold Travel Rule widget mounts from.", "example": "string" }, "token": { "type": "string", "description": "Short-lived auth token for this widget session.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "data": { "type": "object", "additionalProperties": {}, "description": "Provider-specific initialization data for the widget, forwarded unchanged. Its shape is Uphold's and changes without notice — hand it to the widget rather than reading it.", "example": "string" } }, "required": [ "flow", "url", "token", "data" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/custodial/offramp/travel-rule/submit": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Check Travel Rule requirement", "description": "Asks whether the Travel Rule requirement on `offrampId` has been closed, after the merchant has finished in the widget. Takes nothing else: the platform collects no personal data and forwards none, so there is no payload to send and no session to identify — it reads the quote from the off-ramp and asks Uphold for the status of the request for information on it. Returns `released` — whether the off-ramp left `awaiting_travel_rule` and is executing again — and the `status` behind it: `cleared` (closed, released), `pending` (evidence still settling — wait and call again, the same session stands), `failed` (rejected — open a **new** session and redo), `expired` (lapsed — also a new session), `unchecked` (no request for information, or Uphold could not be asked — released anyway, since not knowing is not a refusal). Branch on `released`; show `status`. Safe to call repeatedly.", "tags": [ "Custodial Off-Ramp" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offrampId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "offrampId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cleared", "pending", "failed", "expired", "unchecked" ], "description": "Uphold's verdict on the request for information attached to the quote — **not** a payment or off-ramp status. `cleared`: closed, the off-ramp is released. `pending`: the evidence is still settling, wait and call again with the same session. `failed`: rejected — the merchant needs a **new** session. `expired`: the requirement lapsed — also a new session. `unchecked`: there is no such request, or Uphold could not be asked, and the off-ramp is released anyway because not knowing is not a refusal.", "example": "cleared" }, "released": { "type": "boolean", "description": "Whether the off-ramp left `awaiting_travel_rule` and is executing again. Branch on this. It follows `status` exactly — true for `cleared` and `unchecked`, false for `pending`, `failed` and `expired` — and the two can never disagree: a response pairing them any other way is rejected.", "example": true } }, "required": [ "status", "released" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/payment/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create payment", "description": "Creates a payment from the merchant cabinet. Authorization is the merchant bearer token — no `posTerminalId` or signature is sent: the payment is booked on the merchant's system POS (created lazily on first use). Specify the `amount` and `currency`; the response includes the satoshi amount, the BTC price snapshot, an `expiresAt` deadline, and a `qrString` to present to the payer. Pass an optional `externalId` (your order / invoice id) to make the call idempotent.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "externalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "ttlSeconds": { "type": "number", "example": 900 } }, "required": [ "amount", "currency" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount in satoshis.", "example": "string" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "checkoutUrl": { "type": "string", "example": "string" }, "version": { "type": "integer", "minimum": 0, "example": 0 }, "btcAddress": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" } }, "required": [ "paymentId", "status", "merchantId", "merchantName", "storeId", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "externalId", "amountSats", "currency", "amount", "expiresAt", "btcPriceInUsd", "btcPriceInCurrency", "checkoutUrl", "version", "btcAddress", "qrString" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/merchant/payment/create\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"amount\": 10,\n \"currency\": \"USD\",\n \"externalId\": \"order_123\"\n}'" } ] } }, "/merchant/payment/get": { "post": { "security": [], "summary": "Get payment", "description": "Returns the current state of a payment by `paymentId`, including its `status`, amounts, merchant / POS details, and `qrString`. This endpoint requires no authorization, so the payer can poll it directly to track a payment until it is paid or expired.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "paymentId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "initiated" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "merchantDisplayName": { "type": [ "string", "null" ], "description": "Merchant's public display name (may be null).", "example": "Satoshi Coffee" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "Amount in satoshis.", "example": "string" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "qrString": { "type": "string", "description": "Payment encoded as a BIP-21 URI, ready to render as a QR code.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" }, "version": { "type": "integer", "minimum": 0, "example": 0 }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex) of this receipt. Look it up in any block explorer to show the payer their transaction.", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "amountSats": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "description": "What this transaction paid into **this payment's** address, in satoshis — not the transaction's total, which may pay other outputs as well.", "example": "string" }, "blockHeight": { "anyOf": [ { "type": "number", "example": 845000 }, { "type": "null", "example": null } ], "description": "Height of the block that included the transaction; `null` while it is still in the mempool." }, "blockTime": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Timestamp of that block, Unix seconds; `null` while the transaction is still in the mempool. Historical payments confirmed before this field existed report `null` permanently." }, "confirmations": { "anyOf": [ { "type": "integer", "minimum": 0, "example": 0 }, { "type": "null", "example": null } ], "description": "Confirmations as of **now**, not as of the moment the payment was paid, so the value keeps growing. `0` — seen but not in a block yet. `null` — the current chain tip is not known to us right now, so the count cannot be stated; do not render it as zero, the transaction may well be deeply confirmed. The remaining fields are unaffected." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$", "example": "string" }, { "type": "null", "example": null } ], "description": "Network fee the payer paid for this transaction, in satoshis; `null` when it is not known to us." } }, "required": [ "txid", "amountSats", "blockHeight", "blockTime", "confirmations", "feeSats" ], "additionalProperties": false }, "default": [], "description": "On-chain transactions observed paying this payment, freshest first. Empty until something is seen — and empty is a normal state for a payment in `initiated`. More than one element means the payer sent more than one transaction (an overpayment or a top-up); sum `amountSats` across the list to get what actually arrived. Identical for both payment routes: an in-app payment reports its single transaction here just like one paid from an external wallet." }, "paidAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "default": null, "description": "When the payment was paid, Unix timestamp (seconds); `null` until then. This is the payment's settlement time — for when a single transaction was mined see `transactions[].blockTime`." } }, "required": [ "paymentId", "status", "merchantId", "currency", "merchantName", "storeId", "posTerminalLabel", "posTerminalLocation", "merchantDisplayName", "posTerminalId", "externalId", "amountSats", "btcPriceInUsd", "btcPriceInCurrency", "amount", "expiresAt", "qrString", "version" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/merchant/payment/get\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"paymentId\": \"pay_…\"\n}'" } ] } }, "/merchant/payment/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List payments", "description": "Returns a paginated list of the merchant's payments (the payment entity, not the on-chain transaction), scoped to the authenticated merchant. Supports optional `dateRange`, `status`, `storeIds`, `posIds`, `currency`, `externalId` and `system` filters. For the report of already-paid transactions use `/merchant/reports/transactions`.", "tags": [ "Payments" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false }, "storeIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "posIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "status": { "type": "array", "items": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "example": "initiated" }, "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`." }, "externalId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "system": { "type": "boolean", "example": true }, "paymentIds": { "type": "array", "items": { "type": "string", "example": "string" }, "description": "Return only these payments. Narrows the selection **within your own payments** — an id belonging to another merchant simply matches nothing. Omit for no restriction by id; an empty list matches no payment." } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "initiated" }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description.", "example": "Order #1024" }, "metadata": { "description": "Internal system metadata attached to the payment (reserved; not set by clients).", "example": {} }, "network": { "type": "string", "enum": [ "mainnet", "testnet" ], "example": "mainnet" }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "externalId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "btcAddress": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "settlement": { "anyOf": [ { "type": "object", "properties": { "settledAt": { "type": "integer", "minimum": 0, "description": "When the payment was credited to the platform, Unix timestamp (seconds).", "example": 1718012345 }, "status": { "type": "string", "enum": [ "settled", "reversed" ], "description": "Result of the credit: `settled` — credited to the platform; `reversed` — the credit was rolled back.", "example": "settled" }, "platformFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Platform fee withheld from this payment, in satoshis. `null` when the fee is not known for this payment (credited before fees were introduced) — not zero." }, "netSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Credited to the merchant **for this payment**, in satoshis: the payment amount minus the withheld platform fee. `null` when the fee is unknown, together with `platformFeeSats`. This is the payment's own share — for the total transferred see `settlement.payout.batchAmountSats`." }, "payout": { "anyOf": [ { "type": "object", "properties": { "payoutId": { "type": "string", "description": "Unique id of the payout.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "preparing", "processing", "on_hold", "completed", "failed", "blocked" ], "description": "State of the payout: `preparing` — assembled and on its way out; `processing` — submitted, not finished yet; `on_hold` — held by Uphold (typically a compliance check); `completed` — the money reached the merchant's account; `failed` — the transfer did not go through; `blocked` — the platform is holding it back, see `blockedReason`.", "example": "preparing" }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "When the payout was submitted for transfer, Unix timestamp (seconds); `null` while it is still being prepared or is blocked." }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "When the payout finished, Unix timestamp (seconds); `null` until then." }, "upholdTransactionId": { "type": [ "string", "null" ], "description": "Id of the transfer in Uphold, once there is one; `null` otherwise.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "blockedReason": { "type": [ "string", "null" ], "description": "Why the payout is being held back — set when `status` is `blocked`, `null` otherwise.", "example": "string" }, "batchAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Total amount of the **whole payout**, in satoshis. One payout covers several payments, so this is normally larger than what this payment contributed — that figure is `settlement.netSats`. **Absent** for a credential limited to one store or to a set of POS terminals: a payout is assembled per merchant, so this total covers stores such a credential has no access to. Absent means not disclosed to you, not zero." }, "batchPaymentCount": { "type": "number", "description": "How many payments this payout covers, including the current one. **Absent** for a credential limited to one store or to a set of POS terminals, for the same reason as `batchAmountSats` — and absent means not disclosed to you, not a payout of no payments.", "example": 0 } }, "required": [ "payoutId", "status", "submittedAt", "completedAt", "upholdTransactionId", "blockedReason" ], "additionalProperties": false }, { "type": "null", "example": null } ], "description": "The payout this payment was paid out by. `null` — the payment is credited to the platform but no payout has been assembled yet." } }, "required": [ "settledAt", "status", "platformFeeSats", "netSats", "payout" ], "additionalProperties": false }, { "type": "null", "example": null } ], "description": "How this payment was settled with the platform: when it was credited, what fee was withheld, and the payout it was paid out by. `null` — the payment did not go through the custodial path (funds went straight to the merchant's own wallet) or has not been credited yet. Absent settlement means no credit happened, not a credit of zero." } }, "required": [ "paymentId", "status", "amount", "amountSats", "currency", "description", "network", "btcPriceInUsd", "btcPriceInCurrency", "externalId", "createdAt", "expiresAt", "btcAddress", "storeId", "posTerminalId", "posTerminalLabel", "posTerminalLocation", "settlement" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"$BASE_URL/merchant/payment/list\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"pagination\": {\n \"limit\": 20,\n \"skip\": 0\n }\n}'" } ] } }, "/merchant/store/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create store", "description": "Creates a new store for the authenticated merchant. Accepts a required `name` and optional `address`, `country`, and `timezone`. Returns the created `store`, including its `id`, `merchantId`, `status`, and `posCount`.", "tags": [ "Stores" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "country": { "type": "string", "example": "string" }, "lat": { "type": "number", "example": 1718012345 }, "lng": { "type": "number", "example": 0 }, "timezone": { "type": "string", "example": "string" } }, "required": [ "name" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "store": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "anyOf": [ { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, { "type": "null", "example": null } ] }, "country": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "lat": { "anyOf": [ { "type": "number", "example": 1718012345 }, { "type": "null", "example": null } ] }, "lng": { "anyOf": [ { "type": "number", "example": 0 }, { "type": "null", "example": null } ] }, "timezone": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "posCount": { "type": "number", "example": 0 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "name", "address", "country", "lat", "lng", "timezone", "status", "posCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "store" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get store", "description": "Fetches a single store by `storeId`. Returns the `store` object with `name`, `address`, `country`, `timezone`, `status`, `posCount`, and timestamps.", "tags": [ "Stores" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "storeId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "store": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "anyOf": [ { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, { "type": "null", "example": null } ] }, "country": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "lat": { "anyOf": [ { "type": "number", "example": 1718012345 }, { "type": "null", "example": null } ] }, "lng": { "anyOf": [ { "type": "number", "example": 0 }, { "type": "null", "example": null } ] }, "timezone": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "posCount": { "type": "number", "example": 0 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "name", "address", "country", "lat", "lng", "timezone", "status", "posCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "store" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List stores", "description": "Lists the merchant's stores with optional `pagination` (`limit`, `skip`) and `filters` (`status`, free-text `query`). Returns `items` (array of stores) and `totalCount`.", "tags": [ "Stores" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "query": { "type": "string", "example": "string" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "anyOf": [ { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, { "type": "null", "example": null } ] }, "country": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "lat": { "anyOf": [ { "type": "number", "example": 1718012345 }, { "type": "null", "example": null } ] }, "lng": { "anyOf": [ { "type": "number", "example": 0 }, { "type": "null", "example": null } ] }, "timezone": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "posCount": { "type": "number", "example": 0 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "name", "address", "country", "lat", "lng", "timezone", "status", "posCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/update": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update store", "description": "Updates the store identified by `storeId`. Optionally changes `name`, `address`, `country`, `timezone`, and `status` (active or disabled; deleted is reserved for the delete endpoint). Returns the updated `store`.", "tags": [ "Stores" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "country": { "type": "string", "example": "string" }, "lat": { "type": "number", "example": 1718012345 }, "lng": { "type": "number", "example": 0 }, "timezone": { "type": "string", "example": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "storeId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "store": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "name": { "type": "string", "example": "Satoshi Coffee" }, "address": { "anyOf": [ { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, { "type": "null", "example": null } ] }, "country": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "lat": { "anyOf": [ { "type": "number", "example": 1718012345 }, { "type": "null", "example": null } ] }, "lng": { "anyOf": [ { "type": "number", "example": 0 }, { "type": "null", "example": null } ] }, "timezone": { "anyOf": [ { "type": "string", "example": "string" }, { "type": "null", "example": null } ] }, "status": { "type": "string", "enum": [ "active", "disabled", "deleted" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "posCount": { "type": "number", "example": 0 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "name", "address", "country", "lat", "lng", "timezone", "status", "posCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "store" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete store", "description": "Soft-deletes the store identified by `storeId`, setting its `status` to deleted. Returns `{ ok }`.", "tags": [ "Stores" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "storeId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create POS terminal", "description": "Creates a POS terminal under the given `storeId`, with optional `label` and `location`. Returns the `posTerminal`, including the freshly issued `apiKey`.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": "string", "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" } }, "required": [ "storeId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "posTerminal": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": [ "string", "null" ], "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "apiKey": { "type": "string", "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal.", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "id", "storeId", "merchantId", "label", "location", "status" ], "additionalProperties": false } }, "required": [ "posTerminal" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get POS terminal", "description": "Fetches a single POS terminal by `posTerminalId`. Returns the `posTerminal` with its `storeId`, `label`, `location`, `status`, and its `apiKey`.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "posTerminalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "posTerminal": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": [ "string", "null" ], "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "apiKey": { "type": "string", "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal.", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "id", "storeId", "merchantId", "label", "location", "status", "apiKey" ], "additionalProperties": false } }, "required": [ "posTerminal" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List POS terminals", "description": "Lists POS terminals with optional `pagination` and `filters` by `storeId` and `status`. Returns `items` and `totalCount`.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": [ "string", "null" ], "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "apiKey": { "type": "string", "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal.", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "id", "storeId", "merchantId", "label", "location", "status" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/update": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update POS terminal", "description": "Updates the `label`, `location`, and/or `status` of the POS terminal identified by `posTerminalId`. Returns the updated `posTerminal`; the `apiKey` is not re-issued.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": "string", "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "required": [ "posTerminalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "posTerminal": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "location": { "type": [ "string", "null" ], "description": "Physical location of the POS terminal (optional).", "example": "Lisbon, PT" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "apiKey": { "type": "string", "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal.", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "id", "storeId", "merchantId", "label", "location", "status" ], "additionalProperties": false } }, "required": [ "posTerminal" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete POS terminal", "description": "Deletes the POS terminal identified by `posTerminalId`. Returns `{ ok }`.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "posTerminalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/store/pos/rotate-api-key": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Rotate POS API key", "description": "Rotates the API key for the POS terminal identified by `posTerminalId`, invalidating the previous key and returning a fresh `apiKey`.", "tags": [ "POS Terminals" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "posTerminalId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal.", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "apiKey" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get member", "description": "Returns a single team member identified by `membershipId`. The response `member` includes `userId`, `email`, `displayName`, `role`, `status`, and `createdAt`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "membershipId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "membershipId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "email": { "type": "string", "example": "string" }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "access": { "type": "object", "properties": { "stores": { "type": "array", "items": { "type": "string", "example": "string" } }, "posTerminals": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "stores", "posTerminals" ], "additionalProperties": false } }, "required": [ "id", "userId", "merchantId", "role", "status", "email", "displayName", "createdAt", "access" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List members", "description": "Lists team members for the active merchant. Supports `pagination` (`limit`, `skip`) and `filters` by `role`, `status`, and a free-text `query`. Returns `items` (each member with `email`, `role`, `status`) and `totalCount`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "query": { "type": "string", "example": "string" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "email": { "type": "string", "example": "string" }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "access": { "type": "object", "properties": { "stores": { "type": "array", "items": { "type": "string", "example": "string" } }, "posTerminals": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "stores", "posTerminals" ], "additionalProperties": false } }, "required": [ "id", "userId", "merchantId", "role", "status", "email", "displayName", "createdAt", "access" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/invite": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Invite member", "description": "Invites a user to the active merchant by `email` with the given `role`. Returns the created `invite` including its `id`, `email`, `role`, `status`, and `expiresAt`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "string" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "access": { "type": "object", "properties": { "stores": { "type": "array", "items": { "type": "string", "example": "string" } }, "posTerminals": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "stores", "posTerminals" ], "additionalProperties": false } }, "required": [ "email", "role" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "merchantId", "email", "role", "status", "expiresAt", "createdAt" ], "additionalProperties": false } }, "required": [ "invite" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/invite/accept": { "post": { "security": [], "summary": "Accept invite", "description": "Accepts a pending invitation using the invite `token`. Returns the created or activated `member` for the current user, including its `role`, `status`, and `email`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "token" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "email": { "type": "string", "example": "string" }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "access": { "type": "object", "properties": { "stores": { "type": "array", "items": { "type": "string", "example": "string" } }, "posTerminals": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "stores", "posTerminals" ], "additionalProperties": false } }, "required": [ "id", "userId", "merchantId", "role", "status", "email", "displayName", "createdAt", "access" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/invite/info": { "post": { "security": [], "summary": "Get invite info", "description": "Reads a pending invitation by its `token` without accepting it. Returns the inviting merchant (`merchantName`, `merchantLogoUrl`), the invited `email`, the offered `role`, the current `status` and `expiresAt` — so the invite screen can show who is inviting before the user commits.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "required": [ "token" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantName": { "type": "string", "description": "Merchant's internal name.", "example": "Satoshi Coffee" }, "merchantLogoUrl": { "type": [ "string", "null" ], "example": "string" }, "email": { "type": "string", "example": "string" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "merchantId", "merchantName", "merchantLogoUrl", "email", "role", "status", "expiresAt", "createdAt" ], "additionalProperties": false } }, "required": [ "invite" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/invite/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List invites", "description": "Lists invitations for the active merchant. Supports `pagination` (`limit`, `skip`) and a `status` filter. Returns `items` (each invite with `email`, `role`, `status`, `expiresAt`) and `totalCount`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "email": { "type": "string", "example": "string" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "merchantId", "email", "role", "status", "expiresAt", "createdAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/invite/revoke": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Revoke invite", "description": "Revokes a pending invitation identified by `inviteId`. Returns `{ ok }`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inviteId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "inviteId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/remove": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Remove member", "description": "Removes the membership identified by `membershipId` from the active merchant. Returns `{ ok }`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "membershipId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "membershipId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/users/update-role": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update member role", "description": "Updates the `role` of the membership identified by `membershipId`. Returns the updated `member`.", "tags": [ "Team & Access" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "membershipId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" } }, "required": [ "membershipId", "role" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "userId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role": { "type": "string", "enum": [ "admin", "manager" ], "example": "admin" }, "status": { "type": "string", "enum": [ "active", "invited", "revoked" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "email": { "type": "string", "example": "string" }, "displayName": { "type": [ "string", "null" ], "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "access": { "type": "object", "properties": { "stores": { "type": "array", "items": { "type": "string", "example": "string" } }, "posTerminals": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "stores", "posTerminals" ], "additionalProperties": false } }, "required": [ "id", "userId", "merchantId", "role", "status", "email", "displayName", "createdAt", "access" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/reports/sales-summary": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Sales summary", "description": "Returns headline sales `totals` (`paymentsCount`, `grossAmount`, `grossSats`, `avgTicket`, `currency`) plus a `breakdown` array for a `dateRange`, optionally narrowed by `filters` (`storeIds`, `posIds`, `currency`).", "tags": [ "Reports" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "storeIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "posIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" } }, "additionalProperties": false } }, "required": [ "dateRange" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "paymentsCount": { "type": "number", "example": 0 }, "grossAmount": { "type": "number", "example": 10 }, "grossSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "avgTicket": { "type": "number", "example": 0 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" } }, "required": [ "paymentsCount", "grossAmount", "grossSats", "avgTicket", "currency" ], "additionalProperties": false }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "string" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "paymentsCount": { "type": "number", "example": 0 }, "grossAmount": { "type": "number", "example": 10 }, "grossSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] } }, "required": [ "key", "label", "paymentsCount", "grossAmount", "grossSats" ], "additionalProperties": false } } }, "required": [ "totals", "breakdown" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/reports/transactions": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Transactions report", "description": "Lists detailed report transactions for a `dateRange` with `pagination` (`limit`, `skip`) and optional `filters` (`storeIds`, `posIds`, `status`, `currency`); responds with `items`, `totalCount`, and aggregate `totals`.", "tags": [ "Reports" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false }, "filters": { "type": "object", "properties": { "storeIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "posIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "status": { "type": "array", "items": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "example": "initiated" }, "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`." }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "system": { "type": "boolean", "example": true } }, "additionalProperties": false } }, "required": [ "dateRange" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "paymentTxId": { "anyOf": [ { "type": "string", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, { "type": "null", "example": null } ], "description": "Identifier of the payment transaction (UUID)." }, "status": { "anyOf": [ { "type": "string", "enum": [ "success", "failed", "pending", "cleared" ], "example": "success" }, { "type": "null", "example": null } ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`." }, "paymentStatus": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "example": "initiated" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "storeName": { "type": "string", "example": "string" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "posTerminalLabel": { "type": [ "string", "null" ], "description": "Label of the POS terminal (may be null).", "example": "Front desk" }, "posTerminalLocation": { "type": [ "string", "null" ], "description": "Location of the POS terminal (may be null).", "example": "Lisbon, PT" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "description": { "type": [ "string", "null" ], "description": "Human-readable description.", "example": "Order #1024" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "btcPriceInUsd": { "type": "number", "description": "BTC/USD price captured when the payment was created.", "example": 65000 }, "btcPriceInCurrency": { "type": "number", "description": "BTC price in the payment's `currency`, captured when the payment was created.", "example": 65000 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" }, "amount": { "type": "number", "description": "Amount in the payment's fiat `currency`.", "example": 10 }, "currencySymbol": { "anyOf": [ { "type": "string", "example": "$" }, { "not": {}, "example": {} } ], "description": "Display symbol of the currency, e.g. `$`." }, "onChain": { "anyOf": [ { "type": "object", "properties": { "tx": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "02000000000101a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6071829ffffffff" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "tx", "amountSats", "feeSats", "createdAt" ], "additionalProperties": false }, { "type": "null", "example": null } ] }, "settlement": { "anyOf": [ { "type": "object", "properties": { "settledAt": { "type": "integer", "minimum": 0, "description": "When the payment was credited to the platform, Unix timestamp (seconds).", "example": 1718012345 }, "status": { "type": "string", "enum": [ "settled", "reversed" ], "description": "Result of the credit: `settled` — credited to the platform; `reversed` — the credit was rolled back.", "example": "settled" }, "platformFeeSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Platform fee withheld from this payment, in satoshis. `null` when the fee is not known for this payment (credited before fees were introduced) — not zero." }, "netSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ], "description": "Credited to the merchant **for this payment**, in satoshis: the payment amount minus the withheld platform fee. `null` when the fee is unknown, together with `platformFeeSats`. This is the payment's own share — for the total transferred see `settlement.payout.batchAmountSats`." }, "payout": { "anyOf": [ { "type": "object", "properties": { "payoutId": { "type": "string", "description": "Unique id of the payout.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "preparing", "processing", "on_hold", "completed", "failed", "blocked" ], "description": "State of the payout: `preparing` — assembled and on its way out; `processing` — submitted, not finished yet; `on_hold` — held by Uphold (typically a compliance check); `completed` — the money reached the merchant's account; `failed` — the transfer did not go through; `blocked` — the platform is holding it back, see `blockedReason`.", "example": "preparing" }, "submittedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "When the payout was submitted for transfer, Unix timestamp (seconds); `null` while it is still being prepared or is blocked." }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "When the payout finished, Unix timestamp (seconds); `null` until then." }, "upholdTransactionId": { "type": [ "string", "null" ], "description": "Id of the transfer in Uphold, once there is one; `null` otherwise.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "blockedReason": { "type": [ "string", "null" ], "description": "Why the payout is being held back — set when `status` is `blocked`, `null` otherwise.", "example": "string" }, "batchAmountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Total amount of the **whole payout**, in satoshis. One payout covers several payments, so this is normally larger than what this payment contributed — that figure is `settlement.netSats`. **Absent** for a credential limited to one store or to a set of POS terminals: a payout is assembled per merchant, so this total covers stores such a credential has no access to. Absent means not disclosed to you, not zero." }, "batchPaymentCount": { "type": "number", "description": "How many payments this payout covers, including the current one. **Absent** for a credential limited to one store or to a set of POS terminals, for the same reason as `batchAmountSats` — and absent means not disclosed to you, not a payout of no payments.", "example": 0 } }, "required": [ "payoutId", "status", "submittedAt", "completedAt", "upholdTransactionId", "blockedReason" ], "additionalProperties": false }, { "type": "null", "example": null } ], "description": "The payout this payment was paid out by. `null` — the payment is credited to the platform but no payout has been assembled yet." } }, "required": [ "settledAt", "status", "platformFeeSats", "netSats", "payout" ], "additionalProperties": false }, { "type": "null", "example": null } ], "description": "How this payment was settled with the platform: when it was credited, what fee was withheld, and the payout it was paid out by. `null` — the payment did not go through the custodial path (funds went straight to the merchant's own wallet) or has not been credited yet. Absent settlement means no credit happened, not a credit of zero." } }, "required": [ "paymentId", "paymentTxId", "status", "paymentStatus", "storeId", "storeName", "posTerminalId", "posTerminalLabel", "posTerminalLocation", "amountSats", "description", "createdAt", "btcPriceInUsd", "btcPriceInCurrency", "currency", "amount", "onChain", "settlement" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 }, "totals": { "type": "object", "properties": { "paymentsCount": { "type": "number", "example": 0 }, "grossAmount": { "type": "number", "example": 10 }, "grossSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "avgTicket": { "type": "number", "example": 0 }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" } }, "required": [ "paymentsCount", "grossAmount", "grossSats", "avgTicket", "currency" ], "additionalProperties": false } }, "required": [ "items", "totalCount", "totals" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/reports/aggregated": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Aggregated report", "description": "Aggregates payments over a `dateRange` bucketed by `groupBy`, with optional `filters` (`storeIds`, `posIds`, `currency`) and a `metrics` selector (defaults to count and gross); returns the resulting `groups`.", "tags": [ "Reports" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false }, "groupBy": { "type": "string", "enum": [ "day", "week", "month", "store", "pos", "currency", "status" ], "example": "day" }, "filters": { "type": "object", "properties": { "storeIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "posIds": { "type": "array", "items": { "type": "string", "example": "string" } }, "currency": { "type": "string", "description": "Fiat currency code (ISO 4217), e.g. `USD`.", "example": "USD" } }, "additionalProperties": false }, "metrics": { "type": "array", "items": { "type": "string", "example": "string" } } }, "required": [ "dateRange", "groupBy" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "string" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "paymentsCount": { "type": "number", "example": 0 }, "grossAmount": { "type": "number", "example": 10 }, "grossSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] } }, "required": [ "key", "label", "paymentsCount", "grossAmount", "grossSats" ], "additionalProperties": false } } }, "required": [ "groups" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/reports/export": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create export", "description": "Starts an asynchronous report export for the given `type`, `format`, `dateRange`, and `filters`, returning a `reportJobId` and initial `status`. Poll `/merchant/reports/export/status` with the `reportJobId` to retrieve the download URL once ready.", "tags": [ "Reports" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sales_summary", "transaction_detail", "aggregated" ], "example": "sales_summary" }, "format": { "type": "string", "enum": [ "json", "csv" ], "example": "json" }, "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false }, "filters": { "example": {} } }, "required": [ "type", "format", "dateRange" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "reportJobId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" } }, "required": [ "reportJobId", "status" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/reports/export/status": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Export status", "description": "Polls an export job by `reportJobId` and returns its `status`, plus a `downloadUrl` and `expiresAt` that are populated once the job is `ready` (both null while still processing).", "tags": [ "Reports" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reportJobId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "reportJobId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "downloadUrl": { "type": [ "string", "null" ], "example": "string" }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." } }, "required": [ "status", "downloadUrl", "expiresAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create webhook", "description": "Registers a webhook endpoint. Provide the destination `url` and a `scope` (`merchant` for the whole account, or `store` / `pos` to narrow delivery); `events` defaults to all event types. The response includes the `signingSecret` **shown only once** — store it to verify the `X-GoBTCPay-Signature` header on incoming deliveries.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" } }, "required": [ "url", "scope" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "signingSecret": { "type": "string", "description": "Per-endpoint secret used to verify the `X-GoBTCPay-Signature` header. Returned only on create — store it securely.", "example": "string" } }, "required": [ "id", "merchantId", "url", "scope", "events", "status", "label", "createdAt", "updatedAt", "signingSecret" ], "additionalProperties": false } }, "required": [ "webhook" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List webhooks", "description": "Lists the merchant's webhook endpoints with optional `pagination` and a `status` filter. Returns `items` and `totalCount`. The `signingSecret` is never included.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "url", "scope", "events", "status", "label", "createdAt", "updatedAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get webhook", "description": "Fetches a single webhook endpoint by `webhookId`. The `signingSecret` is not returned — rotate it to obtain a new one.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "webhookId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "url", "scope", "events", "status", "label", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "webhook" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/update": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update webhook", "description": "Updates the `url`, `scope`, `events`, `status` (active / disabled), and/or `label` of the webhook identified by `webhookId`. Returns the updated endpoint; the `signingSecret` is not re-issued.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" } }, "required": [ "webhookId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "merchantId": { "type": "string", "description": "Identifier of the merchant (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "url": { "type": "string", "description": "Destination URL that receives webhook deliveries.", "example": "string" }, "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "merchant", "example": "merchant" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "store", "example": "store" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "storeId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pos", "example": "pos" }, "posTerminalId": { "type": "string", "description": "Identifier of the POS terminal (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "type", "posTerminalId" ], "additionalProperties": false } ], "description": "Which payments this endpoint receives: `merchant` (whole account), or `store` / `pos` to narrow delivery to one store or terminal." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.status.updated" ], "example": "payment.status.updated" }, "description": "Event types this endpoint is subscribed to." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "active" }, "label": { "type": [ "string", "null" ], "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "updatedAt": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "id", "merchantId", "url", "scope", "events", "status", "label", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "webhook" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete webhook", "description": "Deletes the webhook endpoint identified by `webhookId`. Returns `{ ok }`.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "webhookId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/rotate-secret": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Rotate webhook secret", "description": "Rotates the signing secret for the webhook identified by `webhookId`, invalidating the previous secret and returning a fresh `signingSecret` (shown only once).", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "webhookId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "The freshly rotated signing secret. Returned once — store it securely.", "example": "string" } }, "required": [ "signingSecret" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/webhook/test": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Send test event", "description": "Dispatches a sample `payment.status.updated` delivery to the endpoint identified by `webhookId` so you can verify your receiver and signature validation. Returns `{ ok }` once the test delivery is queued.", "tags": [ "Webhooks" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "webhookId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/profile/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get profile", "description": "Returns the merchant's business `profile` — `legalName` (read-only), `displayName`, `description`, `category`, `supportEmail`, and `logoUrl`.", "tags": [ "Business Profile" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "legalName": { "type": "string", "description": "Registered legal business name (read-only, from KYB).", "example": "string" }, "displayName": { "type": "string", "description": "Public business name shown to payers.", "example": "Satoshi Coffee" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description.", "example": "Order #1024" }, "category": { "type": [ "string", "null" ], "description": "Business category, or null.", "example": "string" }, "supportEmail": { "type": [ "string", "null" ], "description": "Public support email address, or null.", "example": "string" }, "logoUrl": { "type": [ "string", "null" ], "description": "URL of the merchant logo, or null when none is set.", "example": "string" } }, "required": [ "id", "legalName", "displayName", "description", "category", "supportEmail", "logoUrl" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/profile/update": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update profile", "description": "Updates the editable business profile fields (`displayName`, `description`, `category`, `supportEmail`). Admin only. Returns the updated `profile`.", "tags": [ "Business Profile" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "category": { "type": "string", "description": "Business category, or null.", "example": "string" }, "supportEmail": { "type": "string", "description": "Public support email address, or null.", "example": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "legalName": { "type": "string", "description": "Registered legal business name (read-only, from KYB).", "example": "string" }, "displayName": { "type": "string", "description": "Public display name shown to payers (optional).", "example": "Satoshi Coffee" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description.", "example": "Order #1024" }, "category": { "type": [ "string", "null" ], "description": "Business category, or null.", "example": "string" }, "supportEmail": { "type": [ "string", "null" ], "description": "Public support email address, or null.", "example": "string" }, "logoUrl": { "type": [ "string", "null" ], "description": "URL of the merchant logo, or null when none is set.", "example": "string" } }, "required": [ "id", "legalName", "displayName", "description", "category", "supportEmail", "logoUrl" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/profile/logo/upload": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Upload logo", "description": "Uploads the merchant logo (PNG / JPG / SVG, ≤2MB) as base64 `fileBase64`. Returns the hosted `logoUrl`.", "tags": [ "Business Profile" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileBase64": { "type": "string", "description": "Logo image as a base64-encoded payload (PNG / JPG / SVG, ≤2MB).", "example": "string" }, "mimeType": { "type": "string", "description": "MIME type of the uploaded file, e.g. `image/png`.", "example": "string" } }, "required": [ "fileBase64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "logoUrl": { "type": "string", "description": "URL of the uploaded logo.", "example": "string" } }, "required": [ "logoUrl" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/profile/logo/delete": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Delete logo", "description": "Removes the merchant logo. Returns `{ ok }`.", "tags": [ "Business Profile" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/link/start": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Start wallet link", "description": "Starts a wallet-link session. Returns a one-time `linkToken`, the `qrPayload` to render as a QR code, and `expiresAt`. The user scans the QR with the GoBTC Pay mobile app to link their wallet; poll **Wallet link status** until it reports `linked`.", "tags": [ "Receiving Wallet" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "linkToken": { "type": "string", "description": "One-time, short-lived wallet-link token; the mobile app reads it from the scanned QR to complete linking.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" }, "qrPayload": { "type": "string", "description": "String to encode as a QR code — an app deep link carrying the link token.", "example": "bitcoin:bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq?amount=0.0005" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Expiry time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "linkToken", "qrPayload", "expiresAt" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/link/status": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Wallet link status", "description": "Polls a link session by `linkToken` (or the active merchant's current state when omitted). Returns `status` (`pending` / `linked` / `expired`) and the linked `address` once available.", "tags": [ "Receiving Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkToken": { "type": "string", "description": "The link token returned by **Start wallet link** to poll.", "example": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImFjY2VzcyJ9.eyJwa2giOiIwMmExNjMzYyIsImNpZCI6IjNmYTg1ZjY0IiwiaWF0IjoxNzE4MDEyMzQ1fQ.MEQCIE3aGoQk0vY9c5kq" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "linked", "expired" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "pending" }, "address": { "type": [ "string", "null" ], "description": "The linked receiving wallet address, or null while pending.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" } }, "required": [ "status", "address" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/get-balance": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Non-custodial balance", "description": "The non-custodial merchant's own money, split into three non-overlapping levels: `connectedWalletSats` (confirmed on the reserved `0/0` address), `paymentWalletsSats` (confirmed on the per-payment addresses of payments that are `detected`, `paid` or `cleared`) and `inFlightSats` (still unconfirmed in the mempool, and **signed** — negative means an outgoing spend not yet in a block).\n\nAll figures come from the chain, never from the payment ledger: the platform does not see the merchant's outgoing transactions, so a ledger-derived number would be total receipts rather than a balance. When the chain cannot be reached the last known values are returned with `balanceStale: true` — they are never substituted with an internally computed amount. `addressesTruncated: true` means the merchant holds funds on more addresses than one refresh may query, so the totals are incomplete and must be presented as such.\n\nCustodial merchants are rejected: their funds sit on the platform treasury address, see **Custodial balance**.", "tags": [ "Receiving Wallet" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "connectedWalletSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "paymentWalletsSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "inFlightSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "walletLinked": { "type": "boolean", "example": true }, "balanceAsOf": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "balanceStale": { "type": "boolean", "example": true }, "addressesTruncated": { "type": "boolean", "example": true }, "signedPsbtSats": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" }, { "type": "number", "example": 50000 } ] }, { "type": "null", "example": null } ] } }, "required": [ "connectedWalletSats", "paymentWalletsSats", "inFlightSats", "walletLinked", "balanceAsOf", "balanceStale", "addressesTruncated", "signedPsbtSats" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Wallets with a balance", "description": "Paginated list of the non-custodial merchant's addresses that currently hold money — the connected `0/0` address and the per-payment addresses under observation. Each row carries `address`, `kind` (`connected` / `payment`), `derivationPath`, `paymentId` (`null` for the connected wallet), `confirmedSats` and `inFlightSats`. Addresses with a zero total are omitted. Custodial merchants are rejected — they have no addresses of their own.", "tags": [ "Receiving Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "kind": { "type": "string", "enum": [ "connected", "payment" ], "example": "connected" }, "derivationPath": { "type": "string", "example": "string" }, "paymentId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ], "description": "Identifier of the payment (UUID)." }, "confirmedSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] }, "inFlightSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ] } }, "required": [ "address", "kind", "derivationPath", "paymentId", "confirmedSats", "inFlightSats" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/build-withdraw-psbt": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Build withdrawal PSBT", "description": "Builds an unsigned single-sig P2WPKH PSBT spending UTXOs of the merchant's own `fromAddresses` to `toAddress`. Exactly one of `amountSats` (leaves change on a connected merchant address) or `sendMax` (sweeps everything selected minus fee, no change) must be set. The server never signs — the merchant signs every input on their own device, then confirms with **Broadcast withdrawal**. The returned `summary` (including the change address) is a display convenience only; the client must verify every output against the PSBT itself before signing. The job is reserved as `prepared` the moment this call returns and expires after a server-side TTL if never broadcast. Custodial merchants are rejected — they have no addresses of their own.", "tags": [ "Receiving Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromAddresses": { "type": "array", "items": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "minItems": 1, "maxItems": 200 }, "toAddress": { "type": "string", "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "sendMax": { "type": "boolean", "description": "If true, sweeps the entire spendable balance to `toAddress` and ignores the amount.", "example": true }, "fee": { "type": "object", "properties": { "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 } }, "required": [ "feeRateSatVb" ], "additionalProperties": false } }, "required": [ "fromAddresses", "toAddress", "fee" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "jobId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "psbtBase64": { "type": "string", "description": "Unsigned transaction as a base64-encoded PSBT (BIP-174). Sign it with the wallet key.", "example": "cHNidP8BAHECAAAAAfYI0kF1pQ0i3xL0AAAAAAD9////AsBdAQAAAAAAFgAUdR5" }, "summary": { "type": "object", "properties": { "toAddress": { "type": "string", "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "vsize": { "type": "integer", "exclusiveMinimum": 0, "description": "Estimated virtual size of the transaction, in vbytes.", "example": 140 }, "change": { "type": "object", "properties": { "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "valueSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Change output value, in satoshis." } }, "required": [ "address", "valueSats" ], "additionalProperties": false }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "vout": { "type": "integer", "minimum": 0, "description": "Index of the referenced output within its transaction.", "example": 0 }, "value": { "type": "integer", "exclusiveMinimum": 0, "description": "Output value, in satoshis.", "example": 50000 }, "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "derivationPath": { "type": "string", "example": "string" } }, "required": [ "txid", "vout", "value", "address", "derivationPath" ], "additionalProperties": false } } }, "required": [ "toAddress", "amountSats", "feeSats", "feeRateSatVb", "vsize", "inputs" ], "additionalProperties": false } }, "required": [ "jobId", "psbtBase64", "summary" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/broadcast": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Broadcast withdrawal", "description": "Hands over the withdrawal transaction the merchant signed and finalized locally, as raw `signedTxHex`, for the server to validate against the stored job and broadcast. Idempotent by `jobId`: `wasAlreadySubmitted: true` means the transaction was already broadcast and the returned `txid` is the stored one, not a new attempt.", "tags": [ "Receiving Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "signedTxHex": { "type": "string", "minLength": 1, "pattern": "^([0-9a-fA-F]{2})+$", "example": "0014751e76e8199196d454941c45d1b3a323f1433bd6" } }, "required": [ "jobId", "signedTxHex" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "txid": { "type": "string", "description": "On-chain Bitcoin transaction id (hex).", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, "wasAlreadySubmitted": { "type": "boolean", "example": true } }, "required": [ "txid", "wasAlreadySubmitted" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/wallet/withdraw-status": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Withdrawal job status", "description": "Reads the current state of a withdrawal job by `jobId` — `prepared` / `broadcasting` / `broadcasted` / `expired` / `failed`, the same set the job row carries. A pure read with no side effects, safe to poll repeatedly; it exists because **Broadcast withdrawal** is idempotent but not informative — retrying it resubmits the same stored hex, but a job that is already `expired` or `failed` makes it fail outright rather than report a state. After a broadcast error, or after the app restarts and loses whatever local state it had, this is the only way left to learn whether the money moved. `txid` is set once the network has one for this job and `null` before that; `summary` (amount, fee, destination, change) and `expiresAt` let the app show the withdrawal without keeping any of it around locally — `expiresAt` goes back to `null` once the job is past waiting on the reservation TTL. A `jobId` belonging to a different merchant is rejected as `NotFound`, identically to one that does not exist.", "tags": [ "Receiving Wallet" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "jobId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "prepared", "broadcasting", "broadcasted", "expired", "failed" ], "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`.", "example": "prepared" }, "txid": { "anyOf": [ { "type": "string", "example": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b" }, { "type": "null", "example": null } ], "description": "On-chain Bitcoin transaction id (hex)." }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ], "description": "Expiry time as a Unix timestamp (seconds)." }, "summary": { "type": "object", "properties": { "toAddress": { "type": "string", "description": "Destination Bitcoin address for the funds.", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "amountSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Amount in satoshis." }, "feeSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Network fee for the transaction, in satoshis." }, "feeRateSatVb": { "type": "number", "exclusiveMinimum": 0, "description": "Fee rate in satoshis per virtual byte (sat/vB).", "example": 50000 }, "change": { "type": "object", "properties": { "address": { "type": "string", "example": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq" }, "valueSats": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "example": "string" }, { "type": "number", "example": 50000 } ], "description": "Change output value, in satoshis." } }, "required": [ "address", "valueSats" ], "additionalProperties": false } }, "required": [ "toAddress", "amountSats", "feeSats", "feeRateSatVb" ], "additionalProperties": false } }, "required": [ "status", "txid", "expiresAt", "summary" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/api-key/create": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Create API key", "description": "Issues a Web SDK integration key of the given `type` (`publishable` / `secret`), optionally scoped to a `storeId`. The response includes the full `secret` **shown only once**.", "tags": [ "API Keys" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable label for the API key.", "example": "Front desk" }, "type": { "type": "string", "enum": [ "publishable", "secret" ], "example": "publishable" }, "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "required": [ "label", "type" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": "string", "description": "Human-readable label for the API key.", "example": "Front desk" }, "type": { "type": "string", "enum": [ "publishable", "secret" ], "example": "publishable" }, "prefix": { "type": "string", "description": "Non-secret key prefix shown for identification (e.g. `pk_live_ab12`).", "example": "string" }, "lastUsedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "secret": { "type": "string", "description": "The secret key value. Returned only on create — shown once, store it securely.", "example": "string" } }, "required": [ "id", "label", "type", "prefix", "lastUsedAt", "createdAt", "secret" ], "additionalProperties": false, "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal." } }, "required": [ "apiKey" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/api-key/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List API keys", "description": "Lists integration keys (masked — `prefix` only, never the full secret) with optional `pagination` and a `storeId` filter. Returns `items` and `totalCount`.", "tags": [ "API Keys" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "storeId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "type": { "type": "string", "enum": [ "publishable", "secret" ], "example": "publishable" }, "prefix": { "type": "string", "description": "Non-secret key prefix shown for identification (e.g. `pk_live_ab12`).", "example": "string" }, "lastUsedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 } }, "required": [ "id", "label", "type", "prefix", "lastUsedAt", "createdAt" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/api-key/rotate": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Rotate API key", "description": "Rotates the key identified by `apiKeyId`, invalidating the previous secret and returning a fresh `secret` (shown only once).", "tags": [ "API Keys" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKeyId": { "type": "string", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "apiKeyId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "label": { "type": "string", "description": "Human-readable label for the POS terminal (optional).", "example": "Front desk" }, "type": { "type": "string", "enum": [ "publishable", "secret" ], "example": "publishable" }, "prefix": { "type": "string", "description": "Non-secret key prefix shown for identification (e.g. `pk_live_ab12`).", "example": "string" }, "lastUsedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Creation time as a Unix timestamp (seconds).", "example": 1718012345 }, "secret": { "type": "string", "description": "The freshly rotated secret key value. Shown once — store it securely.", "example": "string" } }, "required": [ "id", "label", "type", "prefix", "lastUsedAt", "createdAt", "secret" ], "additionalProperties": false, "description": "Secret API key of the POS terminal. Store it securely — it authenticates the terminal." } }, "required": [ "apiKey" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/api-key/revoke": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Revoke API key", "description": "Revokes the key identified by `apiKeyId`. Returns `{ ok }`.", "tags": [ "API Keys" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKeyId": { "type": "string", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" } }, "required": [ "apiKeyId" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/notifications/get": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Get notification preferences", "description": "Returns the per-event notification `preferences`, each with `email`, `inApp`, and `sms` toggles.", "tags": [ "Notifications" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "example": "string" }, "email": { "type": "boolean", "example": true }, "inApp": { "type": "boolean", "example": true }, "sms": { "type": "boolean", "example": true } }, "required": [ "event", "email", "inApp", "sms" ], "additionalProperties": false } } }, "required": [ "preferences" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/notifications/update": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Update notification preferences", "description": "Saves the per-event notification `preferences`. Returns the stored set.", "tags": [ "Notifications" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "example": "string" }, "email": { "type": "boolean", "example": true }, "inApp": { "type": "boolean", "example": true }, "sms": { "type": "boolean", "example": true } }, "required": [ "event", "email", "inApp", "sms" ], "additionalProperties": false } } }, "required": [ "preferences" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "preferences": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "example": "string" }, "email": { "type": "boolean", "example": true }, "inApp": { "type": "boolean", "example": true }, "sms": { "type": "boolean", "example": true } }, "required": [ "event", "email", "inApp", "sms" ], "additionalProperties": false } } }, "required": [ "preferences" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/audit/list": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "List audit log", "description": "Returns the merchant's audit log with optional `pagination` and `filters` (`action`, `dateRange`). Each entry records the actor, action, detail, and request metadata. Returns `items` and `totalCount`.", "tags": [ "Audit Log" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "example": 20 }, "skip": { "type": "number", "minimum": 0, "default": 0, "example": 0 } }, "additionalProperties": false }, "filters": { "type": "object", "properties": { "action": { "type": "string", "description": "The audited action identifier.", "example": "string" }, "dateRange": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "end": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 } }, "required": [ "start", "end" ], "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, "action": { "type": "string", "description": "The audited action identifier.", "example": "string" }, "actorUserId": { "anyOf": [ { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, { "type": "null", "example": null } ], "description": "Id of the user who performed the action." }, "actorApiKeyId": { "anyOf": [ { "type": "string", "example": "possk_live_3fa85f6457174562b3fc2c963f66afa6" }, { "type": "null", "example": null } ] }, "actorName": { "type": "string", "description": "Display name of the user who performed the action.", "example": "string" }, "detail": { "type": "string", "description": "Human-readable detail of the audited action.", "example": "string" }, "ip": { "type": "string", "example": "string" }, "userAgent": { "type": "string", "example": "string" } }, "required": [ "at", "action", "actorUserId", "actorApiKeyId", "actorName", "detail" ], "additionalProperties": false } }, "totalCount": { "type": "number", "description": "Total number of records matching the filters.", "example": 0 } }, "required": [ "items", "totalCount" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } }, "/merchant/dashboard/summary": { "post": { "security": [ { "merchantAuth": [] } ], "summary": "Dashboard summary", "description": "Returns everything the home screen needs in one call: BTC / fiat `balance`, today's volume and transaction metrics (with day-over-day deltas), the 7-day `chart7d`, and the most `recent` payments.", "tags": [ "Dashboard" ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "result": { "type": "object", "properties": { "$case": { "type": "string", "const": "success", "example": "success" }, "success": { "type": "object", "properties": { "businessName": { "type": "string", "example": "string" }, "balanceBtc": { "type": "number", "example": 50000 }, "balanceUsd": { "type": "number", "example": 50000 }, "btcUsdRate": { "type": "number", "example": 0 }, "today": { "type": "object", "properties": { "volumeBtc": { "type": "number", "example": 0 }, "volumeUsd": { "type": "number", "example": 0 }, "txCount": { "type": "number", "example": 0 }, "deltaVolumePct": { "type": "number", "example": 0 }, "deltaTxCount": { "type": "number", "example": 0 }, "pendingBtc": { "type": "number", "example": 0 }, "pendingUsd": { "type": "number", "example": 0 } }, "required": [ "volumeBtc", "volumeUsd", "txCount", "deltaVolumePct", "deltaTxCount", "pendingBtc", "pendingUsd" ], "additionalProperties": false }, "chart7d": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "example": "string" }, "vol": { "type": "number", "example": 0 }, "count": { "type": "number", "example": 0 } }, "required": [ "day", "vol", "count" ], "additionalProperties": false } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "example": "string" }, "amountBtc": { "type": "number", "example": 10 }, "amountUsd": { "type": "number", "example": 10 }, "status": { "type": "array", "items": { "type": "string", "enum": [ "initiated", "detected", "paid", "failed", "expired", "canceled", "cleared" ], "example": "initiated" }, "description": "Current status. Payments: `initiated` / `detected` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`." }, "ref": { "type": "string", "example": "string" }, "paymentId": { "type": "string", "description": "Identifier of the payment (UUID).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "expiredAt": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "UnixTime (seconds since epoch)", "example": 1718012345 }, { "type": "null", "example": null } ] } }, "required": [ "time", "amountBtc", "amountUsd", "ref", "paymentId", "expiredAt" ], "additionalProperties": false } } }, "required": [ "businessName", "balanceBtc", "balanceUsd", "btcUsdRate", "today", "chart7d", "recent" ], "additionalProperties": false } }, "required": [ "$case", "success" ], "additionalProperties": false } }, "required": [ "id", "result" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "500": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "Numeric error status code.", "example": 0 }, "description": { "type": "string", "description": "Human-readable description.", "example": "Order #1024" }, "statusMessage": { "type": "string", "description": "Short machine-readable error message.", "example": "pending" } }, "required": [ "statusCode", "description", "statusMessage" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } } } } }, "webhooks": {}, "tags": [ { "name": "Payments", "description": "Create and inspect payments, list payment history, and build / submit the signed transaction that settles a payment." }, { "name": "Merchant Auth", "description": "Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context." }, { "name": "Stores", "description": "Manage the merchant's stores: create, read, update, and delete." }, { "name": "POS Terminals", "description": "Manage POS terminals within a store, including issuing and rotating their API keys." }, { "name": "Team & Access", "description": "Team members, roles, and invitations for the merchant account." }, { "name": "Reports", "description": "Sales summaries, transaction and aggregated reports, and async exports." }, { "name": "Webhooks", "description": "Configure outbound webhook endpoints (URL, scope, signing secret) so your backend is notified when a payment's status changes — an alternative to polling Get payment." }, { "name": "Dashboard", "description": "Aggregated home-screen summary: balance, today's metrics, the 7-day chart, and recent payments in a single call." }, { "name": "Business Profile", "description": "The merchant's public business profile — display name, description, category, support email, and logo." }, { "name": "Receiving Wallet", "description": "Link a receiving wallet by scanning a QR with the mobile app: start a link session and poll its status." }, { "name": "API Keys", "description": "Issue, list, rotate, and revoke Web SDK integration keys (publishable / secret)." }, { "name": "Notifications", "description": "Per-event notification preferences across email, in-app, and SMS channels." }, { "name": "Audit Log", "description": "Read the merchant's audit log of account actions." }, { "name": "Custodial Withdrawal", "description": "Custodial merchants only: manage saved BTC destination wallets and withdraw the Uphold balance to them, including the Uphold Travel Rule verification a held withdrawal may require." }, { "name": "Custodial Bank Accounts", "description": "Custodial merchants only — register, list, inspect, and remove ACH bank accounts (Uphold External Accounts) used as off-ramp destinations." }, { "name": "Custodial Off-Ramp", "description": "Custodial merchants only — sell BTC from the Uphold account and send USD to a registered bank account, including the Travel Rule compliance step when required. Amounts are denominated in satoshi (BTC debit) and USD (bank destination)." } ], "x-tagGroups": [ { "name": "Merchant Account", "tags": [ "Dashboard", "Merchant Auth", "Business Profile", "Receiving Wallet", "Stores", "POS Terminals", "Payments", "Team & Access", "Reports", "Webhooks", "API Keys", "Notifications", "Audit Log", "Custodial Withdrawal", "Custodial Bank Accounts", "Custodial Off-Ramp" ] } ] }