{ "openapi": "3.1.0", "info": { "title": "Clarian API", "version": "2.0.0", "description": "Customer-facing API for the Clarian B2B crypto/PIX platform. Every route below lives under /v1/{env}/ and is reached with an API key (or, for a handful of owner/admin dashboard actions, a Better Auth session). Wallets, PIX on/off-ramp, OTC/RFQ, KYC, webhooks, payment links and multi-tenant wallet-as-a-service sub-accounts. Rate limit: 120 requests per minute per API key (fixed one-minute window); over it the reply is 429 `rate_limited`, retry after the window resets. Amounts are integer minor units as strings: BRL scale 2 (R$ 10,00 = \"1000\"), USDT/USDC scale 6. Until the workspace holder is KYC-approved, every /v1 route answers 403 `kyc_not_approved` to an API key, in live and test, reads and `ping` included. A dashboard session reaches only the onboarding routes, the read-only KYC routes, public checkout and the stop actions (revoke an API key; delete a webhook, team member, payout account, whitelist entry or payment link)." }, "servers": [ { "url": "https://api.clarian.finance" } ], "security": [ { "ApiKeyAuth": [], "WorkspaceIdHeader": [] } ], "tags": [ { "name": "Probe" }, { "name": "Balances" }, { "name": "Wallets" }, { "name": "Transactions" }, { "name": "PIX" }, { "name": "RFQ" }, { "name": "Prices" }, { "name": "Crypto" }, { "name": "Customers" }, { "name": "KYC" }, { "name": "Whitelist" }, { "name": "BankAccounts" }, { "name": "Webhooks" }, { "name": "PaymentLinks" }, { "name": "Checkout" }, { "name": "SubAccounts" }, { "name": "ApiKeys" }, { "name": "Settings" }, { "name": "Notifications" }, { "name": "Trading", "description": "BRL and stablecoins in the pooled exchange account: send BRL in, convert, withdraw coins to your wallet." }, { "name": "Onboarding", "description": "The workspace holder's own verification. Dashboard session only; open before KYC approval." } ], "paths": { "/v1/{env}/ping": { "get": { "tags": [ "Probe" ], "summary": "Auth probe", "operationId": "ping", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "Credentials are valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pong": { "type": "boolean" }, "workspace_id": { "type": "string" }, "environment": { "type": "string" }, "mock": { "type": "boolean" } } } } } }, "403": { "description": "kyc_not_approved (until the workspace holder is KYC-approved, live and test)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/balances": { "get": { "tags": [ "Balances" ], "summary": "Ledger balances", "operationId": "listBalances", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } } } } }, "403": { "description": "kyc_not_approved (until the workspace holder is KYC-approved, live and test)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/account/balances": { "get": { "tags": [ "Balances" ], "summary": "Ledger balances (alias)", "description": "Alias of GET /v1/{env}/balances.", "operationId": "listBalancesAlias", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List wallets", "operationId": "listWallets", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Create wallet", "description": "Provisions a wallet via the key-management provider (mocked when PROVIDER_MOCK=true). EVM networks share one address, registered on every EVM network at once.", "operationId": "createWallet", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Wallet" } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/wallets/{id}": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet", "operationId": "getWallet", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Wallet" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/wallets/{id}/balance": { "get": { "tags": [ "Wallets" ], "summary": "On-chain balance", "description": "Reads the on-chain (or mocked) balance for the wallet's tokens, plus a `native` field with the chain's gas coin.", "operationId": "getWalletBalance", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Provider-shaped token balances plus `native`.", "additionalProperties": true } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/wallets/{id}/transactions": { "get": { "tags": [ "Wallets" ], "summary": "Wallet's transactions", "operationId": "listWalletTransactions", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet id." }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size, 1..200 (default 50)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "description": "Payment intents, newest first.", "operationId": "listTransactions", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Page size, 1..100 (default 50)." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "id of the last row of the previous page; pages backward (newest first)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "400": { "description": "invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction", "operationId": "getTransaction", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/statement": { "get": { "tags": [ "Transactions" ], "summary": "Ledger statement", "description": "Every ledger line of the workspace's own accounts, newest first.", "operationId": "getStatement", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Page size, 1..100 (default 50)." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "id of the last line seen." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive lower bound on posted_at." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Exclusive upper bound on posted_at." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "available", "pending", "locked", "trading" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatementLine" } } } } } } }, "400": { "description": "invalid_cursor | invalid_date | invalid_kind", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payins": { "post": { "tags": [ "PIX" ], "summary": "Create PIX cash-in", "operationId": "createPixPayin", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePixPayinRequest" } } } }, "responses": { "200": { "description": "Idempotency-Key replay of an existing payin.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "idempotency_key_required | invalid_amount_minor | currency_must_be_BRL | party_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "kyc_not_approved (until the workspace holder is KYC-approved, live and test)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "fee_schedule_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payins/{id}": { "get": { "tags": [ "PIX" ], "summary": "Get PIX cash-in", "operationId": "getPixPayin", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payins/{id}/simulate": { "post": { "tags": [ "PIX" ], "summary": "Simulate PIX cash-in settlement", "description": "Sandbox only.", "operationId": "simulatePixPayin", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateOutcomeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "not_a_payin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "simulate_only_in_sandbox | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payouts": { "post": { "tags": [ "PIX" ], "summary": "Create PIX cash-out", "operationId": "createPixPayout", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePixPayoutRequest" } } } }, "responses": { "200": { "description": "Idempotency-Key replay.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "201": { "description": "Dispatched (API-key one-call) or, for a saved-account session payout, initiated and awaiting confirm.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "202": { "description": "Provider outcome unknown; the hold stays and reconciliation closes it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "idempotency_key_required | pix_key_required | currency_must_be_BRL | invalid_payout_account_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_funds (or another hold-refusal reason)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "kyc_not_approved | payout_account_required | session_required | settlement_key_required | titularity_mismatch | trading_destination_mismatch | source_document_missing | workspace_frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "payout_account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "fee_exceeds_amount | pix_key_rejected | receiver_document_mismatch | destination_verification_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "payout_velocity: this party's payouts are blocked after repeated refusals", "headers": { "Retry-After": { "description": "Seconds until the block lifts.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_unavailable | provider_amount_mismatch | provider_rejected_*", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "fee_schedule_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Starts a PIX cash-out and debits the amount plus fee at once. With an API key the money goes to the workspace's registered settlement key, whatever `pix_key` says (`pix_key` is still required). A workspace with no settlement key gets 403 `settlement_key_required`; the owner registers one in the dashboard. Send `Idempotency-Key`: a retry with the same key returns the same payment and never pays twice. Errors: `insufficient_funds`, `pix_key_required`, `settlement_key_required`, `kyc_not_approved`, `workspace_frozen`, `payout_velocity`. Three refusals (`insufficient_funds` or `pix_key_rejected`) for one party within an hour block that party's payouts in the environment for 24 h: new requests answer 429 `payout_velocity` with `Retry-After`; a replay of a stored payout still returns it." } }, "/v1/{env}/pix/payouts/{id}": { "get": { "tags": [ "PIX" ], "summary": "Get PIX cash-out", "operationId": "getPixPayout", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payouts/{id}/simulate": { "post": { "tags": [ "PIX" ], "summary": "Simulate PIX cash-out settlement", "description": "Sandbox only.", "operationId": "simulatePixPayout", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateOutcomeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "not_a_payout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "simulate_only_in_sandbox | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payouts/{id}/confirm": { "post": { "tags": [ "PIX" ], "summary": "Confirm a saved-account PIX cash-out", "description": "Step 2 of the two-step payout: the customer reviewed the resolved receiver from the initiate call and now confirms. Dashboard session only (an API key gets 403 session_required); needs a fresh X-OTP-Code when the session has 2FA. Must run within 10 minutes of the initiate. A cash-out created with an API key needs no confirm. While the payer party's payouts are velocity-blocked the confirm answers 429 `payout_velocity` and the payout fails; start a new one after `Retry-After`.", "operationId": "confirmPixPayout", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/OtpHeader" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "402": { "description": "insufficient_funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "session_required | kyc_not_approved | workspace_frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "confirmation_expired | not_confirmable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "payout_velocity: this party's payouts are blocked after repeated refusals", "headers": { "Retry-After": { "description": "Seconds until the block lifts.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_rejected_*", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payouts/dict": { "post": { "tags": [ "PIX" ], "summary": "DICT key lookup", "description": "The provider has no standalone lookup; outside the mock provider this answers 501 — a payout resolves the receiver when it initiates.", "operationId": "pixDictLookup", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixDictLookupRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PixDictResult" } } } } } }, "400": { "description": "pix_key_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "dict_lookup_unsupported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payouts/fee": { "post": { "tags": [ "PIX" ], "summary": "Quote a PIX cash-out fee", "operationId": "pixPayoutFee", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPayoutFeeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PixFeeQuote" } } } } } }, "503": { "description": "fee_schedule_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payout-accounts": { "get": { "tags": [ "PIX" ], "summary": "List saved payout accounts", "operationId": "listPayoutAccounts", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutAccount" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "PIX" ], "summary": "Save a payout account", "description": "Dashboard session, owner/admin, with 2FA (fresh X-OTP-Code). Starts `unconfirmed`; the first withdrawal's initiate confirms it against the provider-resolved receiver.", "operationId": "createPayoutAccount", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutAccountRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PayoutAccount" } } } } } }, "400": { "description": "pix_key_required | invalid_pix_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | two_factor_required | source_document_missing | titularity_mismatch | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "payout_account_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/pix/payout-accounts/{id}": { "delete": { "tags": [ "PIX" ], "summary": "Remove a saved payout account", "description": "Soft delete. Dashboard session, owner/admin, with fresh X-OTP-Code.", "operationId": "deletePayoutAccount", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payout account id." }, { "$ref": "#/components/parameters/OtpHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/rfq/quote": { "post": { "tags": [ "RFQ" ], "summary": "Create an RFQ quote", "operationId": "createQuote", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqQuoteRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Quote" } } } } } }, "400": { "description": "invalid_amount_minor | party_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/rfq/execute": { "post": { "tags": [ "RFQ" ], "summary": "Execute an RFQ quote", "operationId": "executeQuote", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqExecuteRequest" } } } }, "responses": { "200": { "description": "Settled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RfqExecuteResult" } } } } } }, "202": { "description": "Processing; poll the payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RfqExecuteResult" } } } } } }, "400": { "description": "invalid_quote_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_trading_balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "quote_not_open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Spends the base currency from the `trading` balance and settles the bought currency into `trading`. Send BRL there first with `POST /trading/deposits`; move coins to your wallet with `POST /trading/crypto-withdrawals`." } }, "/v1/{env}/prices": { "get": { "tags": [ "Prices" ], "summary": "Get prices", "operationId": "getPrices", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated, e.g. `USDT,USDC`. Omit for every symbol the provider quotes." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Price" } } } } } }, "502": { "description": "provider_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/crypto/send": { "post": { "tags": [ "Crypto" ], "summary": "Send crypto", "description": "From one of the party's own wallets. X-OTP-Code is checked only when the caller is a 2FA dashboard session; a plain API-key call is never asked for it. With an API key the destination must be a wallet registered in the dashboard whitelist, whatever the amount; otherwise 403 `destination_not_whitelisted`.", "operationId": "createCryptoSend", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCryptoSendRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "202": { "description": "Provider outcome unknown; the hold stays for reconciliation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "to_address_required | invalid_address | currency_not_supported | from_address_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "insufficient_funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "from_address_not_owned | destination_not_whitelisted | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "provider_rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/crypto/send/{id}/simulate": { "post": { "tags": [ "Crypto" ], "summary": "Simulate crypto send completion", "description": "Sandbox only.", "operationId": "simulateCryptoSend", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateOutcomeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "400": { "description": "not_a_crypto_send", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "simulate_only_in_sandbox | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "already_terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/crypto/networks": { "get": { "tags": [ "Crypto" ], "summary": "List payable networks", "description": "Which networks the caller can currently send crypto from.", "operationId": "payableNetworks", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayableNetwork" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "operationId": "listCustomers", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "Workspace-level caller only; a customer-scoped key cannot create other parties.", "operationId": "createCustomer", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "400": { "description": "customer_create_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "operationId": "getCustomer", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Customer id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Workspace-level caller only.", "operationId": "updateCustomer", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Customer id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/kyc": { "get": { "tags": [ "KYC" ], "summary": "List KYC cases", "operationId": "listKycCases", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KycCase" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "KYC" ], "summary": "Create KYC case", "operationId": "createKycCase", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKycCaseRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KycCase" } } } } } }, "400": { "description": "kyc_create_failed | party_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/kyc/{id}": { "get": { "tags": [ "KYC" ], "summary": "Get KYC case", "operationId": "getKycCase", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "KYC case id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KycCase" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/kyc/{id}/rfi": { "get": { "tags": [ "KYC" ], "summary": "List RFI items", "description": "Compliance's requests for more information on this case.", "operationId": "listKycRfi", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "KYC case id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KycRfi" } } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "KYC" ], "summary": "Create RFI item", "operationId": "createKycRfi", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "KYC case id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKycRfiRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KycRfi" } } } } } }, "400": { "description": "field_name_required | rfi_create_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/onboarding/document": { "put": { "tags": [ "Onboarding" ], "summary": "Set the holder's CPF/CNPJ", "description": "Dashboard session, workspace owner only, `live` only (`test` answers 404). For a holder with no valid CPF/CNPJ for its kind: created before the document became mandatory at sign-up, or stored invalid (wrong check digits, or a CPF on a company). 11 valid digits make the holder a person (CPF), 14 a company (CNPJ). The same document already stored answers 200, so a retry is safe. Open before KYC approval; refused once approved. One document per holder counts only holders whose KYC was submitted or approved; sign-up never checks it.", "operationId": "setOnboardingDocument", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_number" ], "properties": { "document_number": { "type": "string", "description": "CPF or CNPJ digits; punctuation is ignored." } } } } } }, "responses": { "200": { "description": "The holder's onboarding state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "business" ] }, "kyc_status": { "type": "string" }, "document_type": { "type": "string", "enum": [ "cpf", "cnpj" ] }, "document_number": { "type": "string" }, "document_missing": { "type": "boolean", "description": "False once a valid CPF/CNPJ for the kind is stored." }, "required_slots": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "document_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_required | owner_admin_required | session_required | kyc_not_approved (an API key, before approval)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found (`test`) | party_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "document_in_use (another holder's KYC, submitted or later, has it; which one is never said; a not_started, pending or rejected holder with it does not count) | document_already_set (a different valid document is stored) | verification_locked (the holder's KYC is submitted, under review or awaiting an answer; the stored document is what staff review) | kyc_already_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/whitelist": { "get": { "tags": [ "Whitelist" ], "summary": "List whitelisted addresses", "operationId": "listWhitelist", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Whitelist" ], "summary": "Add a whitelisted address", "description": "Dashboard session, owner/admin, with 2FA (fresh X-OTP-Code) — a new destination is a money-out grant.", "operationId": "createWhitelist", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWhitelistRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhitelistEntry" } } } } } }, "400": { "description": "address_required | invalid_network | invalid_address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | two_factor_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/whitelist/settings": { "get": { "tags": [ "Whitelist" ], "summary": "Get whitelist enforcement setting", "operationId": "getWhitelistSettings", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhitelistSettings" } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Whitelist" ], "summary": "Set whitelist enforcement", "description": "Dashboard session, owner/admin, with 2FA (fresh X-OTP-Code). Turning it off reopens crypto sends to any address.", "operationId": "updateWhitelistSettings", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWhitelistSettingsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WhitelistSettings" } } } } } }, "400": { "description": "enabled_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | two_factor_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/whitelist/{id}": { "delete": { "tags": [ "Whitelist" ], "summary": "Remove a whitelisted address", "description": "Dashboard session, owner/admin. Unlike creating an entry, this route is not step-up gated — no fresh X-OTP-Code is required.", "operationId": "deleteWhitelist", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Whitelist entry id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/bank-accounts": { "get": { "tags": [ "BankAccounts" ], "summary": "List bank accounts", "operationId": "listBankAccounts", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "BankAccounts" ], "summary": "Create bank account", "description": "X-OTP-Code is checked only when the caller is a 2FA dashboard session; a plain API-key call is never asked for it.", "operationId": "createBankAccount", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankAccountRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BankAccount" } } } } } }, "400": { "description": "bank_account_create_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhooks", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "operationId": "createWebhook", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookCreateResponse" } } } } } }, "400": { "description": "invalid_webhook_url | webhook_create_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "operationId": "listWebhookDeliveries", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/webhooks/deliveries/{id}/resend": { "post": { "tags": [ "Webhooks" ], "summary": "Resend a webhook delivery", "description": "Sandbox only: replays the delivery as a fresh pending row.", "operationId": "resendWebhookDelivery", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Delivery id." } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "403": { "description": "resend_only_in_sandbox | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook endpoint", "operationId": "getWebhook", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook endpoint id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook endpoint", "operationId": "updateWebhook", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook endpoint id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "invalid_webhook_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook endpoint", "operationId": "deleteWebhook", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook endpoint id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Sandbox only; enqueues a test.ping delivery.", "operationId": "testWebhook", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook endpoint id." } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "boolean" }, "payload": { "type": "object" } } } } } } } }, "403": { "description": "test_only_in_sandbox | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "queue_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links": { "get": { "tags": [ "PaymentLinks" ], "summary": "List payment links", "operationId": "listPaymentLinks", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "PaymentLinks" ], "summary": "Create payment link", "operationId": "createPaymentLink", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "400": { "description": "invalid_amount_minor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "slug_taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links/payments": { "get": { "tags": [ "PaymentLinks" ], "summary": "List checkout payments", "operationId": "listCheckoutPayments", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Page size, 1..100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`|` of the last row of the previous page." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "link_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One of the payment statuses." }, { "name": "payer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A CPF/CNPJ matches by hash; anything else searches the payer name." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "invalid_date | invalid_link_id | invalid_status | invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links/stats": { "get": { "tags": [ "PaymentLinks" ], "summary": "Checkout KPIs", "operationId": "checkoutStats", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "link_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payer", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "invalid_date | invalid_link_id | invalid_status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "stats_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links/{id}": { "get": { "tags": [ "PaymentLinks" ], "summary": "Get payment link", "operationId": "getPaymentLink", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "PaymentLinks" ], "summary": "Update payment link", "operationId": "updatePaymentLink", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentLinkRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "price_required_for_fixed_amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "PaymentLinks" ], "summary": "Delete payment link", "operationId": "deletePaymentLink", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links/{id}/splits": { "get": { "tags": [ "PaymentLinks" ], "summary": "List revenue splits", "operationId": "listLinkSplits", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLinkSplit" } } } } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "PaymentLinks" ], "summary": "Replace revenue splits", "description": "Replaces the whole split set. The set in force when a buyer is charged travels with that payment, so editing later cannot change who a pending PIX pays at settle.", "operationId": "replaceLinkSplits", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceLinkSplitsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLinkSplit" } } } } } } }, "400": { "description": "splits_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "share_must_be_positive | splits_exceed_whole | recipient_label_required | split_party_not_owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/payment-links/{id}/charges": { "post": { "tags": [ "PaymentLinks" ], "summary": "Open a PIX charge on a payment link", "description": "The merchant's own backend opening a charge on its own checkout (gateway-style integration), as opposed to the public buyer-facing pay route.", "operationId": "createCheckoutCharge", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Payment link id." }, { "$ref": "#/components/parameters/SubaccountHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutChargeRequest" } } } }, "responses": { "200": { "description": "Idempotency-Key replay.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CheckoutPaymentResult" } } } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CheckoutPaymentResult" } } } } } }, "400": { "description": "idempotency_key_required | payer_document_required | amount_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "payment_link_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_payer_document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "workspace_entity_missing | provider_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/checkout/{slug}": { "get": { "tags": [ "Checkout" ], "summary": "Public checkout page data", "description": "No credential required: the slug itself is the capability, and only an active link is readable.", "operationId": "getPublicCheckout", "security": [], "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment link slug." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PublicCheckout" } } } } } }, "404": { "description": "payment_link_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/checkout/{slug}/pay": { "post": { "tags": [ "Checkout" ], "summary": "Pay a checkout", "description": "Public buyer-facing pay — no credential required. Rate-limited to 3 attempts per minute per payer document per slug.", "operationId": "checkoutPay", "security": [], "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment link slug." }, { "$ref": "#/components/parameters/IdempotencyKeyOptional" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutPayRequest" } } } }, "responses": { "200": { "description": "Idempotency-Key replay.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CheckoutPaymentResult" } } } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CheckoutPaymentResult" } } } } } }, "400": { "description": "payer_document_required | amount_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "payment_link_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "slug_ambiguous", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_payer_document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "workspace_entity_missing | provider_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/subaccounts": { "get": { "tags": [ "SubAccounts" ], "summary": "List sub-accounts", "operationId": "listSubAccounts", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubAccount" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "SubAccounts" ], "summary": "Create sub-account", "description": "Workspace-level API key, or dashboard session owner/admin. One level only — a sub-account cannot itself have a sub-account.", "operationId": "createSubAccount", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubAccountRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccount" } } } } } }, "400": { "description": "display_name_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "party_scope_limited | owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "subaccount_of_subaccount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/subaccounts/{id}": { "get": { "tags": [ "SubAccounts" ], "summary": "Get sub-account", "operationId": "getSubAccount", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sub-account (child workspace) id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubAccount" } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/subaccounts/{id}/balances": { "get": { "tags": [ "SubAccounts" ], "summary": "Sub-account balances", "operationId": "subAccountBalances", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sub-account id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/subaccounts/{id}/transactions": { "get": { "tags": [ "SubAccounts" ], "summary": "Sub-account transactions", "operationId": "subAccountTransactions", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Sub-account id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size, 1..200 (default 50)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/api-keys": { "get": { "tags": [ "ApiKeys" ], "summary": "List API keys", "description": "Never returns key material.", "operationId": "listApiKeys", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "ApiKeys" ], "summary": "Create API key", "description": "Dashboard session only (an API key cannot mint another); owner/admin with fresh X-OTP-Code when 2FA is enabled. The secret is returned exactly once.", "operationId": "createApiKey", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeySecretResponse" } } } } } }, "400": { "description": "name_required | invalid_allowed_ips | invalid_permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "api_key_create_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/api-keys/audit": { "get": { "tags": [ "ApiKeys" ], "summary": "List API key audit events", "operationId": "listApiKeyAudit", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Page size, 1..500 (default 100)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyAuditEntry" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/api-keys/{id}": { "patch": { "tags": [ "ApiKeys" ], "summary": "Update API key", "description": "Dashboard session only; owner/admin with fresh X-OTP-Code when 2FA is enabled.", "operationId": "updateApiKey", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "API key id." }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "400": { "description": "nothing_to_update | invalid_allowed_ips | invalid_permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "ApiKeys" ], "summary": "Revoke API key", "description": "Dashboard session only, owner/admin. Not step-up gated — no fresh X-OTP-Code is required, unlike create/update/rotate.", "operationId": "revokeApiKey", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "API key id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKey" } } } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/api-keys/{id}/rotate": { "post": { "tags": [ "ApiKeys" ], "summary": "Rotate API key", "description": "Issues a new secret with the same settings; the old one stops working in the same statement. Dashboard session only, owner/admin, fresh X-OTP-Code when 2FA is enabled.", "operationId": "rotateApiKey", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "API key id." }, { "$ref": "#/components/parameters/OtpHeader" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApiKeySecretResponse" } } } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/settings": { "get": { "tags": [ "Settings" ], "summary": "Get workspace settings", "operationId": "getWorkspaceSettings", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceSettings" } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Settings" ], "summary": "Update workspace settings", "description": "Dashboard session only, owner/admin, fresh X-OTP-Code when 2FA is enabled. Deep-merges `settings`; never replaces the document. Feature flags are not here (staff-only).", "operationId": "updateWorkspaceSettings", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/OtpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceSettingsRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceSettings" } } } } } }, "400": { "description": "settings_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "owner_admin_required | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List in-app notifications", "operationId": "listNotifications", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "4XX": { "description": "See the operation description for the `error` codes this route returns, plus the shared 401/403/429 codes from Authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Upstream/provider failure; `error` is one of the codes named in the operation description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/team": { "get": { "tags": [ "Team" ], "summary": "List team members", "operationId": "listTeam", "description": "Members with role and status. Invites and role changes stay in the dashboard (they need the member's own 2FA). Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/workflows": { "get": { "tags": [ "Workflows" ], "summary": "List workflows", "operationId": "listWorkflows", "description": "Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Workflows" ], "summary": "Create a workflow", "operationId": "createWorkflow", "description": "`name` is required. Pass a full `definition`, or `trigger` (default `manual`) and `steps`. Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "definition": { "type": "object", "additionalProperties": true } } } } } } } }, "/v1/{env}/workflows/runs": { "get": { "tags": [ "Workflows" ], "summary": "List workflow runs", "operationId": "listWorkflowRuns", "description": "Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/approvals": { "get": { "tags": [ "Approvals" ], "summary": "List approval requests", "operationId": "listApprovals", "description": "Pending and decided four-eyes requests. Voting needs a member's session and 2FA, so it is not on the API. Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/approval-policy": { "get": { "tags": [ "Approvals" ], "summary": "Get the approval policy", "operationId": "getApprovalPolicy", "description": "Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/treasury": { "get": { "tags": [ "Treasury" ], "summary": "List treasury wallets", "operationId": "listTreasuryWallets", "description": "Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Treasury" ], "summary": "Register a treasury wallet", "operationId": "createTreasuryWallet", "description": "`address` is required; `network` defaults to polygon. Workspace-level keys only; a customer-scoped key gets 403 `party_scope_limited`.", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "party_scope_limited | kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "network": { "type": "string" }, "label": { "type": "string" } } } } } } } }, "/v1/{env}/trading/summary": { "get": { "tags": [ "Trading" ], "summary": "Trading balance", "description": "BRL in the trading balance (the pooled exchange account) and how much of it can be withdrawn now. Coins bought by a conversion also sit in `trading`; see `GET /balances` (kind `trading`).", "operationId": "getTradingSummary", "parameters": [ { "$ref": "#/components/parameters/EnvPath" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TradingSummary" } } } } } } } } }, "/v1/{env}/trading/deposits": { "post": { "tags": [ "Trading" ], "summary": "Send BRL to trading", "description": "Moves BRL from `available` to `trading` with a PIX to the exchange account. The destination is fixed by the platform; any `pix_key` sent is ignored. Conversions (`/rfq/execute`) spend BRL from `trading`, so send it here first. Live money-out needs the party KYC approved.", "operationId": "createTradingDeposit", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_minor" ], "properties": { "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units." } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "402": { "description": "insufficient_funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "account_temporarily_locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "trading_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/trading/withdrawals": { "post": { "tags": [ "Trading" ], "summary": "Withdraw BRL from trading", "description": "Moves BRL from `trading` back to `available` (exchange account → your account). Minimum R$ 10,00. Capped by `withdrawable_minor`; five refused attempts in 24 h lock trading money-out temporarily.", "operationId": "createTradingWithdrawal", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_minor" ], "properties": { "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units." } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "403": { "description": "kyc_not_approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "trading_under_review | idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "below_minimum | exceeds_withdrawable | invalid_amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "account_temporarily_locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "trading_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/{env}/trading/crypto-withdrawals": { "post": { "tags": [ "Trading" ], "summary": "Withdraw stablecoins from trading to your wallet", "description": "Moves USDT/USDC bought by a conversion from `trading` to the party's own wallet on `network`, where it becomes `available`. No fee. Minimum 5.00 gross (7.8 on Tron). The party needs a wallet on that network.", "operationId": "createTradingCryptoWithdrawal", "parameters": [ { "$ref": "#/components/parameters/EnvPath" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_minor" ], "properties": { "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Gross amount in the coin's minor units (scale 6)." }, "currency": { "type": "string", "enum": [ "USDT", "USDC" ], "default": "USDT" }, "network": { "type": "string", "default": "polygon", "description": "e.g. polygon, ethereum, tron." } } } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "402": { "description": "insufficient_trading_balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "network_not_supported | amount_below_minimum | wallet_required | wallet_network_mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "account_temporarily_locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "trading_withdrawal_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "trading_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "payment.completed": { "post": { "tags": [ "Webhooks" ], "summary": "payment.completed", "description": "Sent when a PIX payin/payout, crypto send, or RFQ settlement reaches status completed. Signed with HMAC-SHA256: the endpoint's secret signs the string `${x-clarian-timestamp}.${raw request body}`; the hex digest is sent as `x-clarian-signature`. Verify by recomputing the HMAC over the exact bytes received and comparing with a constant-time check. `x-clarian-timestamp` is the send time of this attempt (ISO-8601), so a retry carries a fresh one; the body's `created_at` stays the event time; `x-clarian-event` repeats the event type. The JSON body is `{id, type, created_at, data}`, where `data` is the payload below. Delivery retries on a non-2xx response.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.completed", "payment.failed" ] }, "payment_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "pix_in | pix_out | crypto_send | convert, etc." }, "status": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units, as a string." }, "currency": { "type": "string" }, "payment_link_id": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false } } } ] } } } }, "responses": { "200": { "description": "Any 2xx response marks the delivery as delivered." } } } }, "payment.failed": { "post": { "tags": [ "Webhooks" ], "summary": "payment.failed", "description": "Sent when a payment reaches status failed. Signed with HMAC-SHA256: the endpoint's secret signs the string `${x-clarian-timestamp}.${raw request body}`; the hex digest is sent as `x-clarian-signature`. Verify by recomputing the HMAC over the exact bytes received and comparing with a constant-time check. `x-clarian-timestamp` is the send time of this attempt (ISO-8601), so a retry carries a fresh one; the body's `created_at` stays the event time; `x-clarian-event` repeats the event type. The JSON body is `{id, type, created_at, data}`, where `data` is the payload below. Delivery retries on a non-2xx response.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment.completed", "payment.failed" ] }, "payment_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "pix_in | pix_out | crypto_send | convert, etc." }, "status": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units, as a string." }, "currency": { "type": "string" }, "payment_link_id": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false } } } ] } } } }, "responses": { "200": { "description": "Any 2xx response marks the delivery as delivered." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cl_{test|live}_sk_...", "description": "`Authorization: Bearer cl_test_sk_...` (sandbox) or `Bearer cl_live_sk_...` (live). A live key additionally needs production enabled by the workspace owner. Using a live key against the sandbox path revokes it on sight (leak signal); a sandbox key on live is refused and logged, but not revoked." }, "WorkspaceIdHeader": { "type": "apiKey", "in": "header", "name": "X-Workspace-Id", "description": "The workspace (tenant) UUID. Always required, including on session-authenticated dashboard calls." } }, "parameters": { "EnvPath": { "name": "env", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "sandbox", "live" ] }, "description": "`test` is also accepted on the wire as an alias of `sandbox`; the key prefix must match (cl_test_sk_ for sandbox/test, cl_live_sk_ for live)." }, "SubaccountHeader": { "name": "X-Subaccount-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Wallet-as-a-service: act on one of the caller's own sub-accounts (its ledger, parties and wallets) instead of the workspace itself. Only valid on balances/wallets/transactions/statement/crypto/pix/payment-links/rfq routes, only for a workspace-level caller (not a party-scoped key), and only for a sub-account the caller's workspace owns." }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required. The same key with the same request body replays the stored result; the same key with a different body is 409 idempotency_key_reuse." }, "IdempotencyKeyOptional": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional here. When sent, the same key with the same request body replays the stored result; a different body is 409 idempotency_key_reuse." }, "OtpHeader": { "name": "X-OTP-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A fresh TOTP code. Required only when the caller authenticated with a dashboard session (Better Auth cookie) that has two-factor enabled; ignored for a plain API-key call, which this step-up check never sees. Missing/invalid returns 422 {\"error\":\"otp_required\"|\"otp_invalid\"} (or passkey_required/passkey_invalid for a passkey-step-up account)." } }, "schemas": { "Error": { "type": "object", "description": "Every error from this API has this exact shape (`Http.err` / `Http.errMsg`).", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code, e.g. `invalid_amount_minor`." }, "message": { "type": "string", "description": "Present only on a subset of errors; human-readable detail." } }, "additionalProperties": false }, "Payment": { "type": "object", "description": "A payment intent / ledger-facing operation: a PIX cash-in or cash-out, a crypto send, or an RFQ settlement. Exact fields vary by `kind`.", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid", "description": "The customer (or workspace entity) this payment belongs to." }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "kind": { "type": "string", "description": "pix_in | pix_out | crypto_send | convert (RFQ) — other internal kinds may appear." }, "status": { "type": "string", "enum": [ "created", "pending", "processing", "awaiting_funds", "completed", "failed", "cancelled", "expired" ] }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units, as a string (BRL scale 2; USDT/USDC scale 6)." }, "currency": { "type": "string" }, "fee_minor": { "type": "string", "pattern": "^[0-9]+$", "nullable": true, "description": "Fee in the payment currency's minor units, as a string." }, "description": { "type": "string", "nullable": true }, "provider_ref": { "type": "string", "nullable": true }, "pix_qr_code": { "type": "string", "nullable": true }, "pix_tx_id": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "to_address": { "type": "string", "nullable": true }, "network": { "type": "string", "nullable": true }, "tx_hash": { "type": "string", "nullable": true }, "failure_reason": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "idempotency_key": { "type": "string", "nullable": true }, "counterparty": { "type": "object", "nullable": true }, "pix_txid": { "type": "string", "nullable": true }, "from_address": { "type": "string", "nullable": true }, "wallet_id": { "type": "string", "format": "uuid", "nullable": true }, "source_currency": { "type": "string", "nullable": true }, "target_currency": { "type": "string", "nullable": true }, "exchange_rate": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "quote_id": { "type": "string", "format": "uuid", "nullable": true }, "related_payment_id": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": true }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "network": { "type": "string", "description": "e.g. polygon, base, ethereum, tron, solana." }, "address": { "type": "string" }, "is_primary": { "type": "boolean" }, "provider_ref": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "Customer": { "type": "object", "description": "A party of kind customer. Fields mirror CreateCustomerRequest plus server-assigned ones.", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "person", "business" ] }, "display_name": { "type": "string" }, "legal_name": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "status": { "type": "string" }, "kyc_status": { "type": "string" }, "external_id": { "type": "string", "nullable": true }, "payout_mode": { "type": "string", "nullable": true }, "payout_asset": { "type": "string", "nullable": true }, "payout_wallet_address": { "type": "string", "nullable": true }, "payout_wallet_network": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "KycCase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "type": "string" }, "provider_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "KycRfi": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kyc_case_id": { "type": "string", "format": "uuid" }, "field_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "WhitelistEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "party_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Absent/null = workspace-wide entry." }, "network": { "type": "string" }, "address": { "type": "string" }, "label": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" } }, "additionalProperties": true }, "WhitelistSettings": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "When true, a crypto send may only target an address already on the whitelist." }, "unlistedMaxUsdCents": { "type": "integer", "nullable": true, "description": "USD cents. A single send at or under it may go to an address off the list; null = none." } }, "additionalProperties": false }, "BankAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "bank_code": { "type": "string", "nullable": true }, "branch": { "type": "string", "nullable": true }, "account_number": { "type": "string", "nullable": true }, "account_digit": { "type": "string", "nullable": true }, "account_type": { "type": "string", "nullable": true }, "holder_name": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "pix_key": { "type": "string", "nullable": true }, "pix_key_type": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "PayoutAccount": { "type": "object", "description": "A saved PIX withdrawal destination. Starts `unconfirmed`; the first payout initiate confirms it.", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "pix_key": { "type": "string" }, "key_type": { "type": "string", "description": "cpf | cnpj | email | phone | randomKey." }, "label": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "unconfirmed", "confirmed" ] }, "name_masked": { "type": "string", "nullable": true }, "document_masked": { "type": "string", "nullable": true }, "bank": { "type": "string", "nullable": true }, "ispb": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "url": { "type": "string", "format": "uri" }, "events": { "type": "string", "description": "Comma-separated event types, or `*` for every event." }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "WebhookCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret, in cleartext. Shown exactly once — there is no route that reads it back." } } } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "endpoint_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "event_type": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": "integer", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "party_id": { "type": "string", "format": "uuid", "nullable": true }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "0 when the link has no fixed price (open-amount)." }, "currency": { "type": "string" }, "allow_custom_amount": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "design": { "type": "object", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "title": { "type": "string", "nullable": true }, "metadata": { "type": "object" } }, "additionalProperties": true }, "PaymentLinkSplit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "payment_link_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid", "nullable": true }, "recipient_label": { "type": "string" }, "share_bps": { "type": "integer", "description": "Basis points of the charge; every link's shares sum to at most 10000." } }, "additionalProperties": true }, "SubAccount": { "type": "object", "description": "A child workspace (wallet-as-a-service tenant). One level only — a sub-account cannot have its own sub-account.", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_workspace_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "legal_name": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "party_id": { "type": "string", "format": "uuid" }, "settings": { "type": "object" } }, "additionalProperties": true }, "ApiKey": { "type": "object", "description": "Never carries the secret — only the hash is stored; `key_prefix` is shown for the owner to tell keys apart.", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "name": { "type": "string" }, "key_prefix": { "type": "string", "description": "First 14 characters of the secret, e.g. `cl_live_sk_abc1`." }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "IPs/CIDRs; empty = no IP restriction." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Resource scopes (see `permissionResources`); empty = full access." }, "is_active": { "type": "boolean" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "prefix": { "type": "string" }, "scope": { "type": "string" }, "production_enabled": { "type": "boolean" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_count": { "type": "integer" } }, "additionalProperties": true }, "ApiKeySecretResponse": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "type": "string", "description": "The raw key (e.g. `cl_live_sk_...`). Shown exactly once." } }, "additionalProperties": false }, "ApiKeyAuditEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": "string", "format": "uuid", "nullable": true }, "event": { "type": "string", "description": "e.g. api_key.created, api_key.updated, api_key.rotated, api_key.revoked, workspace_mismatch, prod_key_on_sandbox_revoked, prod_key_on_sandbox_replay, api_key_sandbox_on_production." }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "api_key_name": { "type": "string" }, "prefix": { "type": "string" }, "event_type": { "type": "string" }, "ip": { "type": "string", "nullable": true } }, "additionalProperties": true }, "WorkspaceSettings": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "settings": { "type": "object", "description": "Freeform, workspace-chosen preferences. Feature flags are not here (staff-only)." }, "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "feature_flags": { "type": "object" }, "country": { "type": "string", "nullable": true }, "status": { "type": "string" } }, "additionalProperties": true }, "StatementLine": { "type": "object", "description": "One ledger posting on the workspace's own accounts (intercompany/system accounts excluded).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Posting id." }, "journal_id": { "type": "string", "format": "uuid" }, "reference_type": { "type": "string", "nullable": true }, "reference_id": { "type": "string", "nullable": true }, "posted_at": { "type": "string", "format": "date-time" }, "party_id": { "type": "string", "format": "uuid", "nullable": true }, "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "available", "pending", "locked", "trading" ] }, "scale": { "type": "integer", "description": "Currency's decimal scale (BRL 2, USDT/USDC 6)." }, "direction": { "type": "string", "enum": [ "debit", "credit" ], "description": "From the customer's point of view: a debit raises their balance." }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units, always positive; `direction` carries the sign." } }, "additionalProperties": false }, "Balance": { "type": "object", "description": "One ledger balance bucket (currency x kind) for the caller's workspace or party.", "properties": { "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "available", "pending", "locked", "trading" ] }, "party_id": { "type": "string", "format": "uuid" }, "balance_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units, as a string. Divide by 10^scale to display." }, "scale": { "type": "integer", "description": "Decimal places of the currency: BRL 2, USDT/USDC 6, BTC/ETH 8." } }, "additionalProperties": true, "required": [ "currency", "kind", "balance_minor", "scale" ] }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "PayableNetwork": { "type": "object", "description": "A network the caller can currently send crypto from (gas and provider support considered).", "properties": { "network": { "type": "string" }, "payable": { "type": "boolean" }, "treasury_ready": { "type": "boolean" } }, "additionalProperties": true }, "Price": { "type": "object", "description": "Provider-sourced quote for one symbol. Shape is provider-defined; keys below are typical.", "properties": { "symbol": { "type": "string" }, "price": { "type": "string" } }, "additionalProperties": true }, "Quote": { "type": "object", "description": "An RFQ quote. `quote_id`/`id` is what POST /rfq/execute takes back.", "properties": { "id": { "type": "string", "format": "uuid" }, "quote_id": { "type": "string", "format": "uuid" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "base_currency": { "type": "string" }, "quote_currency": { "type": "string" }, "base_amount_minor": { "type": "string" }, "quote_amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "What you receive, in quote_currency minor units, after fees." }, "rate": { "type": "string", "description": "Decimal rate as a string, quote units per base unit." }, "status": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string", "format": "uuid" }, "party_id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "spread_bps": { "type": "integer" }, "fee_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Total fee, in fee_currency minor units (spread plus fixed fee)." }, "fee_currency": { "type": "string" }, "fixed_fee_minor": { "type": "string", "pattern": "^[0-9]+$" }, "fill_price": { "type": "number", "nullable": true }, "executed_payment_id": { "type": "string", "format": "uuid", "nullable": true }, "executed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "PixFeeQuote": { "type": "object", "description": "What a PIX withdrawal costs before sending — the same schedule the actual payout holds.", "properties": { "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Echoes the requested amount." }, "fee_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "The fee for this amount, under the workspace's PIX-out schedule." }, "debit_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "What the ledger locks: amount plus fee when the merchant bears it." }, "sent_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "What is actually sent to the receiver: amount minus fee when the payer bears it." }, "max_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "The largest amount_minor whose debit still fits budget_minor, if that was sent." } }, "additionalProperties": false }, "PixDictResult": { "type": "object", "description": "DICT key resolution. The provider has no standalone lookup endpoint — this answers 501 dict_lookup_unsupported outside the mock provider; a real payout resolves the receiver when it initiates instead.", "additionalProperties": true, "properties": { "pix_key": { "type": "string" }, "holder_name": { "type": "string" }, "document_masked": { "type": "string" }, "bank_name": { "type": "string" }, "bank_code": { "type": "string" }, "account_type": { "type": "string" } } }, "PublicCheckout": { "type": "object", "description": "What an unauthenticated buyer page may see about a payment link.", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "0 for an open-amount link." }, "currency": { "type": "string" }, "allow_custom_amount": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "design": { "type": "object", "nullable": true }, "status": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "title": { "type": "string", "nullable": true }, "merchant_name": { "type": "string" } }, "additionalProperties": true }, "CheckoutPaymentResult": { "type": "object", "properties": { "payment_link_id": { "type": "string", "format": "uuid", "nullable": true }, "payment": { "$ref": "#/components/schemas/Payment" } }, "additionalProperties": false }, "CreateWalletRequest": { "type": "object", "properties": { "network": { "type": "string", "default": "polygon", "description": "polygon | base | ethereum | tron | solana, etc. Accepts `wallet_name`/`walletName` and `is_primary`/`isPrimary` aliases too." }, "address": { "type": "string", "description": "Only when the caller supplies its own key material; otherwise one is provisioned." }, "wallet_name": { "type": "string" }, "is_primary": { "type": "boolean", "default": false }, "party_id": { "type": "string", "format": "uuid", "description": "Required unless the key is already party-scoped or the workspace has one default entity party." } }, "additionalProperties": true }, "CreatePixPayinRequest": { "type": "object", "required": [ "amount_minor" ], "properties": { "amount_minor": { "description": "Integer minor units (BRL scale 2). A JSON number or a digit string.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "currency": { "type": "string", "default": "BRL", "description": "Only BRL is accepted; anything else is `currency_must_be_BRL`." }, "party_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "idempotency_key": { "type": "string", "description": "Alternative to the `Idempotency-Key` header." } }, "additionalProperties": true }, "SimulateOutcomeRequest": { "type": "object", "description": "Sandbox only. Any body other than `{\"status\":\"failed\"}` settles the payment as completed.", "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ], "default": "completed" }, "reason": { "type": "string", "description": "Stored as failure_reason when status is failed." }, "tx_hash": { "type": "string", "description": "Crypto send only; a mock hash is generated when omitted." } }, "additionalProperties": true }, "CreatePixPayoutRequest": { "type": "object", "description": "A session (dashboard) caller must supply `payout_account_id` — this call only initiates and shows the resolved receiver; confirm with POST /pix/payouts/{id}/confirm. An API-key caller must omit `payout_account_id` and supply `pix_key` directly; that single call holds and pays.", "required": [ "amount_minor" ], "properties": { "amount_minor": { "description": "Integer minor units (BRL scale 2).", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "currency": { "type": "string", "default": "BRL" }, "pix_key": { "type": "string", "description": "Required unless `payout_account_id` is given (session callers) or the workspace is pinned to a settlement key." }, "payout_account_id": { "type": "string", "format": "uuid", "description": "Session callers only; selects a saved PayoutAccount." }, "party_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "receiver_name": { "type": "string", "description": "Checked against the provider-resolved receiver; a mismatch on name is not enforced, only on document." }, "receiver_document": { "type": "string", "description": "CPF/CNPJ the caller expects to receive; mismatch with the resolved receiver is `receiver_document_mismatch`." }, "pix_key_type": { "type": "string", "description": "Used only to match an approval-gate request, not validated server-side here." }, "approval_id": { "type": "string", "format": "uuid", "description": "Links this payout to a previously approved multisig request." } }, "additionalProperties": true }, "PixDictLookupRequest": { "type": "object", "required": [ "pix_key" ], "properties": { "pix_key": { "type": "string" } }, "additionalProperties": true }, "PixPayoutFeeRequest": { "type": "object", "description": "Both fields are optional digit amounts; omit either to get a 0 for it.", "properties": { "amount_minor": { "description": "The amount a withdrawal would send.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "budget_minor": { "description": "The most the customer can debit; used to compute max_minor.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] } }, "additionalProperties": true }, "CreatePayoutAccountRequest": { "type": "object", "required": [ "pix_key" ], "properties": { "pix_key": { "type": "string", "description": "Any PIX key type; a document key must be the party's own CPF/CNPJ." }, "label": { "type": "string", "description": "Trimmed and capped at 60 characters." }, "party_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "RfqQuoteRequest": { "type": "object", "required": [ "base_amount_minor" ], "properties": { "base_amount_minor": { "description": "Integer minor units of base_currency.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "side": { "type": "string", "enum": [ "buy", "sell" ], "deprecated": true, "description": "Ignored. Recorded on the quote for reference only; the direction is always base_currency to quote_currency." }, "base_currency": { "type": "string", "default": "BRL" }, "quote_currency": { "type": "string", "default": "USDT" }, "party_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true, "description": "You pay `base_amount_minor` of `base_currency` and receive `quote_currency`. To buy USDT with BRL: base BRL, quote USDT. To sell USDT for BRL: base USDT, quote BRL." }, "RfqExecuteRequest": { "type": "object", "required": [ "quote_id" ], "properties": { "quote_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "CreateCryptoSendRequest": { "type": "object", "required": [ "amount_minor", "to_address" ], "properties": { "amount_minor": { "description": "Integer minor units of currency (USDT/USDC scale 6).", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "to_address": { "type": "string", "description": "Must fit the target network's address shape; cross-chain addresses are refused." }, "network": { "type": "string", "default": "polygon" }, "currency": { "type": "string", "default": "USDT" }, "from_address": { "type": "string", "description": "Must be one of the party's own wallets on `network`; omit to use its only wallet there." }, "party_id": { "type": "string", "format": "uuid" }, "description": { "type": "string" } }, "additionalProperties": true }, "CreateCustomerRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "business" ], "default": "person" }, "display_name": { "type": "string", "default": "Customer" }, "legal_name": { "type": "string" }, "document_type": { "type": "string" }, "document_number": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "external_id": { "type": "string" }, "metadata": { "type": "object" }, "payout_mode": { "type": "string" }, "payout_asset": { "type": "string" }, "payout_wallet_address": { "type": "string" }, "payout_wallet_network": { "type": "string", "description": "Only kept when it is one of the supported networks." } }, "additionalProperties": true }, "UpdateCustomerRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "status": { "type": "string", "description": "One of the valid party statuses." }, "external_id": { "type": "string" }, "metadata": { "type": "object" } }, "additionalProperties": true }, "CreateKycCaseRequest": { "type": "object", "properties": { "party_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "CreateKycRfiRequest": { "type": "object", "required": [ "field_name" ], "properties": { "field_name": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true }, "CreateWhitelistRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "network": { "type": "string", "default": "polygon" }, "label": { "type": "string" }, "party_id": { "type": "string", "format": "uuid", "description": "Omit for a workspace-wide entry." } }, "additionalProperties": true }, "UpdateWhitelistSettingsRequest": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "CreateBankAccountRequest": { "type": "object", "properties": { "bank_code": { "type": "string" }, "branch": { "type": "string" }, "account_number": { "type": "string" }, "account_digit": { "type": "string" }, "account_type": { "type": "string" }, "holder_name": { "type": "string" }, "document_number": { "type": "string" }, "pix_key": { "type": "string" }, "pix_key_type": { "type": "string" }, "is_default": { "type": "boolean", "default": false }, "party_id": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "https in production; http allowed only outside production. A private/loopback/link-local host (checked by string AND by resolved DNS at delivery time) is refused." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to receive; omit or send empty for every event (`*`)." }, "description": { "type": "string" } }, "additionalProperties": true }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "description": { "type": "string" } }, "additionalProperties": true }, "CreatePaymentLinkRequest": { "type": "object", "description": "Either a fixed amount_minor, or allow_custom_amount=true for an open-amount page the buyer prices.", "properties": { "amount_minor": { "description": "Required unless allow_custom_amount is true.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "allow_custom_amount": { "type": "boolean", "default": false }, "currency": { "type": "string", "default": "BRL" }, "description": { "type": "string" }, "slug": { "type": "string", "description": "Globally unique across every merchant; a random one is generated when omitted." }, "expires_at": { "type": "string", "format": "date-time" }, "party_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object" } }, "additionalProperties": true }, "UpdatePaymentLinkRequest": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "allow_custom_amount": { "type": "boolean", "description": "Flipping to false on a link with no fixed price fails with price_required_for_fixed_amount." }, "design": { "type": "object" } }, "additionalProperties": true }, "ReplaceLinkSplitsRequest": { "type": "object", "required": [ "splits" ], "properties": { "splits": { "type": "array", "items": { "type": "object", "required": [ "recipient_label", "share_bps" ], "properties": { "party_id": { "type": "string", "format": "uuid", "description": "Must already belong to the workspace when present." }, "recipient_label": { "type": "string" }, "share_bps": { "type": "integer", "minimum": 1, "description": "Basis points; the set's total must not exceed 10000." } }, "additionalProperties": true } } }, "additionalProperties": false }, "CreateCheckoutChargeRequest": { "type": "object", "required": [ "payer_document" ], "properties": { "payer_document": { "type": "string", "description": "CPF or CNPJ, any formatting; validated as a real document number." }, "payer_name": { "type": "string" }, "amount_minor": { "description": "Required (and only used) on an open-amount link; a fixed-price link always charges its own price.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "email": { "type": "string" } }, "additionalProperties": true }, "CheckoutPayRequest": { "type": "object", "required": [ "payer_document" ], "properties": { "payer_document": { "type": "string", "description": "CPF or CNPJ, any formatting; validated as a real document number." }, "payer_name": { "type": "string" }, "amount_minor": { "description": "Required (and only used) on an open-amount link.", "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,16}$" }, { "type": "integer", "minimum": 1 } ] }, "email": { "type": "string" } }, "additionalProperties": true }, "CreateSubAccountRequest": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "type": "string" }, "legal_name": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": true }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "Plain IPs or CIDR ranges (IPv4/IPv6). Empty/omitted = no IP restriction." }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Resources this key may call, e.g. [\"pix\", \"wallets:read\"]. Empty/omitted = full access." } }, "additionalProperties": false }, "UpdateApiKeyRequest": { "type": "object", "description": "At least one of name, allowed_ips, permissions must be present.", "properties": { "name": { "type": "string" }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "UpdateWorkspaceSettingsRequest": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "object", "description": "Merged (deep patch) into the stored settings; never replaces the whole document." } }, "additionalProperties": false }, "RfqExecuteResult": { "type": "object", "properties": { "quote_id": { "type": "string", "format": "uuid" }, "payment": { "$ref": "#/components/schemas/Payment" }, "status": { "type": "string", "enum": [ "processing" ], "description": "Only on 202; poll the payment." }, "ledger": { "type": "object", "description": "Only on 200 (settled).", "properties": { "from_journal_id": { "type": "string" }, "to_journal_id": { "type": "string" }, "from_currency": { "type": "string" }, "to_currency": { "type": "string" }, "from_minor": { "type": "string" }, "to_minor": { "type": "string" } } } } }, "TradingSummary": { "type": "object", "required": [ "currency", "scale", "trading_minor", "withdrawable_minor", "under_review", "locked_until" ], "properties": { "currency": { "type": "string", "enum": [ "BRL" ] }, "scale": { "type": "integer" }, "trading_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "Integer minor units." }, "withdrawable_minor": { "type": "string", "pattern": "^[0-9]+$", "description": "BRL that can leave trading now; 0 while under review." }, "under_review": { "type": "boolean", "description": "Ledger and provider proofs disagree: trading withdrawals are frozen." }, "locked_until": { "type": [ "string", "null" ], "format": "date-time" } } } } } }