{ "openapi": "3.1.0", "info": { "title": "Settlane API", "version": "1.0.0", "description": "The Settlane merchant API: take stablecoin payments (USDT on Tron, USDC on Ethereum) and pay out USDT, without holding a private key.\n\n**Authentication.** Every `/v1` call sends `Authorization: Bearer `. A key starts `sk_live_` or `sk_test_`. Keep it on your server.\n\n**Live and test mode.** A `sk_test_` key sees and creates only test-mode objects, and a `sk_live_` key only live ones. Today a test key can read, manage customers, list assets and trigger a test webhook, but it **cannot create an invoice or a payout** (`POST /v1/invoices` answers `409 CONFLICT`: production has no test-mode wallets). Build and rehearse with a live key and small amounts.\n\n**Money.** Amounts in are US cents (`amount_cents`, an integer). Token amounts out are base units as decimal strings (`token_base_units`, `amount_base_units`), because they do not fit a JavaScript number. Parse them with `BigInt`. There is no exchange rate: one token is one US dollar.\n\n**Retries.** `POST /v1/invoices`, `POST /v1/webhook_endpoints` and `POST /v1/webhook_endpoints/{id}/test` require an `Idempotency-Key` header: derive it from your own order id, so a retry after a timeout is a lookup and not a second object. A payout is idempotent on its `reference`, and a customer on its `external_id`.\n\n**Errors.** Every error is `{ \"error\": { \"code\", \"message\", \"param\"? } }`. Branch on `code`.\n\n**Webhooks.** Settlane POSTs signed events to your endpoint. They are described under *Webhooks* below.\n\nGuides: https://docs.settlane.com. Help: support@originstats.com." }, "servers": [ { "url": "https://api.settlane.com", "description": "Production (live and test keys both use it)" } ], "tags": [ { "name": "Health", "description": "Is the API up." }, { "name": "Account", "description": "The account a key belongs to." }, { "name": "Invoices", "description": "Take a payment for one order." }, { "name": "Customers", "description": "Your customers, their deposit addresses and their identity checks." }, { "name": "Payouts", "description": "Send money to a customer." }, { "name": "Screening", "description": "Check an address before you pay it." }, { "name": "Assets", "description": "What you can be paid in." }, { "name": "Events", "description": "Everything that happened, as a list you can page through." }, { "name": "Webhook endpoints", "description": "Where Settlane sends events." }, { "name": "Webhooks", "description": "What Settlane POSTs to your endpoint." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Liveness and database reachability", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "version", "db" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "version": { "type": "string" }, "db": { "type": "string", "enum": [ "ok", "down" ] } } }, "examples": { "example": { "value": { "status": "ok", "version": "1.0.0", "db": "ok" } } } } } } }, "security": [] } }, "/v1/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "The authenticated tenant, its status and the key's mode", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant", "mode", "scopes" ], "additionalProperties": false, "properties": { "tenant": { "type": "object", "required": [ "id", "name", "slug", "status", "contact_email", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "onboarding", "active", "suspended", "closed" ] }, "country": { "type": [ "null", "string" ] }, "contact_email": { "type": "string" }, "activated_at": { "type": [ "null", "string" ] }, "suspended_at": { "type": [ "null", "string" ] }, "created_at": { "type": "string" } } }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "examples": { "example": { "value": { "tenant": { "id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "name": "Example Store", "slug": "example-store", "status": "active", "country": "AU", "contact_email": "payments@example.com", "activated_at": "2026-10-22T08:00:00.000Z", "suspended_at": null, "created_at": "2026-10-22T08:00:00.000Z" }, "mode": "live", "scopes": [ "invoices:read", "invoices:write" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Create a webhook endpoint", "description": "REQUIRES A LIVE-MODE KEY. An endpoint has no mode: a test event is delivered to the same endpoint with `\"livemode\": false`, so creating one is creating a destination for real money events and a `sk_test_` key is refused `LIVE_MODE_REQUIRED` (403). The secret is returned exactly once, here, and never by a read.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 64 } } }, "examples": { "example": { "value": { "url": "https://example.com/webhooks/settlane", "description": "Production order handler" } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "url", "description", "event_types", "status", "created_at", "consecutive_failures" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "event_types": { "type": [ "null", "array" ], "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "failing" ] }, "created_at": { "type": "string" }, "last_success_at": { "type": [ "null", "string" ] }, "last_failure_at": { "type": [ "null", "string" ] }, "consecutive_failures": { "type": "integer" }, "previous_secret_expires_at": { "type": [ "null", "string" ] }, "secret": { "type": "string" } } }, "examples": { "example": { "value": { "id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "url": "https://example.com/webhooks/settlane", "description": "Production order handler", "event_types": null, "status": "enabled", "created_at": "2026-10-22T08:00:00.000Z", "last_success_at": null, "last_failure_at": null, "consecutive_failures": 0, "previous_secret_expires_at": null, "secret": "whsec_2f8Qd6hK1wRzYv4mBn7pLtXc9sJgAe3U" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own stable key for this create, derived from your order id. A retry with the same key and body returns the first result; the same key with a different body is `IDEMPOTENCY_CONFLICT`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ] }, "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhook endpoints" ], "summary": "List webhook endpoints", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "starting_after", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" } } }, "examples": { "example": { "value": { "data": [ { "id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "url": "https://example.com/webhooks/settlane", "description": "Production order handler", "event_types": null, "status": "enabled", "created_at": "2026-10-22T08:00:00.000Z", "last_success_at": "2026-10-22T08:20:00.000Z", "last_failure_at": null, "consecutive_failures": 0, "previous_secret_expires_at": null } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook_endpoints/{id}": { "get": { "operationId": "getWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Retrieve a webhook endpoint", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "example": { "value": { "id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "url": "https://example.com/webhooks/settlane", "description": "Production order handler", "event_types": null, "status": "enabled", "created_at": "2026-10-22T08:00:00.000Z", "last_success_at": "2026-10-22T08:20:00.000Z", "last_failure_at": null, "consecutive_failures": 0, "previous_secret_expires_at": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Update a webhook endpoint", "description": "REQUIRES A LIVE-MODE KEY -- a `sk_test_` key is refused `LIVE_MODE_REQUIRED` (403). An endpoint has no mode, so changing its URL changes where REAL money events are delivered.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 64 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, "examples": { "example": { "value": { "event_types": [ "invoice.paid", "invoice.paid_late", "invoice.settled_payment_reorged" ] } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "example": { "value": { "id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "url": "https://example.com/webhooks/settlane", "description": "Production order handler", "event_types": [ "invoice.paid", "invoice.paid_late", "invoice.settled_payment_reorged" ], "status": "enabled", "created_at": "2026-10-22T08:00:00.000Z", "last_success_at": "2026-10-22T08:20:00.000Z", "last_failure_at": null, "consecutive_failures": 0, "previous_secret_expires_at": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "disableWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Disable a webhook endpoint (soft delete)", "description": "REQUIRES A LIVE-MODE KEY -- a `sk_test_` key is refused `LIVE_MODE_REQUIRED` (403). Disabling an endpoint stops LIVE deliveries too, because an endpoint has no mode.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "example": { "value": { "id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "url": "https://example.com/webhooks/settlane", "description": "Production order handler", "event_types": null, "status": "disabled", "created_at": "2026-10-22T08:00:00.000Z", "last_success_at": "2026-10-22T08:20:00.000Z", "last_failure_at": null, "consecutive_failures": 0, "previous_secret_expires_at": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/webhook_endpoints/{id}/test": { "post": { "operationId": "sendTestWebhook", "tags": [ "Webhook endpoints" ], "summary": "Send a test event to one webhook endpoint", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own stable key for this create, derived from your order id. A retry with the same key and body returns the first result; the same key with a different body is `IDEMPOTENCY_CONFLICT`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "example": { "value": { "id": "evt_01K83QD4J6L8N0Q2S4U6W8Y0A2", "type": "settlane.test", "livemode": true, "object_kind": "webhook_endpoint", "object_id": "we_01K83QE5K7M9P1R3T5V7X9Z1B3", "payload": { "message": "This is a test event from Settlane." }, "created_at": "2026-10-22T08:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/screenings": { "post": { "operationId": "screenAddress", "tags": [ "Screening" ], "summary": "Screen a payout address", "description": "Runs the request-stage address checks and records the answer. A refusal answers PAYOUT_ADDRESS_NOT_PERMITTED with one fixed sentence and never names which check refused.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain", "address" ], "additionalProperties": false, "properties": { "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "address": { "type": "string", "minLength": 1, "maxLength": 128 }, "customer_id": { "type": [ "string", "null" ], "maxLength": 64 } } }, "examples": { "example": { "value": { "chain": "tron", "address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9" } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "subject_kind", "chain", "address", "stage", "outcome", "checked_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "subject_kind": { "type": "string", "enum": [ "address", "payout" ] }, "subject_id": { "type": [ "null", "string" ] }, "customer_id": { "type": [ "null", "string" ] }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "address": { "type": "string" }, "stage": { "type": "string", "enum": [ "request", "create", "execute" ] }, "outcome": { "type": "string", "enum": [ "passed", "refused" ] }, "shared_with_customer_ids": { "type": "array", "items": { "type": "string" } }, "shared_confirmed": { "type": "boolean" }, "checked_at": { "type": "string" } } }, "examples": { "example": { "value": { "id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "object": "screening", "subject_kind": "address", "subject_id": null, "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "chain": "tron", "address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "stage": "request", "outcome": "passed", "shared_with_customer_ids": [], "shared_confirmed": false, "checked_at": "2026-10-22T08:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "starting_after", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "maxLength": 100 }, "in": "query", "name": "object_kind", "required": false }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "object_id", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" } } }, "examples": { "example": { "value": { "data": [ { "id": "evt_01K83QD4J6L8N0Q2S4U6W8Y0A2", "type": "invoice.paid", "livemode": true, "object_kind": "invoice", "object_id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "payload": { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "paid", "received_base_units": "25000000", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": "2026-10-22T08:04:00.000Z", "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:04:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "0" }, "created_at": "2026-10-22T08:04:00.000Z" } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/events/{id}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Retrieve an event", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "example": { "value": { "id": "evt_01K83QD4J6L8N0Q2S4U6W8Y0A2", "type": "invoice.paid", "livemode": true, "object_kind": "invoice", "object_id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "payload": { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "paid", "received_base_units": "25000000", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": "2026-10-22T08:04:00.000Z", "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:04:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "0" }, "created_at": "2026-10-22T08:04:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts": { "post": { "operationId": "createPayout", "tags": [ "Payouts" ], "summary": "Create a payout", "description": "Idempotent on `reference`. Refused synchronously when the destination is malformed for the asset's chain, when the customer has not completed identity verification and the tenant requires it, or when screening refuses -- each with its own code. Otherwise the policy decides `queued`, `held` or `pending_approval`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "asset_id", "amount_cents", "destination", "reference" ], "additionalProperties": false, "properties": { "customer_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "asset_id": { "type": "string", "minLength": 1, "maxLength": 32 }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "destination": { "type": "string", "minLength": 1, "maxLength": 128 }, "reference": { "type": "string", "minLength": 1, "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "amount_cents": 5000, "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "metadata": { "withdrawal_id": "77" } } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "example": { "value": { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "pending_approval", "hold_reason": null, "release_at": null, "approved_by": null, "approved_at": null, "approvals": [], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": null, "broadcast_at": null, "completed_at": null, "cancelled_at": null, "retry_of": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "listPayouts", "tags": [ "Payouts" ], "summary": "List payouts", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "starting_after", "required": false }, { "schema": { "type": "string", "enum": [ "created", "pending_approval", "held", "queued", "signing", "broadcast", "confirming", "completed", "failed", "refused", "rejected", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "customer_id", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "reference", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "has_more": { "type": "boolean" } } }, "examples": { "example": { "value": { "data": [ { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "pending_approval", "hold_reason": null, "release_at": null, "approved_by": null, "approved_at": null, "approvals": [], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": null, "broadcast_at": null, "completed_at": null, "cancelled_at": null, "retry_of": null } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts/{id}": { "get": { "operationId": "getPayout", "tags": [ "Payouts" ], "summary": "Retrieve a payout", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "example": { "value": { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "pending_approval", "hold_reason": null, "release_at": null, "approved_by": null, "approved_at": null, "approvals": [], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": null, "broadcast_at": null, "completed_at": null, "cancelled_at": null, "retry_of": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts/{id}/cancel": { "post": { "operationId": "cancelPayout", "tags": [ "Payouts" ], "summary": "Cancel a payout", "description": "Allowed until the payout reaches `signing`. A later status is refused with CONFLICT.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 500 } } }, "examples": { "example": { "value": { "reason": "Customer withdrew the request" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "example": { "value": { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "cancelled", "hold_reason": null, "release_at": null, "approved_by": null, "approved_at": null, "approvals": [], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": null, "broadcast_at": null, "completed_at": null, "cancelled_at": "2026-10-22T08:10:00.000Z", "retry_of": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts/{id}/approve": { "post": { "operationId": "approvePayout", "tags": [ "Payouts" ], "summary": "Approve a payout that is waiting for approval", "description": "Needs the `payouts:approve` scope (not included in `payouts:write`) AND the workspace's own switch: while `api_approval_enabled` is off -- the default -- this answers 403 `FORBIDDEN` with `param` `api_approval_enabled`. A payout above `api_approval_max_cents`, or one that would take this workspace's API approvals over `api_approval_daily_cents` in a rolling 24 hours, is refused 403 with `param` naming the cap and stays waiting for a person. Only a `pending_approval` payout is approved; `held` and every other status are refused with `CONFLICT`, and one waiting for identity verification (`hold_reason: kyc_required`) is refused 403 with `param` `hold_reason` -- it is approved in the dashboard. `note` and `approved_by` are one line of plain text: no line breaks, control or formatting characters, and `approved_by` needs a visible character. An API approval is ONE approval: with two approvals required, a person still approves in the dashboard. The key that created a payout cannot approve it. Approving a payout that is already approved, or that already carries this key's approval, answers its current state. Every approval is audited and emailed to the workspace's owners.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note", "approved_by" ], "additionalProperties": false, "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "approved_by": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "examples": { "example": { "value": { "note": "Checked against withdrawal 77", "approved_by": "ops@example.com" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "example": { "value": { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "queued", "hold_reason": null, "release_at": null, "approved_by": "ops@example.com", "approved_at": "2026-10-22T08:10:00.000Z", "approvals": [ { "by": "ops@example.com", "at": "2026-10-22T08:10:00.000Z" } ], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": "2026-10-22T08:10:00.000Z", "broadcast_at": null, "completed_at": null, "cancelled_at": null, "retry_of": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts/{id}/reject": { "post": { "operationId": "rejectPayout", "tags": [ "Payouts" ], "summary": "Reject a payout that is waiting for approval", "description": "The same scope and switch as approve (403 `FORBIDDEN`, `param` `api_approval_enabled`, while it is off); no cap applies, because a rejection moves no money. Only a `pending_approval` payout is rejected: an approved one is refused with `CONFLICT`, exactly as the dashboard refuses it, and so is a `held` one. A payout waiting for identity verification may be rejected. `note` and `approved_by` follow approve's rules. Rejecting a payout that is already `rejected` answers its current state. The payout ends `rejected` and the tenant receives `payout.cancelled` with `status: \"rejected\"`. Every rejection is audited and emailed to the workspace's owners.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note", "approved_by" ], "additionalProperties": false, "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 }, "approved_by": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "examples": { "example": { "value": { "note": "Destination does not match the customer's saved address", "approved_by": "ops@example.com" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "example": { "value": { "id": "po_01K83QC3H5K7M9P1R3T5V7X9Z1", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdt_tron", "chain": "tron", "amount_cents": "5000", "amount_base_units": "50000000", "destination": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "reference": "withdrawal-77", "status": "rejected", "hold_reason": null, "release_at": null, "approved_by": null, "approved_at": null, "approvals": [], "screening_id": "scr_01K83QG7M9P1R3T5V7X9Z1B3D5", "tx_hash": null, "failure_code": null, "metadata": { "withdrawal_id": "77" }, "created_at": "2026-10-22T08:00:00.000Z", "queued_at": null, "broadcast_at": null, "completed_at": null, "cancelled_at": "2026-10-22T08:10:00.000Z", "retry_of": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts/{id}/events": { "get": { "operationId": "listPayoutTransitions", "tags": [ "Payouts" ], "summary": "The transitions of one payout, oldest first", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "status_to", "actor", "at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "status_from": { "type": [ "null", "string" ] }, "status_to": { "type": "string" }, "actor": { "type": "string" }, "reason": { "type": [ "null", "string" ] }, "detail": { "type": "object", "additionalProperties": true }, "at": { "type": "string" } } } } } }, "examples": { "example": { "value": { "data": [ { "id": "pst_01K83QJ9P1R3T5V7X9Z1B3D5F7", "status_from": null, "status_to": "pending_approval", "actor": "api", "reason": null, "detail": {}, "at": "2026-10-22T08:00:00.000Z" } ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/invoices": { "post": { "operationId": "createInvoice", "tags": [ "Invoices" ], "summary": "Create an invoice", "description": "Requires an `Idempotency-Key` header. Without a `customer_id`, reserves a deposit address that belongs to this invoice for ever. WITH one, quotes that customer's own address in this asset (reserved on their first invoice) and cancels the customer's open invoice, if any (`invoice.cancelled`, `cancel_reason: \"replaced\"`); the customer's funds pay it within seconds when they already cover it, and `amount_due` says what is still to send. Returns the exact token amount, the expiry, the payment URI and the confirmation rule. Refused when the asset does not accept deposits, when the named customer is unknown, or when this tenant has no deposit root on the asset's chain.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_id", "amount_cents" ], "additionalProperties": false, "properties": { "asset_id": { "type": "string", "minLength": 1, "maxLength": 32 }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "customer_id": { "type": [ "string", "null" ], "maxLength": 64 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "metadata": { "type": "object", "additionalProperties": true }, "pay_from_funds": { "type": "boolean" } } }, "examples": { "example": { "value": { "asset_id": "usdc_eth", "amount_cents": 2500, "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "description": "Order 1042", "reference": "order-1042", "metadata": { "order_id": "1042" } } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "example": { "value": { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "pending", "received_base_units": "0", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": null, "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:00:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "2500", "deposit_address": "0x0000000000000000000000000000000000000001", "token_contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "payment_uri": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/transfer?address=0x0000000000000000000000000000000000000001&uint256=25000000", "min_confirmations": 12, "estimated_arrival": 180 } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own stable key for this create, derived from your order id. A retry with the same key and body returns the first result; the same key with a different body is `IDEMPOTENCY_CONFLICT`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ] }, "get": { "operationId": "listInvoices", "tags": [ "Invoices" ], "summary": "List invoices", "description": "The invoice objects only. The deposit address and the payment URI are on `GET /v1/invoices/{id}` -- a list of payment URIs is one join per row for something a caller renders one at a time.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "starting_after", "required": false }, { "schema": { "type": "string", "enum": [ "pending", "detected", "confirming", "underpaid", "paid", "paid_late", "expired", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "maxLength": 64 }, "in": "query", "name": "customer_id", "required": false }, { "schema": { "type": "string", "maxLength": 255 }, "in": "query", "name": "reference", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" } }, "has_more": { "type": "boolean" } } }, "examples": { "example": { "value": { "data": [ { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "pending", "received_base_units": "0", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": null, "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:00:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "2500" } ], "has_more": false } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "tags": [ "Invoices" ], "summary": "Retrieve an invoice", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "example": { "value": { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "pending", "received_base_units": "0", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": null, "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:00:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "2500", "deposit_address": "0x0000000000000000000000000000000000000001", "token_contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "payment_uri": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/transfer?address=0x0000000000000000000000000000000000000001&uint256=25000000", "min_confirmations": 12, "estimated_arrival": 180 } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/invoices/{id}/cancel": { "post": { "operationId": "cancelInvoice", "tags": [ "Invoices" ], "summary": "Cancel an invoice", "description": "Allowed ONLY while `pending`. Any other status is refused with CONFLICT -- once a payment has been seen at the address, cancelling would void an order a customer has already paid for, which is a refund conversation rather than a status change.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSummary" }, "examples": { "example": { "value": { "id": "inv_01K83QB2G4J6L8N0Q2S4U6W8Y0", "tenant_id": "ten_01K83Q9V2B7N4M6R8T0W2Y4A6C", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "asset_id": "usdc_eth", "chain": "ethereum", "amount_cents": "2500", "token_base_units": "25000000", "deposit_address_id": "da_01K83QH8N0Q2S4U6W8Y0A2C4E6", "status": "cancelled", "received_base_units": "0", "overpaid_base_units": "0", "expires_at": "2026-10-22T08:30:00.000Z", "late_window_ends_at": "2026-10-23T08:30:00.000Z", "paid_at": null, "description": "Order 1042", "metadata": { "order_id": "1042" }, "reference": "order-1042", "created_at": "2026-10-22T08:00:00.000Z", "updated_at": "2026-10-22T08:05:00.000Z", "cancel_reason": null, "funds_available": null, "amount_due": "2500" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/customers": { "post": { "operationId": "createCustomer", "tags": [ "Customers" ], "summary": "Create a customer (or get the one with this external_id)", "description": "Idempotent on `external_id`: a new customer answers 201, an existing one answers 200 with the customer unchanged. Send the returned `id` as `customer_id` on `POST /v1/invoices` and every invoice for this customer quotes the customer's own deposit address; money the customer sends there becomes their funds, which pay their invoices. Requires `invoices:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_id" ], "additionalProperties": false, "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": [ "string", "null" ], "maxLength": 320 }, "customer_since": { "type": [ "string", "null" ], "maxLength": 40 }, "metadata": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "external_id": "user-8812", "email": "player@example.com", "customer_since": "2025-03-01", "metadata": { "tier": "gold" } } } } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRecord" }, "examples": { "example": { "value": { "id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "external_id": "user-8812", "email": "player@example.com", "customer_since": "2025-03-01", "metadata": { "tier": "gold" }, "status": "active", "created_at": "2026-10-22T08:00:00.000Z" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRecord" }, "examples": { "example": { "value": { "id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "external_id": "user-8812", "email": "player@example.com", "customer_since": "2025-03-01", "metadata": { "tier": "gold" }, "status": "active", "created_at": "2026-10-22T08:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/customers/{id}/verifications": { "post": { "operationId": "startVerification", "tags": [ "Customers" ], "summary": "Start an identity verification for a customer", "description": "Opens a hosted verification with the tenant's provider and answers 201 with its `hosted_url`, which the customer completes in their own browser. A customer with an attempt still pending gets that attempt back with 200 (and its url); an already-verified customer gets the approved attempt with 200 and no url. Refused with IDENTITY_IN_REVIEW, IDENTITY_UNDER_AGE, IDENTITY_ATTEMPTS_EXHAUSTED or IDENTITY_RETRY_TOO_SOON (409), IDENTITY_DATE_OF_BIRTH_INVALID (400), CUSTOMER_BLOCKED (409), IDENTITY_VERIFICATION_UNAVAILABLE (503, no provider configured) or IDENTITY_PROVIDER_FAILED (502). Requires `customers:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "return_url" ], "additionalProperties": false, "properties": { "return_url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "language": { "type": "string", "minLength": 2, "maxLength": 8 }, "expected_date_of_birth": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "examples": { "example": { "value": { "return_url": "https://example.com/account/verified", "language": "en" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSession" }, "examples": { "example": { "value": { "id": "ver_01K83QF6L8N0Q2S4U6W8Y0A2C4", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "status": "pending", "hosted_url": "https://verify.example.com/session/7f3c" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSession" }, "examples": { "example": { "value": { "id": "ver_01K83QF6L8N0Q2S4U6W8Y0A2C4", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "status": "pending", "hosted_url": "https://verify.example.com/session/7f3c" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/customers/{id}/kyc": { "get": { "operationId": "getCustomerKyc", "tags": [ "Customers" ], "summary": "A customer's identity-verification state", "description": "`state` is the customer-level answer (`verified` means the latest decided attempt is approved), the same rule `POST /v1/payouts` gates on; `latest_verification` is that decided attempt, or null before any decision; `retry` says whether a new attempt may be started now (`blocked_by: customer_blocked` for a customer an operator has blocked). Never carries a hosted url. Not cached. Requires `customers:read`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "external_id", "state", "verified_at", "latest_verification", "retry" ], "additionalProperties": false, "properties": { "customer_id": { "type": "string" }, "external_id": { "type": "string" }, "state": { "type": "string", "enum": [ "verified", "pending", "needs_review", "declined", "not_started", "unavailable" ] }, "verified_at": { "type": [ "null", "string" ] }, "latest_verification": { "type": [ "null", "object" ], "required": [ "id", "status", "decided_at", "decision_reason", "dob_matches", "age_check" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "declined", "needs_review", "expired", "abandoned" ] }, "decided_at": { "type": [ "null", "string" ] }, "decision_reason": { "type": [ "null", "string" ] }, "dob_matches": { "type": [ "null", "boolean" ] }, "age_check": { "type": [ "null", "boolean" ] } } }, "retry": { "type": "object", "required": [ "can_retry", "retry_at", "blocked_by", "attempts_in_window" ], "additionalProperties": false, "properties": { "can_retry": { "type": "boolean" }, "retry_at": { "type": [ "null", "string" ] }, "blocked_by": { "type": [ "null", "string" ], "enum": [ "under_age", "exhausted", "cooldown", "customer_blocked", null ] }, "attempts_in_window": { "type": "integer" } } } } }, "examples": { "example": { "value": { "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "external_id": "user-8812", "state": "verified", "verified_at": "2026-10-22T08:15:00.000Z", "latest_verification": { "id": "ver_01K83QF6L8N0Q2S4U6W8Y0A2C4", "status": "approved", "decided_at": "2026-10-22T08:15:00.000Z", "decision_reason": null, "dob_matches": true, "age_check": true }, "retry": { "can_retry": false, "retry_at": null, "blocked_by": null, "attempts_in_window": 1 } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/verifications/{id}": { "get": { "operationId": "getVerification", "tags": [ "Customers" ], "summary": "One verification attempt", "description": "The attempt as `customer.kyc.updated` describes it. With `?include=document_dob` (a key holding `customers:read` AND `customers:write`) the answer adds `document_date_of_birth`, read live from the provider's decision and never stored -- only for a decided attempt (`approved`, `declined`, `needs_review`) decided by the provider; an undecided or simulated attempt, or a decision that carries no date of birth, answers without the field. Once the provider session has been deleted it is VERIFICATION_DOCUMENT_GONE (409). Every such read is audited and counts against the key's create budget. Requires `customers:read`.", "parameters": [ { "schema": { "type": "string", "enum": [ "document_dob" ] }, "in": "query", "name": "include", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" }, "examples": { "example": { "value": { "id": "ver_01K83QF6L8N0Q2S4U6W8Y0A2C4", "customer_id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "status": "approved", "document_country": "AU", "document_type": "passport", "dob_matches": true, "age_check": true, "aml_hit": false, "duplicate_customer_ids": [], "decision_reason": null, "created_at": "2026-10-22T08:00:00.000Z", "decided_at": "2026-10-22T08:15:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/customers/{id}": { "get": { "operationId": "getCustomer", "tags": [ "Customers" ], "summary": "One customer, with its KYC state and deposit addresses", "description": "The customer as `POST /v1/customers` answers it, plus `kyc` (the state and when it was verified) and `deposit_addresses` -- one per asset, reserved by the first invoice that named the customer. A blocked customer is answered with its status, not hidden. Requires `customers:read`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "examples": { "example": { "value": { "id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "external_id": "user-8812", "email": "player@example.com", "customer_since": "2025-03-01", "metadata": { "tier": "gold" }, "status": "active", "created_at": "2026-10-22T08:00:00.000Z", "kyc": { "state": "verified", "verified_at": "2026-10-22T08:15:00.000Z" }, "deposit_addresses": [ { "asset_id": "usdc_eth", "chain": "ethereum", "address": "0x0000000000000000000000000000000000000001" }, { "asset_id": "usdt_tron", "chain": "tron", "address": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb" } ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateCustomer", "tags": [ "Customers" ], "summary": "Update a customer", "description": "Sets `email`, `customer_since` (`YYYY-MM-DD` or an ISO instant with a zone, at or before now; the payout policy's \"established\" rule counts from it, and every change is audited against the key with the old and new values) and `metadata` (replaced whole). `status` is an operator's decision and is not settable here. Requires `customers:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "email": { "type": [ "string", "null" ], "maxLength": 320 }, "customer_since": { "type": [ "string", "null" ], "maxLength": 40 }, "metadata": { "type": "object", "additionalProperties": true } } }, "examples": { "example": { "value": { "email": "player.new@example.com" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRecord" }, "examples": { "example": { "value": { "id": "cus_01K83QA1F3H5J7K9M1P3R5T7V9", "external_id": "user-8812", "email": "player.new@example.com", "customer_since": "2025-03-01", "metadata": { "tier": "gold" }, "status": "active", "created_at": "2026-10-22T08:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/assets": { "get": { "operationId": "listAssets", "tags": [ "Assets" ], "summary": "The deposit assets this key can invoice in", "description": "One row per asset this gateway accepts deposits in, for the calling key's own mode -- a `sk_test_` key sees the testnet assets and a `sk_live_` key the live ones, with different contracts, and the two lists need not name the same assets. An asset this gateway does not accept deposits in is absent rather than listed as disabled, because `POST /v1/invoices` refuses it. `min_confirmations` and `estimated_arrival` are the same two integers the invoice carries; `estimated_arrival` is in SECONDS and describes the typical case rather than bounding it. `network_fee` is what the CUSTOMER pays the network to send the transfer -- it goes to the network and never to Settlane, it is descriptive and never a bound, and a wallet shows the real figure before the customer confirms. Read `network_fee.status` before `network_fee.native_base_units`: a null there is an absent estimate, never a zero one.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "mode" ], "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "asset_id", "chain", "symbol", "decimals", "token_contract", "min_confirmations", "estimated_arrival", "network_fee" ], "additionalProperties": false, "properties": { "asset_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "token_contract": { "type": "string" }, "min_confirmations": { "type": "integer" }, "estimated_arrival": { "type": "integer", "description": "Typical seconds between a customer broadcasting a payment and Settlane treating it as confirmed. SECONDS, not minutes. Descriptive of the typical case and not a bound -- a chain that stalls takes longer." }, "network_fee": { "type": "object", "required": [ "status", "native_base_units", "native_symbol", "native_decimals", "max_age_seconds", "estimated_at" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "estimated", "unreadable", "not_configured" ], "description": "`estimated`: a price was read from the chain. `unreadable`: this deployment prices this chain but could not reach it just now -- pick another network, nothing is refused. `not_configured`: this deployment prices no fee on this chain at all. The last two are different facts and are never collapsed into one." }, "native_base_units": { "type": [ "null", "string" ], "description": "An integer count of the chain's smallest native unit (wei on Ethereum, sun on Tron), as a decimal string -- never a number, because the Ethereum figure leaves IEEE-754 integer range. Null unless `status` is `estimated`; a null is an ABSENT estimate and never a zero one. A literal \"0\" under `estimated` means the price was read and is zero." }, "native_symbol": { "type": "string", "description": "`ETH` or `TRX`. A fact about the chain, so it is present in every status." }, "native_decimals": { "type": "integer", "description": "Decimals that turn `native_base_units` into a display figure: 18 for wei, 6 for sun." }, "max_age_seconds": { "type": "integer", "description": "How stale `native_base_units` may be. A gas figure is wrong within the hour, so this is the bound rather than a hope: it is the same constant as the server-side cache TTL, so a served figure cannot be older than this. Present in every status, because it is this route's contract and not part of the estimate." }, "estimated_at": { "type": [ "null", "string" ], "description": "When the PRICE was read, ISO-8601. Not when this response was built -- so a client can check the age itself instead of taking `max_age_seconds` on trust. Null unless `status` is `estimated`." } } } } } }, "mode": { "type": "string", "enum": [ "live", "test" ] } } }, "examples": { "example": { "value": { "data": [ { "asset_id": "usdc_eth", "chain": "ethereum", "symbol": "USDC", "decimals": 6, "token_contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "min_confirmations": 12, "estimated_arrival": 180, "network_fee": { "status": "estimated", "native_base_units": "420000000000000", "native_symbol": "ETH", "native_decimals": 18, "max_age_seconds": 300, "estimated_at": "2026-10-22T08:00:00.000Z" } }, { "asset_id": "usdt_tron", "chain": "tron", "symbol": "USDT", "decimals": 6, "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "min_confirmations": 19, "estimated_arrival": 60, "network_fee": { "status": "estimated", "native_base_units": "8200000", "native_symbol": "TRX", "native_decimals": 6, "max_age_seconds": 300, "estimated_at": "2026-10-22T08:00:00.000Z" } } ], "mode": "live" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "invoice.payment_detected": { "post": { "operationId": "invoicePaymentDetectedWebhook", "summary": "A payment has been seen on the chain.", "description": "A payment has been seen on the chain. Nothing is credited yet — do not ship on this.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.payment_detected" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.paid": { "post": { "operationId": "invoicePaidWebhook", "summary": "Settled in full and on time.", "description": "Settled in full and on time. This is the one to credit the customer on.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.paid" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.underpaid": { "post": { "operationId": "invoiceUnderpaidWebhook", "summary": "Money was credited and it is not enough.", "description": "Money was credited and it is not enough. The invoice stays open.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.underpaid" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.expired": { "post": { "operationId": "invoiceExpiredWebhook", "summary": "The invoice passed `expires_at` with nothing credited.", "description": "The invoice passed `expires_at` with nothing credited.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.expired" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.paid_late": { "post": { "operationId": "invoicePaidLateWebhook", "summary": "Settled in full, after `expires_at` but inside the late window.", "description": "Settled in full, after `expires_at` but inside the late window. Credit it or refund it — the decision is yours.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.paid_late" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.cancelled": { "post": { "operationId": "invoiceCancelledWebhook", "summary": "The invoice was cancelled.", "description": "The invoice was cancelled.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.cancelled" }, "payload": { "$ref": "#/components/schemas/InvoiceSummary" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.counterparty_flagged": { "post": { "operationId": "invoiceCounterpartyFlaggedWebhook", "summary": "The address that paid this invoice was flagged by screening after the fact.", "description": "The address that paid this invoice was flagged by screening after the fact.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.counterparty_flagged" }, "payload": { "type": "object", "additionalProperties": true, "description": "The movement that paid this invoice, whose sender screening flagged after the fact. Read the invoice itself with `GET /v1/invoices/{id}`.", "properties": { "invoice_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "tx_hash": { "type": "string" }, "log_index": { "type": "integer" }, "from_address": { "type": "string" }, "amount_base_units": { "type": "string" }, "refusal_code": { "type": "string" }, "screening_id": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "invoice.settled_payment_reorged": { "post": { "operationId": "invoiceSettledPaymentReorgedWebhook", "summary": "A payment Settlane had confirmed was taken back by a deep reorg.", "description": "A payment Settlane had confirmed was taken back by a deep reorg. THE INVOICE STAYS `paid` — this event is the only thing that tells you the money is not there.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "invoice.settled_payment_reorged" }, "payload": { "type": "object", "additionalProperties": true, "description": "The confirmed transfer a deep reorg took back. The invoice stays `paid`; `received_base_units` is what is now really received.", "properties": { "invoice_id": { "type": "string" }, "tx_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "tx_hash": { "type": "string" }, "log_index": { "type": "integer" }, "credited_base_units": { "type": "string" }, "invoice_status": { "type": "string" }, "received_base_units": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.pending_approval": { "post": { "operationId": "payoutPendingApprovalWebhook", "summary": "A payout needs a person.", "description": "A payout needs a person.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.pending_approval" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.queued": { "post": { "operationId": "payoutQueuedWebhook", "summary": "A payout was approved and is waiting for the executor.", "description": "A payout was approved and is waiting for the executor.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.queued" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.broadcast": { "post": { "operationId": "payoutBroadcastWebhook", "summary": "A payout was signed and sent to the chain.", "description": "A payout was signed and sent to the chain.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.broadcast" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.completed": { "post": { "operationId": "payoutCompletedWebhook", "summary": "A payout settled.", "description": "A payout settled.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.completed" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.failed": { "post": { "operationId": "payoutFailedWebhook", "summary": "A payout attempt failed.", "description": "A payout attempt failed.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.failed" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.cancelled": { "post": { "operationId": "payoutCancelledWebhook", "summary": "A payout was cancelled.", "description": "A payout was cancelled.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.cancelled" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.held": { "post": { "operationId": "payoutHeldWebhook", "summary": "A payout is waiting out a time-based rule (a destination nobody has vouched for yet).", "description": "A payout is waiting out a time-based rule (a destination nobody has vouched for yet). An operator's approval releases it early.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.held" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "payout.refused": { "post": { "operationId": "payoutRefusedWebhook", "summary": "Screening, or the signer, refused a payout.", "description": "Screening, or the signer, refused a payout. No transaction was ever built; refund your customer.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "payout.refused" }, "payload": { "$ref": "#/components/schemas/Payout" } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "customer.kyc.updated": { "post": { "operationId": "customerKycUpdatedWebhook", "summary": "A customer's identity verification reached a decision.", "description": "A customer's identity verification reached a decision.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "customer.kyc.updated" }, "payload": { "type": "object", "additionalProperties": true, "description": "The customer-level identity state after the decision, the same answer `GET /v1/customers/{id}/kyc` gives now.", "properties": { "verification_id": { "type": "string" }, "customer_id": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "verified", "pending", "needs_review", "declined", "not_started", "unavailable" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "declined", "needs_review", "expired", "abandoned" ] }, "decided_at": { "type": [ "string", "null" ] }, "dob_matches": { "type": [ "boolean", "null" ] }, "age_check": { "type": [ "boolean", "null" ] }, "duplicate_customer_ids": { "type": "array", "items": { "type": "string" } }, "decision_reason": { "type": [ "string", "null" ] }, "retry": { "type": "object", "properties": { "can_retry": { "type": "boolean" }, "retry_at": { "type": [ "string", "null" ] }, "blocked_by": { "type": [ "string", "null" ] } } } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "customer.funds_received": { "post": { "operationId": "customerFundsReceivedWebhook", "summary": "Money reached a customer's own deposit address and no open invoice took it; it is now that customer's funds.", "description": "Money reached a customer's own deposit address and no open invoice took it; it is now that customer's funds. Create an invoice for what it buys and the funds pay it.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "customer.funds_received" }, "payload": { "type": "object", "additionalProperties": true, "description": "One confirmed transfer to the customer's own deposit address that no open invoice took. It is now the customer's funds; an invoice created with `pay_from_funds` spends them.", "properties": { "customer_id": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "asset_id": { "type": "string" }, "amount_base_units": { "type": "string" }, "amount_cents": { "type": "string" }, "funds_available_base_units": { "type": "string" }, "funds_available_cents": { "type": "string" }, "tx_hash": { "type": "string" }, "log_index": { "type": "integer" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "customer.counterparty_flagged": { "post": { "operationId": "customerCounterpartyFlaggedWebhook", "summary": "The address that sent money to a customer's own deposit address was flagged by screening, and the flag cannot be tied to one invoice: no invoice took the money, or the screening only answered later.", "description": "The address that sent money to a customer's own deposit address was flagged by screening, and the flag cannot be tied to one invoice: no invoice took the money, or the screening only answered later. The money is in the customer's funds. A flag found when the movement went to an invoice is reported as invoice.counterparty_flagged on that invoice instead.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "customer.counterparty_flagged" }, "payload": { "type": "object", "additionalProperties": true, "properties": { "customer_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "tx_hash": { "type": "string" }, "log_index": { "type": "integer" }, "from_address": { "type": "string" }, "amount_base_units": { "type": "string" }, "refusal_code": { "type": "string" }, "screening_id": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "wallet.low_gas": { "post": { "operationId": "walletLowGasWebhook", "summary": "A hot wallet is running out of native currency and will stop being able to send.", "description": "A hot wallet is running out of native currency and will stop being able to send.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "wallet.low_gas" }, "payload": { "type": "object", "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "wallet.unexpected_funds": { "post": { "operationId": "walletUnexpectedFundsWebhook", "summary": "Money arrived somewhere it was not expected — past an invoice's late window, or to an address with no open invoice.", "description": "Money arrived somewhere it was not expected — past an invoice's late window, or to an address with no open invoice.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "wallet.unexpected_funds" }, "payload": { "type": "object", "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "screening.refused": { "post": { "operationId": "screeningRefusedWebhook", "summary": "A screening refused an address.", "description": "A screening refused an address.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "screening.refused" }, "payload": { "type": "object", "additionalProperties": true } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } }, "settlane.test": { "post": { "operationId": "settlaneTestWebhook", "summary": "Sent by `POST /v1/webhook_endpoints/{id}/test`.", "description": "Sent by `POST /v1/webhook_endpoints/{id}/test`. Use it to check your endpoint and your signature check.", "tags": [ "Webhooks" ], "security": [], "parameters": [ { "name": "Settlane-Signature", "in": "header", "required": true, "description": "`t=,v1=`. Verify it against the RAW body before you trust anything. See https://docs.settlane.com/webhooks#the-signature-algorithm.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Id", "in": "header", "required": true, "description": "The event id, also in the body. The same on every retry: de-duplicate on it.", "schema": { "type": "string" } }, { "name": "Settlane-Event-Type", "in": "header", "required": true, "description": "The event type, also in the body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "const": "settlane.test" }, "payload": { "type": "object", "properties": { "message": { "type": "string" } } } } } ] } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery. Anything else is retried on the backoff ladder." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer sk_live_…` or `Bearer sk_test_…`. Keep the key on your server; never put it in a browser or an app." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Stable and machine-readable. Branch on this.", "examples": [ "IDEMPOTENCY_CONFLICT" ] }, "message": { "type": "string", "description": "For a person. May be reworded." }, "param": { "type": "string", "description": "The request field at fault, when there is exactly one." } } } } }, "Invoice": { "type": "object", "required": [ "id", "tenant_id", "asset_id", "chain", "amount_cents", "token_base_units", "status", "received_base_units", "overpaid_base_units", "expires_at", "late_window_ends_at", "created_at", "updated_at", "cancel_reason", "funds_available", "amount_due", "deposit_address", "token_contract", "payment_uri", "min_confirmations", "estimated_arrival" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "customer_id": { "type": [ "null", "string" ] }, "asset_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "amount_cents": { "type": "string" }, "token_base_units": { "type": "string" }, "deposit_address_id": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "detected", "confirming", "underpaid", "paid", "paid_late", "expired", "cancelled" ] }, "received_base_units": { "type": "string" }, "overpaid_base_units": { "type": "string" }, "expires_at": { "type": "string" }, "late_window_ends_at": { "type": "string" }, "paid_at": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "metadata": { "type": "object", "additionalProperties": true }, "reference": { "type": [ "null", "string" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "cancel_reason": { "type": [ "null", "string" ], "enum": [ "replaced", null ] }, "funds_available": { "type": [ "null", "string" ] }, "amount_due": { "type": "string" }, "deposit_address": { "type": "string" }, "token_contract": { "type": "string" }, "payment_uri": { "type": "string" }, "min_confirmations": { "type": "integer" }, "estimated_arrival": { "type": "integer" } } }, "InvoiceSummary": { "type": "object", "required": [ "id", "tenant_id", "asset_id", "chain", "amount_cents", "token_base_units", "status", "received_base_units", "overpaid_base_units", "expires_at", "late_window_ends_at", "created_at", "updated_at", "cancel_reason", "funds_available", "amount_due" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "customer_id": { "type": [ "null", "string" ] }, "asset_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "amount_cents": { "type": "string" }, "token_base_units": { "type": "string" }, "deposit_address_id": { "type": [ "null", "string" ] }, "status": { "type": "string", "enum": [ "pending", "detected", "confirming", "underpaid", "paid", "paid_late", "expired", "cancelled" ] }, "received_base_units": { "type": "string" }, "overpaid_base_units": { "type": "string" }, "expires_at": { "type": "string" }, "late_window_ends_at": { "type": "string" }, "paid_at": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "metadata": { "type": "object", "additionalProperties": true }, "reference": { "type": [ "null", "string" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "cancel_reason": { "type": [ "null", "string" ], "enum": [ "replaced", null ] }, "funds_available": { "type": [ "null", "string" ] }, "amount_due": { "type": "string" } } }, "Payout": { "type": "object", "required": [ "id", "tenant_id", "customer_id", "asset_id", "chain", "amount_cents", "amount_base_units", "destination", "reference", "status", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "customer_id": { "type": "string" }, "asset_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "amount_cents": { "type": "string" }, "amount_base_units": { "type": "string" }, "destination": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "pending_approval", "held", "queued", "signing", "broadcast", "confirming", "completed", "failed", "refused", "rejected", "cancelled" ] }, "hold_reason": { "type": [ "null", "string" ] }, "release_at": { "type": [ "null", "string" ] }, "approved_by": { "type": [ "null", "string" ] }, "approved_at": { "type": [ "null", "string" ] }, "approvals": { "type": "array", "items": { "type": "object", "required": [ "by", "at" ], "additionalProperties": false, "properties": { "by": { "type": "string" }, "at": { "type": "string" } } } }, "screening_id": { "type": [ "null", "string" ] }, "tx_hash": { "type": [ "null", "string" ] }, "failure_code": { "type": [ "null", "string" ] }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string" }, "queued_at": { "type": [ "null", "string" ] }, "broadcast_at": { "type": [ "null", "string" ] }, "completed_at": { "type": [ "null", "string" ] }, "cancelled_at": { "type": [ "null", "string" ] }, "retry_of": { "type": [ "null", "string" ] } } }, "Customer": { "type": "object", "required": [ "id", "external_id", "email", "customer_since", "metadata", "status", "created_at", "kyc", "deposit_addresses" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "customer_since": { "type": [ "null", "string" ] }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "created_at": { "type": "string" }, "kyc": { "type": "object", "required": [ "state", "verified_at" ], "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "verified", "pending", "needs_review", "declined", "not_started", "unavailable" ] }, "verified_at": { "type": [ "null", "string" ] } } }, "deposit_addresses": { "type": "array", "items": { "type": "object", "required": [ "asset_id", "chain", "address" ], "additionalProperties": false, "properties": { "asset_id": { "type": "string" }, "chain": { "type": "string", "enum": [ "ethereum", "tron" ] }, "address": { "type": "string" } } } } } }, "CustomerRecord": { "type": "object", "required": [ "id", "external_id", "email", "customer_since", "metadata", "status", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "email": { "type": [ "null", "string" ] }, "customer_since": { "type": [ "null", "string" ] }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "created_at": { "type": "string" } } }, "Verification": { "type": "object", "required": [ "id", "customer_id", "status", "document_country", "document_type", "dob_matches", "age_check", "aml_hit", "duplicate_customer_ids", "decision_reason", "created_at", "decided_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "declined", "needs_review", "expired", "abandoned" ] }, "document_country": { "type": [ "null", "string" ] }, "document_type": { "type": [ "null", "string" ] }, "dob_matches": { "type": [ "null", "boolean" ] }, "age_check": { "type": [ "null", "boolean" ] }, "aml_hit": { "type": [ "null", "boolean" ] }, "duplicate_customer_ids": { "type": "array", "items": { "type": "string" } }, "decision_reason": { "type": [ "null", "string" ] }, "created_at": { "type": "string" }, "decided_at": { "type": [ "null", "string" ] }, "document_date_of_birth": { "type": "string" } } }, "VerificationSession": { "type": "object", "required": [ "id", "customer_id", "status", "hosted_url" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "declined", "needs_review", "expired", "abandoned" ] }, "hosted_url": { "type": [ "null", "string" ] } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "description", "event_types", "status", "created_at", "consecutive_failures" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "event_types": { "type": [ "null", "array" ], "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled", "failing" ] }, "created_at": { "type": "string" }, "last_success_at": { "type": [ "null", "string" ] }, "last_failure_at": { "type": [ "null", "string" ] }, "consecutive_failures": { "type": "integer" }, "previous_secret_expires_at": { "type": [ "null", "string" ] } } }, "Event": { "type": "object", "required": [ "id", "type", "livemode", "object_kind", "object_id", "payload", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "livemode": { "type": "boolean" }, "object_kind": { "type": "string" }, "object_id": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string" } } } }, "responses": { "Error": { "description": "An error. Branch on `error.code`, never on the message. See https://docs.settlane.com/errors.", "headers": { "Settlane-Request-Id": { "description": "Quote it in a support request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }