{ "openapi": "3.1.0", "info": { "title": "Cryptonera API", "version": "2026-10-12", "description": "Merchant API of the Crypto Billing and Crypto Splitter platform, revision 2026-10-12 (also the webhook `schema_version`). Amounts are decimal strings; asset identifiers include the network (`USDT_TRON`). `Idempotency-Key` is required on endpoints that move money and optional elsewhere. Lists use cursor pagination. Errors: `{error: {code, message, retryable, request_id, …}}`. Base URL `/api/v1`. Human-readable reference: `/developers`." }, "servers": [ { "url": "{base_url}/api/v1", "variables": { "base_url": { "default": "https://example.com" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Invoices", "description": "Invoices, their checkout designs, and accepting partial, late or extra payments.", "x-product": "billing" }, { "name": "Refunds", "description": "Refunds of an invoice's payment to the address that paid it.", "x-product": "billing" }, { "name": "Payouts", "description": "Paying your customers from your payout wallet; the payout wallets themselves.", "x-product": "billing" }, { "name": "Settlements", "description": "What reaches you: settlements with their on-chain transfers, and withdrawals of your balance.", "x-product": "billing" }, { "name": "Balances", "description": "Your money per asset, with a USD estimate.", "x-product": "billing" }, { "name": "Activity", "description": "The customer payments (deposits) of both products.", "x-product": "shared" }, { "name": "Assets", "description": "Supported assets and your commission per asset.", "x-product": "shared" }, { "name": "Webhooks", "description": "Webhook endpoints, the event log and replays.", "x-product": "shared" }, { "name": "Wallets", "description": "Managed and watch-only wallets of your account.", "x-product": "shared" }, { "name": "Splitters", "description": "Persistent receiving wallets that split every deposit.", "x-product": "splitter" }, { "name": "Split sessions", "description": "One-off fresh deposit addresses that split one payment.", "x-product": "splitter" } ], "paths": { "/checkout-themes": { "get": { "operationId": "listCheckoutThemes", "summary": "List the checkout designs", "tags": [ "Invoices" ], "description": "Scope `invoices:read`. Every design with live previews on sample data; `store_default` for a key restricted to a store.", "x-scope": "invoices:read", "x-idempotency": "none", "responses": { "200": { "description": "The designs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "default", "data", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "default": { "type": "string", "enum": [ "modern", "classic", "minimal", "midnight", "vivid" ], "description": "The platform's default design." }, "store_default": { "type": "string", "enum": [ "modern", "classic", "minimal", "midnight", "vivid" ], "description": "A key restricted to a store: that store's design." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutTheme" }, "description": "The designs." }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "tags": [ "Invoices" ], "description": "Scope `invoices:read`. Newest first; every filter is exact. `merchant_reference` was renamed `order_id` (sending it: `422`).", "x-scope": "invoices:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "awaiting_payment", "confirming", "partially_paid", "paid", "overpaid", "expired", "underpaid", "paid_late", "cancelled", "refund_pending", "partially_refunded", "refunded" ] }, "description": "Only this status." }, { "name": "store_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this store (a key restricted to a store lists only its own; another store: `403 store_not_allowed`)." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant order ID (exact)." }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Transaction ID (any case, dashes optional; not a transaction id: no results)." }, { "name": "number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Invoice number." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer ID." }, { "name": "customer_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer email (any case)." }, { "name": "needs_decision", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "`true`: only invoices whose held money waits for your decision; `false`: the others (`1`/`0` too)." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createInvoice", "summary": "Create an invoice", "tags": [ "Invoices" ], "description": "Scope `invoices:write`. See [create an invoice](#billing-create). With `order_id`, one order keeps one open invoice per store: the same order again answers `200` with that invoice (`\"created\": false`); other terms `409 order_id_in_use`; a paid order `409 order_already_paid`. A setting that is missing answers `422 validation_failed` with a `reason` (the key stays free).", "x-scope": "invoices:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pricing_mode", "currency", "amount" ], "additionalProperties": false, "properties": { "pricing_mode": { "type": "string", "enum": [ "crypto", "fiat" ], "description": "`crypto`: priced in one asset. `fiat`: priced in a currency, converted per allowed asset at creation." }, "currency": { "type": "string", "maxLength": 40, "description": "crypto: an asset identifier (`/developers#allowed-assets`); fiat: an ISO-4217 code the price source quotes (fiat currencies (`/developers#fiat-currencies`)). Case-insensitive. Crypto pricing: on an invoice that settles to a wallet, for a store with payment assets one of them that can be paid in this environment (another payment option: `asset_not_in_store`); a split-settled invoice is paid in the splitter's asset." }, "amount": { "type": "string", "maxLength": 64, "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,18})?$", "description": "A positive decimal string, e.g. `\"49.99\"`. A JSON string, never a number. Crypto pricing: at most the asset's decimals. At least the asset's minimum deposit and more than twice the fixed fee per invoice." }, "order_id": { "type": "string", "maxLength": 120, "description": "Any text up to 120 characters after trimming; control characters are removed. Your order number (duplicate protection (`/developers#order-id`)). While an invoice of this order is open in the store, the same order with the same terms (`pricing_mode`, `currency`, `amount`, and the allowed assets only when the request chose them) returns that invoice unchanged (`200`, `\"created\": false`; every other field is ignored); other terms: `409 order_id_in_use`; an order whose invoice received money: `409 order_already_paid`." }, "customer_id": { "type": "string", "maxLength": 120, "description": "Any text up to 120 characters. Your customer reference: find the customer's invoices and refunds by it." }, "customer_email": { "type": "string", "format": "email", "maxLength": 160, "description": "An email address up to 160 characters. Stored in lower case. Never shown to the payer." }, "description": { "type": "string", "maxLength": 255, "description": "Up to 255 characters; HTML tags are removed. Shown to the payer." }, "lines": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "description" ], "additionalProperties": false, "properties": { "description": { "type": "string", "maxLength": 255, "description": "The line, as the payer reads it." }, "quantity": { "type": "number", "minimum": 0, "maximum": 1000000000, "description": "Quantity (display only)." }, "amount": { "type": "string", "maxLength": 64, "description": "Amount as a decimal string (display only, never added up)." } } }, "description": "Up to 100 objects `{description, quantity, amount}`. Shown on the payer's receipt; display only, never added up." }, "allowed_assets": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "maxLength": 40 }, "description": "Asset identifiers (`/developers#allowed-assets`). Ignored on an invoice that settles to a wallet when its store has payment assets (still checked to be a list of 1-20 strings): those are enforced. A store without them lets the request decide: crypto pricing exactly one, equal to `currency`; fiat pricing needs it (`allowed_assets_missing`). An empty list is an error." }, "expires_in_seconds": { "type": "integer", "description": "300–2592000 (clamped, never refused). The store's Invoice expiry wins when it sets one; `expires_at` in the response is the expiry that applies." }, "return_url": { "type": "string", "maxLength": 512, "format": "uri", "description": "An absolute https:// URL. Link on the checkout after payment." }, "cancel_url": { "type": "string", "maxLength": 512, "format": "uri", "description": "An absolute https:// URL. Link on the checkout to go back." }, "metadata": { "type": "object", "description": "A JSON object up to 4096 bytes. Returned as sent; the keys settlement_address, settlement_addresses and settlement_asset_addresses are reserved." }, "settlement_type": { "type": "string", "enum": [ "wallet", "splitter" ], "description": "`splitter` when `settlement_target_id` is sent, `wallet` when an address is sent. Wallet invoices settle to your settlement wallets (`/developers#billing-settlement`) on the per_invoice and daily schedules, into your balance on on_request (the default)." }, "settlement_target_id": { "type": "string", "maxLength": 26, "description": "An active splitter id of this account. Refused while the settlement lock (`/developers#billing-settlement-lock`) is on (`422 settlement_address_locked`)." }, "settlement_address": { "type": "string", "maxLength": 128, "description": "An address valid for every allowed asset's network, never an address of this platform (a payment, collection or payout wallet address it holds the keys for: `422 validation_failed`). Refused while the settlement lock (`/developers#billing-settlement-lock`) is on (`422 settlement_address_locked`). Used by the per_invoice and daily schedules; on on_request (the default) the share goes to your balance." }, "settlement_addresses": { "type": "object", "properties": { "evm": { "type": "string", "maxLength": 128, "description": "Settlement address for the assets of the evm family." }, "bitcoin": { "type": "string", "maxLength": 128, "description": "Settlement address for the assets of the bitcoin family." }, "bitcoincash": { "type": "string", "maxLength": 128, "description": "Settlement address for the assets of the bitcoincash family." }, "tron": { "type": "string", "maxLength": 128, "description": "Settlement address for the assets of the tron family." } }, "additionalProperties": false, "description": "Keys: `evm`, `bitcoin`, `bitcoincash`, `tron` (network families); never an address of this platform (`422 validation_failed`). Refused while the settlement lock (`/developers#billing-settlement-lock`) is on (`422 settlement_address_locked`). Used by the per_invoice and daily schedules; on on_request (the default) the share goes to your balance." }, "store_id": { "type": "string", "maxLength": 26, "description": "A store id of this account. A key restricted to a store may only use that store (`403 store_not_allowed`)." }, "checkout_theme": { "type": "string", "enum": [ "modern", "classic", "minimal", "midnight", "vivid" ], "description": "Only the look changes (designs (`/developers#billing-themes`))." } } } } } }, "responses": { "201": { "description": "A new invoice (`\"created\": true`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/InvoiceCreated" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "200": { "description": "The open invoice of the same `order_id` with the same terms (`\"created\": false`); nothing new.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/InvoiceCreated" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Read an invoice", "tags": [ "Invoices" ], "description": "Scope `invoices:read`. `{id}` is the Payment ID or the `transaction_id` (any case, dashes optional).", "x-scope": "invoices:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment ID or Transaction ID." } ], "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/invoices/{id}/accept": { "post": { "operationId": "acceptInvoice", "summary": "Accept held money", "tags": [ "Invoices" ], "description": "Scope `invoices:write`. Accepts the money an invoice holds in one asset (underpaid, paid late, an excess or a payment after it was paid): within about a minute it is settled like a payment with the invoice's fee (`invoice.accepted`, then `invoice.paid`), or `invoice.accept_failed`. An open, partly paid invoice is closed first (refused with `409 payment_confirming` while a payment to it confirms); an invoice still `awaiting_payment` or `confirming` gets `409 nothing_to_accept`.", "x-scope": "invoices:write", "x-idempotency": "required", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment ID or Transaction ID." }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "maxLength": 40, "description": "The asset; required when money is held in several assets." }, "expected_amount": { "type": "string", "maxLength": 64, "pattern": "^\\d+(\\.\\d+)?$", "description": "The held amount you saw (`decision.held[].amount`); `409 held_amount_changed` when it differs. Recommended." }, "reason": { "type": "string", "maxLength": 500, "description": "Your note (audit log)." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Recorded: the invoice with `decision.status: accepting`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/invoices/{id}/cancel": { "post": { "operationId": "cancelInvoice", "summary": "Cancel an invoice", "tags": [ "Invoices" ], "description": "Scope `invoices:write`. Only an open invoice. A partly paid one becomes `underpaid` (its confirmed money held for your decision); its addresses stay watched.", "x-scope": "invoices:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment ID or Transaction ID." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 255, "description": "Why (audit log, `invoice.cancelled`). Default: `api`." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/refunds": { "get": { "operationId": "listRefunds", "summary": "List refunds", "tags": [ "Refunds" ], "description": "Scope `refunds:read`. Newest first; every filter is exact. A key restricted to a store lists the refunds of that store's invoices.", "x-scope": "refunds:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_approval", "queued", "processing", "completed", "failed", "cancelled" ] }, "description": "Only this status." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Asset identifier." }, { "name": "invoice_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The invoice (Payment ID)." }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The invoice's Transaction ID (any case, dashes optional)." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant order ID." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer ID." }, { "name": "customer_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer email (any case)." }, { "name": "destination", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Destination address." }, { "name": "tx_hash", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "The refund transfer's hash." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createRefund", "summary": "Refund an invoice", "tags": [ "Refunds" ], "description": "Scope `refunds:write`. See [refunds](#billing-refunds). Answers `201` (`processing`, or `pending_approval` when API refunds need approval) or `202` (`queued`: sent automatically once the money is there).", "x-scope": "refunds:write", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string", "maxLength": 64, "description": "The invoice (Payment ID); or `transaction_id`." }, "transaction_id": { "type": "string", "maxLength": 64, "description": "The invoice's Transaction ID (any case, dashes optional); or `invoice_id`." }, "amount": { "type": "string", "maxLength": 64, "pattern": "^\\d+(\\.\\d+)?$", "description": "In the invoice currency (fiat: its minor unit; crypto: the asset's decimals); an asset a fiat invoice has no payment option for (another token sent to its address) in that asset, up to what was received. Default: the most refundable." }, "asset": { "type": "string", "maxLength": 40, "description": "Which payment, when the invoice was paid in several assets." }, "destination": { "type": "string", "maxLength": 128, "description": "An address that paid the invoice (`payer_addresses`). Default: the payer of its largest payment." }, "destination_memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." }, "funding_source": { "type": "string", "enum": [ "balance", "payout_wallet" ], "description": "Pay it from your balance (default) or your payout wallet; ignored when the invoice's held payment pays it." }, "reason": { "type": "string", "maxLength": 500, "description": "Your note." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created: `processing` or `pending_approval`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "202": { "description": "Queued until the money is there (`status_reason`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/refunds/{id}": { "get": { "operationId": "getRefund", "summary": "Read a refund", "tags": [ "Refunds" ], "description": "Scope `refunds:read`.", "x-scope": "refunds:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Refund id." } ], "responses": { "200": { "description": "The refund.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/refunds/{id}/cancel": { "post": { "operationId": "cancelRefund", "summary": "Cancel a refund", "tags": [ "Refunds" ], "description": "Scope `refunds:write`. Only while `queued` or `pending_approval` (nothing was taken): it becomes `cancelled` and the invoice can be refunded again.", "x-scope": "refunds:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Refund id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The refund.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/payout-wallets": { "get": { "operationId": "listPayoutWallets", "summary": "List the payout wallets", "tags": [ "Payouts" ], "description": "Scope `payouts:read`. One per chain family with an enabled network (`status` `none` until created), with its money per asset.", "x-scope": "payouts:read", "x-idempotency": "none", "responses": { "200": { "description": "The payout wallets.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "environment", "data", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutWallet" }, "description": "The objects." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createPayoutWallet", "summary": "Create a payout wallet", "tags": [ "Payouts" ], "description": "Scope `payouts:write`. Records the request; the address is allocated within a minute or two (`202 allocating`). An existing one answers `200`.", "x-scope": "payouts:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "network_family" ], "properties": { "network_family": { "type": "string", "enum": [ "evm", "bitcoin", "bitcoincash", "tron" ], "description": "A family with an enabled network in this environment." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "It exists (`active`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PayoutWallet" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "202": { "description": "Being created (`allocating`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PayoutWallet" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/payouts": { "get": { "operationId": "listPayouts", "summary": "List payouts", "tags": [ "Payouts" ], "description": "Scope `payouts:read`. Payouts to your customers, newest first; every filter is exact.", "x-scope": "payouts:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_approval", "processing", "completed", "failed", "cancelled" ] }, "description": "Only this status." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Asset identifier." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer ID." }, { "name": "customer_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer email (any case)." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant order ID." }, { "name": "destination", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Destination address." }, { "name": "tx_hash", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "The payout transfer's hash." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createPayout", "summary": "Pay a customer", "tags": [ "Payouts" ], "description": "Scope `payouts:write`. See [payouts](#billing-payouts). From your payout wallet to a destination your settings allow; the network fee on top. Not enough in the payout wallet: `409 insufficient_balance`, nothing created (payouts are never queued).", "x-scope": "payouts:write", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "amount", "destination" ], "properties": { "asset": { "type": "string", "maxLength": 40, "description": "Asset identifier (tokens on EVM and Tron; BTC, BCH)." }, "amount": { "type": "string", "maxLength": 64, "pattern": "^\\d+(\\.\\d+)?$", "description": "What the customer receives (at most the asset's decimals)." }, "destination": { "type": "string", "maxLength": 128, "description": "The customer's address." }, "destination_memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." }, "customer_id": { "type": "string", "maxLength": 120, "description": "Your customer's id (allows any address of a customer with a paid invoice, when that basis is on)." }, "customer_email": { "type": "string", "maxLength": 160, "format": "email", "description": "Your customer's email (the same rule by email)." }, "order_id": { "type": "string", "maxLength": 120, "description": "Your Merchant order ID for this payout." }, "note": { "type": "string", "maxLength": 255, "description": "Your note." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created: `processing` or `pending_approval`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/payouts/{id}": { "get": { "operationId": "getPayout", "summary": "Read a payout", "tags": [ "Payouts" ], "description": "Scope `payouts:read`.", "x-scope": "payouts:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payout id." } ], "responses": { "200": { "description": "The payout.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/payouts/{id}/cancel": { "post": { "operationId": "cancelPayout", "summary": "Cancel a payout", "tags": [ "Payouts" ], "description": "Scope `payouts:write`. Only while `pending_approval`: its money is available again.", "x-scope": "payouts:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payout id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The payout.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/settlements": { "get": { "operationId": "listSettlements", "summary": "List settlements", "tags": [ "Settlements" ], "description": "Scope `activity:read`. Newest first, each with its `transfers[]`; refunds and payouts are not listed (read them by id) and the platform's own fee collections never appear.", "x-scope": "activity:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "planned", "funds_reserved", "awaiting_resources", "submitting", "settling", "pooled", "completed", "partially_completed", "reconciliation_required", "held", "credited", "requested", "cancelled" ] }, "description": "Only this status." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "invoice", "daily", "split_session", "splitter", "balance_release", "withdrawal" ] }, "description": "Only this kind." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Asset identifier." }, { "name": "owner_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 26 }, "description": "The owner's id." }, { "name": "invoice_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 26 }, "description": "One invoice's settlements and the daily settlement that paid it." }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "The invoice or split session with this Transaction ID." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Invoices and split sessions with this Merchant order ID." }, { "name": "tx_hash", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "A customer payment's or a transfer's hash." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/settlements/{id}": { "get": { "operationId": "getSettlement", "summary": "Read a settlement", "tags": [ "Settlements" ], "description": "Scope `activity:read`. Any settlement of this environment (a refund's or payout's too); a platform fee collection: `404`.", "x-scope": "activity:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Settlement id." } ], "responses": { "200": { "description": "The settlement.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Settlement" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/withdrawals": { "get": { "operationId": "listWithdrawals", "summary": "List withdrawals", "tags": [ "Settlements" ], "description": "Scope `balances:read`. Settlements of kind `withdrawal`, newest first.", "x-scope": "balances:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "planned", "funds_reserved", "awaiting_resources", "submitting", "settling", "pooled", "completed", "partially_completed", "reconciliation_required", "held", "credited", "requested", "cancelled" ] }, "description": "Only this status." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 }, "description": "Asset identifier." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createWithdrawal", "summary": "Withdraw your balance", "tags": [ "Settlements" ], "description": "Scope `balances:withdraw`. See [settlements and withdrawals](#billing-settlements). Takes `amount` (default: everything available) from the balance for your saved settlement wallet; planned within about a minute; the transfer's network cost comes out of it.", "x-scope": "balances:withdraw", "x-idempotency": "required", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset" ], "properties": { "asset": { "type": "string", "maxLength": 40, "description": "Asset identifier." }, "amount": { "type": "string", "maxLength": 64, "pattern": "^\\d+(\\.\\d+)?$", "description": "At most the asset's decimals and what is available. Default: everything available." }, "destination_address": { "type": "string", "maxLength": 128, "description": "Only while the settlement lock is off. Default: your saved settlement wallet. Never an address of this platform (a payment, collection or payout wallet address it holds the keys for: `422 validation_failed`)." }, "destination_memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." }, "note": { "type": "string", "maxLength": 255, "description": "Your note (`withdrawal.note`)." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Recorded: the withdrawal (`requested`).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Settlement" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/withdrawals/{id}": { "get": { "operationId": "getWithdrawal", "summary": "Read a withdrawal", "tags": [ "Settlements" ], "description": "Scope `balances:read`.", "x-scope": "balances:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Withdrawal (settlement) id." } ], "responses": { "200": { "description": "The withdrawal.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Settlement" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/withdrawals/{id}/cancel": { "post": { "operationId": "cancelWithdrawal", "summary": "Cancel a withdrawal", "tags": [ "Settlements" ], "description": "Scope `balances:withdraw`. Only while `requested`: it becomes `cancelled` and its amount is available again.", "x-scope": "balances:withdraw", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Withdrawal (settlement) id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The withdrawal.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Settlement" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/balances": { "get": { "operationId": "getBalances", "summary": "Read your balances", "tags": [ "Balances" ], "description": "Scope `balances:read`. Per asset: available to withdraw, pending, held, reserved, payout wallet, retained, deficit, with a USD estimate.", "x-scope": "balances:read", "x-idempotency": "none", "responses": { "200": { "description": "The balances.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceList" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/deposits": { "get": { "operationId": "listDeposits", "summary": "List deposits", "tags": [ "Activity" ], "description": "Scope `activity:read`. Customer payments of both products, newest first.", "x-scope": "activity:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this status." }, { "name": "asset", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Asset identifier." }, { "name": "owner_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The owner's id." }, { "name": "tx_hash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Transaction hash." }, { "name": "invoice_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One invoice's payments." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Invoices with this Merchant order ID." }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The invoice with this Transaction ID (a split session's payments: `?owner_id=` the session id)." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/assets": { "get": { "operationId": "listAssets", "summary": "List the assets", "tags": [ "Assets" ], "description": "Scope `assets:read`. The assets of the key's environment with their network, minimums and your commission.", "x-scope": "assets:read", "x-idempotency": "none", "responses": { "200": { "description": "The assets.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "environment", "data", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" }, "description": "The objects." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/fee-policy": { "get": { "operationId": "getFeePolicy", "summary": "Read your fee policy", "tags": [ "Assets" ], "description": "Scope `fees:read`. Your commission per asset, the cost model and your settlement schedule.", "x-scope": "fees:read", "x-idempotency": "none", "responses": { "200": { "description": "The fee policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeePolicy" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "description": "Scope `webhooks:read`.", "x-scope": "webhooks:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "description": "Scope `webhooks:write`. The URL must be public https (SSRF-checked). The signing secret is shown once.", "x-scope": "webhooks:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "maxLength": 512, "description": "Public https URL." }, "event_types": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1, "description": "Subscriptions: `*`, `.*` or event names with a known prefix (invoice, deposit, settlement, fee, refund, split_session, splitter, payout); anything else: `422`. `payout.*` before the platform's database update 000037: `503 schema_update_pending`." }, "store_id": { "type": "string", "maxLength": 26, "description": "Only events of this store." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "The endpoint with its `secret` (shown once).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpointSecret" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhook-endpoints/{id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Read a webhook endpoint", "tags": [ "Webhooks" ], "description": "Scope `webhooks:read`.", "x-scope": "webhooks:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Endpoint id." } ], "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Change a webhook endpoint", "tags": [ "Webhooks" ], "description": "Scope `webhooks:write`. URL, subscriptions, status; `rotate_secret` returns a new secret (the old one signs too for a while). Disabling cancels its pending deliveries.", "x-scope": "webhooks:write", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Endpoint id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 512, "description": "Public https URL." }, "event_types": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1, "description": "Subscriptions: `*`, `.*` or event names with a known prefix (invoice, deposit, settlement, fee, refund, split_session, splitter, payout); anything else: `422`. `payout.*` before the platform's database update 000037: `503 schema_update_pending`." }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`disabled`: receives nothing." }, "rotate_secret": { "type": "boolean", "description": "Create a new signing secret." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The endpoint (with `secret` after a rotation).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpointSecret" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Disable a webhook endpoint", "tags": [ "Webhooks" ], "description": "Scope `webhooks:write`. Endpoints are disabled, never deleted (delivery history stays); pending deliveries are cancelled.", "x-scope": "webhooks:write", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Endpoint id." } ], "responses": { "200": { "description": "Disabled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted", "disabled", "id", "deliveries_cancelled", "note", "request_id" ], "properties": { "deleted": { "type": "boolean", "description": "Always false." }, "disabled": { "type": "boolean", "description": "Always true." }, "id": { "type": "string", "description": "The endpoint." }, "deliveries_cancelled": { "type": "integer", "description": "Pending deliveries cancelled." }, "note": { "type": "string", "description": "For people." }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhook-events": { "get": { "operationId": "listWebhookEvents", "summary": "List webhook events", "tags": [ "Webhooks" ], "description": "Scope `webhooks:read`. Every event with its deliveries, newest first: also a polling feed.", "x-scope": "webhooks:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this event type." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/webhook-events/{id}/replay": { "post": { "operationId": "replayWebhookEvent", "summary": "Replay a webhook event", "tags": [ "Webhooks" ], "description": "Scope `webhooks:write`. One new delivery per endpoint (or `endpoint_id` only), with the same event id; disabled endpoints are skipped (`422` when none is left).", "x-scope": "webhooks:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint_id": { "type": "string", "maxLength": 26, "description": "Only this endpoint." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "The new deliveries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "endpoint_id", "status" ], "properties": { "id": { "type": "string", "description": "Delivery id." }, "endpoint_id": { "type": "string", "description": "The endpoint." }, "status": { "type": "string", "description": "Its status." } }, "additionalProperties": false }, "description": "The deliveries." }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/wallets": { "get": { "operationId": "listWallets", "summary": "List wallets", "tags": [ "Wallets" ], "description": "Scope `wallets:read`.", "x-scope": "wallets:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createWallet", "summary": "Create a wallet", "tags": [ "Wallets" ], "description": "Scope `wallets:write`. A managed wallet (keys at the custody provider) or a watch-only address; never accepts seeds or keys.", "x-scope": "wallets:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "label", "asset" ], "properties": { "kind": { "type": "string", "enum": [ "managed", "watch_only" ], "description": "Managed or watch-only." }, "label": { "type": "string", "maxLength": 80, "description": "Your label." }, "asset": { "type": "string", "maxLength": 40, "description": "Asset identifier." }, "address": { "type": "string", "maxLength": 128, "description": "Watch-only: the address." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "The wallet.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Wallet" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "202": { "description": "Being provisioned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "status", "reason", "request_id" ], "properties": { "object": { "type": "string", "const": "wallet", "description": "Always `wallet`." }, "status": { "type": "string", "description": "`provisioning`." }, "reason": { "type": [ "string", "null" ], "description": "Why it waits." }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/splitters": { "get": { "operationId": "listSplitters", "summary": "List splitters", "tags": [ "Splitters" ], "description": "Scope `splitters:read`.", "x-scope": "splitters:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this status." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Splitter" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createSplitter", "summary": "Create a splitter", "tags": [ "Splitters" ], "description": "Scope `splitters:write`. A persistent receiving wallet that splits every deposit; `draft` until signer control is verified.", "x-scope": "splitters:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "asset", "recipients" ], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name." }, "asset": { "type": "string", "maxLength": 40, "description": "Asset identifier." }, "recipients": { "type": "array", "items": { "type": "object", "required": [ "address", "percentage" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "A valid address for the asset's network." }, "percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "description": "Share with at most two decimals; all shares add up to exactly `100.00`." }, "label": { "type": "string", "maxLength": 80, "description": "For people." }, "memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "Who receives what." }, "receiving_mode": { "type": "string", "enum": [ "managed", "watch_only" ], "description": "`managed` (default) or `watch_only` (monitoring only)." }, "receiving_address": { "type": "string", "maxLength": 128, "description": "watch_only: the address." }, "settlement_mode": { "type": "string", "enum": [ "each_confirmed_deposit", "threshold" ], "description": "When it splits." }, "settlement_threshold": { "type": "string", "maxLength": 64, "description": "threshold: the amount (decimal string)." }, "store_id": { "type": "string", "maxLength": 26, "description": "The store." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "The splitter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Splitter" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/splitters/{id}": { "get": { "operationId": "getSplitter", "summary": "Read a splitter", "tags": [ "Splitters" ], "description": "Scope `splitters:read`. With every recipient version.", "x-scope": "splitters:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Splitter id." } ], "responses": { "200": { "description": "The splitter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SplitterDetail" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "updateSplitter", "summary": "Change the recipients", "tags": [ "Splitters" ], "description": "Scope `splitters:write`. A new recipient version from the next block on.", "x-scope": "splitters:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Splitter id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "items": { "type": "object", "required": [ "address", "percentage" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "A valid address for the asset's network." }, "percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "description": "Share with at most two decimals; all shares add up to exactly `100.00`." }, "label": { "type": "string", "maxLength": 80, "description": "For people." }, "memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "Who receives what." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The splitter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Splitter" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/splitters/{id}/pause": { "post": { "operationId": "pauseSplitter", "summary": "Pause a splitter", "tags": [ "Splitters" ], "description": "Scope `splitters:write`. Sends stop; deposits are still watched and accounted.", "x-scope": "splitters:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Splitter id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The splitter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Splitter" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/splitters/{id}/resume": { "post": { "operationId": "resumeSplitter", "summary": "Resume a splitter", "tags": [ "Splitters" ], "description": "Scope `splitters:write`.", "x-scope": "splitters:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Splitter id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The splitter.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Splitter" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/split-sessions": { "get": { "operationId": "listSplitSessions", "summary": "List split sessions", "tags": [ "Split sessions" ], "description": "Scope `sessions:read`.", "x-scope": "sessions:read", "x-idempotency": "none", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this status." }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant order ID (exact)." }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Transaction ID (any case, dashes optional)." }, { "name": "store_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this store." } ], "responses": { "200": { "description": "The page: `data` newest first, `next_cursor` for the next.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "next_cursor", "has_more", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SplitSession" }, "description": "The page of objects, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `?cursor=` for the next page; null on the last page." }, "has_more": { "type": "boolean", "description": "Whether a next page exists." }, "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createSplitSession", "summary": "Create a split session", "tags": [ "Split sessions" ], "description": "Scope `sessions:write`. A fresh deposit address for one payment (`202` with `allocating` until it is ready: poll `status_url`). No order check: a new `Idempotency-Key` per session protects a retry.", "x-scope": "sessions:write", "x-idempotency": "optional", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "recipients" ], "properties": { "asset": { "type": "string", "maxLength": 40, "description": "Asset identifier." }, "recipients": { "type": "array", "items": { "type": "object", "required": [ "address", "percentage" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "A valid address for the asset's network." }, "percentage": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$", "description": "Share with at most two decimals; all shares add up to exactly `100.00`." }, "label": { "type": "string", "maxLength": 80, "description": "For people." }, "memo": { "type": "string", "maxLength": 64, "description": "Memo or tag." } }, "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "Who receives what." }, "order_id": { "type": "string", "maxLength": 120, "description": "Your order number (any text; no duplicate check)." }, "expected_amount": { "type": "string", "maxLength": 64, "description": "The target (required for `target_confirmed_amount`; decimal string)." }, "settlement_trigger": { "type": "string", "enum": [ "each_confirmed_deposit", "target_confirmed_amount" ], "description": "When it is split (default `each_confirmed_deposit`)." }, "expires_in_seconds": { "type": "integer", "description": "300–604800 (default 3600)." }, "webhook_endpoint_id": { "type": "string", "maxLength": 26, "description": "Send its events only to this endpoint." }, "metadata": { "type": "object", "x-free-form": true, "description": "Returned as sent (at most 4096 bytes)." }, "store_id": { "type": "string", "maxLength": 26, "description": "The store." } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "The session.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SplitSession" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "202": { "description": "Allocating its address.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SplitSession" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/split-sessions/{id}": { "get": { "operationId": "getSplitSession", "summary": "Read a split session", "tags": [ "Split sessions" ], "description": "Scope `sessions:read`. With its deposits and settlements; retries the allocation while `allocating`.", "x-scope": "sessions:read", "x-idempotency": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Split session id." } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SplitSessionDetail" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/split-sessions/{id}/close": { "post": { "operationId": "closeSplitSession", "summary": "Close a split session", "tags": [ "Split sessions" ], "description": "Scope `sessions:write`. Stops normal payments (cancelled when unpaid); its address stays watched.", "x-scope": "sessions:write", "x-idempotency": "optional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Split session id." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SplitSession" }, { "$ref": "#/components/schemas/RequestId" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "webhooks": { "invoice.created": { "post": { "operationId": "webhook_invoice_created", "summary": "An invoice was created (also from the dashboard).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.created" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "number": { "type": "string", "description": "Invoice number." }, "amount": { "type": "string", "description": "The price (decimal string in `currency`)." }, "currency": { "type": "string", "description": "Its currency." }, "expires_at": { "type": "string", "format": "date-time", "description": "When it expires." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.confirming": { "post": { "operationId": "webhook_invoice_confirming", "summary": "Payments that cover the invoice were seen and wait for confirmations.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.confirming" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.payment_dropped": { "post": { "operationId": "webhook_invoice_payment_dropped", "summary": "The payment it was confirming left the chain and nothing else covers it: open again until it expires.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.payment_dropped" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "tx_hash": { "type": "string", "description": "Its transaction hash." }, "reason": { "type": [ "string", "null" ], "description": "Why (dropped, reorganised)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.partially_paid": { "post": { "operationId": "webhook_invoice_partially_paid", "summary": "A confirmed payment covers part of the amount (sent at confirmation only).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.partially_paid" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.paid": { "post": { "operationId": "webhook_invoice_paid", "summary": "Paid in full with confirmed money, or your accept made it paid: ship the order.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.paid" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "number": { "type": "string", "description": "Invoice number." }, "deposit_id": { "type": [ "string", "null" ], "description": "The payment that completed it (null after an accept)." }, "excess": { "type": "string", "description": "More than asked (decimal string; 0 when exact)." }, "excess_atomic": { "type": "string", "description": "The same in the smallest unit." }, "accepted": { "type": "boolean", "description": "true when your accept made it paid." }, "accepted_kind": { "type": [ "string", "null" ], "description": "The kind of that accept." }, "acceptance_id": { "type": [ "string", "null" ], "description": "That accept." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.overpaid": { "post": { "operationId": "webhook_invoice_overpaid", "summary": "Paid with more than asked: ship the order; the excess is held for your decision.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.overpaid" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "number": { "type": "string", "description": "Invoice number." }, "deposit_id": { "type": [ "string", "null" ], "description": "The payment that completed it (null after an accept)." }, "excess": { "type": "string", "description": "More than asked (decimal string; 0 when exact)." }, "excess_atomic": { "type": "string", "description": "The same in the smallest unit." }, "accepted": { "type": "boolean", "description": "true when your accept made it paid." }, "accepted_kind": { "type": [ "string", "null" ], "description": "The kind of that accept." }, "acceptance_id": { "type": [ "string", "null" ], "description": "That accept." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.underpaid": { "post": { "operationId": "webhook_invoice_underpaid", "summary": "It closed with a confirmed partial payment (or its amounts changed): held for your decision.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.underpaid" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "trigger": { "type": "string", "description": "`expired`, `cancelled`, `late_payment`, `payment_after_close`, `payment_reorganized`, `accepted_early` or `legacy`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Its expiry." }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was cancelled." }, "deposit_id": { "type": [ "string", "null" ], "description": "The payment concerned." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.late_payment": { "post": { "operationId": "webhook_invoice_late_payment", "summary": "A payment that arrived after it closed confirmed and is held.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.late_payment" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "tx_hash": { "type": "string", "description": "Its transaction hash." }, "deposit_asset": { "type": [ "string", "null" ], "description": "Its asset." }, "deposit_amount": { "type": [ "string", "null" ], "description": "Its amount (decimal string)." }, "deposit_amount_atomic": { "type": "string", "description": "The same in the smallest unit." }, "held": { "type": "boolean", "description": "Always true: the money is held." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.paid_late": { "post": { "operationId": "webhook_invoice_paid_late", "summary": "Confirmed money after it closed now covers it (or, already paid late, an on-time payment was held too): held for your decision (accept or refund).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.paid_late" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": [ "string", "null" ], "description": "The payment concerned." }, "trigger": { "type": "string", "description": "Why it was re-evaluated." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.payment_held": { "post": { "operationId": "webhook_invoice_payment_held", "summary": "A payment was held for another reason (`reason`: after it was paid, on a second option, below the minimum, another asset).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.payment_held" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "tx_hash": { "type": "string", "description": "Its transaction hash." }, "deposit_asset": { "type": [ "string", "null" ], "description": "Its asset." }, "deposit_amount": { "type": [ "string", "null" ], "description": "Its amount (decimal string)." }, "deposit_amount_atomic": { "type": "string", "description": "The same in the smallest unit." }, "reason": { "type": [ "string", "null" ], "description": "Why it is held." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.accepted": { "post": { "operationId": "webhook_invoice_accepted", "summary": "Your accept of held money was planned (then `invoice.paid` for an underpaid or paid-late invoice).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.accepted" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "acceptance_id": { "type": "string", "description": "The accept." }, "kind": { "type": "string", "description": "`underpayment`, `late_payment` or `extra_payment`." }, "accepted_asset": { "type": "string", "description": "The asset accepted." }, "accepted_amount": { "type": "string", "description": "The amount accepted (decimal string)." }, "accepted_amount_atomic": { "type": "string", "description": "Smallest unit." }, "status_before": { "type": "string", "description": "The invoice status before." }, "settlement_id": { "type": "string", "description": "The settlement that settles it." }, "platform_fee": { "type": "string", "description": "The platform fee taken (decimal string)." }, "platform_fee_atomic": { "type": "string", "description": "Smallest unit." }, "network_fee": { "type": "string", "description": "The network fee taken (decimal string)." }, "network_fee_atomic": { "type": "string", "description": "Smallest unit." }, "via": { "type": "string", "description": "`api` or `dashboard`." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.accept_failed": { "post": { "operationId": "webhook_invoice_accept_failed", "summary": "Your accept could not be planned; nothing moved and the decision is needed again.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.accept_failed" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "acceptance_id": { "type": "string", "description": "The accept." }, "accepted_asset": { "type": "string", "description": "The asset." }, "accepted_amount": { "type": "string", "description": "The amount (decimal string)." }, "accepted_amount_atomic": { "type": "string", "description": "Smallest unit." }, "reason": { "type": "string", "description": "Why: `held_amount_changed`, `amount_too_small_to_settle`, `settlement_destination_missing`, `network_fee_unavailable`, `operator_review_required`, `not_plannable`, `cancelled`." }, "message": { "type": [ "string", "null" ], "description": "For people." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.expired": { "post": { "operationId": "webhook_invoice_expired", "summary": "It closed at `expires_at` without any confirmed payment.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.expired" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "number": { "type": "string", "description": "Invoice number." }, "trigger": { "type": "string", "description": "`expired`, or `payment_reorganized` when its only payment was undone." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.cancelled": { "post": { "operationId": "webhook_invoice_cancelled", "summary": "You cancelled it.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.cancelled" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "reason": { "type": [ "string", "null" ], "description": "Your reason." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" }, { "$ref": "#/components/schemas/InvoiceEventAmounts" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.settlement_processing": { "post": { "operationId": "webhook_invoice_settlement_processing", "summary": "Its settlement is sending your share.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.settlement_processing" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "status": { "type": "string", "description": "The settlement's status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.settlement_scheduled": { "post": { "operationId": "webhook_invoice_settlement_scheduled", "summary": "Daily schedule: collected, sent with the next daily settlement.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.settlement_scheduled" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "status": { "type": "string", "description": "The settlement's status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.settlement_credited": { "post": { "operationId": "webhook_invoice_settlement_credited", "summary": "On-request schedule: your share is in your balance.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.settlement_credited" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "status": { "type": "string", "description": "The settlement's status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.settlement_settled": { "post": { "operationId": "webhook_invoice_settlement_settled", "summary": "Your share reached your wallet or splitter.", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.settlement_settled" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "status": { "type": "string", "description": "The settlement's status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "invoice.settlement_held": { "post": { "operationId": "webhook_invoice_settlement_held", "summary": "Its settlement waits (see the settlement's `hold_reason`).", "tags": [ "Invoices" ], "x-resource": "invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "invoice.settlement_held" }, "resource": { "type": "object", "properties": { "type": { "const": "invoice" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "status": { "type": "string", "description": "The settlement's status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.created": { "post": { "operationId": "webhook_refund_created", "summary": "A refund was created.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.created" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.queued": { "post": { "operationId": "webhook_refund_queued", "summary": "It waits for money (`status_reason`); sent automatically when the money suffices.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.queued" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "needed": { "type": "string", "description": "What it needs (decimal string)." }, "available": { "type": "string", "description": "What is available now (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.processing": { "post": { "operationId": "webhook_refund_processing", "summary": "Funded; its transfer is on its way.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.processing" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "settlement_id": { "type": "string", "description": "The settlement that sends it." }, "network_fee": { "type": "string", "description": "The network fee on top (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.completed": { "post": { "operationId": "webhook_refund_completed", "summary": "Sent and confirmed.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.completed" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transaction hash." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link." }, "network_fee": { "type": [ "string", "null" ], "description": "The network fee charged (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.failed": { "post": { "operationId": "webhook_refund_failed", "summary": "Its transfer failed.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.failed" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transaction hash, if any." }, "funds_returned": { "type": "boolean", "description": "The money went back where it came from." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "refund.cancelled": { "post": { "operationId": "webhook_refund_cancelled", "summary": "Cancelled before anything was sent.", "tags": [ "Refunds" ], "x-resource": "refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "refund.cancelled" }, "resource": { "type": "object", "properties": { "type": { "const": "refund" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "refund_id": { "type": "string", "description": "The refund." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits or failed." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the payer receives (decimal string)." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the fiat amount." }, "funding_source": { "type": "string", "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_type": { "type": "string", "description": "`payer_address` or `merchant_asserted`." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "payout.created": { "post": { "operationId": "webhook_payout_created", "summary": "A payout was created (funded, or waiting for approval).", "tags": [ "Payouts" ], "x-resource": "payout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "payout.created" }, "resource": { "type": "object", "properties": { "type": { "const": "payout" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "payout_id": { "type": "string", "description": "The payout." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed or waits." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the customer receives (decimal string)." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_basis": { "type": "string", "description": "Why it was allowed." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer's id." }, "customer_email": { "type": [ "string", "null" ], "description": "Your customer's email." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID for it." }, "matched_invoice_id": { "type": [ "string", "null" ], "description": "The paid invoice that made it eligible." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "network_fee": { "type": "string", "description": "The network fee on top (decimal string), once funded." } }, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "payout.completed": { "post": { "operationId": "webhook_payout_completed", "summary": "Sent and confirmed.", "tags": [ "Payouts" ], "x-resource": "payout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "payout.completed" }, "resource": { "type": "object", "properties": { "type": { "const": "payout" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "payout_id": { "type": "string", "description": "The payout." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed or waits." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the customer receives (decimal string)." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_basis": { "type": "string", "description": "Why it was allowed." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer's id." }, "customer_email": { "type": [ "string", "null" ], "description": "Your customer's email." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID for it." }, "matched_invoice_id": { "type": [ "string", "null" ], "description": "The paid invoice that made it eligible." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transaction hash." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link." }, "network_fee": { "type": [ "string", "null" ], "description": "The network fee charged (decimal string)." } }, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "payout.failed": { "post": { "operationId": "webhook_payout_failed", "summary": "Its transfer failed.", "tags": [ "Payouts" ], "x-resource": "payout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "payout.failed" }, "resource": { "type": "object", "properties": { "type": { "const": "payout" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "payout_id": { "type": "string", "description": "The payout." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed or waits." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the customer receives (decimal string)." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_basis": { "type": "string", "description": "Why it was allowed." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer's id." }, "customer_email": { "type": [ "string", "null" ], "description": "Your customer's email." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID for it." }, "matched_invoice_id": { "type": [ "string", "null" ], "description": "The paid invoice that made it eligible." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transaction hash, if any." }, "funds_returned": { "type": "boolean", "description": "The money went back to the payout wallet." } }, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "payout.cancelled": { "post": { "operationId": "webhook_payout_cancelled", "summary": "Cancelled before anything was sent.", "tags": [ "Payouts" ], "x-resource": "payout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "payout.cancelled" }, "resource": { "type": "object", "properties": { "type": { "const": "payout" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "payout_id": { "type": "string", "description": "The payout." }, "status": { "type": "string", "description": "Its status." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed or waits." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "What the customer receives (decimal string)." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_basis": { "type": "string", "description": "Why it was allowed." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer's id." }, "customer_email": { "type": [ "string", "null" ], "description": "Your customer's email." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID for it." }, "matched_invoice_id": { "type": [ "string", "null" ], "description": "The paid invoice that made it eligible." }, "created_via": { "type": "string", "description": "`api` or `dashboard`." } }, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.requested": { "post": { "operationId": "webhook_settlement_requested", "summary": "A withdrawal was recorded (its amount set aside).", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.requested" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "`requested`." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "destination": { "type": "object", "description": "Where it goes.", "required": [ "address", "memo", "label", "source" ], "properties": { "address": { "type": [ "string", "null" ], "description": "Address." }, "memo": { "type": [ "string", "null" ], "description": "Memo." }, "label": { "type": [ "string", "null" ], "description": "Label." }, "source": { "type": [ "string", "null" ], "description": "`settlement_wallet` or `request`." } }, "additionalProperties": false }, "estimated_network_cost": { "type": [ "string", "null" ], "description": "The kept estimate (decimal string); null when none." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.planned": { "post": { "operationId": "webhook_settlement_planned", "summary": "A settlement was planned with its fees.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.planned" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "gross": { "type": "string", "description": "Gross (decimal string)." }, "platform_fee": { "type": "string", "description": "Platform commission." }, "network_fee": { "type": "string", "description": "Network fee in the token." }, "execution_cost_reserve": { "type": "string", "description": "Coins: the reserve." }, "distributable": { "type": "string", "description": "What reaches you or the recipients." }, "asset": { "type": "string", "description": "The asset." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.held": { "post": { "operationId": "webhook_settlement_held", "summary": "A settlement waits (`reason`, e.g. below the minimum payout).", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.held" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "reason": { "type": "string", "description": "Why: a code (e.g. `fee_estimate_unavailable`, `recipient_share_below_minimum_payout`, `settlement_destination_missing`); never the provider's own error text." }, "asset": { "type": "string", "description": "The asset." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.awaiting_resources": { "post": { "operationId": "webhook_settlement_awaiting_resources", "summary": "A settlement waits for gas; it continues by itself.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.awaiting_resources" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "reason": { "type": "string", "description": "Why, e.g. `insufficient_native_gas_budget`." }, "needed": { "type": [ "string", "null" ], "description": "What is needed, in `fee_asset` (decimal string)." }, "available": { "type": [ "string", "null" ], "description": "What is there, in `fee_asset` (decimal string)." }, "fee_asset": { "type": [ "string", "null" ], "description": "The gas coin." }, "budget_owner": { "type": [ "string", "null" ], "description": "`operator` (the platform's gas pool) or `merchant` (your own budget)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.settling": { "post": { "operationId": "webhook_settlement_settling", "summary": "Its transfers are broadcast.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.settling" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.pooled": { "post": { "operationId": "webhook_settlement_pooled", "summary": "Daily schedule: moved to your collection address.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.pooled" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.completed": { "post": { "operationId": "webhook_settlement_completed", "summary": "Every transfer confirmed.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.completed" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." }, "settlement_batch_id": { "type": "string", "description": "Daily schedule: the batch that paid it." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.partially_completed": { "post": { "operationId": "webhook_settlement_partially_completed", "summary": "Some transfers confirmed, others failed.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.partially_completed" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.reconciliation_required": { "post": { "operationId": "webhook_settlement_reconciliation_required", "summary": "It needs operator review (a failed transfer, or a payment reversed after it was credited: `reason`, `reversed`).", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.reconciliation_required" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." }, "reason": { "type": "string", "description": "`deposit_reorged_after_credit` when a credited payment was reversed." }, "reversed": { "type": "string", "description": "What was taken back from your balance (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.credited": { "post": { "operationId": "webhook_settlement_credited", "summary": "On-request schedule: your share was credited to your balance.", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.credited" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "The new status." }, "transfers_confirmed": { "type": "integer", "description": "Transfers confirmed." }, "transfers_total": { "type": "integer", "description": "Transfers in all." }, "credited": { "type": "string", "description": "The amount credited (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.cancelled": { "post": { "operationId": "webhook_settlement_cancelled", "summary": "A withdrawal was cancelled or could not be planned (`reason`; its amount is available again), or a held invoice settlement was replaced by a new plan of the same payment (`reason` `replanned: ` with `replaced_by`, or `replanned: nothing left`), or recorded by the platform operator as paid to you outside the platform (`replanned: settled outside`).", "tags": [ "Settlements" ], "x-resource": "settlement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.cancelled" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "kind": { "type": "string", "description": "The settlement kind." }, "status": { "type": "string", "description": "`cancelled`." }, "reason": { "type": [ "string", "null" ], "description": "Why: a code (`cancelled_by_merchant`, `insufficient_balance`, `unwound` …), or `replanned: ` / `replanned: nothing left` / `replanned: settled outside` for a replaced invoice settlement." }, "replaced_by": { "type": [ "string", "null" ], "description": "A replaced invoice settlement: the new settlement that plans the same payment (null: nothing was left to plan). Absent for withdrawals." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.transfer_confirmed": { "post": { "operationId": "webhook_settlement_transfer_confirmed", "summary": "One on-chain transfer of a settlement confirmed (not sent for the platform fee or the collection address).", "tags": [ "Settlements" ], "x-resource": "settlement_transfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.transfer_confirmed" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement_transfer" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "settlement_kind": { "type": "string", "description": "Its kind." }, "kind": { "type": "string", "description": "The transfer kind." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "destination": { "type": [ "string", "null" ], "description": "Where it went." }, "memo": { "type": [ "string", "null" ], "description": "Memo." }, "tx_hash": { "type": [ "string", "null" ], "description": "Transaction hash." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link." }, "status": { "type": "string", "description": "The transfer status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "settlement.transfer_failed": { "post": { "operationId": "webhook_settlement_transfer_failed", "summary": "One on-chain transfer of a settlement failed.", "tags": [ "Settlements" ], "x-resource": "settlement_transfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "settlement.transfer_failed" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement_transfer" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "settlement_id": { "type": "string", "description": "The settlement." }, "settlement_kind": { "type": "string", "description": "Its kind." }, "kind": { "type": "string", "description": "The transfer kind." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "destination": { "type": [ "string", "null" ], "description": "Where it went." }, "memo": { "type": [ "string", "null" ], "description": "Memo." }, "tx_hash": { "type": [ "string", "null" ], "description": "Transaction hash." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link." }, "status": { "type": "string", "description": "The transfer status." }, "reason": { "type": [ "string", "null" ], "description": "Why, in one short sentence in the platform's own words (as the transfer's `error` in `GET /settlements/{id}`); never the provider's error text, which stays on Admin pages." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "fee.collected": { "post": { "operationId": "webhook_fee_collected", "summary": "The platform fee transfer of a settlement confirmed.", "tags": [ "Settlements" ], "x-resource": "settlement_transfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "fee.collected" }, "resource": { "type": "object", "properties": { "type": { "const": "settlement_transfer" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The fee (decimal string)." }, "tx_hash": { "type": [ "string", "null" ], "description": "Transaction hash." }, "settlement_id": { "type": "string", "description": "The settlement." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "deposit.observed": { "post": { "operationId": "webhook_deposit_observed", "summary": "A payment was seen on the network.", "tags": [ "Activity" ], "x-resource": "deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "deposit.observed" }, "resource": { "type": "object", "properties": { "type": { "const": "deposit" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The deposit's status." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "tx_hash": { "type": "string", "description": "The payment's transaction hash." }, "block_number": { "type": [ "integer", "null" ], "description": "Its block." }, "confirmations": { "type": "integer", "description": "Confirmations so far." }, "classification": { "type": [ "string", "null" ], "description": "What kind of money it is." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it is held." }, "owner": { "type": "object", "description": "What the address belongs to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "What received it." }, "id": { "type": "string", "description": "Its id." } }, "additionalProperties": false }, "address": { "type": [ "string", "null" ], "description": "The receiving address." }, "payer_address": { "type": [ "string", "null" ], "description": "Who sent it (canonical form), when known." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "deposit.confirmed": { "post": { "operationId": "webhook_deposit_confirmed", "summary": "A payment confirmed.", "tags": [ "Activity" ], "x-resource": "deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "deposit.confirmed" }, "resource": { "type": "object", "properties": { "type": { "const": "deposit" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The deposit's status." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "tx_hash": { "type": "string", "description": "The payment's transaction hash." }, "block_number": { "type": [ "integer", "null" ], "description": "Its block." }, "confirmations": { "type": "integer", "description": "Confirmations so far." }, "classification": { "type": [ "string", "null" ], "description": "What kind of money it is." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it is held." }, "owner": { "type": "object", "description": "What the address belongs to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "What received it." }, "id": { "type": "string", "description": "Its id." } }, "additionalProperties": false }, "address": { "type": [ "string", "null" ], "description": "The receiving address." }, "payer_address": { "type": [ "string", "null" ], "description": "Who sent it (canonical form), when known." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "deposit.reorged": { "post": { "operationId": "webhook_deposit_reorged", "summary": "A confirmed payment was undone by a reorganisation.", "tags": [ "Activity" ], "x-resource": "deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "deposit.reorged" }, "resource": { "type": "object", "properties": { "type": { "const": "deposit" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The deposit's status." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "tx_hash": { "type": "string", "description": "The payment's transaction hash." }, "block_number": { "type": [ "integer", "null" ], "description": "Its block." }, "confirmations": { "type": "integer", "description": "Confirmations so far." }, "classification": { "type": [ "string", "null" ], "description": "What kind of money it is." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it is held." }, "owner": { "type": "object", "description": "What the address belongs to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "What received it." }, "id": { "type": "string", "description": "Its id." } }, "additionalProperties": false }, "address": { "type": [ "string", "null" ], "description": "The receiving address." }, "payer_address": { "type": [ "string", "null" ], "description": "Who sent it (canonical form), when known." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "deposit.held": { "post": { "operationId": "webhook_deposit_held", "summary": "A payment was kept aside (`reason`).", "tags": [ "Activity" ], "x-resource": "deposit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "deposit.held" }, "resource": { "type": "object", "properties": { "type": { "const": "deposit" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "reason": { "type": "string", "description": "Why." }, "amount": { "type": "string", "description": "The amount (decimal string)." }, "asset": { "type": "string", "description": "The asset." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.created": { "post": { "operationId": "webhook_split_session_created", "summary": "A split session was created.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.created" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "Its status." }, "asset": { "type": "string", "description": "The asset." }, "deposit_address": { "type": [ "string", "null" ], "description": "Where to pay." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.payment_detected": { "post": { "operationId": "webhook_split_session_payment_detected", "summary": "A payment was seen.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.payment_detected" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.payment_dropped": { "post": { "operationId": "webhook_split_session_payment_dropped", "summary": "The payment it detected left the chain before it confirmed.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.payment_dropped" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "tx_hash": { "type": "string", "description": "Its hash." }, "reason": { "type": [ "string", "null" ], "description": "Why." }, "status": { "type": "string", "description": "The session's status now." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.late_payment": { "post": { "operationId": "webhook_split_session_late_payment", "summary": "A payment arrived after it closed; it is held.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.late_payment" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "deposit_id": { "type": "string", "description": "The payment." }, "asset": { "type": "string", "description": "The asset." }, "amount": { "type": "string", "description": "The amount (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.closed": { "post": { "operationId": "webhook_split_session_closed", "summary": "You closed it.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.closed" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "Its status." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.expired": { "post": { "operationId": "webhook_split_session_expired", "summary": "It expired without a payment.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.expired" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "expired_at": { "type": "string", "format": "date-time", "description": "When." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.processing": { "post": { "operationId": "webhook_split_session_processing", "summary": "Its split is being sent.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.processing" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The session's status." }, "asset": { "type": "string", "description": "The asset." }, "settled_gross": { "type": "string", "description": "Settled so far (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.settled": { "post": { "operationId": "webhook_split_session_settled", "summary": "Every recipient was paid.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.settled" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The session's status." }, "asset": { "type": "string", "description": "The asset." }, "settled_gross": { "type": "string", "description": "Settled so far (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.partially_settled": { "post": { "operationId": "webhook_split_session_partially_settled", "summary": "Some transfers confirmed, others not.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.partially_settled" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The session's status." }, "asset": { "type": "string", "description": "The asset." }, "settled_gross": { "type": "string", "description": "Settled so far (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "split_session.held": { "post": { "operationId": "webhook_split_session_held", "summary": "It is held: late money, or its target cannot pay out as configured.", "tags": [ "Split sessions" ], "x-resource": "split_session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "split_session.held" }, "resource": { "type": "object", "properties": { "type": { "const": "split_session" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "The session's status." }, "asset": { "type": "string", "description": "The asset." }, "settled_gross": { "type": "string", "description": "Settled so far (decimal string)." }, "reason": { "type": "string", "description": "Why it is held." }, "hold_reason": { "type": "string", "description": "The settlement's reason." }, "expected_amount": { "type": "string", "description": "Its target (decimal string)." }, "platform_fee": { "type": "string", "description": "The platform fee (decimal string)." }, "network_fee": { "type": "string", "description": "The network fee (decimal string)." }, "minimum_payout": { "type": "string", "description": "The minimum payout (decimal string)." } }, "allOf": [ { "$ref": "#/components/schemas/PaymentRefs" } ], "unevaluatedProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "splitter.created": { "post": { "operationId": "webhook_splitter_created", "summary": "A splitter was created.", "tags": [ "Splitters" ], "x-resource": "splitter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "splitter.created" }, "resource": { "type": "object", "properties": { "type": { "const": "splitter" } } }, "data": { "type": "object", "description": "The event data.", "properties": { "status": { "type": "string", "description": "Its status." }, "asset": { "type": "string", "description": "The asset." } }, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "splitter.paused": { "post": { "operationId": "webhook_splitter_paused", "summary": "A splitter was paused.", "tags": [ "Splitters" ], "x-resource": "splitter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "splitter.paused" }, "resource": { "type": "object", "properties": { "type": { "const": "splitter" } } }, "data": { "type": "object", "description": "The event data.", "properties": {}, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } }, "splitter.resumed": { "post": { "operationId": "webhook_splitter_resumed", "summary": "A splitter was resumed.", "tags": [ "Splitters" ], "x-resource": "splitter", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" } ], "properties": { "type": { "const": "splitter.resumed" }, "resource": { "type": "object", "properties": { "type": { "const": "splitter" } } }, "data": { "type": "object", "description": "The event data.", "properties": {}, "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received: answer any 2xx within the timeout." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key ck___; sandbox and live keys are separate namespaces." } }, "parameters": { "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z0-9_\\-:.]+$" }, "description": "Required: this endpoint moves money (`400 idempotency_key_required` without it). A new UUID per request; the same one only to retry that request (same key and body: the stored answer, `Idempotent-Replayed: true`; another body, or a key restricted to another store: `409 idempotency_key_reused`). See [idempotency](#idempotency)." }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z0-9_\\-:.]+$" }, "description": "Optional: makes a retry after a timeout safe (same key and body: the stored answer). A new UUID per request; never your order number. See [idempotency](#idempotency)." }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Page size." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`next_cursor` of the previous page." } }, "responses": { "BadRequest": { "description": "Bad request: `idempotency_key_required`, `idempotency_key_invalid`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthenticated": { "description": "Unauthenticated: `unauthenticated`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Forbidden: `forbidden`, `store_not_allowed`, `payouts_api_disabled`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found: `not_found`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "Method not allowed: `http_405`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflict: `idempotency_key_reused`, `request_in_progress`, `order_id_in_use`, `order_already_paid`, `insufficient_balance`, `refund_exists`, `refund_not_cancellable`, `payout_not_cancellable`, `withdrawal_not_cancellable`, `nothing_to_accept`, `payment_confirming`, `accept_in_progress`, `refund_in_progress`, `held_amount_changed`, `operator_review_required`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Unprocessable: `validation_failed`, `invalid_argument`, `asset_not_supported`, `amount_below_minimum`, `refund_not_allowed`, `refund_amount_too_large`, `refund_destination_not_payer`, `payout_destination_not_allowed`, `payout_wallet_missing`, `asset_not_acceptable`, `amount_too_small_to_settle`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Too many requests: `rate_limited`, `invoice_rate_limited`, `open_invoice_limit`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Server error: `internal_error`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadGateway": { "description": "Bad gateway: `price_source_error`, `provider_error`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Unavailable: `price_source_unavailable`, `provider_unavailable`, `network_fee_unavailable`, `schema_update_pending`, `not_installed`. See the [errors table](#errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "RequestId": { "type": "object", "description": "Added to every answer.", "required": [ "request_id" ], "properties": { "request_id": { "type": "string", "description": "The id of this request (also the `X-Request-Id` header): quote it to support." } } }, "Error": { "type": "object", "description": "The answer to every refused request (4xx, 5xx). Ignore keys you do not know.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "The error.", "required": [ "code", "message", "retryable", "request_id" ], "properties": { "code": { "type": "string", "examples": [ "idempotency_key_required", "idempotency_key_invalid", "unauthenticated", "forbidden", "store_not_allowed", "payouts_api_disabled", "not_found", "http_405", "idempotency_key_reused", "request_in_progress", "order_id_in_use", "order_already_paid", "insufficient_balance", "refund_exists", "refund_not_cancellable", "payout_not_cancellable", "withdrawal_not_cancellable", "nothing_to_accept", "payment_confirming", "accept_in_progress", "refund_in_progress", "held_amount_changed", "operator_review_required", "validation_failed", "invalid_argument", "asset_not_supported", "amount_below_minimum", "refund_not_allowed", "refund_amount_too_large", "refund_destination_not_payer", "payout_destination_not_allowed", "payout_wallet_missing", "asset_not_acceptable", "amount_too_small_to_settle", "rate_limited", "invoice_rate_limited", "open_invoice_limit", "internal_error", "price_source_error", "provider_error", "price_source_unavailable", "provider_unavailable", "network_fee_unavailable", "schema_update_pending", "not_installed" ], "description": "Machine-readable code: see the [errors table](#errors)." }, "message": { "type": "string", "description": "For people; may change." }, "retryable": { "type": "boolean", "description": "true: retry later (honour `Retry-After`) with the same request." }, "request_id": { "type": [ "string", "null" ], "description": "The id of this request: quote it to support." }, "fields": { "type": "object", "description": "validation_failed: the problems per field (a field name, or a path such as `lines.0.description`).", "additionalProperties": { "type": [ "array", "string" ], "items": { "type": "string" } } }, "reason": { "type": "string", "examples": [ "allowed_assets_missing", "asset_not_in_store", "settlement_address_locked", "settlement_wallet_invalid", "settlement_destination_missing", "store_settlement_invalid", "price_source_missing", "not_available", "gas_coin_on_account_chain", "invoice_status", "payment_confirming", "nothing_paid", "asset_required", "no_payment_rate", "held_funds_on_several_addresses", "unheld_partial_payment", "held_funds_changed", "not_a_payer", "no_payer_address_known", "not_a_past_payer", "customer_unknown", "platform_address", "no_destination_allowed" ], "description": "With `validation_failed`: the missing setting (fix it, then send the same request again). With a business code: why (see the errors table)." }, "hint": { "type": "string", "description": "One paragraph for people: what is missing and how to fix it." }, "dashboard_url": { "type": "string", "description": "The dashboard page that fixes it." }, "docs_url": { "type": "string", "description": "Where this is documented." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "description": "The environment the setting is missing in." }, "store_id": { "type": "string", "description": "allowed_assets_missing, asset_not_in_store, store_settlement_invalid: the store used. store_not_allowed: the key's store." }, "asset": { "type": "string", "description": "The asset concerned." }, "store_assets": { "type": "array", "items": { "type": "string" }, "description": "asset_not_in_store: the store's Payment assets payable in this environment." }, "family": { "type": "string", "enum": [ "evm", "bitcoin", "bitcoincash", "tron" ], "description": "settlement_wallet_invalid: the network family of that wallet." }, "settlement_lock": { "type": "boolean", "description": "Present (true) while the settlement lock is on." }, "missing": { "type": "array", "items": { "type": "object", "required": [ "family", "label", "assets" ], "properties": { "family": { "type": "string", "description": "Network family." }, "label": { "type": "string", "description": "The family for people." }, "assets": { "type": "array", "items": { "type": "string" }, "description": "The assets without a settlement wallet." } }, "additionalProperties": false }, "description": "settlement_destination_missing, settlement_address_locked: what has no saved settlement wallet (never the saved addresses)." }, "order_id": { "type": "string", "description": "order_id_in_use, order_already_paid: the order of the request." }, "existing_invoice": { "type": "object", "description": "The invoice that blocks a new one.", "required": [ "id", "transaction_id", "number", "status", "amount", "currency", "allowed_assets", "checkout_url", "created_at" ], "properties": { "id": { "type": "string", "description": "Payment ID." }, "transaction_id": { "type": [ "string", "null" ], "description": "Transaction ID." }, "number": { "type": "string", "description": "Invoice number." }, "status": { "type": "string", "description": "Its status." }, "amount": { "type": "string", "description": "Its amount." }, "currency": { "type": "string", "description": "Its currency." }, "allowed_assets": { "type": "array", "items": { "type": "string" }, "description": "Its assets." }, "checkout_url": { "type": "string", "description": "Its checkout page." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "additionalProperties": false }, "differences": { "type": "array", "items": { "type": "string" }, "description": "order_id_in_use: the terms that differ, in this order: `pricing_mode`, `currency`, `amount`, `allowed_assets`." }, "limit": { "type": "integer", "description": "invoice_rate_limited: new invoices per minute; open_invoice_limit: open invoices allowed." }, "open": { "type": "integer", "description": "open_invoice_limit: open invoices now." }, "required_scope": { "type": "string", "description": "forbidden: the scope the key lacks." }, "available": { "type": "string", "description": "What is available now (decimal string of the asset)." }, "amount": { "type": "string", "description": "The amount concerned (decimal string)." }, "amount_atomic": { "type": "string", "description": "held_amount_changed: the held amount now, in the smallest unit." }, "network_fee": { "type": "string", "description": "insufficient_balance of a payout: the network fee on top (decimal string)." }, "needed": { "type": "string", "description": "insufficient_balance of a payout: amount + network fee (decimal string)." }, "minimum": { "type": "string", "description": "amount_below_minimum: the least that must arrive (decimal string)." }, "estimated_network_cost": { "type": [ "string", "null" ], "description": "amount_below_minimum: the kept estimate of the network cost (null when none is known)." }, "status": { "type": "string", "description": "The current status of the object (not cancellable, nothing to accept…)." }, "refund": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Refund id." }, "status": { "type": "string", "description": "Its status." } }, "additionalProperties": false, "description": "refund_exists, refund_in_progress: the invoice's refund." }, "acceptance": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Acceptance id." }, "status": { "type": "string", "description": "Its status." } }, "additionalProperties": false, "description": "accept_in_progress: the accept that waits." }, "max_amount": { "type": "string", "description": "refund_amount_too_large: the most that can be refunded, in the invoice currency." }, "max_crypto": { "type": "string", "description": "refund_amount_too_large: the same in the asset." }, "funding_source": { "type": "string", "description": "refund_amount_too_large: where the refund would be paid from." }, "payer_addresses": { "type": "array", "items": { "type": "string" }, "description": "refund_destination_not_payer: the addresses that paid the invoice." }, "assets": { "type": "array", "items": { "type": "string" }, "description": "refund_not_allowed: the assets the invoice was paid in." }, "invoice_status": { "type": "string", "description": "refund_not_allowed (invoice_status): the invoice's status." }, "needs_decision": { "type": "boolean", "description": "nothing_to_accept: whether the invoice needs a decision." }, "platform_fee": { "type": "string", "description": "amount_too_small_to_settle: the platform fee an accept would take." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "payout_destination_not_allowed: the destination bases that are on." }, "network_family": { "type": "string", "description": "payout_wallet_missing: the network family without a payout wallet." } }, "additionalProperties": false } }, "additionalProperties": false }, "PaymentRefs": { "type": "object", "description": "Who paid: added to every invoice, deposit, settlement, transfer, refund and split session event when known (keys whose value is unknown are left out).", "properties": { "invoice_id": { "type": "string", "description": "The invoice (Payment ID) this concerns." }, "invoice_number": { "type": "string", "description": "Its invoice number (`INV-…`)." }, "transaction_id": { "type": "string", "description": "Its Transaction ID (`TRX-…`, sandbox `TST-…`): the reference support asks for." }, "order_id": { "type": "string", "description": "Your Merchant order ID of that invoice or split session." } } }, "PaymentOption": { "type": "object", "description": "One way to pay an invoice: an asset with its amount and (once chosen) its address.", "required": [ "id", "asset", "status", "required_amount", "received_confirmed", "received_unconfirmed", "address", "quote_expires_at" ], "properties": { "id": { "type": "string", "description": "Payment option id." }, "asset": { "type": "string", "description": "The asset the payer may pay with (identifier, e.g. `USDT_TRON`)." }, "status": { "type": "string", "enum": [ "pending_address", "available", "locked", "paid", "superseded" ], "x-enum-descriptions": { "pending_address": "No deposit address yet: it is allocated when the payer chooses this option.", "available": "The address is ready; the payer may pay with this option.", "locked": "The option the payer chose (or paid with).", "paid": "Paid in full with this option.", "superseded": "Another option was paid." }, "description": "The option's state." }, "required_amount": { "type": "string", "description": "What the payer must send with this option. Decimal string in the asset's units." }, "received_confirmed": { "type": "string", "description": "Confirmed so far. Decimal string in the asset's units." }, "received_unconfirmed": { "type": "string", "description": "Seen, not confirmed yet. Decimal string in the asset's units." }, "address": { "type": [ "string", "null" ], "description": "The deposit address; null until the payer chooses this option on the checkout." }, "quote_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Fiat invoices: when the quoted rate expires." } }, "additionalProperties": false }, "PayerAddress": { "type": "object", "description": "An address that paid the invoice.", "required": [ "address", "network", "asset" ], "properties": { "address": { "type": "string", "description": "The address (canonical form for its chain family)." }, "network": { "type": "string", "description": "The network code it paid on." }, "asset": { "type": "string", "description": "The asset it paid." } }, "additionalProperties": false }, "InvoiceRefundSummary": { "type": "object", "description": "The invoice's refund (one per invoice).", "required": [ "id", "status", "amount", "asset" ], "properties": { "id": { "type": "string", "description": "Refund id (`GET /refunds/{id}`)." }, "status": { "type": "string", "enum": [ "pending_approval", "queued", "processing", "completed", "failed", "cancelled" ], "x-enum-descriptions": { "pending_approval": "Created from the API while \"Refunds from the API need approval\" is on: approve or cancel it in the dashboard.", "queued": "Waits for money (`status_reason`); sent automatically, oldest first, when the money suffices. You may cancel it.", "processing": "Funded; its transfer is on its way.", "completed": "Sent: `tx_hash` and `explorer_url` prove it.", "failed": "The transfer failed (`status_reason`); the operator retries it or returns the money (`funds_returned`).", "cancelled": "Cancelled before anything was sent." }, "description": "The refund's status." }, "amount": { "type": "string", "description": "What the payer receives. Decimal string in the asset's units." }, "asset": { "type": "string", "description": "Its asset." } }, "additionalProperties": false }, "HeldAmount": { "type": "object", "description": "Money held for an invoice in one asset.", "required": [ "asset", "amount", "amount_atomic" ], "properties": { "asset": { "type": "string", "description": "Asset identifier." }, "amount": { "type": "string", "description": "Held: what an accept or a refund would move, never more than your held funds of the asset have (the accept's expected_amount). Decimal string in the asset's units." }, "amount_atomic": { "type": "string", "description": "The same in the smallest unit (integer string)." } }, "additionalProperties": false }, "InvoiceAcceptance": { "type": "object", "description": "An accept of held money (the latest one is `decision.acceptance`).", "required": [ "id", "status", "status_reason", "kind", "asset", "amount", "amount_atomic", "settlement_id", "via", "requested_at", "planned_at", "failed_at" ], "properties": { "id": { "type": "string", "description": "Acceptance id." }, "status": { "type": "string", "enum": [ "requested", "planned", "failed", "cancelled" ], "x-enum-descriptions": { "requested": "Waits to be planned (within about a minute).", "planned": "Settled with the invoice's fee (`settlement_id`).", "failed": "Nothing moved (`status_reason`); the decision is needed again.", "cancelled": "Cancelled in the dashboard before it was planned." }, "description": "The accept's state." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed: `held_amount_changed`, `amount_too_small_to_settle`, `settlement_destination_missing`, `network_fee_unavailable`, `operator_review_required`, `not_plannable`, `cancelled`." }, "kind": { "type": "string", "enum": [ "underpayment", "late_payment", "extra_payment" ], "x-enum-descriptions": { "underpayment": "An underpaid invoice, or one accepted early while partly paid: the invoice becomes `paid` and pays its fixed fee too.", "late_payment": "A paid-late invoice: becomes `paid`, fixed fee too.", "extra_payment": "Extra money of a paid invoice: percentage fee only." }, "description": "What was accepted." }, "asset": { "type": "string", "description": "The asset accepted." }, "amount": { "type": "string", "description": "The amount accepted. Decimal string in the asset's units." }, "amount_atomic": { "type": "string", "description": "The same in the smallest unit." }, "settlement_id": { "type": [ "string", "null" ], "description": "The settlement that settles it, once planned." }, "via": { "type": "string", "enum": [ "dashboard", "api" ], "description": "Where it was requested." }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was requested." }, "planned_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was planned." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it failed." } }, "additionalProperties": false }, "InvoiceDecision": { "type": "object", "description": "The decision about an invoice's held money: [partial, late and extra payments](#billing-invoices).", "required": [ "status", "reason", "needed_since", "held", "actions", "acceptance" ], "properties": { "status": { "type": "string", "enum": [ "needed", "accepting", "accepted", "refunded", "resolved" ], "x-enum-descriptions": { "needed": "Held money waits for you: accept or refund it.", "accepting": "An accept waits to be planned.", "accepted": "You accepted it (the latest accept planned).", "refunded": "It was refunded.", "resolved": "Nothing is held any more (for example a held payment was reorganised away)." }, "description": "Where the decision stands." }, "reason": { "type": [ "string", "null" ], "enum": [ "underpaid", "late_payment", "overpaid", "payment_after_fulfilment", "other_asset", "below_minimum", null ], "x-enum-descriptions": { "underpaid": "Closed with a partial payment.", "late_payment": "Paid after it closed.", "overpaid": "More than asked.", "payment_after_fulfilment": "A payment after it was paid.", "other_asset": "Paid in an asset that is none of its options (refund only).", "below_minimum": "Payments below the asset's minimum deposit." }, "description": "Why money is held." }, "needed_since": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when it needs your decision." }, "held": { "type": "array", "items": { "$ref": "#/components/schemas/HeldAmount" }, "description": "What an accept or a refund would move, per asset." }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "accept", "refund" ] }, "description": "What you can do now (empty unless `needed`)." }, "acceptance": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceAcceptance" }, { "type": "null" } ], "description": "The latest accept, or null." } }, "additionalProperties": false }, "Invoice": { "type": "object", "description": "An invoice: one customer payment, with its options, decision and refund.", "required": [ "id", "object", "transaction_id", "number", "order_id", "store_id", "environment", "status", "settlement_status", "pricing_mode", "currency", "amount", "amount_asset", "amount_paid", "amount_pending", "amount_due", "needs_decision", "decision", "description", "lines", "customer_id", "customer_email", "allowed_assets", "settlement_type", "rate_source", "payment_options", "payer_addresses", "refund", "metadata", "return_url", "cancel_url", "checkout_url", "checkout_theme", "expires_at", "paid_at", "cancelled_at", "created_at" ], "properties": { "id": { "type": "string", "description": "Payment ID (ULID, 26 characters)." }, "object": { "type": "string", "const": "invoice", "description": "Always `invoice`." }, "transaction_id": { "type": [ "string", "null" ], "pattern": "^(TRX|TST)-[0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4}-[0-9A-HJKMNP-TV-Z]{4}$", "description": "Platform reference `TRX-XXXX-XXXX-XXXX` (sandbox `TST-…`): quote it to support; `GET /invoices/{id}` takes it too." }, "number": { "type": "string", "description": "Invoice number shown to the payer (`INV-MAIN-000123`), unique per store and environment." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID, as sent (cleaned)." }, "store_id": { "type": [ "string", "null" ], "description": "The store (also `data-store` of the website widget)." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "status": { "type": "string", "enum": [ "awaiting_payment", "confirming", "partially_paid", "paid", "overpaid", "expired", "underpaid", "paid_late", "cancelled", "refund_pending", "partially_refunded", "refunded" ], "x-enum-descriptions": { "awaiting_payment": "Open: waiting for the payer; payments seen before `expires_at` count.", "confirming": "Payments that cover the invoice wait for the network's confirmations; it does not expire meanwhile.", "partially_paid": "Open: part of the amount is confirmed; the payer may send the rest before `expires_at`.", "paid": "Paid in full with confirmed money, or a partial or late payment you accepted (`decision.status: accepted`). Ship the order.", "overpaid": "Paid, with more than asked: ship the order; the excess is held for you to refund or accept.", "expired": "Closed at `expires_at` without any confirmed payment.", "underpaid": "Closed (expired or cancelled) with a confirmed partial payment: held until you accept it (the invoice becomes `paid`) or refund it.", "paid_late": "It had expired or been cancelled when confirmed money covering it arrived: held until you accept (`paid`) or refund it.", "cancelled": "Cancelled by you before anything was paid.", "refund_pending": "Its refund is being sent.", "partially_refunded": "Part of the payment was refunded.", "refunded": "The payment was refunded in full." }, "description": "See [invoice statuses](#status-invoice)." }, "settlement_status": { "type": "string", "enum": [ "not_started", "pending", "processing", "scheduled", "settled", "held", "credited" ], "x-enum-descriptions": { "not_started": "No accepted payment yet.", "pending": "Paid; the settlement is being prepared.", "processing": "Its transfers are being sent.", "scheduled": "Daily schedule: collected, sent with the next daily settlement.", "settled": "Your share reached your settlement wallet or splitter.", "held": "Waiting: see the settlement's `hold_reason`.", "credited": "On-request schedule: your share is in your balance (\"In balance\"), to withdraw when you want." }, "description": "Where your share is: see [settlement status](#status-invoice-settlement)." }, "pricing_mode": { "type": "string", "enum": [ "crypto", "fiat" ], "description": "`crypto`: priced in one asset; `fiat`: priced in a currency and quoted per option." }, "currency": { "type": "string", "description": "The asset identifier (crypto) or ISO-4217 code (fiat) of `amount`." }, "amount": { "type": "string", "description": "The price as sent (decimal string in `currency`)." }, "amount_asset": { "type": [ "string", "null" ], "description": "The asset of the four amounts below: the option paid, else the only option; null while an invoice of several assets is unpaid." }, "amount_paid": { "type": "string", "description": "Confirmed money received in `amount_asset` (late, excess and held payments included; `\"0\"` without an asset). Decimal string in the asset's units." }, "amount_pending": { "type": "string", "description": "Payments seen, not confirmed yet. Decimal string in the asset's units." }, "amount_due": { "type": [ "string", "null" ], "description": "Still missing while open: `0` once paid or accepted; null without `amount_asset`. Decimal string in the asset's units." }, "needs_decision": { "type": "boolean", "description": "true while held money waits for your accept (`POST /invoices/{id}/accept`) or refund (`POST /refunds`)." }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceDecision" }, { "type": "null" } ], "description": "The decision about held money; null when it never needed one." }, "description": { "type": [ "string", "null" ], "description": "Shown to the payer." }, "lines": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "description": "The line." }, "quantity": { "type": [ "number", "null" ], "description": "Quantity, as sent." }, "amount": { "type": [ "string", "null" ], "description": "Amount, as sent (display only)." } }, "additionalProperties": false }, "description": "Receipt lines as sent (display only)." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer reference, as sent." }, "customer_email": { "type": [ "string", "null" ], "description": "Lower-cased; never shown to the payer." }, "allowed_assets": { "type": "array", "items": { "type": "string" }, "description": "The assets the payer may choose from." }, "settlement_type": { "type": [ "string", "null" ], "enum": [ "wallet", "splitter", null ], "description": "`wallet`: to your settlement wallets (or balance); `splitter`: through a splitter." }, "rate_source": { "type": [ "string", "null" ], "description": "Fiat invoices: the price source of the quotes." }, "payment_options": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOption" }, "description": "One per allowed asset: see [payment option](#payment-option-object)." }, "payer_addresses": { "type": "array", "items": { "$ref": "#/components/schemas/PayerAddress" }, "description": "Addresses its confirmed payments came from (largest first): where a refund goes back to." }, "refund": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceRefundSummary" }, { "type": "null" } ], "description": "The invoice's refund (one per invoice), or null." }, "metadata": { "type": "object", "x-free-form": true, "description": "Returned as sent (reserved settlement keys removed)." }, "return_url": { "type": [ "string", "null" ], "description": "Link on the checkout after payment." }, "cancel_url": { "type": [ "string", "null" ], "description": "Link on the checkout to go back." }, "checkout_url": { "type": "string", "description": "The payer's page (`/pay/i/{token}`): keep it out of analytics and shared URLs." }, "checkout_theme": { "type": "string", "enum": [ "modern", "classic", "minimal", "midnight", "vivid" ], "description": "The design the payer sees: see [checkout designs](#billing-themes)." }, "expires_at": { "type": "string", "format": "date-time", "description": "The expiry that applies (the store's Invoice expiry, else `expires_in_seconds`, else one hour); later payments are held as late." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became paid." }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was cancelled." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "additionalProperties": false }, "InvoiceCreated": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "object", "required": [ "created" ], "properties": { "created": { "type": "boolean", "description": "true: a new invoice (`201`). false: the open invoice of the same `order_id` (`200`); nothing new was created." } } } ], "description": "The answer to `POST /invoices`." }, "InvoiceEventAmounts": { "type": "object", "description": "The amount block of every `invoice.*` event (except `invoice.settlement_*`): decimal strings in `asset`, each with an `*_atomic` sibling in the smallest unit. `asset` null (nothing paid to an invoice of several assets): the amounts are null, except `amount_paid` and `amount_pending` (`\"0\"`).", "properties": { "status": { "type": "string", "enum": [ "awaiting_payment", "confirming", "partially_paid", "paid", "overpaid", "expired", "underpaid", "paid_late", "cancelled", "refund_pending", "partially_refunded", "refunded" ], "x-enum-descriptions": { "awaiting_payment": "Open: waiting for the payer; payments seen before `expires_at` count.", "confirming": "Payments that cover the invoice wait for the network's confirmations; it does not expire meanwhile.", "partially_paid": "Open: part of the amount is confirmed; the payer may send the rest before `expires_at`.", "paid": "Paid in full with confirmed money, or a partial or late payment you accepted (`decision.status: accepted`). Ship the order.", "overpaid": "Paid, with more than asked: ship the order; the excess is held for you to refund or accept.", "expired": "Closed at `expires_at` without any confirmed payment.", "underpaid": "Closed (expired or cancelled) with a confirmed partial payment: held until you accept it (the invoice becomes `paid`) or refund it.", "paid_late": "It had expired or been cancelled when confirmed money covering it arrived: held until you accept (`paid`) or refund it.", "cancelled": "Cancelled by you before anything was paid.", "refund_pending": "Its refund is being sent.", "partially_refunded": "Part of the payment was refunded.", "refunded": "The payment was refunded in full." }, "description": "The invoice status after the change." }, "asset": { "type": [ "string", "null" ], "description": "The asset of the amounts." }, "amount_required": { "type": [ "string", "null" ], "description": "What the invoice asks in `asset`. Decimal string in the asset's units." }, "amount_required_atomic": { "type": [ "string", "null" ], "description": "Smallest unit." }, "amount_paid": { "type": [ "string", "null" ], "description": "Confirmed so far. Decimal string in the asset's units." }, "amount_paid_atomic": { "type": [ "string", "null" ], "description": "Smallest unit." }, "amount_pending": { "type": [ "string", "null" ], "description": "Seen, not confirmed. Decimal string in the asset's units." }, "amount_pending_atomic": { "type": [ "string", "null" ], "description": "Smallest unit." }, "amount_due": { "type": [ "string", "null" ], "description": "Still missing. Decimal string in the asset's units." }, "amount_due_atomic": { "type": [ "string", "null" ], "description": "Smallest unit." }, "amount_held": { "type": [ "string", "null" ], "description": "Held for your decision (as `decision.held`: what an accept would take, never more than your held funds have). Decimal string in the asset's units." }, "amount_held_atomic": { "type": [ "string", "null" ], "description": "Smallest unit." }, "needs_decision": { "type": "boolean", "description": "Held money waits for your decision." } } }, "CheckoutTheme": { "type": "object", "description": "A design of the hosted (and embedded) checkout; only the look differs.", "required": [ "object", "key", "name", "description", "default", "preview_url", "preview_urls" ], "properties": { "object": { "type": "string", "const": "checkout_theme", "description": "Always `checkout_theme`." }, "key": { "type": "string", "enum": [ "modern", "classic", "minimal", "midnight", "vivid" ], "description": "Value for `checkout_theme`, `?theme=` and the widget's `theme`." }, "name": { "type": "string", "description": "Its name." }, "description": { "type": "string", "description": "What it looks like." }, "default": { "type": "boolean", "description": "The platform's default design." }, "preview_url": { "type": "string", "description": "Live preview with sample data (pay step); not payable." }, "preview_urls": { "type": "object", "description": "Previews of every payer step.", "required": [ "choose", "pay", "confirming", "paid", "expired" ], "properties": { "choose": { "type": "string", "description": "Preview of the choose step." }, "pay": { "type": "string", "description": "Preview of the pay step." }, "confirming": { "type": "string", "description": "Preview of the confirming step." }, "paid": { "type": "string", "description": "Preview of the paid step." }, "expired": { "type": "string", "description": "Preview of the expired step." } }, "additionalProperties": false } }, "additionalProperties": false }, "Refund": { "type": "object", "description": "A refund of an invoice's payment to the address that paid it: once per invoice, at most what was paid, the network fee charged to you on top.", "required": [ "id", "object", "status", "status_reason", "environment", "invoice_id", "transaction_id", "invoice_number", "order_id", "customer_id", "customer_email", "asset", "amount", "fiat_currency", "fiat_amount", "quote", "network_fee", "network_fee_final", "total_charged", "funding_source", "destination", "destination_memo", "destination_type", "reason", "created_via", "settlement_id", "tx_hash", "explorer_url", "funds_returned", "created_at", "approved_at", "funded_at", "completed_at", "failed_at", "cancelled_at" ], "properties": { "id": { "type": "string", "description": "Refund id." }, "object": { "type": "string", "const": "refund", "description": "Always `refund`." }, "status": { "type": "string", "enum": [ "pending_approval", "queued", "processing", "completed", "failed", "cancelled" ], "x-enum-descriptions": { "pending_approval": "Created from the API while \"Refunds from the API need approval\" is on: approve or cancel it in the dashboard.", "queued": "Waits for money (`status_reason`); sent automatically, oldest first, when the money suffices. You may cancel it.", "processing": "Funded; its transfer is on its way.", "completed": "Sent: `tx_hash` and `explorer_url` prove it.", "failed": "The transfer failed (`status_reason`); the operator retries it or returns the money (`funds_returned`).", "cancelled": "Cancelled before anything was sent." }, "description": "See [refund statuses](#status-refund)." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it waits, failed or was cancelled: `insufficient_balance`, `network_fee_unavailable`, `no_collection_address`, `payout_wallet_missing`, `held_funds_on_several_addresses`, `held_funds_changed`, `paid_amount_changed` (at funding or approval the invoice's confirmed payment no longer covered it, e.g. a payment reorganized away; nothing was taken), `transfer_failed`, `transfer_failed_funds_returned`, `cancelled_by_merchant`, `superseded` (an older refund of the invoice from before one refund per invoice), or a transfer wait." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "invoice_id": { "type": "string", "description": "The invoice refunded." }, "transaction_id": { "type": [ "string", "null" ], "description": "Its Transaction ID." }, "invoice_number": { "type": [ "string", "null" ], "description": "Its number." }, "order_id": { "type": [ "string", "null" ], "description": "Its Merchant order ID." }, "customer_id": { "type": [ "string", "null" ], "description": "Its customer ID." }, "customer_email": { "type": [ "string", "null" ], "description": "Its customer email." }, "asset": { "type": "string", "description": "The asset sent back." }, "amount": { "type": "string", "description": "What the payer receives (exactly). Decimal string in the asset's units." }, "fiat_currency": { "type": [ "string", "null" ], "description": "Fiat invoices: the invoice currency." }, "fiat_amount": { "type": [ "string", "null" ], "description": "Fiat invoices: the amount refunded in that currency (`amount` = `fiat_amount` / `quote.rate`, rounded down)." }, "quote": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "rate", "source", "fetched_at" ], "properties": { "rate": { "type": "string", "description": "Fiat per whole unit of the asset." }, "source": { "type": [ "string", "null" ], "description": "The price source." }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the rate was read." } }, "description": "Fiat invoices: the current rate it was converted at when created." }, "network_fee": { "type": [ "string", "null" ], "description": "Charged to you on top (null before funding): a token's fee, or a coin's reserve until the transfer confirmed, then its actual cost. Decimal string in the asset's units." }, "network_fee_final": { "type": "boolean", "description": "`network_fee` is final." }, "total_charged": { "type": [ "string", "null" ], "description": "`amount` + `network_fee`: what left the funding account. Decimal string in the asset's units." }, "funding_source": { "type": "string", "enum": [ "held_funds", "balance", "payout_wallet" ], "x-enum-descriptions": { "held_funds": "The invoice's own held payment, sent from the address it was paid to.", "balance": "Your balance, sent from your collection address.", "payout_wallet": "Your payout wallet." }, "description": "Where the money comes from." }, "destination": { "type": "string", "description": "Where it goes: an address that paid the invoice." }, "destination_memo": { "type": [ "string", "null" ], "description": "Memo or tag of the destination." }, "destination_type": { "type": "string", "enum": [ "payer_address", "merchant_asserted" ], "x-enum-descriptions": { "payer_address": "An address that paid the invoice.", "merchant_asserted": "Entered by you because no paying address was known." }, "description": "Why this destination." }, "reason": { "type": [ "string", "null" ], "description": "Your note." }, "created_via": { "type": "string", "enum": [ "api", "dashboard" ], "description": "Where it was created." }, "settlement_id": { "type": [ "string", "null" ], "description": "The settlement that sends it (`GET /settlements/{id}`, kind `refund`)." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transfer's transaction hash, once sent." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link of `tx_hash`." }, "funds_returned": { "type": "boolean", "description": "A failed refund whose money went back where it came from: the invoice can be refunded again." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was created." }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was approved." }, "funded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its money was set aside." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its transfer confirmed." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it failed." }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was cancelled." } }, "additionalProperties": false }, "Payout": { "type": "object", "description": "A payout to one of your customers from your payout wallet: the customer receives exactly `amount`; the network fee is charged to you on top.", "required": [ "id", "object", "status", "status_reason", "environment", "asset", "amount", "network_fee", "network_fee_final", "total_charged", "destination", "destination_memo", "destination_basis", "matched_invoice_id", "matched_transaction_id", "customer_id", "customer_email", "order_id", "note", "created_via", "settlement_id", "tx_hash", "explorer_url", "funds_returned", "created_at", "approved_at", "funded_at", "completed_at", "failed_at", "cancelled_at" ], "properties": { "id": { "type": "string", "description": "Payout id." }, "object": { "type": "string", "const": "payout", "description": "Always `payout`." }, "status": { "type": "string", "enum": [ "pending_approval", "processing", "completed", "failed", "cancelled" ], "x-enum-descriptions": { "pending_approval": "Created from the API while \"API payouts need approval\" is on; its money is set aside in the payout wallet.", "processing": "Funded; its transfer is on its way.", "completed": "Sent: `tx_hash` and `explorer_url` prove it.", "failed": "The transfer failed (`status_reason`); the operator retries it or returns the money to the payout wallet (`funds_returned`).", "cancelled": "Cancelled before anything was sent." }, "description": "See [payout statuses](#status-payout)." }, "status_reason": { "type": [ "string", "null" ], "description": "Why it failed or waits: `transfer_failed`, `transfer_failed_funds_returned`, `cancelled_by_merchant`, or a transfer wait." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "asset": { "type": "string", "description": "The asset paid." }, "amount": { "type": "string", "description": "What the customer receives (exactly). Decimal string in the asset's units." }, "network_fee": { "type": [ "string", "null" ], "description": "Charged on top: a token's fee (0 when your own gas budget pays), a coin's reserve until completed, then its actual cost. Decimal string in the asset's units." }, "network_fee_final": { "type": "boolean", "description": "`network_fee` is final." }, "total_charged": { "type": [ "string", "null" ], "description": "`amount` + `network_fee`. Decimal string in the asset's units." }, "destination": { "type": "string", "description": "Where it goes." }, "destination_memo": { "type": [ "string", "null" ], "description": "Memo or tag of the destination." }, "destination_basis": { "type": "string", "enum": [ "past_payer", "customer_id", "customer_email", "any_address" ], "x-enum-descriptions": { "past_payer": "The address paid you before.", "customer_id": "A paid invoice names this `customer_id`.", "customer_email": "A paid invoice names this `customer_email`.", "any_address": "Any address is allowed." }, "description": "Why the destination was allowed (Payouts → Settings)." }, "matched_invoice_id": { "type": [ "string", "null" ], "description": "The paid invoice that made it eligible." }, "matched_transaction_id": { "type": [ "string", "null" ], "description": "Its Transaction ID." }, "customer_id": { "type": [ "string", "null" ], "description": "Your customer's id, as sent." }, "customer_email": { "type": [ "string", "null" ], "description": "Your customer's email (lower case)." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID for this payout." }, "note": { "type": [ "string", "null" ], "description": "Your note." }, "created_via": { "type": "string", "enum": [ "api", "dashboard" ], "description": "Where it was created." }, "settlement_id": { "type": [ "string", "null" ], "description": "The settlement that sends it (kind `payout`); null while it waits for approval." }, "tx_hash": { "type": [ "string", "null" ], "description": "The transfer's transaction hash, once sent." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link of `tx_hash`." }, "funds_returned": { "type": "boolean", "description": "A failed payout whose money went back to the payout wallet." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was created." }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was approved." }, "funded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its money was set aside." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its transfer confirmed." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it failed." }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was cancelled." } }, "additionalProperties": false }, "PayoutWalletBalance": { "type": "object", "description": "The payout wallet's money in one asset.", "required": [ "asset", "network", "available", "pending_approval", "low_balance_threshold", "alert_email", "below_threshold" ], "properties": { "asset": { "type": "string", "description": "Asset identifier." }, "network": { "type": "string", "description": "The network code." }, "available": { "type": "string", "description": "What payouts can spend now. Decimal string in the asset's units." }, "pending_approval": { "type": "string", "description": "Set aside for payouts waiting for approval. Decimal string in the asset's units." }, "low_balance_threshold": { "type": [ "string", "null" ], "description": "Your alert threshold (null: none). Decimal string in the asset's units." }, "alert_email": { "type": "boolean", "description": "Email me when below." }, "below_threshold": { "type": "boolean", "description": "Below the threshold now." } }, "additionalProperties": false }, "PayoutWallet": { "type": "object", "description": "Your payout wallet of one chain family: on EVM and Tron it holds tokens only (a gas coin sent there funds your gas budget).", "required": [ "object", "network_family", "status", "address", "networks", "environment", "balances" ], "properties": { "object": { "type": "string", "const": "payout_wallet", "description": "Always `payout_wallet`." }, "network_family": { "type": "string", "enum": [ "evm", "bitcoin", "bitcoincash", "tron" ], "description": "The chain family (one address for every EVM network)." }, "status": { "type": "string", "enum": [ "active", "allocating", "none" ], "x-enum-descriptions": { "active": "Its address exists and is watched for top-ups.", "allocating": "Being created (within a minute or two).", "none": "Not created yet." }, "description": "Whether it exists." }, "address": { "type": [ "string", "null" ], "description": "Its address (send money here to top it up); null until created." }, "networks": { "type": "array", "items": { "type": "string" }, "description": "The networks it receives on." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutWalletBalance" }, "description": "Its money per asset." } }, "additionalProperties": false }, "NetworkFeeDetail": { "type": "object", "description": "How `network_fee` was estimated at planning.", "required": [ "transfers", "recipients", "per_transfer", "fee_asset", "coin_per_transfer", "coin_usd", "token_usd", "estimated_at" ], "properties": { "transfers": { "type": "integer", "description": "Transfers charged." }, "recipients": { "type": "integer", "description": "Recipients among them." }, "per_transfer": { "type": "string", "description": "One transfer's estimated cost in the token. Decimal string in the asset's units." }, "fee_asset": { "type": [ "string", "null" ], "description": "The coin the gas is paid in." }, "coin_per_transfer": { "type": [ "string", "null" ], "description": "One transfer's estimated cost in `fee_asset` (decimal string)." }, "coin_usd": { "type": [ "string", "null" ], "description": "The coin's USD rate used." }, "token_usd": { "type": [ "string", "null" ], "description": "The token's USD rate used." }, "estimated_at": { "type": [ "string", "null" ], "description": "When it was estimated." } }, "additionalProperties": false }, "SettlementTransfer": { "type": "object", "description": "One on-chain transfer of a settlement.", "required": [ "id", "object", "settlement_id", "kind", "status", "hold_reason", "asset", "amount", "destination", "memo", "label", "network_fee", "network_fee_asset", "tx_hash", "explorer_url", "attempts", "error", "submitted_at", "confirmed_at" ], "properties": { "id": { "type": "string", "description": "Transfer id." }, "object": { "type": "string", "const": "settlement_transfer", "description": "Always `settlement_transfer`." }, "settlement_id": { "type": "string", "description": "Its settlement." }, "kind": { "type": "string", "enum": [ "recipient", "platform_fee", "consolidation", "refund", "balance_release", "withdrawal", "customer_payout", "payout_funding" ], "x-enum-descriptions": { "recipient": "To you (your settlement wallet) or a splitter recipient.", "platform_fee": "The platform commission (shown for transparency).", "consolidation": "To your collection address (daily schedule, or on request: into your balance).", "refund": "A refund to the paying customer.", "balance_release": "A balance release (before 2026-10-12).", "withdrawal": "A withdrawal of your balance to your settlement wallet.", "customer_payout": "A payout to your customer.", "payout_funding": "From your collection address into your payout wallet." }, "description": "Where it goes: see [transfer kinds](#status-transfer-kind)." }, "status": { "type": "string", "enum": [ "planned", "reserved", "submitted", "broadcast", "confirming", "confirmed", "rejected", "failed", "replaced", "unknown_outcome", "held" ], "x-enum-descriptions": { "planned": "Recorded, not sent yet.", "reserved": "Funds set aside for it.", "submitted": "Handed to the wallet provider.", "broadcast": "On the network, not in a block yet.", "confirming": "In a block, waiting for confirmations.", "confirmed": "Confirmed: final.", "rejected": "Refused by the provider before it was sent.", "failed": "Failed on the chain.", "replaced": "Replaced by a new transfer (fee bump).", "unknown_outcome": "Sent; its outcome is being verified with the provider. Never sent twice.", "held": "Waiting: see `hold_reason`." }, "description": "See [transfer statuses](#status-transfer)." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it waits: a code (e.g. `deposit_reorged`, `below_minimum_payout_accumulating`)." }, "asset": { "type": "string", "description": "The asset sent." }, "amount": { "type": "string", "description": "What is sent. Decimal string in the asset's units." }, "destination": { "type": [ "string", "null" ], "description": "The receiving address." }, "memo": { "type": [ "string", "null" ], "description": "Memo or tag." }, "label": { "type": [ "string", "null" ], "description": "The destination for people." }, "network_fee": { "type": [ "string", "null" ], "description": "What the network charged, in `network_fee_asset` (decimal string); null until known, and on the 2nd+ output of a shared Bitcoin transaction." }, "network_fee_asset": { "type": [ "string", "null" ], "description": "The coin that pays the network fee (e.g. `TRX_TRON` for `USDT_TRON`)." }, "tx_hash": { "type": [ "string", "null" ], "description": "Transaction hash once sent." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link of `tx_hash`: proof the money left." }, "attempts": { "type": "integer", "description": "Send attempts." }, "error": { "type": [ "string", "null" ], "description": "Why it waits or failed, in one short sentence in the platform's own words (e.g. waiting for the platform's network fee wallet; retried automatically). Never the provider's error text. Null when there is nothing to say." }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was sent." }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it confirmed." } }, "additionalProperties": false }, "WithdrawalDetails": { "type": "object", "description": "What a withdrawal asked for.", "required": [ "requested_amount", "destination", "estimate", "channel", "note", "cancellable", "cancel_reason" ], "properties": { "requested_amount": { "type": "string", "description": "Taken from the balance (= `gross`). Decimal string in the asset's units." }, "destination": { "type": "object", "description": "Where it goes.", "required": [ "address", "memo", "label", "source" ], "properties": { "address": { "type": [ "string", "null" ], "description": "The address." }, "memo": { "type": [ "string", "null" ], "description": "Memo or tag." }, "label": { "type": [ "string", "null" ], "description": "For people." }, "source": { "type": [ "string", "null" ], "enum": [ "settlement_wallet", "request", null ], "description": "`settlement_wallet`: your saved wallet; `request`: `destination_address` (settlement lock off)." } }, "additionalProperties": false }, "estimate": { "type": "object", "description": "The cost shown when it was requested (the planning estimates again).", "required": [ "network_fee", "execution_cost_reserve", "net", "basis" ], "properties": { "network_fee": { "type": [ "string", "null" ], "description": "Tokens: one transfer's network fee. Decimal string in the asset's units." }, "execution_cost_reserve": { "type": [ "string", "null" ], "description": "Coins: one transfer's reserve. Decimal string in the asset's units." }, "net": { "type": [ "string", "null" ], "description": "What would arrive at that estimate. Decimal string in the asset's units." }, "basis": { "type": [ "string", "null" ], "enum": [ "kept", "own_gas", "none", null ], "description": "`kept`: the platform's kept estimate; `own_gas`: your gas budget pays; `none`: no estimate yet." } }, "additionalProperties": false }, "channel": { "type": [ "string", "null" ], "enum": [ "dashboard", "api", "system", null ], "description": "Where it was requested." }, "note": { "type": [ "string", "null" ], "description": "Your note." }, "cancellable": { "type": "boolean", "description": "Still `requested`: `POST /withdrawals/{id}/cancel` works." }, "cancel_reason": { "type": [ "string", "null" ], "description": "Why a cancelled withdrawal was not sent: a code (e.g. `cancelled_by_merchant`, `insufficient_balance`, `unwound`)." } }, "additionalProperties": false }, "Settlement": { "type": "object", "description": "What one movement sends: your share of a payment with its fees and on-chain transfers, or a withdrawal of your balance.", "required": [ "id", "object", "kind", "status", "hold_reason", "environment", "asset", "owner", "invoice_id", "invoice_number", "transaction_id", "order_id", "gross", "platform_fee", "fixed_fee", "network_fee", "network_fee_detail", "execution_cost_reserve", "actual_network_cost", "residual_retained", "distributable", "cost_funding", "fee_snapshot_id", "gas_paid", "settlement_schedule", "settlement_batch_id", "withdrawal", "transfers", "created_at", "completed_at" ], "properties": { "id": { "type": "string", "description": "Settlement id." }, "object": { "type": "string", "const": "settlement", "description": "Always `settlement`." }, "kind": { "type": "string", "enum": [ "invoice", "daily", "split_session", "splitter", "balance_release", "refund", "withdrawal", "payout", "payout_wallet_funding" ], "x-enum-descriptions": { "invoice": "An invoice payment.", "daily": "A daily settlement: one transfer for the invoices collected that day.", "split_session": "A split session payment.", "splitter": "A deposit to a splitter.", "balance_release": "A balance release (before 2026-10-12; no longer created).", "refund": "A refund's transfer (listed under refunds, not among settlements).", "withdrawal": "A withdrawal of your balance.", "payout": "A payout's transfer (listed under payouts, not among settlements).", "payout_wallet_funding": "A move from your balance into the payout wallet." }, "description": "What is settled: see [settlement kinds](#status-settlement-kind)." }, "status": { "type": "string", "enum": [ "planned", "funds_reserved", "awaiting_resources", "submitting", "settling", "pooled", "completed", "partially_completed", "reconciliation_required", "held", "credited", "requested", "cancelled" ], "x-enum-descriptions": { "planned": "Recorded with its fees; not funded yet.", "funds_reserved": "Funded; its transfers will be sent.", "awaiting_resources": "Waits for gas or another resource (`hold_reason`); continues by itself.", "submitting": "Its transfers are being sent.", "settling": "Transfers broadcast, waiting for confirmations.", "pooled": "Daily schedule: on your collection address, sent with the next daily settlement.", "completed": "Every transfer confirmed.", "partially_completed": "Some transfers confirmed, others failed: the operator reviews it.", "reconciliation_required": "Needs operator review (a failed transfer or a reversed payment).", "held": "Waits (`hold_reason`), for example below the minimum payout.", "credited": "On-request schedule: your share is in your balance.", "requested": "A withdrawal you asked for: the amount is set aside and planned within about a minute.", "cancelled": "A withdrawal (or another transfer of yours) cancelled or refused before anything was sent (`hold_reason`), or a held invoice settlement replaced by a new plan of the same payment (`hold_reason` `replanned: `, or `replanned: nothing left`), or recorded by the platform operator as paid to you outside the platform (`replanned: settled outside`)." }, "description": "See [settlement statuses](#status-settlement)." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it waits or was cancelled: a code (e.g. `below_minimum_payout`, `fee_estimate_unavailable`, `insufficient_native_gas_budget`, `settlement_destination_missing`, `cancelled_by_merchant`, `unwound`), or `replanned: ` / `replanned: nothing left` / `replanned: settled outside`; `liability_short`: the platform operator reviews money that is no longer in your pending balance. Never the provider's own error text; an unknown code means the platform operator reviews it." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "asset": { "type": "string", "description": "The asset." }, "owner": { "type": "object", "description": "What the settlement belongs to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "payment_option", "invoice", "split_session", "splitter", "balance_release", "refund", "withdrawal", "customer_payout", "payout_funding", "settlement_batch" ], "description": "What it belongs to (`settlement_batch`: a daily settlement; `withdrawal`: itself)." }, "id": { "type": "string", "description": "Its id." } }, "additionalProperties": false }, "invoice_id": { "type": [ "string", "null" ], "description": "The invoice (Payment ID) this belongs to; null for splitters, withdrawals and daily settlements." }, "invoice_number": { "type": [ "string", "null" ], "description": "Its invoice number." }, "transaction_id": { "type": [ "string", "null" ], "description": "The Transaction ID of that invoice or split session (`TRX-…`, sandbox `TST-…`)." }, "order_id": { "type": [ "string", "null" ], "description": "The Merchant order ID of that invoice or split session." }, "gross": { "type": "string", "description": "What is settled. Decimal string in the asset's units." }, "platform_fee": { "type": "string", "description": "The platform commission, the fixed fee included. Decimal string in the asset's units." }, "fixed_fee": { "type": "string", "description": "The fixed fee per invoice in `platform_fee`. Decimal string in the asset's units." }, "network_fee": { "type": "string", "description": "Token gas of every transfer, charged in the token before the split (0 for coins and when your own gas budget pays). Decimal string in the asset's units." }, "network_fee_detail": { "anyOf": [ { "$ref": "#/components/schemas/NetworkFeeDetail" }, { "type": "null" } ], "description": "How `network_fee` was estimated; null when none was charged." }, "execution_cost_reserve": { "type": "string", "description": "Coins: the network cost reserved from the payment. Decimal string in the asset's units." }, "actual_network_cost": { "type": [ "string", "null" ], "description": "Coins: what the network charged. Decimal string in the asset's units." }, "residual_retained": { "type": [ "string", "null" ], "description": "The unused reserve kept (null until known). Decimal string in the asset's units." }, "distributable": { "type": "string", "description": "What reaches you or the recipients: gross − platform_fee − network_fee − execution_cost_reserve. Decimal string in the asset's units." }, "cost_funding": { "type": [ "string", "null" ], "enum": [ "separate_gas", "same_asset_reserve", null ], "description": "`separate_gas`: tokens, gas from a gas budget; `same_asset_reserve`: coins, reserved from the payment." }, "fee_snapshot_id": { "type": [ "string", "null" ], "description": "The fee snapshot it was planned with." }, "gas_paid": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "asset", "amount" ], "properties": { "asset": { "type": "string", "description": "The fee asset." }, "amount": { "type": "string", "description": "Decimal string in the fee asset." } }, "description": "Tokens: the gas its transfers actually spent (null until known)." }, "settlement_schedule": { "type": [ "string", "null" ], "enum": [ "on_request", "per_invoice", "daily", null ], "x-enum-descriptions": { "on_request": "Credited to your balance; you withdraw when you want (the default).", "per_invoice": "Sent to your settlement wallet for each invoice.", "daily": "Collected and sent once a day." }, "description": "Invoice settlements: the schedule it was planned under; null for the other kinds." }, "settlement_batch_id": { "type": [ "string", "null" ], "description": "Daily schedule: the batch that settles it." }, "withdrawal": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalDetails" }, { "type": "null" } ], "description": "Withdrawals only: what was asked for; null for every other kind." }, "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementTransfer" }, "description": "Its on-chain transfers, in order." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it completed (or was credited)." } }, "additionalProperties": false }, "UsdEstimate": { "type": "object", "description": "A USD estimate at the rate the platform keeps (display only, never used for a payment).", "required": [ "rate", "rate_source", "rate_at", "stale", "available", "total" ], "properties": { "rate": { "type": "string", "description": "USD per whole unit (decimal string)." }, "rate_source": { "type": "string", "description": "The price source, or `stablecoin_par` (a USD stablecoin counted 1:1)." }, "rate_at": { "type": "string", "format": "date-time", "description": "When the rate was read." }, "stale": { "type": "boolean", "description": "The rate is older than an hour." }, "available": { "type": "string", "description": "`available` in USD, rounded down to the cent." }, "total": { "type": "string", "description": "`total` in USD, rounded toward zero to the cent." } }, "additionalProperties": false }, "Balance": { "type": "object", "description": "Your money in one asset (the key's environment). Assets are never added together.", "required": [ "object", "asset", "symbol", "decimals", "available", "pending", "pending_detail", "held", "reserved", "payout_wallet", "retained", "deficit", "total", "minimum_withdrawal", "usd" ], "properties": { "object": { "type": "string", "const": "balance", "description": "Always `balance`." }, "asset": { "type": "string", "description": "Asset identifier." }, "symbol": { "type": "string", "description": "Its symbol." }, "decimals": { "type": "integer", "description": "Its decimals." }, "available": { "type": "string", "description": "In your balance and not set aside: what `POST /withdrawals` can take. Decimal string in the asset's units." }, "pending": { "type": "string", "description": "Confirmed payments on their way into the balance (or to your wallet on the other schedules); `pending_detail` says why each part waits. Decimal string in the asset's units." }, "pending_detail": { "type": "array", "items": { "$ref": "#/components/schemas/PendingPart" }, "description": "What `pending` is made of and why it waits, one part per reason in a fixed order; the amounts add up to `pending` exactly. Empty when nothing is pending. From stored records only (no network call)." }, "held": { "type": "string", "description": "Waiting for your decision (late, underpaid, extra payments). Decimal string in the asset's units." }, "reserved": { "type": "string", "description": "Set aside for withdrawals and refunds on their way. Decimal string in the asset's units." }, "payout_wallet": { "type": [ "string", "null" ], "description": "What the payout wallet can pay out now; null without payout-wallet money in this asset. Decimal string in the asset's units." }, "retained": { "type": "string", "description": "Unused network-fee reserves. Decimal string in the asset's units." }, "deficit": { "type": "string", "description": "What you owe after a payment was reversed; taken from the next payments. Decimal string in the asset's units." }, "total": { "type": "string", "description": "available + pending + held + reserved + payout_wallet + retained − deficit (signed decimal string)." }, "minimum_withdrawal": { "type": "string", "description": "The least a withdrawal must deliver after its network cost. Decimal string in the asset's units." }, "usd": { "anyOf": [ { "$ref": "#/components/schemas/UsdEstimate" }, { "type": "null" } ], "description": "USD estimate; null without a usable rate." } }, "additionalProperties": false }, "PendingPart": { "type": "object", "description": "One part of a balance's `pending`: why that money is not in your balance (or your wallet) yet.", "required": [ "code", "label", "amount", "amount_atomic", "count" ], "properties": { "code": { "type": "string", "enum": [ "waiting_for_gas", "paused", "splitter_paused", "operator_review", "on_its_way", "replanning", "too_small", "no_destination", "open_invoice", "split_waiting", "scheduled_daily", "other" ], "x-enum-descriptions": { "waiting_for_gas": "Planned; its token transfer waits for network fee (gas) funds: the platform's gas wallet (the operator is notified) or, when your own gas budget pays your transfers, that budget. It continues by itself once they are topped up.", "paused": "Planned; transfers are paused by the platform (all of them, a network, a provider or your account; live transfers not activated yet). It continues by itself when the pause is lifted.", "splitter_paused": "Planned; your own splitter is paused. Resume it (Splitters) and its transfers continue.", "operator_review": "Stopped: a transfer failed or needs a check, the money is held for a reason only the platform operator can clear (an archived splitter included), or the operator decides about money from before 2026-10-12. The operator reviews it.", "on_its_way": "Planned and sent, or about to be sent: waiting for network confirmations. Into your balance on the on-request schedule, to your wallet on the others.", "replanning": "Not planned yet (no network fee estimate at the time, unwound by the operator, below the minimum payout, or a settlement wallet saved since): the platform plans it again by itself.", "too_small": "Too small to move on its own (the network cost would take most or all of it, or, for an invoice paid out through a splitter, a recipient's share is below the minimum payout): it waits until the platform operator plans it again.", "no_destination": "A paid invoice with nowhere to settle to: save a settlement wallet for its network (an older invoice without an address of its own), or its splitter has no current version. It moves on by itself once there is one.", "open_invoice": "Confirmed part-payments of invoices that are still open: they wait for the rest of the payment.", "split_waiting": "Payments to a splitter or split session that wait for more: its threshold, the minimum payout or the next payment.", "scheduled_daily": "Daily schedule: collected, and paid to your wallet by the next daily payout.", "other": "Anything else not settled yet (for example money from an older release, or a settlement in a state not listed here). Ask support if it stays." }, "description": "Why it waits. New codes may be added; treat an unknown one like `other`." }, "label": { "type": "string", "description": "The reason in a short English sentence, for people (its wording may change; use `code` in code)." }, "amount": { "type": "string", "description": "Decimal string in the asset's units." }, "amount_atomic": { "type": "string", "description": "The same in the smallest unit (integer string)." }, "count": { "type": "integer", "minimum": 0, "description": "How many settlements, invoices or payments it is made of (for `other`: only settlements in a state no other code covers, often 0)." } }, "additionalProperties": false }, "BalanceList": { "type": "object", "description": "The answer to `GET /balances`.", "required": [ "object", "environment", "data", "usd_totals", "request_id" ], "properties": { "object": { "type": "string", "const": "list", "description": "Always `list`." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" }, "description": "One per asset with money." }, "usd_totals": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "available", "total", "oldest_rate_at", "complete", "missing", "note" ], "properties": { "available": { "type": "string", "description": "Available in USD." }, "total": { "type": "string", "description": "Total in USD." }, "oldest_rate_at": { "type": "string", "format": "date-time", "description": "The oldest rate used." }, "complete": { "type": "boolean", "description": "Every asset had a rate." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "Assets without a rate." }, "note": { "type": "string", "description": "What the estimate means." } }, "description": "Sums over the assets with a rate; null when there is nothing." }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false }, "Deposit": { "type": "object", "description": "A payment seen on the network (both products).", "required": [ "id", "object", "status", "hold_reason", "classification", "environment", "asset", "amount", "tx_hash", "explorer_url", "block_number", "confirmations", "address", "payer_address", "owner", "settlement_id", "invoice_id", "invoice_number", "transaction_id", "order_id", "observed_at", "confirmed_at", "accepted_at" ], "properties": { "id": { "type": "string", "description": "Deposit id." }, "object": { "type": "string", "const": "deposit", "description": "Always `deposit`." }, "status": { "type": "string", "enum": [ "observed", "confirming", "confirmed", "dropped", "conflicted", "reorged", "unsupported", "held" ], "x-enum-descriptions": { "observed": "Seen on the network, not confirmed yet.", "confirming": "In a block, waiting for confirmations.", "confirmed": "Confirmed: counted.", "dropped": "Left the chain before it confirmed.", "conflicted": "Two sources disagree about it; checked again.", "reorged": "Undone by a chain reorganisation after it confirmed.", "unsupported": "An asset or contract the platform does not accept.", "held": "Kept aside (`hold_reason`): late, extra, below the minimum, or waiting for your decision." }, "description": "See [deposit statuses](#status-deposit)." }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it is held." }, "classification": { "type": [ "string", "null" ], "enum": [ "customer", "internal", "gas_topup", "unsupported", "payout_topup", null ], "x-enum-descriptions": { "customer": "A customer payment.", "internal": "A transfer between the platform's own addresses.", "gas_topup": "Network coin for gas (your gas budget or the platform's).", "unsupported": "Not a payment the platform accepts.", "payout_topup": "Money you sent to your payout wallet (credited to it; no `deposit.*` webhook)." }, "description": "What kind of money it is." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "asset": { "type": [ "string", "null" ], "description": "The asset." }, "amount": { "type": [ "string", "null" ], "description": "The amount. Decimal string in the asset's units." }, "tx_hash": { "type": "string", "description": "The payment's transaction hash." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link of `tx_hash`: proof the customer paid." }, "block_number": { "type": [ "integer", "null" ], "description": "Its block (null while unconfirmed)." }, "confirmations": { "type": [ "integer", "null" ], "description": "Confirmations so far." }, "address": { "type": [ "string", "null" ], "description": "The receiving address." }, "payer_address": { "type": [ "string", "null" ], "description": "Who sent it (canonical form), where a refund goes back to; null when the source names no sender (Bitcoin Cash, block scans)." }, "owner": { "type": "object", "description": "What the address belongs to.", "required": [ "type", "id" ], "properties": { "type": { "type": [ "string", "null" ], "description": "What received it (`payment_option`, `split_session`, `splitter`, …)." }, "id": { "type": [ "string", "null" ], "description": "Its id." } }, "additionalProperties": false }, "settlement_id": { "type": [ "string", "null" ], "description": "The settlement that took it." }, "invoice_id": { "type": [ "string", "null" ], "description": "The invoice (Payment ID) this belongs to; null for splitters, withdrawals and daily settlements." }, "invoice_number": { "type": [ "string", "null" ], "description": "Its invoice number." }, "transaction_id": { "type": [ "string", "null" ], "description": "The Transaction ID of that invoice or split session (`TRX-…`, sandbox `TST-…`)." }, "order_id": { "type": [ "string", "null" ], "description": "The Merchant order ID of that invoice or split session." }, "observed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First seen." }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Confirmed." }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Accepted into a settlement." } }, "additionalProperties": false }, "Asset": { "type": "object", "description": "A supported asset in the key's environment.", "required": [ "asset", "symbol", "name", "kind", "token_standard", "contract_address", "decimals", "network", "fee_asset", "requires_memo", "minimum_deposit", "minimum_payout", "max_recipients", "customer_payment_option", "capabilities", "platform_fee_percentage", "network_cost_mode" ], "properties": { "asset": { "type": "string", "description": "Identifier (asset + network), e.g. `USDT_TRON`." }, "symbol": { "type": "string", "description": "Symbol." }, "name": { "type": "string", "description": "Name." }, "kind": { "type": "string", "enum": [ "native", "token" ], "x-enum-descriptions": { "native": "The network's own coin.", "token": "A token on the network." }, "description": "Coin or token." }, "token_standard": { "type": [ "string", "null" ], "description": "`erc20`, `trc20`… for tokens." }, "contract_address": { "type": [ "string", "null" ], "description": "The token contract." }, "decimals": { "type": "integer", "description": "Decimals." }, "network": { "type": "object", "description": "Its network.", "required": [ "code", "name", "family", "chain_id", "environment", "required_confirmations", "finality_policy", "average_block_seconds", "explorer_tx_url" ], "properties": { "code": { "type": "string", "description": "Network code." }, "name": { "type": "string", "description": "Name." }, "family": { "type": "string", "description": "Chain family." }, "chain_id": { "type": [ "string", "null" ], "description": "EVM chain id." }, "environment": { "type": "string", "description": "Its environment." }, "required_confirmations": { "type": "integer", "description": "Confirmations before money counts." }, "finality_policy": { "type": "string", "description": "How finality is decided." }, "average_block_seconds": { "type": "integer", "description": "Average block time." }, "explorer_tx_url": { "type": [ "string", "null" ], "description": "Explorer link template." } }, "additionalProperties": false }, "fee_asset": { "type": [ "string", "null" ], "description": "The coin that pays its network fees." }, "requires_memo": { "type": "boolean", "description": "A memo or tag is needed." }, "minimum_deposit": { "type": "string", "description": "Smaller payments are held. Decimal string in the asset's units." }, "minimum_payout": { "type": "string", "description": "The smallest transfer sent. Decimal string in the asset's units." }, "max_recipients": { "type": "integer", "description": "Most splitter recipients." }, "customer_payment_option": { "type": "boolean", "description": "May be offered to payers." }, "capabilities": { "type": "object", "description": "What it can do.", "required": [ "receive", "settle", "strict_fresh_address", "invoice_payment_option" ], "properties": { "receive": { "type": "boolean", "description": "Can receive." }, "settle": { "type": "boolean", "description": "Can settle." }, "strict_fresh_address": { "type": "boolean", "description": "Fresh addresses are checked." }, "invoice_payment_option": { "type": "boolean", "description": "May be listed in an invoice's `allowed_assets`." } }, "additionalProperties": false }, "platform_fee_percentage": { "type": [ "string", "null" ], "description": "Your commission for it (`\"1.00\"`); null when none is configured." }, "network_cost_mode": { "type": "string", "enum": [ "separate_native_gas_budget", "same_asset_execution_reserve" ], "x-enum-descriptions": { "separate_native_gas_budget": "Tokens: gas comes from a gas budget.", "same_asset_execution_reserve": "Coins: the cost is reserved from the payment." }, "description": "How network costs are paid." } }, "additionalProperties": false }, "FeePolicy": { "type": "object", "description": "The fee snapshot of a split.", "required": [ "snapshot_id", "platform_percentage", "recipient_basis", "network_cost_mode", "operator_fee_wallet_configured" ], "properties": { "snapshot_id": { "type": "string", "description": "The fee snapshot." }, "platform_percentage": { "type": "string", "description": "The commission, e.g. `\"1.00\"`." }, "recipient_basis": { "type": "string", "enum": [ "after_platform_fee_and_disclosed_same_asset_costs" ], "description": "Recipients share what is left after the fee and the disclosed costs." }, "network_cost_mode": { "type": "string", "enum": [ "separate_native_gas_budget", "same_asset_execution_reserve" ], "x-enum-descriptions": { "separate_native_gas_budget": "Tokens: gas from a gas budget.", "same_asset_execution_reserve": "Coins: reserved from the payment." }, "description": "How network costs are paid." }, "operator_fee_wallet_configured": { "type": "boolean", "description": "The platform fee is sent to a fee wallet." } }, "additionalProperties": false }, "MerchantFeePolicy": { "type": "object", "description": "The answer to `GET /fee-policy`.", "required": [ "object", "environment", "recipient_basis", "network_cost_mode", "cost_model", "max_recipients", "assets", "settlement_schedule", "request_id" ], "properties": { "object": { "type": "string", "const": "fee_policy", "description": "Always `fee_policy`." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "recipient_basis": { "type": "string", "description": "How recipients share." }, "network_cost_mode": { "type": "string", "description": "Kept for older clients: read each asset's own mode." }, "cost_model": { "type": "object", "description": "How costs are charged.", "required": [ "tokens", "native_assets", "rounding" ], "properties": { "tokens": { "type": "string", "description": "Tokens." }, "native_assets": { "type": "string", "description": "Coins." }, "rounding": { "type": "string", "description": "Rounding." } }, "additionalProperties": false }, "max_recipients": { "type": "integer", "description": "Most splitter recipients." }, "assets": { "type": "object", "description": "Per asset identifier.", "additionalProperties": { "type": "object", "description": "Per asset.", "required": [ "platform_percentage", "network_cost_mode" ], "properties": { "platform_percentage": { "type": [ "string", "null" ], "description": "Your commission." }, "source": { "type": "string", "description": "Where it comes from (merchant, asset, platform)." }, "minimum_payout": { "type": "string", "description": "The smallest transfer (decimal string)." }, "minimum_withdrawal": { "type": "string", "description": "The least a withdrawal must deliver (decimal string)." }, "error": { "type": "string", "description": "Why no commission resolves." }, "network_cost_mode": { "type": "string", "description": "How network costs are paid for it." } }, "additionalProperties": false } }, "settlement_schedule": { "type": "object", "description": "When your paid invoices are settled.", "required": [ "current", "platform_default", "merchant_may_choose", "daily_hour_utc" ], "properties": { "current": { "type": "string", "enum": [ "on_request", "per_invoice", "daily" ], "x-enum-descriptions": { "on_request": "Credited to your balance; you withdraw when you want (the default).", "per_invoice": "Sent to your settlement wallet for each invoice.", "daily": "Collected and sent once a day." }, "description": "Your schedule now." }, "platform_default": { "type": "string", "enum": [ "on_request", "per_invoice", "daily" ], "x-enum-descriptions": { "on_request": "Credited to your balance; you withdraw when you want (the default).", "per_invoice": "Sent to your settlement wallet for each invoice.", "daily": "Collected and sent once a day." }, "description": "The platform's default." }, "merchant_may_choose": { "type": "boolean", "description": "You may choose it (Balances → Settlement schedule)." }, "daily_hour_utc": { "type": "integer", "description": "The hour of the daily schedule (UTC)." } }, "additionalProperties": false }, "request_id": { "type": "string", "description": "The id of this request." } }, "additionalProperties": false }, "Recipient": { "type": "object", "description": "A split recipient.", "required": [ "address", "memo", "percentage", "label" ], "properties": { "address": { "type": "string", "description": "The address." }, "memo": { "type": [ "string", "null" ], "description": "Memo or tag." }, "percentage": { "type": "string", "description": "Share, two decimals (`\"60.00\"`)." }, "label": { "type": [ "string", "null" ], "description": "For people." } }, "additionalProperties": false }, "SplitSession": { "type": "object", "description": "A one-off fresh deposit address that splits its payment.", "required": [ "id", "object", "transaction_id", "status", "environment", "asset", "network", "deposit_address", "memo", "payment_uri", "order_id", "settlement_trigger", "expected_amount", "minimum_deposit", "received_confirmed", "settled_gross", "held", "recipients", "fee_policy", "confirmation_policy", "freshness", "late_payment_policy", "metadata", "expires_at", "closed_at", "first_payment_at", "settled_at", "created_at", "status_url", "checkout_url" ], "properties": { "id": { "type": "string", "description": "Split session id." }, "object": { "type": "string", "const": "split_session", "description": "Always `split_session`." }, "transaction_id": { "type": [ "string", "null" ], "description": "Its Transaction ID (`TRX-…`, sandbox `TST-…`)." }, "status": { "type": "string", "enum": [ "allocating", "awaiting_payment", "payment_detected", "processing", "settled", "partially_settled", "expired", "held", "cancelled" ], "x-enum-descriptions": { "allocating": "No fresh address yet: poll `status_url` (or `GET /split-sessions/{id}`).", "awaiting_payment": "Waiting for the payment to `deposit_address`.", "payment_detected": "A payment is seen, waiting for confirmations.", "processing": "Confirmed; the split is being sent.", "settled": "Every recipient was paid.", "partially_settled": "Some transfers confirmed, others not (the operator reviews them).", "expired": "Closed at `expires_at` without a payment.", "held": "Kept aside (late or not payable as configured): see the settlement or `split_session.held`.", "cancelled": "Closed by you before a payment." }, "description": "See [split session statuses](#splitter-lifecycle)." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "asset": { "type": "string", "description": "The asset." }, "network": { "type": "string", "description": "Its network." }, "deposit_address": { "type": [ "string", "null" ], "description": "The fresh address to pay; null while `allocating`." }, "memo": { "type": [ "string", "null" ], "description": "Memo or tag to send with the payment." }, "payment_uri": { "type": [ "string", "null" ], "description": "Payment link for wallets (BIP-21, EIP-681; null for Tron)." }, "order_id": { "type": [ "string", "null" ], "description": "Your Merchant order ID." }, "settlement_trigger": { "type": "string", "enum": [ "each_confirmed_deposit", "target_confirmed_amount" ], "description": "When it is split." }, "expected_amount": { "type": [ "string", "null" ], "description": "The target amount. Decimal string in the asset's units." }, "minimum_deposit": { "type": "string", "description": "Smaller payments are held. Decimal string in the asset's units." }, "received_confirmed": { "type": "string", "description": "Confirmed so far. Decimal string in the asset's units." }, "settled_gross": { "type": "string", "description": "Settled so far. Decimal string in the asset's units." }, "held": { "type": "string", "description": "Held. Decimal string in the asset's units." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Who receives what." }, "fee_policy": { "$ref": "#/components/schemas/FeePolicy", "description": "The fee snapshot." }, "confirmation_policy": { "type": "object", "description": "When a payment counts.", "required": [ "required_confirmations", "finality" ], "properties": { "required_confirmations": { "type": "integer", "description": "Confirmations needed." }, "finality": { "type": "string", "description": "Finality rule." } }, "additionalProperties": false }, "freshness": { "type": [ "object", "null" ], "x-free-form": true, "description": "How the address was checked to be unused (`pending_reason` while allocating)." }, "late_payment_policy": { "type": [ "string", "null" ], "description": "What happens to late money (`hold_for_review`)." }, "metadata": { "type": [ "object", "null" ], "x-free-form": true, "description": "As sent." }, "expires_at": { "type": "string", "format": "date-time", "description": "When it expires." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it closed." }, "first_payment_at": { "type": [ "string", "null" ], "format": "date-time", "description": "First payment." }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When settled." }, "created_at": { "type": "string", "format": "date-time", "description": "When created." }, "status_url": { "type": "string", "description": "`GET` this to poll it." }, "checkout_url": { "type": "string", "description": "The payer's page (`/pay/s/{token}`)." } }, "additionalProperties": false }, "SplitSessionDetail": { "allOf": [ { "$ref": "#/components/schemas/SplitSession" }, { "type": "object", "required": [ "deposits", "settlements" ], "properties": { "deposits": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" }, "description": "Its payments." }, "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" }, "description": "Its settlements." } } } ], "description": "`GET /split-sessions/{id}`: the session with its deposits and settlements." }, "SplitterVersion": { "type": "object", "description": "A recipient version of a splitter.", "required": [ "id", "version", "activation_block", "recipients", "fee_policy" ], "properties": { "id": { "type": "string", "description": "Version id." }, "version": { "type": "integer", "description": "Version number." }, "activation_block": { "type": [ "integer", "null" ], "description": "From this block on." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Recipients." }, "fee_policy": { "$ref": "#/components/schemas/FeePolicy", "description": "Fee snapshot." } }, "additionalProperties": false }, "Splitter": { "type": "object", "description": "A persistent receiving wallet that splits every deposit.", "required": [ "id", "object", "name", "status", "environment", "asset", "execution_mode", "receiving_address", "settlement_mode", "settlement_threshold", "start_block", "current_version", "created_at", "activated_at", "paused_at" ], "properties": { "id": { "type": "string", "description": "Splitter id." }, "object": { "type": "string", "const": "splitter", "description": "Always `splitter`." }, "name": { "type": "string", "description": "Name." }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "x-enum-descriptions": { "draft": "Waits for signer verification.", "active": "Receives and splits.", "paused": "Receives; sends are paused.", "archived": "Closed." }, "description": "Its state." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "asset": { "type": "string", "description": "The asset." }, "execution_mode": { "type": "string", "enum": [ "managed", "watch_only" ], "description": "Managed (sends) or watch-only." }, "receiving_address": { "type": [ "string", "null" ], "description": "Where payers send." }, "settlement_mode": { "type": "string", "enum": [ "each_confirmed_deposit", "threshold" ], "description": "When it splits." }, "settlement_threshold": { "type": [ "string", "null" ], "description": "The threshold. Decimal string in the asset's units." }, "start_block": { "type": [ "integer", "null" ], "description": "Watched from this block." }, "current_version": { "anyOf": [ { "$ref": "#/components/schemas/SplitterVersion" }, { "type": "null" } ], "description": "The recipients that apply now." }, "created_at": { "type": "string", "format": "date-time", "description": "When created." }, "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When activated." }, "paused_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When paused." } }, "additionalProperties": false }, "SplitterDetail": { "allOf": [ { "$ref": "#/components/schemas/Splitter" }, { "type": "object", "required": [ "versions" ], "properties": { "versions": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "activation_block", "recipients", "fee_policy", "activated_at", "retired_at" ], "properties": { "id": { "type": "string", "description": "Version id." }, "version": { "type": "integer", "description": "Version number." }, "activation_block": { "type": [ "integer", "null" ], "description": "From this block on." }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Recipients." }, "fee_policy": { "$ref": "#/components/schemas/FeePolicy", "description": "Fee snapshot." }, "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it applied." }, "retired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stopped applying." } }, "additionalProperties": false }, "description": "Every version, newest first." } } } ], "description": "`GET /splitters/{id}`: with every version." }, "Wallet": { "type": "object", "description": "A wallet of your account.", "required": [ "id", "object", "kind", "label", "status", "environment", "provider", "signer_verified", "execution", "addresses", "created_at" ], "properties": { "id": { "type": "string", "description": "Wallet id." }, "object": { "type": "string", "const": "wallet", "description": "Always `wallet`." }, "kind": { "type": "string", "enum": [ "managed", "watch_only" ], "x-enum-descriptions": { "managed": "Keys held by the custody provider.", "watch_only": "An address you own; only watched." }, "description": "Managed or watch-only." }, "label": { "type": [ "string", "null" ], "description": "Your label." }, "status": { "type": "string", "description": "Its state." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "provider": { "type": [ "string", "null" ], "description": "The custody provider." }, "signer_verified": { "type": "boolean", "description": "Signer control was verified." }, "execution": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Whether it can send." }, "addresses": { "type": "array", "items": { "type": "object", "required": [ "address", "network", "purpose", "status" ], "properties": { "address": { "type": "string", "description": "Address." }, "network": { "type": "string", "description": "Network code." }, "purpose": { "type": "string", "description": "What it is for." }, "status": { "type": "string", "description": "Its state." } }, "additionalProperties": false }, "description": "Its addresses." }, "created_at": { "type": "string", "format": "date-time", "description": "When created." } }, "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "description": "A webhook endpoint.", "required": [ "id", "object", "url", "environment", "event_types", "status", "key_id", "consecutive_failures", "created_at" ], "properties": { "id": { "type": "string", "description": "Endpoint id." }, "object": { "type": "string", "const": "webhook_endpoint", "description": "Always `webhook_endpoint`." }, "url": { "type": "string", "description": "Where events are posted." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Subscriptions: `*`, `.*` or event names." }, "status": { "type": "string", "enum": [ "active", "failing", "disabled" ], "x-enum-descriptions": { "active": "Receives events.", "failing": "Many failures in a row; still receives.", "disabled": "Receives nothing." }, "description": "Its state." }, "key_id": { "type": [ "string", "null" ], "description": "The signing key version (`X-Webhook-Key-Id`)." }, "consecutive_failures": { "type": [ "integer", "null" ], "description": "Failed deliveries in a row." }, "created_at": { "type": "string", "format": "date-time", "description": "When created." } }, "additionalProperties": false }, "WebhookEndpointSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret (`whsec_…`): shown only now." }, "note": { "type": "string", "description": "A reminder." }, "previous_secret_valid_until": { "type": "string", "format": "date-time", "description": "After a rotation: until when the old secret also signs." } } } ], "description": "An endpoint with its new secret (on creation and rotation)." }, "WebhookDelivery": { "type": "object", "description": "One delivery of an event to one endpoint.", "required": [ "id", "endpoint_id", "status", "attempt", "response_code", "last_error", "next_attempt_at", "delivered_at", "replayed" ], "properties": { "id": { "type": "string", "description": "Delivery id." }, "endpoint_id": { "type": "string", "description": "The endpoint." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead", "cancelled" ], "x-enum-descriptions": { "pending": "Waiting to be sent (or retried).", "delivered": "Answered 2xx.", "dead": "Every attempt failed.", "cancelled": "The endpoint was disabled before it was delivered." }, "description": "Its state." }, "attempt": { "type": "integer", "description": "Attempts so far." }, "response_code": { "type": [ "integer", "null" ], "description": "The last HTTP answer." }, "last_error": { "type": [ "string", "null" ], "description": "The last error." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Next try." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When delivered." }, "replayed": { "type": "boolean", "description": "A replay." } }, "additionalProperties": false }, "WebhookEvent": { "type": "object", "description": "A recorded event with its deliveries (`GET /webhook-events` is also a polling feed).", "required": [ "id", "object", "type", "resource", "occurred_at", "data", "deliveries" ], "properties": { "id": { "type": "string", "description": "Event id (`X-Webhook-Id`)." }, "object": { "type": "string", "const": "webhook_event", "description": "Always `webhook_event`." }, "type": { "type": "string", "description": "Event type." }, "resource": { "type": "object", "description": "What it is about.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "Resource type." }, "id": { "type": "string", "description": "Its id." } }, "additionalProperties": false }, "occurred_at": { "type": "string", "format": "date-time", "description": "When." }, "data": { "type": "object", "x-free-form": true, "description": "The event data (see [events](#webhook-events))." }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "Its deliveries." } }, "additionalProperties": false }, "WebhookEnvelope": { "type": "object", "description": "The body of every delivery. Headers: `X-Webhook-Id`, `X-Webhook-Timestamp`, `X-Webhook-Key-Id`, `X-Webhook-Signature` (`v1=` HMAC-SHA256 of `timestamp.body`; two during a secret rotation), `X-Webhook-Event`.", "required": [ "id", "schema_version", "type", "occurred_at", "delivery_attempt_id", "environment", "resource", "data" ], "properties": { "id": { "type": "string", "description": "Event id: the same in every retry and replay (dedupe on it, or on `X-Webhook-Id`)." }, "schema_version": { "type": "string", "const": "2026-10-12", "description": "The API revision of the payload." }, "type": { "type": "string", "description": "Event type." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened." }, "delivery_attempt_id": { "type": "string", "description": "This delivery." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ], "x-enum-descriptions": { "sandbox": "Test networks and test coins; nothing is real.", "live": "Real networks and real money." }, "description": "The environment of the object (the API key's)." }, "resource": { "type": "object", "description": "What it is about.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "Resource type." }, "id": { "type": "string", "description": "Its id: re-fetch it before acting (GET /invoices|refunds|payouts|settlements|split-sessions|splitters/{id}; a settlement_transfer through GET /settlements/{data.settlement_id}, a deposit through GET /deposits?tx_hash=)." } }, "additionalProperties": false }, "data": { "type": "object", "x-free-form": true, "description": "Event data: small and event-specific; amounts are decimal strings." } }, "additionalProperties": false } } } }