{ "openapi": "3.1.0", "info": { "title": "UnifiWallet Payment Gateway", "version": "1.0.0", "summary": "Non-custodial crypto payments.", "description": "Buyers pay merchants directly, inside one transaction they sign themselves.\nUnifiWallet builds the calldata and never holds the funds — which is also why\nthere is no balance endpoint, no payout endpoint, and no way for us to reverse\na transfer.\n\n**Every request is signed.** There is no bearer token to leak: the secret never\ntravels, and a captured request cannot be replayed or edited. See the\nauthentication guide for the exact string to sign.\n\n**Try-it-out will not work from a browser.** Executing a request needs an HMAC\nover the body with your secret, and a secret that reaches a browser is a secret\nyou have published. Generate a client from this document instead.", "contact": { "url": "https://payment.unifiwallet.com/docs" } }, "servers": [ { "url": "https://api.payment.unifiwallet.com", "description": "This deployment" } ], "paths": { "/v1/status": { "get": { "operationId": "getStatus", "summary": "Is the service up", "description": "Public, and deliberately minimal.", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "This document", "description": "Public. Generate a client from it.", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/checkout/{token}": { "get": { "operationId": "getCheckout", "summary": "What the buyer sees", "description": "Public — the token is the authorisation. Treat it as a capability: whoever holds it can quote and submit this checkout, so keep it out of logs and analytics.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/checkout/{token}/status": { "get": { "operationId": "getCheckoutStatus", "summary": "Poll a checkout", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/checkout/{token}/quote": { "post": { "operationId": "quoteCheckout", "summary": "Quote an asset and build the call", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "description": "Symbol of the token the buyer intends to pay with, as listed by `GET /v1/assets`.", "type": "string" }, "chain_id": { "description": "Chain the buyer is paying on. Defaults to the asset's only chain when it has one.", "type": "number" }, "payer_address": { "description": "The wallet that will send the funds. Used to price gas and to check the balance.", "type": "string" }, "refund_address": { "description": "Where a refund of this payment should go, if it is not the paying wallet.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "refund_address_signature": { "description": "Signature from `payer_address` over the refund address. Required whenever `refund_address` is given: whoever holds the checkout link is not necessarily the buyer.", "type": "string", "pattern": "^0x[a-fA-F0-9]+$" } }, "required": [ "asset", "payer_address" ] } } } } } }, "/v1/checkout/{token}/authorize": { "post": { "operationId": "authorizeCheckout", "summary": "Build an escrow authorization", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "description": "Token the buyer is paying with. Must be one the merchant accepts.", "type": "string" }, "chain_id": { "description": "Chain the buyer is paying on.", "type": "number" }, "payer_address": { "description": "The wallet that will send the funds. The returned calldata is built for it.", "type": "string" } }, "required": [ "asset", "payer_address" ] } } } } } }, "/v1/checkout/{token}/deposit-address": { "post": { "operationId": "checkoutDepositAddress", "summary": "Issue a deposit address", "description": "For wallets that cannot sign a contract call. Derived deterministically, and fixed once issued — the refund address is part of how it is derived. ERC-20 settlement assets only: a native-coin transfer leaves no log to observe. Anything unforwarded at expiry is returned to the refund address.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_address": { "description": "Where to send funds if this payment is refunded or overpaid. Worth collecting: a deposit address has no sender to refund to automatically.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } } } } } } } }, "/v1/checkout/{token}/submit": { "post": { "operationId": "submitCheckout", "summary": "Report the transaction", "description": "A claim, not proof. The payment moves to `settling` and the hash is checked: if it reverts or settles nothing, the checkout reopens (`payment.submission_failed`). Settlement is only ever recognised from the chain event.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_hash": { "description": "Hash of the transaction the buyer broadcast. Watching starts from it; the payment still only settles on a confirmed on-chain event.", "type": "string" }, "payer_address": { "description": "The wallet that sent it, when known.", "type": "string" } }, "required": [ "tx_hash" ] } } } } } }, "/v1/checkout/{token}/simulate": { "post": { "operationId": "simulateCheckout", "summary": "Simulate an outcome (test mode)", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Checkout" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "description": "Which ending to act out — see `GET /v1/test/outcomes`. Defaults to a successful payment. Refused for a live payment.", "type": "string" } } } } } } } }, "/v1/manage/{token}": { "get": { "operationId": "getSubscriptionManage", "summary": "What the buyer sees about their own subscription", "description": "Public — the manage token is the authorisation, like a checkout token. Returned once as `manage_url` when the subscription is created, and included in the mail we send the payer. Put it in your own emails and account pages too: the shortest route out should be inside your product. It shows the price, the interval and the next charge, and nothing about your account.", "tags": [ "Subscription management" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/manage/{token}/revocation": { "get": { "operationId": "getSubscriptionRevocation", "summary": "The on-chain revoke call", "description": "The exact `revoke` call for the spend permission behind an `auto_charge` subscription. Cancelling here stops us charging — that is a promise we keep. Revoking is the buyer's own key acting on chain, needs neither us nor you, and is the half that does not require trusting anybody. 409 `no_permission` for a link-collected subscription, where nothing was pre-authorised.", "tags": [ "Subscription management" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/manage/{token}/cancel": { "post": { "operationId": "cancelSubscriptionAsBuyer", "summary": "The buyer cancels", "description": "No credential, no confirmation step and no retention flow — one request ends it. Defaults to stopping at the end of the period already paid for, which is what a person means by cancelling; `immediately` ends it now. You are told either way (`subscription.cancel_scheduled` or `subscription.canceled`, with `canceled_by: \"buyer\"`), and you must act on it: stop providing the service at `current_period_end`.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Subscription management" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "immediately": { "description": "End it now rather than at the end of the period already paid for. Defaults to false, which is what a person usually means by cancelling: do not charge me again, and let me keep what I have paid for.", "type": "boolean" }, "reason": { "description": "Optional, and never required — a cancellation must not be gated on answering a question.", "type": "string", "maxLength": 300 } } } } } } } }, "/v1/status/detail": { "get": { "operationId": "getStatusDetail", "summary": "Operational health", "description": "Watcher lag, relayer balances, queue depths. Behind its own scope.", "tags": [ "Reference" ], "security": [ { "signedRequest": [ "ops:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Scopes and event types", "description": "Read this rather than keeping your own copy — it is the list that cannot drift.", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/assets": { "get": { "operationId": "listAssets", "summary": "Supported assets", "description": "Decimals are per chain, deliberately: USDT is 6 on Ethereum and 18 on BNB Chain, and assuming otherwise mis-prices a payment by a factor of a trillion.", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/chains": { "get": { "operationId": "listChains", "summary": "Chains and confirmation policy", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/rates": { "get": { "operationId": "getRate", "summary": "A rate between two assets", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/fees": { "get": { "operationId": "getFeePlan", "summary": "Your fee plan", "tags": [ "Reference" ], "security": [ { "signedRequest": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/payments": { "post": { "operationId": "createPayment", "summary": "Create a payment", "description": "Fixes the fee, the rate and the settlement address onto the payment, so what settles is what was quoted — including weeks later, if it comes to an argument.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "201": { "description": "The payment, with a `checkout_url` to send the buyer to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "What to charge, as a decimal string in `currency` — `\"49.99\"`, not `4999` and not `49.99` the float. Sending money as a float is how you lose a cent a thousand times.", "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "currency": { "description": "The currency the price is quoted in: a fiat code such as `USD` or `EUR`, or a token symbol to price directly in crypto.", "type": "string", "minLength": 2, "maxLength": 10 }, "merchant_order_id": { "description": "Your own order number. Returned on every event and settlement so you can reconcile without storing our ids.", "type": "string", "maxLength": 200 }, "description": { "description": "What the buyer is paying for. Shown on the hosted checkout page.", "type": "string", "maxLength": 500 }, "customer": { "description": "Who is paying. Every field is optional — a payment needs no customer at all.", "type": "object", "properties": { "reference": { "description": "Your id for this customer.", "type": "string" }, "email": { "description": "Where the receipt goes, and where a refund notice goes.", "type": "string", "format": "email" }, "email_receipt": { "description": "Send the buyer a receipt when the payment settles.", "type": "boolean" }, "address": { "description": "Billing address, used for tax and for the invoice.", "type": "object", "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code. Determines the tax treatment.", "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "description": "Postal code, where the tax rate depends on it.", "type": "string" } } }, "tax_id": { "description": "The buyer's tax registration, for a reverse-charge invoice.", "type": "object", "properties": { "type": { "description": "Kind of registration, e.g. `eu_vat`.", "type": "string" }, "value": { "description": "The number itself.", "type": "string" } } }, "refund_address": { "description": "Where a refund should go. If absent, refunds go back to the wallet that paid.", "type": "string" } } }, "line_items": { "description": "The itemised breakdown. When present, the lines must sum to `amount`.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Line description, shown to the buyer.", "type": "string" }, "quantity": { "description": "How many.", "default": 1, "type": "integer", "minimum": 1 }, "unit_amount": { "description": "Price of one, as a decimal string in `currency`.", "type": "string" }, "tax_rate_ids": { "description": "Tax rates to apply to this line, overriding `tax_rate_percent`.", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "unit_amount" ] } }, "discounts": { "description": "Reductions applied before tax.", "type": "array", "items": { "type": "object", "properties": { "coupon": { "description": "Id of a coupon on your account.", "type": "string" }, "amount": { "description": "A flat reduction, as a decimal string in `currency`.", "type": "string" } } } }, "tax_behavior": { "description": "Whether `amount` already contains the tax (`inclusive`) or the tax is added on top (`exclusive`).", "type": "string", "enum": [ "inclusive", "exclusive" ] }, "tax_rate_percent": { "description": "A single rate to apply to the whole payment, when you are not using tax rate ids.", "type": "number", "minimum": 0, "maximum": 100 }, "settlement": { "description": "Where this payment pays out, when not the account default.", "type": "object", "properties": { "destination_id": { "description": "A verified destination on your account. Overrides the account default for this payment only.", "type": "string" }, "address": { "description": "Pay this one out to an address that is not on your account — a marketplace paying the seller who made the sale. Refused unless per-payment routing is switched on in the panel, because an API key that can name any payout address is an API key that can drain the account.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "asset": { "description": "Token to settle in.", "type": "string" }, "chain_id": { "description": "Chain to settle on.", "type": "number" } } }, "capture_method": { "description": "`automatic` settles as soon as the funds confirm. `manual` holds the payment authorised until you call capture — for orders you might not be able to fulfil.", "type": "string", "enum": [ "automatic", "manual" ] }, "hold_window_hours": { "description": "For a `manual` payment: how long the funds stay held before the buyer may reclaim them. Defaults to your account setting, and is capped by the platform maximum — 168 hours is what a card authorization gets.", "type": "number", "minimum": 1 }, "rate_mode": { "description": "`fixed_rate` locks the crypto amount for `rate_lock_seconds`, so you carry no price risk inside the window. `floating_rate` prices at confirmation.", "type": "string", "enum": [ "fixed_rate", "floating_rate" ] }, "rate_lock_seconds": { "description": "How long a fixed rate holds, in seconds. Longer costs a wider spread.", "type": "number", "minimum": 300, "maximum": 1800 }, "payer_address_hint": { "description": "The wallet you expect to pay, when you already know it.", "type": "string" }, "return_url": { "description": "Where the buyer lands after paying. Never treat arriving here as proof of payment — the webhook is the proof.", "type": "string", "format": "uri" }, "cancel_url": { "description": "Where the buyer lands if they abandon the checkout.", "type": "string", "format": "uri" }, "failure_url": { "description": "Where the buyer lands if the payment fails.", "type": "string", "format": "uri" }, "expires_in": { "description": "Seconds until the payment expires unpaid. Anything arriving after that is refunded, not settled.", "type": "number", "minimum": 60, "maximum": 86400 }, "fee_payer": { "description": "Who carries the gateway fee. `buyer` adds it to the amount they are shown.", "type": "string", "enum": [ "merchant", "buyer" ] }, "gas_payer": { "description": "Who carries the network fee for putting this payment on chain. `buyer` adds it to their total; `merchant` takes it from the settlement. Defaults to the account setting. A held payment is two transactions, so it is priced as two.", "type": "string", "enum": [ "merchant", "buyer" ] }, "metadata": { "description": "Your own key/value pairs, returned on every event. Never put anything secret here — it is echoed to your webhook endpoint and visible in the panel.", "type": "object" } }, "required": [ "amount", "currency" ] } } } } }, "get": { "operationId": "listPayments", "summary": "List payments", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "A page of payments, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Retrieve a payment", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "The payment, including the snapshot of the terms that applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/payments/{id}/events": { "get": { "operationId": "listPaymentEvents", "summary": "Payment status history", "description": "The states this payment has been through, with reasons. The fastest answer to \"why is this stuck\", and better than inferring it from the current state.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/payments/{id}/cancel": { "post": { "operationId": "cancelPayment", "summary": "Cancel a payment", "description": "Only one nobody has paid. Money already on chain must be refunded instead. Cancelling cannot reach into the buyer's wallet: an order they signed before the deadline can still be mined, and arrives as `payment.late_settled`.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/payments/{id}/expire": { "post": { "operationId": "expirePayment", "summary": "Expire a payment early", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/payments/{id}/capture": { "post": { "operationId": "capturePayment", "summary": "Capture an authorized payment", "description": "Part of authorize-and-capture, which is not available yet.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:capture" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "How much of the authorised amount to take, as a decimal string. Defaults to all of it. The remainder is released, not held.", "type": "string" } } } } } } } }, "/v1/payments/{id}/void": { "post": { "operationId": "voidPayment", "summary": "Void an authorization", "description": "Part of authorize-and-capture, which is not available yet.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Payments" ], "security": [ { "signedRequest": [ "payments:capture" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/subscriptions": { "post": { "operationId": "createSubscription", "summary": "Create a subscription", "description": "Charges nothing. A new subscription stays `incomplete` until the buyer acts — read that literally, or you will ship for nothing.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "201": { "description": "The subscription, and for auto-charge the structure the buyer signs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Price of one cycle, as a decimal string in `currency`.", "type": "string", "pattern": "^\\d+(\\.\\d{1,8})?$" }, "currency": { "description": "Currency the cycle price is quoted in, as a three-letter code.", "type": "string", "minLength": 3, "maxLength": 3 }, "interval": { "description": "The billing period. `month` and `year` follow the calendar, so a subscription started on the 31st bills on the last day of a shorter month.", "type": "string", "enum": [ "day", "week", "month", "year" ] }, "interval_count": { "description": "Number of intervals per cycle — `interval: \"month\", interval_count: 3` bills quarterly. Defaults to 1.", "type": "integer", "minimum": 1, "maximum": 52 }, "collection_method": { "description": "`auto_charge` takes each cycle from a spend permission the buyer signed once. `payment_link` emails a fresh payment every cycle and takes nothing on its own.", "type": "string", "enum": [ "auto_charge", "payment_link" ] }, "description": { "description": "What the buyer is subscribing to. Shown when they authorise it.", "type": "string", "maxLength": 500 }, "merchant_reference": { "description": "Your own id for this subscription.", "type": "string", "maxLength": 200 }, "trial_end": { "description": "When the free period ends, ISO 8601. The first cycle is billed then, not now.", "type": "string", "format": "date-time" }, "ends_at": { "description": "When the subscription stops on its own, ISO 8601. Absent means it runs until cancelled.", "type": "string", "format": "date-time" }, "allowance_multiplier": { "description": "Headroom in the signed spend permission, as a multiple of one cycle. `2` lets the price rise up to double before the buyer has to sign again. It does not let you charge more than a cycle in a period — the on-chain permission caps that.", "type": "number", "minimum": 1, "maximum": 12 }, "settlement": { "description": "Where each cycle of this subscription pays out.", "type": "object", "properties": { "destination_id": { "description": "A verified destination on your account.", "type": "string" }, "address": { "description": "An address off your account. Needs per-payment routing switched on in the panel.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "asset": { "description": "Token to settle in.", "type": "string" }, "chain_id": { "description": "Chain to settle on.", "type": "number" } } }, "customer": { "description": "Who is subscribing.", "type": "object", "properties": { "reference": { "description": "Your id for this customer.", "type": "string", "maxLength": 200 }, "email": { "description": "Where the authorisation request and the cycle receipts go.", "type": "string", "format": "email" }, "wallet_address": { "description": "The wallet that will sign the spend permission, when you already know it.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "address": { "description": "Billing address.", "type": "object", "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code, for tax.", "type": "string", "minLength": 2, "maxLength": 2 } } } } }, "metadata": { "description": "Your own key/value pairs, echoed on every cycle event.", "type": "object" } }, "required": [ "amount", "currency", "interval" ] } } } } }, "get": { "operationId": "listSubscriptions", "summary": "List subscriptions", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/subscriptions/{id}": { "get": { "operationId": "getSubscription", "summary": "Retrieve a subscription", "description": "Includes whether the spend permission is still live on chain. The buyer can revoke without telling us, so the stored status is a guess until the chain is asked.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/subscriptions/{id}/cycles": { "get": { "operationId": "listSubscriptionCycles", "summary": "List billing cycles", "description": "Every period and what happened to it, including the ones that failed and how often they were retried.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCycleList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/subscriptions/{id}/authorization": { "get": { "operationId": "getSubscriptionAuthorization", "summary": "The permission the buyer signs", "description": "An EIP-712 structure with the ceiling, the period, your address and the fee all inside it, plus a plain-language summary of what the buyer is agreeing to.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/subscriptions/{id}/authorize": { "post": { "operationId": "authorizeSubscription", "summary": "Submit the signature", "description": "Makes the subscription billable. Verified here, not only on chain.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "permission": { "description": "The permission the buyer signed, field for field. It must match the one we issued exactly; anything else is refused rather than reconciled.", "type": "object", "properties": { "account": { "description": "The buyer's wallet — the account being debited.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "spender": { "description": "The contract allowed to pull, from `GET /v1/subscriptions/{id}/authorization`.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "token": { "description": "Contract address of the token being spent.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "recipient": { "description": "Where each charge lands — your settlement address. Signed by the buyer, so we cannot redirect it afterwards.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "fee_recipient": { "description": "Where the gateway fee lands. Also signed, for the same reason.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "fee_bps": { "description": "The fee, in basis points, capped at 500. The buyer signs the number, so it cannot be raised later.", "type": "integer", "minimum": 0, "maximum": 500 }, "allowance": { "description": "Maximum spendable per period, in the token's base units, as a decimal string.", "type": "string", "pattern": "^\\d+$" }, "period": { "description": "Length of a spending period in seconds. Allowance resets each period and does not accumulate: an unused period is lost, not banked.", "type": "integer", "minimum": 60 }, "start": { "description": "Unix time the permission becomes usable.", "type": "integer" }, "end": { "description": "Unix time it stops. Charges after this fail on-chain, not in our code.", "type": "integer" }, "salt": { "description": "Uniqueness value, so two identical permissions are distinguishable.", "type": "string", "pattern": "^\\d+$" }, "chain_id": { "description": "Chain the permission is for.", "type": "number" } }, "required": [ "account", "spender", "token", "recipient", "fee_recipient", "fee_bps", "allowance", "period", "start", "end", "salt" ] }, "signature": { "description": "The buyer's EIP-712 signature over `permission`. Smart-contract wallets are checked through ERC-1271.", "type": "string", "pattern": "^0x[a-fA-F0-9]+$" } }, "required": [ "permission", "signature" ] } } } } } }, "/v1/subscriptions/{id}/charge": { "post": { "operationId": "chargeSubscription", "summary": "Charge a cycle now", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "summary": "Stop charging", "description": "Stops us charging. It does not revoke the buyer's on-chain permission — only they can, from their own wallet. The response includes the call they would make.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Subscriptions" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "at_period_end": { "description": "Let the paid-for cycle run to its end instead of stopping now. Default is to stop immediately.", "type": "boolean" }, "reason": { "description": "Why, for your own records and the audit log.", "type": "string", "maxLength": 500 } } } } } } } }, "/v1/destinations": { "post": { "operationId": "createDestination", "summary": "Register a destination", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementDestination" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "`shield` settles into a UnifiWallet Shield account by code. `address` settles to a wallet you control and must be verified by signature before it can receive.", "type": "string", "enum": [ "shield", "address" ] }, "shield_code": { "description": "The Shield code to pay into. Required when `kind` is `shield`.", "type": "string" }, "address": { "description": "The wallet to pay into. Required when `kind` is `address`.", "type": "string" }, "chains": { "description": "Chain ids this destination can receive on. Defaults to every chain the asset exists on.", "type": "array", "items": { "type": "number" } }, "asset": { "description": "Restrict this destination to one token. Absent means any accepted token.", "type": "string" }, "label": { "description": "Your name for it, shown in the panel.", "type": "string", "maxLength": 100 } }, "required": [ "kind" ] } } } } }, "get": { "operationId": "listDestinations", "summary": "List settlement destinations", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementDestinationList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/destinations/{id}": { "get": { "operationId": "getDestination", "summary": "Retrieve a destination", "description": "Carries the verification message while ownership is unproved.", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementDestination" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "operationId": "removeDestination", "summary": "Remove a destination", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/destinations/{id}/balance": { "get": { "operationId": "getDestinationBalance", "summary": "Live on-chain balance", "description": "Read from the chain. This is your wallet, not an account with us.", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/destinations/{id}/verify": { "post": { "operationId": "verifyDestination", "summary": "Prove you hold the wallet", "description": "Sign the message from the destination itself. Pasting an address proves nothing, and a settlement address nobody controls is money burnt on every future payment.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Destinations" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementDestination" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "description": "Signature from the destination address over the challenge returned when it was created. Proves you hold the key, so a mistyped address cannot be settled to.", "type": "string" } }, "required": [ "signature" ] } } } } } }, "/v1/settlements": { "get": { "operationId": "listSettlements", "summary": "What actually arrived", "description": "Gross, fee, net and the transaction hash. Refused events are excluded; ask for them with `?status=quarantined`.", "tags": [ "Settlements" ], "security": [ { "signedRequest": [ "settlements:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/settlements/summary": { "get": { "operationId": "getSettlementSummary", "summary": "Volume by asset and chain", "tags": [ "Settlements" ], "security": [ { "signedRequest": [ "settlements:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/settlements/{id}": { "get": { "operationId": "getSettlement", "summary": "Retrieve a settlement", "tags": [ "Settlements" ], "security": [ { "signedRequest": [ "settlements:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/statements": { "get": { "operationId": "listStatements", "summary": "Flow records with fiat valuations", "description": "Valued at the moment each one arrived, which is what an accountant needs.", "tags": [ "Settlements" ], "security": [ { "signedRequest": [ "settlements:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/refunds": { "post": { "operationId": "createRefund", "summary": "Record a refund", "description": "Records what is owed, with a deadline. It does not move money — we never held it, so you send it and we verify it. Only for a `completed` payment: refunding one that a reorg can still take back would cost you twice.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "refunds:write" ] } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "description": "The settled payment being refunded.", "type": "string" }, "amount": { "description": "How much to return, as a decimal string. Defaults to the whole payment. Partial refunds may be repeated up to the full amount.", "type": "string" }, "to_address": { "description": "Where to send it. Defaults to the address the payment came from, which is the safe answer; naming a different one is only for a buyer who has told you to.", "type": "string" }, "reason": { "description": "Why, for your records and the buyer's receipt.", "type": "string", "maxLength": 500 } }, "required": [ "payment_id" ] } } } } }, "get": { "operationId": "listRefunds", "summary": "List refunds", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/refunds/{id}": { "get": { "operationId": "getRefund", "summary": "Retrieve a refund", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/refunds/{id}/prepare": { "post": { "operationId": "prepareRefund", "summary": "Build the transaction to send", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "refunds:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/refunds/{id}/submit": { "post": { "operationId": "submitRefund", "summary": "Submit the transaction hash", "description": "Verified on chain before the refund is marked complete, and one transfer can only ever settle one refund.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "refunds:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tx_hash": { "description": "Hash of the transaction that sent the refund. The refund is only marked paid once that transaction is seen confirmed on-chain.", "type": "string" } }, "required": [ "tx_hash" ] } } } } } }, "/v1/refunds/{id}/cancel": { "post": { "operationId": "cancelRefund", "summary": "Withdraw a refund", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Refunds" ], "security": [ { "signedRequest": [ "refunds:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhook-endpoints": { "post": { "operationId": "createWebhookEndpoint", "summary": "Register an endpoint", "description": "Must be a public HTTPS host. Private and internal addresses are refused.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "201": { "description": "The endpoint, and its signing secret — shown exactly once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Where events are delivered. HTTPS only — an event carries payment detail, and plaintext delivery would hand it to the network.", "type": "string", "format": "uri" }, "events": { "description": "Event types to send, from `GET /v1/capabilities`. Absent means all of them.", "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List endpoints", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhook-endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "summary": "Disable an endpoint", "description": "Undelivered events are kept and stay replayable to a new endpoint.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhook-endpoints/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Both signatures are sent during the overlap, so you can migrate without downtime.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test event", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Delivery attempts", "description": "With response codes and errors. Use this when a merchant says the callback never arrived.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a delivery", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List events", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/events/{id}/replay": { "post": { "operationId": "replayEvent", "summary": "Replay an event", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Webhooks" ], "security": [ { "signedRequest": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/account": { "get": { "operationId": "getAccount", "summary": "Account configuration", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/account/settlement": { "patch": { "operationId": "updateSettlement", "summary": "Change settlement preferences", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/account/accepted-assets": { "put": { "operationId": "updateAcceptedAssets", "summary": "Change what you accept", "description": "Requires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/account/preferences": { "patch": { "operationId": "updateAccountPreferences", "summary": "Change how you take money", "description": "Whether payments are held before they are charged, and who carries the network fee. Neither can move money anywhere new, which is why this is not a step-up action — unlike changing where you settle.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capture_method": { "description": "`manual` holds each payment until you capture it; `automatic` settles at once.", "type": "string", "enum": [ "automatic", "manual" ] }, "gas_payer": { "description": "Who carries the network fee: added to the buyer's total, or taken from your settlement beside the gateway fee.", "type": "string", "enum": [ "buyer", "merchant" ] }, "hold_window_hours": { "description": "How long a held payment waits before the buyer can take their money back. Capped by the platform — Stripe holds a card authorization for 168 hours and offers up to 720; ours defaults to the same.", "type": "number", "minimum": 1 }, "rate_mode": { "description": "Default pricing mode for new payments.", "type": "string", "enum": [ "fixed_rate", "floating_rate" ] } } } } } } } }, "/v1/account/domains": { "post": { "operationId": "claimDomain", "summary": "Claim a domain", "description": "Claimed, not verified. Return URLs must be on a verified domain, so this issues a DNS challenge you publish and then check.\n\nBearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/account/domains/{domain}/verify": { "post": { "operationId": "verifyDomain", "summary": "Check the DNS challenge", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/account/domains/{domain}": { "delete": { "operationId": "removeDomain", "summary": "Stop trusting a domain", "description": "Bearer credentials are refused here. The request must be signed.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/audit-log": { "get": { "operationId": "listAuditLog", "summary": "Everything consequential anyone did", "tags": [ "Account" ], "security": [ { "signedRequest": [ "account:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/test/outcomes": { "get": { "operationId": "listTestOutcomes", "summary": "Outcomes you can produce", "tags": [ "Test mode" ], "security": [ { "signedRequest": [ "payments:read" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/test/payments/{id}/simulate": { "post": { "operationId": "simulatePayment", "summary": "Drive a payment to an outcome", "description": "Including underpayment and reorgs — the branches nobody builds until they have to.\n\nRequires an `Idempotency-Key` header.", "tags": [ "Test mode" ], "security": [ { "signedRequest": [ "payments:write" ] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "description": "Which ending to act out — see `GET /v1/test/outcomes`. Defaults to a successful payment. Always refused for a live credential.", "type": "string" } } } } } } } } }, "components": { "securitySchemes": { "signedRequest": { "type": "apiKey", "in": "header", "name": "X-UW-Signature", "description": "HMAC-SHA256 over six newline-joined parts: `v1`, the method, the path, the timestamp, the nonce, and the SHA-256 of the raw body. Sent as `v1=` alongside `X-UW-Org-Id`, `X-UW-Key-Id`, `X-UW-Timestamp` and `X-UW-Nonce`." }, "panelSession": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A merchant panel session. Not an API credential — these routes are deliberately unreachable with one." } }, "responses": { "Error": { "description": "A code to branch on, a message to act on, and a request id to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests. `Retry-After` says how long to wait.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Payment": { "type": "object", "description": "A request for money, and everything decided when it was created.", "properties": { "id": { "type": "string", "description": "The payment. Ids are prefixed `pay_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `payment`." }, "mode": { "type": "string", "description": "Whether this is real money or test money.", "enum": [ "live", "test" ] }, "status": { "type": "string", "description": "Where the payment is. `succeeded` is the only status that means you have been paid — and even then, on a non-custodial gateway, paid means the funds reached your address.", "enum": [ "requires_payment", "processing", "requires_capture", "succeeded", "canceled", "expired", "failed", "refunded", "partially_refunded" ] }, "amount": { "type": "string", "description": "What was charged, in `currency`. Decimal string — never parse it as a float." }, "currency": { "type": "string", "description": "Currency the price was quoted in." }, "merchant_order_id": { "type": "string", "description": "Your own order number, as you sent it." }, "description": { "type": "string", "description": "What the buyer is paying for." }, "metadata": { "type": "object", "description": "Your own key/value pairs, as you sent them.", "properties": {} }, "customer": { "type": "object", "description": "Who is paying. Only the fields safe to return.", "properties": { "reference": { "type": "string", "description": "Your id for this customer." }, "country": { "type": "string", "description": "Two-letter country code, where one was given." }, "refund_address": { "type": "string", "description": "Where a refund of this payment would go." } } }, "required": { "type": "object", "description": "Exactly what the buyer has to send, once they have chosen an asset.", "properties": { "asset": { "type": "string", "description": "Token symbol." }, "chain_id": { "type": "number", "description": "Chain the payment must arrive on." }, "amount": { "type": "string", "description": "The amount in that token. Decimal string — never parse it as a float." }, "amount_base_units": { "type": "string", "description": "The same amount in the token's smallest unit. This is the figure to compare against an on-chain value; the decimal form is for people." } } }, "rate_lock": { "type": "object", "description": "The held exchange rate, when `rate_mode` is `fixed_rate`.", "properties": { "rate": { "type": "string", "description": "Units of the token per unit of `currency`." }, "source": { "type": "string", "description": "Which price feed it came from." }, "locked_at": { "type": "string", "format": "date-time", "description": "When it was struck." }, "expires_at": { "type": "string", "format": "date-time", "description": "When it stops being honoured. After this the buyer is re-quoted." }, "tolerance_bps": { "type": "number", "description": "How far the market may move before the payment is short-paid, in basis points." } } }, "snapshot": { "type": "object", "description": "The terms as they stood when the payment was created. Frozen on purpose: changing your account settings must not change what an outstanding payment costs, or where it pays out.", "properties": { "fee_plan_version": { "type": "string", "description": "Which fee plan applied." }, "capture_method": { "type": "string", "description": "As requested.", "enum": [ "automatic", "manual" ] }, "authorization_expires_at": { "type": "string", "format": "date-time", "description": "When an uncaptured authorisation is released." }, "rate_mode": { "type": "string", "description": "As requested.", "enum": [ "fixed_rate", "floating_rate" ] }, "settlement": { "type": "object", "description": "Where this payment pays out, resolved at creation.", "properties": { "path": { "type": "string", "description": "How the funds get there — direct transfer, router, or deposit address." }, "destination_id": { "type": "string", "description": "The destination used, if one was named." }, "resolved_address": { "type": "string", "description": "The address that will receive. What an on-chain event is checked against." }, "asset": { "type": "string", "description": "Token being settled in." }, "chain_id": { "type": "number", "description": "Chain being settled on." } } }, "collector": { "type": "string", "description": "The address or contract the buyer sends to." }, "confirmations_required": { "type": "number", "description": "Confirmations before the money is treated as arrived." }, "fee_bps": { "type": "number", "description": "What the contract enforces: the gateway fee plus whatever share of the network fee this payment's settings put on it." }, "gas_base_units": { "type": "string", "description": "The estimated network fee for this payment, in the settlement asset's base units. A held payment is two transactions and is priced as two." }, "gas_payer": { "type": "string", "description": "Who carries that network fee.", "enum": [ "buyer", "merchant" ] }, "tax": { "type": "object", "description": "Tax as computed at creation.", "properties": {} }, "totals": { "type": "object", "description": "The arithmetic: subtotal, discount, tax, total.", "properties": {} } } }, "escrow_operation": { "type": "object", "description": "A capture or void that has been sent and not yet confirmed. While this is present, another one is refused — that is what stops a buyer being charged twice.", "properties": { "kind": { "type": "string", "description": "What was sent.", "enum": [ "capture", "void", "reclaim" ] }, "tx_hash": { "type": "string", "description": "The transaction to watch." }, "amount_base_units": { "type": "string", "description": "How much it was for." }, "submitted_at": { "type": "string", "format": "date-time", "description": "When it was sent." } } }, "deposit_return": { "type": "object", "description": "Money owed back to the buyer from a deposit address, and how the return is going.", "properties": { "state": { "type": "string", "description": "`returned` is done; `failed` needs a person.", "enum": [ "pending", "failed", "returned" ] }, "reason": { "type": "string", "description": "Why the last attempt did not land." }, "attempts": { "type": "number", "description": "Attempts made so far." }, "tx_hash": { "type": "string", "description": "The transaction that returned it, once one did." } } }, "intent_address": { "type": "string", "description": "The single-use deposit address for this payment, when the buyer chose to pay by transfer rather than by contract call." }, "payer_address": { "type": "string", "description": "The wallet that paid, once seen." }, "confirmations": { "type": "number", "description": "Confirmations counted so far." }, "amount_capturable": { "type": "string", "description": "Authorised and still capturable. Decimal string — never parse it as a float." }, "amount_captured": { "type": "string", "description": "Captured so far. Decimal string — never parse it as a float." }, "expires_at": { "type": "string", "format": "date-time", "description": "When an unpaid payment stops being payable." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } } }, "Subscription": { "type": "object", "description": "A recurring charge and, once the buyer has signed, the permission that allows it.", "properties": { "id": { "type": "string", "description": "The subscription. Ids are prefixed `sub_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `subscription`." }, "mode": { "type": "string", "description": "Real money or test money.", "enum": [ "live", "test" ] }, "status": { "type": "string", "description": "Creating a subscription charges nothing. It cannot bill until it reaches `active`.", "enum": [ "incomplete", "trialing", "active", "past_due", "canceled", "ended" ] }, "collection_method": { "type": "string", "description": "How each cycle is collected.", "enum": [ "auto_charge", "payment_link" ] }, "amount": { "type": "string", "description": "Price of one cycle. Decimal string — never parse it as a float." }, "currency": { "type": "string", "description": "Currency of the cycle price." }, "description": { "type": "string", "description": "What the buyer subscribed to." }, "merchant_reference": { "type": "string", "description": "Your own id." }, "metadata": { "type": "object", "description": "Your own key/value pairs.", "properties": {} }, "interval": { "type": "string", "description": "The billing period.", "enum": [ "day", "week", "month", "year" ] }, "interval_count": { "type": "number", "description": "Intervals per cycle." }, "trial_end": { "type": "string", "format": "date-time", "description": "When the free period ends." }, "ends_at": { "type": "string", "format": "date-time", "description": "When the subscription stops on its own." }, "customer": { "type": "object", "description": "Who is subscribing.", "properties": { "reference": { "type": "string", "description": "Your id for them." }, "country": { "type": "string", "description": "Two-letter country code." }, "payer_address": { "type": "string", "description": "The wallet paying." } } }, "settlement": { "type": "object", "description": "Where cycles pay out.", "properties": { "destination_id": { "type": "string", "description": "Destination used." }, "target": { "type": "string", "description": "How it resolves." }, "address": { "type": "string", "description": "The receiving address. Signed into the permission, so it cannot be changed without the buyer signing again." }, "asset": { "type": "string", "description": "Token settled in." }, "chain_id": { "type": "number", "description": "Chain settled on." } } }, "fee_bps": { "type": "number", "description": "Gateway fee in basis points, as signed." }, "spend_permission": { "type": "object", "description": "The on-chain authorisation. Never includes the signature: whoever holds that can submit an approval we did not initiate.", "properties": { "account": { "type": "string", "description": "The buyer's wallet." }, "token": { "type": "string", "description": "Token contract being spent." }, "allowance": { "type": "string", "description": "Maximum per period, in base units." }, "allowance_formatted": { "type": "string", "description": "The same allowance in human units. Decimal string — never parse it as a float." }, "allowance_asset": { "type": "string", "description": "Which token that allowance is in." }, "period_seconds": { "type": "number", "description": "Length of a spending period. The allowance resets each period and does not accumulate." }, "start": { "type": "number", "description": "Unix time it becomes usable." }, "end": { "type": "number", "description": "Unix time it expires." }, "chain_id": { "type": "number", "description": "Chain it is valid on." }, "manager": { "type": "string", "description": "Address of the SpendPermissionManager holding it." }, "hash": { "type": "string", "description": "EIP-712 hash of the permission. What the contract keys revocation on." }, "approved_at": { "type": "string", "format": "date-time", "description": "When the buyer signed." }, "revoked_at": { "type": "string", "format": "date-time", "description": "When it was revoked, on-chain or by cancellation." } } }, "cycle_count": { "type": "number", "description": "Cycles opened so far." }, "current_period_start": { "type": "string", "format": "date-time", "description": "Start of the period being paid for." }, "current_period_end": { "type": "string", "format": "date-time", "description": "End of it." }, "next_charge_at": { "type": "string", "format": "date-time", "description": "When the next charge is attempted." }, "last_charged_at": { "type": "string", "format": "date-time", "description": "When the last successful charge happened." }, "failure_count": { "type": "number", "description": "Consecutive failed cycles." }, "last_failure_reason": { "type": "string", "description": "Why the last one failed." }, "cancel_at_period_end": { "type": "boolean", "description": "Whether it stops when the paid period runs out." }, "canceled_at": { "type": "string", "format": "date-time", "description": "When it was cancelled." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } } }, "SubscriptionCycle": { "type": "object", "description": "One billing period of a subscription. The unit of subscription revenue.", "properties": { "id": { "type": "string", "description": "The cycle. Ids are prefixed `cyc_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `subscription_cycle`." }, "subscription_id": { "type": "string", "description": "The subscription it belongs to." }, "sequence": { "type": "number", "description": "Which cycle this is, from 1. Unique per subscription, which is what stops a restarted worker billing the same period twice." }, "status": { "type": "string", "description": "Where this cycle got to.", "enum": [ "pending", "processing", "paid", "failed", "skipped", "canceled" ] }, "amount": { "type": "string", "description": "Charged for this cycle, in `currency`. Decimal string — never parse it as a float." }, "currency": { "type": "string", "description": "Currency of that amount." }, "period_start": { "type": "string", "format": "date-time", "description": "Start of the period." }, "period_end": { "type": "string", "format": "date-time", "description": "End of it." }, "due_at": { "type": "string", "format": "date-time", "description": "When payment is due." }, "charged": { "type": "string", "description": "What was actually taken, in the settlement token. Decimal string — never parse it as a float." }, "asset": { "type": "string", "description": "Token taken." }, "chain_id": { "type": "number", "description": "Chain it was taken on." }, "tx_hash": { "type": "string", "description": "The charge transaction." }, "payment_id": { "type": "string", "description": "For a `payment_link` subscription, the payment raised for this cycle." }, "checkout_url": { "type": "string", "description": "Where to send the buyer to pay this cycle." }, "attempts": { "type": "number", "description": "Charge attempts made." }, "next_attempt_at": { "type": "string", "format": "date-time", "description": "When the next retry happens." }, "failure_reason": { "type": "string", "description": "Why the last attempt failed." }, "paid_at": { "type": "string", "format": "date-time", "description": "When it was paid." }, "created_at": { "type": "string", "format": "date-time", "description": "When the cycle was opened." } } }, "Settlement": { "type": "object", "description": "Money that arrived on-chain, and where it went. The gateway never holds it — a settlement is a record of a transfer between the buyer and you.", "properties": { "id": { "type": "string", "description": "The settlement. Ids are prefixed `stl_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `settlement`." }, "payment_id": { "type": "string", "description": "The payment this settles." }, "path": { "type": "string", "description": "How it was settled — direct, router, or swept from a deposit address." }, "chain_id": { "type": "number", "description": "Chain it happened on." }, "tx_hash": { "type": "string", "description": "The transaction. This is the receipt; everything else here is derived from it." }, "block_number": { "type": "number", "description": "Block it was included in." }, "block_timestamp": { "type": "string", "format": "date-time", "description": "When that block was mined." }, "asset": { "type": "string", "description": "Token received." }, "gross": { "type": "string", "description": "What arrived. Decimal string — never parse it as a float." }, "fee": { "type": "string", "description": "Gateway fee taken. Decimal string — never parse it as a float." }, "gas": { "type": "string", "description": "Gas recovered, where the gateway paid it. Decimal string — never parse it as a float." }, "net": { "type": "string", "description": "What reached your address. This is your revenue. Decimal string — never parse it as a float." }, "excess_returned": { "type": "string", "description": "Overpayment sent back to the buyer. Decimal string — never parse it as a float." }, "to_address": { "type": "string", "description": "Where the net went." }, "fiat_value": { "type": "object", "description": "The value at settlement time, for your books.", "properties": {} }, "confirmations": { "type": "number", "description": "Confirmations at the last check." }, "reorged": { "type": "boolean", "description": "Whether the block was later reorganised away. If true, this settlement did not happen and the payment went back to unpaid." }, "status": { "type": "string", "description": "A `quarantined` settlement is a transaction that carried this payment's id but did not match its terms — wrong recipient, wrong token, too little. Nothing was credited. It is listed rather than hidden so you can see the attempt.", "enum": [ "recorded", "quarantined" ] }, "mismatches": { "type": "array", "description": "On a quarantined settlement, which terms disagreed.", "items": { "type": "string" } }, "note": { "type": "string", "description": "On a quarantined settlement, a plain-language explanation." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was recorded." } } }, "Refund": { "type": "object", "description": "Money going back. Non-custodial means we cannot send it for you: a refund is prepared here and broadcast by whoever holds the funds.", "properties": { "id": { "type": "string", "description": "The refund. Ids are prefixed `re_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `refund`." }, "payment_id": { "type": "string", "description": "The payment being refunded." }, "kind": { "type": "string", "description": "Whether this is a requested refund, an overpayment return, or a late payment sent back." }, "amount": { "type": "string", "description": "Being returned. Decimal string — never parse it as a float." }, "amount_base_units": { "type": "string", "description": "The same amount in the token's smallest unit." }, "asset": { "type": "string", "description": "Token being returned." }, "chain_id": { "type": "number", "description": "Chain it goes back on." }, "to_address": { "type": "string", "description": "Where it goes." }, "destination_kind": { "type": "string", "description": "How that address was chosen. `payer_address` is the wallet that paid — which is often an exchange withdrawal address that cannot receive, so a stated refund address wins over it.", "enum": [ "buyer_confirmed", "buyer_refund_address", "payer_address" ] }, "state": { "type": "string", "description": "Where the refund got to.", "enum": [ "pending", "prepared", "submitted", "succeeded", "failed", "canceled" ] }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for." }, "sla_due_at": { "type": "string", "format": "date-time", "description": "When you undertook to have sent it by." }, "fulfilment_tx_hash": { "type": "string", "description": "The transaction that sent it." }, "failure_reason": { "type": "string", "description": "Why the last submitted transaction did not complete this refund — `reverted`, `no_matching_transfer`, `transfer_predates_payment`, `not_mined_after_24h`, `transfer_already_used`. The refund is still owed." }, "verified_at": { "type": "string", "format": "date-time", "description": "When that transaction was seen confirmed. Until then the refund is a claim, not a fact." }, "reason": { "type": "string", "description": "Why it was refunded." }, "created_at": { "type": "string", "format": "date-time", "description": "When the record was created." } } }, "SettlementDestination": { "type": "object", "description": "Somewhere your money can be sent. The highest-value object in the account: whoever can add one and make it the default can redirect every future payment.", "properties": { "id": { "type": "string", "description": "The destination. Ids are prefixed `dst_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `settlement_destination`." }, "kind": { "type": "string", "description": "A Shield account, or a plain address.", "enum": [ "shield", "address" ] }, "shield_code": { "type": "string", "description": "The Shield code, when that is what it is." }, "resolved_address": { "type": "string", "description": "The address that actually receives." }, "chains": { "type": "array", "description": "Chain ids it can receive on.", "items": { "type": "number" } }, "asset": { "type": "string", "description": "Token it is restricted to, if any." }, "label": { "type": "string", "description": "Your name for it." }, "status": { "type": "string", "description": "A destination cannot receive until it is `active`. `pending_verification` means nobody has proved they hold the key yet.", "enum": [ "pending_verification", "pending_screening", "active", "blocked", "removed" ] }, "verified_at": { "type": "string", "format": "date-time", "description": "When the signature proof was accepted." }, "usable_at": { "type": "string", "format": "date-time", "description": "When it may first be settled to. New destinations wait, so a stolen session cannot add an address and drain the next payment before anyone notices." }, "screening_state": { "type": "string", "description": "Result of sanctions screening on the address." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added." }, "verification": { "type": "object", "description": "Re-offered on every read while proof is outstanding, so closing the page between adding a destination and signing for it is not a dead end.", "properties": { "method": { "type": "string", "description": "Always `signature`." }, "message": { "type": "string", "description": "The exact message to sign with the destination wallet." }, "instructions": { "type": "string", "description": "What to do with it." } } } } }, "WebhookEndpoint": { "type": "object", "description": "Where events are delivered.", "properties": { "id": { "type": "string", "description": "The endpoint. Ids are prefixed `whe_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `webhook_endpoint`." }, "url": { "type": "string", "description": "Where events are POSTed. HTTPS only." }, "events": { "type": "array", "description": "Event types sent here.", "items": { "type": "string" } }, "api_version": { "type": "string", "description": "The payload version this endpoint receives." }, "status": { "type": "string", "description": "A repeatedly failing endpoint is disabled rather than retried forever.", "enum": [ "enabled", "disabled" ] }, "mode": { "type": "string", "description": "Whether it receives live or test events.", "enum": [ "live", "test" ] }, "consecutive_failures": { "type": "number", "description": "Failed deliveries in a row. Resets on success." }, "disabled_at": { "type": "string", "format": "date-time", "description": "When it was disabled for failing." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was registered." } } }, "Account": { "type": "object", "description": "Your merchant account, as the API sees it.", "properties": { "id": { "type": "string", "description": "The account. Ids are prefixed `org_` and opaque; do not parse them." }, "object": { "type": "string", "description": "Always `account`." }, "name": { "type": "string", "description": "Business name." }, "kyb_status": { "type": "string", "description": "Where verification got to." }, "merchant_of_record": { "type": "boolean", "description": "Whether you are the merchant of record. On this gateway you are: the money never touches us, so it cannot be ours to be liable for." }, "settlement": { "type": "object", "description": "Account-default settlement: destination, asset, chain and mode.", "properties": {} }, "accepted": { "type": "object", "description": "Which assets and chains you take.", "properties": {} }, "branding": { "type": "object", "description": "How the hosted checkout looks.", "properties": {} }, "capture_method": { "type": "string", "description": "Default for new payments. `manual` holds the funds in escrow until you capture them.", "enum": [ "automatic", "manual" ] }, "gas_payer": { "type": "string", "description": "Who carries the network fee: added to the buyer's total, or taken from your settlement beside the gateway fee.", "enum": [ "buyer", "merchant" ] }, "hold_window_hours": { "type": "number", "description": "How long a held payment waits before the buyer may reclaim it." }, "hold_window_max_hours": { "type": "number", "description": "The longest this platform allows. Your window cannot exceed it." }, "rate_mode": { "type": "string", "description": "Default for new payments.", "enum": [ "fixed_rate", "floating_rate" ] }, "tier": { "type": "string", "description": "Fee tier." }, "refund_sla_hours": { "type": "number", "description": "How quickly you undertake to send refunds." }, "verified_domains": { "type": "array", "description": "Domains proved yours. Only these may embed the checkout.", "items": { "type": "string" } }, "pending_domains": { "type": "array", "description": "Claimed but not yet proved.", "items": { "type": "object", "description": "A domain awaiting its DNS record.", "properties": { "domain": { "type": "string", "description": "The domain claimed." }, "token": { "type": "string", "description": "The challenge value to publish. Yours to see — it proves nothing on its own." }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was claimed." }, "last_checked_at": { "type": "string", "format": "date-time", "description": "When DNS was last read." }, "last_error": { "type": "string", "description": "Why the last check did not pass." } } } }, "status": { "type": "string", "description": "Whether the account can take money." } } }, "PaymentList": { "type": "object", "description": "A page of payments, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/Payment" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "SubscriptionList": { "type": "object", "description": "A page of subscriptions, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/Subscription" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "SubscriptionCycleList": { "type": "object", "description": "A page of cycles, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/SubscriptionCycle" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "SettlementList": { "type": "object", "description": "A page of settlements, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/Settlement" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "RefundList": { "type": "object", "description": "A page of refunds, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/Refund" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "SettlementDestinationList": { "type": "object", "description": "A page of destinations, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/SettlementDestination" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "WebhookEndpointList": { "type": "object", "description": "A page of endpoints, newest first.", "properties": { "object": { "type": "string", "description": "Always `list`." }, "data": { "type": "array", "description": "The page.", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean", "description": "Whether another page exists." }, "next_cursor": { "type": "string", "description": "Pass as `starting_after` to fetch it. Absent on the last page." } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "invalid_request_error" }, "code": { "type": "string", "example": "below_minimum_payment" }, "message": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" } }, "required": [ "type", "code", "message", "request_id" ] } } } } } }