{ "openapi": "3.0.3", "info": { "title": "Bitnob API v2", "version": "2.0.0", "description": "# Bitnob API v2\n\nA single, ready-to-use collection for the Bitnob Core API v2 — balances, payouts, cards, trading, lightning, bulk transfers and more.\n\n## Quick start\n\n1. Set the collection variables:\n - `base_url` — e.g. `https://api.bitnob.com`\n - `client_id` — your workspace client id\n - `client_secret` — your workspace client secret\n2. Run any request. The **collection-level pre-request script** automatically:\n - generates a fresh `timestamp` + `nonce`,\n - canonicalises the JSON body (compact form),\n - computes `HmacSHA256(client_id:timestamp:nonce:body, client_secret)`, and\n - injects `X-Auth-Client`, `X-Auth-Timestamp`, `X-Auth-Nonce`, `X-Auth-Signature`.\n\nYou never modify headers manually — just edit the body and hit send.\n\n## Conventions\n\n- **Amounts** are in *base units* (whole integers, no decimals). For USDT that's `1 USDT = 1_000_000` units. For BTC that's sats.\n- **`memo`** is only meaningful for chains that require a destination tag (e.g. Stellar). Omit it for Tron/Ethereum.\n- **`reference`** is caller-supplied and should be unique per action for safe retries / idempotency.\n- Most error responses follow RFC 7807 (`type`, `title`, `status`, `detail`, `correlation_id`, `timestamp`).\n\n## Folders\n\nEvery resource lives in its own folder. Happy-path requests come first, followed by list/filter endpoints, then action endpoints (`confirm`, `retry`, `cancel`, etc.).", "contact": { "name": "Bitnob", "url": "https://bitnob.com" }, "license": { "name": "Proprietary", "url": "https://bitnob.com/terms" } }, "servers": [ { "url": "https://api.bitnob.com", "description": "Production" } ], "security": [ { "BitnobHmacAuth": [] } ], "tags": [ { "name": "Identity", "description": "Authentication probe for verifying workspace credentials." }, { "name": "Balances", "description": "Wallet balances per currency for the authenticated workspace." }, { "name": "Addresses", "description": "On-chain deposit addresses for receiving crypto." }, { "name": "Withdrawals", "description": "On-chain withdrawals from workspace balance to an external wallet address." }, { "name": "Transactions", "description": "Unified transaction history across all movement types." }, { "name": "Exchange rates", "description": "Point-in-time conversion rates between supported currencies." }, { "name": "Trading", "description": "Spot trading: quotes, orders, scheduled DCA, and target (limit-style) orders." }, { "name": "Bulk transfers", "description": "Batched disbursements from CSV or inline items, with optional recurring schedules." }, { "name": "Virtual accounts", "description": "Dedicated NGN bank account numbers issued against a customer. Deposits credit your NGN balance." }, { "name": "Cards", "description": "Virtual and physical card issuance, funding, controls, and transactions. Amounts are in micro-units of `currency` (1 whole unit = 1,000,000 — e.g. $50.00 on a USD card is `50000000`)." }, { "name": "Lightning", "description": "Bitcoin Lightning invoices and payments." }, { "name": "Customers", "description": "Customer lifecycle + KYC geography helpers." }, { "name": "Beneficiaries", "description": "Saved crypto and fiat payout recipients." }, { "name": "Payouts", "description": "Fiat payouts to bank accounts and mobile money across supported countries. Flow: **quote → initialize → finalize**." } ], "paths": { "/api/whoami": { "get": { "tags": [ "Identity" ], "summary": "Who am I", "description": "Returns the workspace identity associated with the presented HMAC credentials. Useful as a first call to confirm keys, clock skew, and signature formula are all correct.", "operationId": "get_api_whoami", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Authenticated", "data": { "active": true, "active_company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "auth_method": "hmac", "client_id": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "client_name": "vaden travels", "environment": "sandbox", "permissions": null }, "timestamp": "2026-06-19T10:39:49.945108267Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/balances": { "get": { "tags": [ "Balances" ], "summary": "List balances", "description": "Returns a paginated balance snapshot per currency. Use it to display wallet balances or reconcile holdings.", "operationId": "get_api_balances", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Company balances retrieved successfully", "data": { "accounts": [ { "account_id": "d4bde299-c991-48c1-86f5-175ac0bb93bd", "account_number": "3968048558", "currency": "BTC", "ledger_balance": "0", "available_balance": "0", "ledger_balance_formatted": "0.0 BTC", "available_balance_formatted": "0.0 BTC", "created_at": "2026-05-14T22:10:20.074479+00:00" }, { "account_id": "c33d126d-07e2-43ae-893e-bd2dbb7a4337", "account_number": "3968048558", "currency": "USDC", "ledger_balance": "2995328", "available_balance": "2995328", "ledger_balance_formatted": "2.995328 USDC", "available_balance_formatted": "2.995328 USDC", "created_at": "2026-05-14T22:10:20.107985+00:00" }, { "account_id": "e2154020-2395-419d-b224-ebbaa2d93a3b", "account_number": "3968048558", "currency": "USDT", "ledger_balance": "5017200", "available_balance": "5017200", "ledger_balance_formatted": "5.0172 USDT", "available_balance_formatted": "5.0172 USDT", "created_at": "2026-05-14T22:10:20.139973+00:00" }, { "account_id": "a7dfd5e6-f5c8-4738-ab65-b5cf8f61e984", "account_number": "3968048558", "currency": "NGN", "ledger_balance": "0", "available_balance": "0", "ledger_balance_formatted": "0.0 NGN", "available_balance_formatted": "0.0 NGN", "created_at": "2026-06-04T07:35:05.574532+00:00" } ], "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a" }, "timestamp": "2026-06-19T10:39:50.811363982Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/balances/{currency}": { "get": { "tags": [ "Balances" ], "summary": "Get balance by currency", "description": "Single-currency balance (e.g. `USDT`, `BTC`, `USDC`). 404 if the workspace holds no wallet for that currency.", "operationId": "get_api_balances_currency", "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" }, "description": "currency identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Account balance retrieved successfully", "data": { "account_number": "3968048558", "available_balance": "5017200", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "currency": "USDT", "pending_balance": "0", "total_balance": "5017200" }, "timestamp": "2026-06-19T10:39:51.424374223Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses": { "post": { "tags": [ "Addresses" ], "summary": "Generate address", "description": "Provisions a deposit address for the given `chain`. Labels / references are caller metadata — they don't affect the wallet.", "operationId": "post_api_addresses", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Address generated successfully", "data": { "id": "019edf77-5761-78c7-a930-4918c2ba470a", "chain": "ethereum", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "address": "0x2a84e1D4eB75B5F7CFc0F00578d7a9641C8c4Dd8", "status": "active", "label": "test-address", "reference": "addr-1781865600" }, "timestamp": "2026-06-19T10:40:01.010497229Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain": { "type": "string", "example": "ethereum" }, "customer_id": { "type": "string", "example": "cust_abc123" }, "customer_email": { "type": "string", "example": "john@example.com" }, "label": { "type": "string", "example": "USDT deposit address" }, "reference": { "type": "string", "example": "ref-addr-001" } }, "required": [ "chain", "customer_id", "customer_email", "label", "reference" ] }, "example": { "chain": "ethereum", "label": "test-address", "reference": "addr-1781865600" } } } } }, "get": { "tags": [ "Addresses" ], "summary": "List addresses", "description": "Paginated list of all provisioned addresses across the workspace.", "operationId": "get_api_addresses", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Addresses retrieved successfully", "data": { "addresses": [ { "id": "019edf77-5761-78c7-a930-4918c2ba470a", "address": "0x2a84e1D4eB75B5F7CFc0F00578d7a9641C8c4Dd8", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-address", "chain": "ethereum", "status": "active", "created_at": "2026-06-19T10:40:00.865575Z", "reference": "addr-1781865600" }, { "id": "019edba8-0f16-762c-a701-401f305bb3dd", "address": "0xCb076A040337D74998759e253921a34202C6ffB2", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "USDT deposit address", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T16:54:44.758404Z", "reference": "ADDR_KW71LHGX639B7874L638YNJ85F2F07" }, { "id": "019edba1-6b31-7204-8c1d-7a15f4dcab96", "address": "0x53e619C1892AadbFE5a63E3000F3B377Cbba6Ccf", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "audit-eth", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T16:47:29.585132Z", "reference": "ADDR_9253b8598d7f" }, { "id": "019edb52-1eed-77b5-8cc3-95f96ae5e042", "address": "0x7d4f031358be8313591E1173cEf31e8Cf9877929", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-polygon", "chain": "polygon", "status": "active", "created_at": "2026-06-18T15:20:52.717505Z", "reference": "ADDR_580477ff14e2" }, { "id": "019edb52-1a8f-7583-8d1b-44bd7b0d21a7", "address": "0x15cc319a01a93efda5b198A79545b0165A25F631", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-optimism", "chain": "optimism", "status": "active", "created_at": "2026-06-18T15:20:51.599361Z", "reference": "ADDR_cc52b9f0815e" }, { "id": "019edb52-164a-7e6f-af0b-0847e5eff43c", "address": "0x7b5577067aA8317f3e50F98993F0981C975eC8f4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-ethereum", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T15:20:50.506946Z", "reference": "ADDR_3e94025f7fb6" }, { "id": "019edb51-7053-7d5f-bb64-c6d23378174e", "address": "0x6cd491913ec23a016ebE817aA6a895361f7801CC", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-base", "chain": "base", "status": "active", "created_at": "2026-06-18T15:20:08.019876Z", "reference": "ADDR_89b01f678379" }, { "id": "019edb51-6be9-7522-a53c-3f4ccf6158f8", "address": "0x3EC916E353C705ef90E4cdD5CF883BF094d5131d", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-avalanche", "chain": "avalanche", "status": "active", "created_at": "2026-06-18T15:20:06.889336Z", "reference": "ADDR_5fe03ba64e74" }, { "id": "019edb4f-5640-7055-b82e-e2bb739124a7", "address": "0xE4bED524CD17879072f25AcbB6BCcce0909d6dDf", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-eth", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T15:17:50.272022Z", "reference": "ADDR_94ae49c05fd0" }, { "id": "019edb4a-bded-7938-9b64-2d0f25b8e0d5", "address": "0xCc3635182D7c1a5e63224CDbe0DC3f004182e46a", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "USDT deposit address", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T15:12:49.133604Z", "reference": "ADDR_PK72IIBD0083001005350735" }, { "id": "019edb2d-b2bb-731c-bc9c-e754b0e0ded3", "address": "0xf5de0571D77576F638670Aef5b13c777C8F29238", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "USDT deposit address", "chain": "ethereum", "status": "active", "created_at": "2026-06-18T14:41:05.723204Z", "reference": "ADDR_SI25948234004090013" }, { "id": "019e842d-182b-7e78-a702-d25d7db87b21", "address": "0xDE931C2A75042EEd879Ed598dD5d55B5D5eDB3B9", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "t-optimism", "chain": "optimism", "status": "active", "created_at": "2026-06-01T17:13:28.363948Z", "reference": "tr-1780334007416868352-optimism" }, { "id": "019e842d-11ab-736c-a655-9e90cfa7e978", "address": "0x1E5D4c21Af9511064Afb3B10E7F601c7700535bB", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "t-avalanche", "chain": "avalanche", "status": "active", "created_at": "2026-06-01T17:13:26.699224Z", "reference": "tr-1780334005813816064-avalanche" }, { "id": "019e842d-0ae3-7d83-9069-981796c99c05", "address": "0x83b0892De9A84C8f6D439A8f46607Afd5BE20FBe", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "t-base", "chain": "base", "status": "active", "created_at": "2026-06-01T17:13:24.963885Z", "reference": "tr-1780334003768998144-base" }, { "id": "019e842d-03b5-720f-8eb3-70523e2b88c4", "address": "GC2W7P2HNP4QQEMUWP25EMJIUHV4DPJRBDLHECB4EODLLNELFS2ZXYMX", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "t-stellar", "chain": "stellar", "status": "active", "created_at": "2026-06-01T17:13:23.125135Z", "reference": "tr-1780334002332417280-stellar" }, { "id": "019e842b-41e5-7dac-9564-83de4d9aa33b", "address": "Gw2Hc9UvK8MwF5EgatdXMnW4ghjMnJq4So7s3Ymwezgk", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-solana", "chain": "solana", "status": "active", "created_at": "2026-06-01T17:11:27.973896Z", "reference": "test-addr-1780333887143947776-solana" }, { "id": "019e842b-3a0e-7f39-b682-62681bfeed58", "address": "0x5C88D76afD1BD43cd03C89ecEb1A8ccdA8F46dC4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-polygon", "chain": "polygon", "status": "active", "created_at": "2026-06-01T17:11:25.966997Z", "reference": "test-addr-1780333884928326400-polygon" }, { "id": "019e842b-2fc4-7634-bb92-7456cc5a3dc7", "address": "0x8377544EB6F9291f73e7e78407Bc36978eb28162", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-ethereum", "chain": "ethereum", "status": "active", "created_at": "2026-06-01T17:11:23.332406Z", "reference": "test-addr-1780333882435904000-ethereum" }, { "id": "019e560b-78f1-76af-aa48-98fc984e3702", "address": "0x36502198c2a38E535CC687e18b47A49f734F0fa3", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "ADDRESS::STATIC", "chain": "ethereum", "status": "active", "created_at": "2026-05-23T18:14:12.977438Z", "reference": "ADDR_ab6e7df42f25" } ], "next_cursor": "", "has_more": false }, "timestamp": "2026-06-19T10:40:01.677696254Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses/{id}": { "get": { "tags": [ "Addresses" ], "summary": "Get address by id", "description": "Single address by internal id. Useful when reconciling deposits back to a specific address record.", "operationId": "get_api_addresses_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Address retrieved successfully", "data": { "id": "019edf77-5761-78c7-a930-4918c2ba470a", "address": "0x2a84e1D4eB75B5F7CFc0F00578d7a9641C8c4Dd8", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "label": "test-address", "chain": "ethereum", "status": "active", "created_at": "2026-06-19T10:40:00.865575Z", "reference": "addr-1781865600" }, "timestamp": "2026-06-19T10:40:02.298371085Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/addresses/validate": { "post": { "tags": [ "Addresses" ], "summary": "Validate address", "description": "Structural validation for an external address + chain pair. Returns `{valid: true|false}`; does not verify on-chain existence.", "operationId": "post_api_addresses_validate", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Address validation completed", "data": { "valid": true, "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "chain": "ethereum" }, "timestamp": "2026-06-19T10:40:02.968832668Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "chain": { "type": "string", "example": "ethereum" } }, "required": [ "address", "chain" ] }, "example": { "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "chain": "ethereum" } } } } } }, "/api/stablecoins/supported-chains": { "get": { "tags": [ "Addresses" ], "summary": "Supported chains", "description": "Chains accepted by the address endpoints, including display names and precision.", "operationId": "get_api_addresses_supported_chains", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Supported chains retrieved successfully", "data": { "chains": [ { "chain": "avalanche", "native_token": { "symbol": "AVAX", "decimals": 18 }, "stablecoins": [ { "symbol": "USDT", "decimals": 6 }, { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "base", "native_token": { "symbol": "ETH", "decimals": 18 }, "stablecoins": [ { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "bitcoin", "native_token": { "symbol": "BTC", "decimals": 8 }, "stablecoins": [] }, { "chain": "ethereum", "native_token": { "symbol": "ETH", "decimals": 18 }, "stablecoins": [ { "symbol": "USDT", "decimals": 6 }, { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "optimism", "native_token": { "symbol": "ETH", "decimals": 18 }, "stablecoins": [ { "symbol": "USDT", "decimals": 6 }, { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "polygon", "native_token": { "symbol": "POL", "decimals": 18 }, "stablecoins": [ { "symbol": "USDT", "decimals": 6 }, { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "solana", "native_token": { "symbol": "SOL", "decimals": 9 }, "stablecoins": [ { "symbol": "USDT", "decimals": 6 }, { "symbol": "USDC", "decimals": 6 } ] }, { "chain": "stellar", "native_token": { "symbol": "XLM", "decimals": 7 }, "stablecoins": [ { "symbol": "USDC", "decimals": 6 } ] } ] }, "timestamp": "2026-06-19T10:40:04.611879891Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/withdrawals": { "post": { "tags": [ "Withdrawals" ], "summary": "Initiate withdrawal", "description": "Debits the workspace balance and broadcasts a transfer. `amount` is in base units (whole integer). `memo` only applies to chains requiring a destination tag (e.g. Stellar).", "operationId": "post_api_withdrawals", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "amount": { "type": "string", "example": "150500000" }, "currency": { "type": "string", "example": "USDT" }, "chain": { "type": "string", "example": "ethereum" }, "reference": { "type": "string", "example": "withdraw-ref-001" }, "description": { "type": "string", "example": "Vendor payment" } }, "required": [ "to_address", "amount", "currency", "chain", "reference", "description" ] }, "example": { "to_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "150500000", "currency": "USDT", "chain": "ethereum", "reference": "withdraw-ref-001", "description": "Vendor payment" } } } } } }, "/api/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "description": "Retrieves a paginated list of transactions, with support for filtering via query parameters. Commonly used to list transaction histories, audit flows, or search for specific transactions across various dimensions.", "operationId": "get_api_transactions", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "example": "completed" }, "description": "" }, { "name": "ascending", "in": "query", "required": false, "schema": { "type": "string", "example": "true" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Transactions retrieved successfully", "data": { "transactions": [ { "transaction_id": "41d289c8-63e2-489c-92b7-b2f45bde891b", "account_number": "3968048558", "currency": "USDC", "type": "CARD_TOPUP", "state": "SETTLED", "amount": "-3000000", "fee": "1000000", "reference": "8684473f-5493-4df0-8a4f-2a9e0ec28cc8", "idempotency_key": "", "trade_id": "", "metadata": { "base_amount": "3000000", "card_id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "3d470828-daf9-43c5-ba33-77b4d699363a", "fee_amount": "1000000", "operation": "fund", "provider_transaction_id": "mock_tx_824bcbf5-17e7-4acb-b62a-adb996d7abcd", "settled_at": "1779720770", "transaction_id": "078e0597-625f-44d5-b07f-51e0df130933", "tx_id": "078e0597-625f-44d5-b07f-51e0df130933", "type": "CARD_TOPUP" }, "created_at": "2026-05-25T14:52:50.484120+00:00", "updated_at": "2026-05-25T14:52:50.579181+00:00", "value_date": "2026-05-25", "amount_formatted": "-3.0 USDC", "fee_formatted": "1.0 USDC", "side": "Debit" }, { "transaction_id": "28be8827-fa87-45e6-87e9-d4497a73c789", "account_number": "3968048558", "currency": "USDC", "type": "TRADE_CREDIT", "state": "SETTLED", "amount": "4995328", "fee": "0", "reference": "16183126-3dd5-408a-88ca-8058a4deec17", "idempotency_key": "", "trade_id": "16183126-3dd5-408a-88ca-8058a4deec17", "metadata": { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "fill_id": "589bc6e8-51a1-4725-9637-dd9719895bff", "order_side": "Sell", "order_type": "standard", "settlement_type": "trade_credit" }, "created_at": "2026-05-25T14:52:19.516231+00:00", "updated_at": "2026-05-25T14:52:19.516231+00:00", "value_date": "2026-05-25", "amount_formatted": "4.995328 USDC", "fee_formatted": "0.0 USDC", "side": "Credit" }, { "transaction_id": "de1f83d4-e771-4937-b281-d39c48eb41e1", "account_number": "3968048558", "currency": "USDT", "type": "TRADE_DEBIT", "state": "SETTLED", "amount": "-5000000", "fee": "0", "reference": "16183126-3dd5-408a-88ca-8058a4deec17", "idempotency_key": "", "trade_id": "16183126-3dd5-408a-88ca-8058a4deec17", "metadata": { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "fill_id": "589bc6e8-51a1-4725-9637-dd9719895bff", "order_id": "16183126-3dd5-408a-88ca-8058a4deec17", "order_side": "Buy", "order_type": "standard", "settled_at": "2026-05-25T14:52:19.391211431+00:00" }, "created_at": "2026-05-25T14:52:19.269255+00:00", "updated_at": "2026-05-25T14:52:19.430068+00:00", "value_date": "2026-05-25", "amount_formatted": "-5.0 USDT", "fee_formatted": "0.0 USDT", "side": "Debit" } ], "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yNVQxNDo1MjoxOS4yNjkyNTVaIiwidHJhbnNhY3Rpb25faWQiOiJkZTFmODNkNC1lNzcxLTQ5MzctYjI4MS1kMzljNDhlYjQxZTEiLCJhc2NlbmRpbmciOmZhbHNlfQ==", "previous_cursor": "", "total_count": 10, "has_more": true }, "timestamp": "2026-06-19T10:40:05.927542085Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction by id", "description": "Single transaction envelope with full lifecycle metadata.", "operationId": "get_api_transactions_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Transaction retrieved successfully", "data": { "transaction_id": "41d289c8-63e2-489c-92b7-b2f45bde891b", "account_number": "3968048558", "currency": "USDC", "type": "CARD_TOPUP", "state": "SETTLED", "amount": "-4000000", "fee": "1000000", "reference": "8684473f-5493-4df0-8a4f-2a9e0ec28cc8", "idempotency_key": "", "trade_id": "", "metadata": { "base_amount": "3000000", "card_id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "3d470828-daf9-43c5-ba33-77b4d699363a", "fee_amount": "1000000", "operation": "fund", "provider_transaction_id": "mock_tx_824bcbf5-17e7-4acb-b62a-adb996d7abcd", "settled_at": "1779720770", "transaction_id": "078e0597-625f-44d5-b07f-51e0df130933", "tx_id": "078e0597-625f-44d5-b07f-51e0df130933", "type": "CARD_TOPUP" }, "created_at": "2026-05-25T14:52:50.484120+00:00", "updated_at": "2026-05-25T14:52:50.579181+00:00", "value_date": "2026-05-25", "amount_formatted": "-4.0 USDC", "fee_formatted": "1.0 USDC", "side": "Debit" }, "timestamp": "2026-06-19T10:40:06.83128084Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/exchange-rates": { "get": { "tags": [ "Exchange rates" ], "summary": "Get single-pair rate", "description": "Mid-market rate for `from`→`to`.", "operationId": "get_api_exchange_rates", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "USDT" }, "description": "" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "NGN" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "examples": { "single_pair": { "summary": "Single pair (?from=USDT&to=NGN)", "value": { "success": true, "message": "Exchange rate retrieved", "data": { "base_currency": "USDT", "target_currency": "NGN", "buy_rate": "1389.41998218", "sell_rate": "1375.59771120", "mid_rate": "1382.50884669", "inverse_rate": "0.00072696", "timestamp": "2026-06-19T10:39:17Z", "valid_for_seconds": 300, "percent_change_24h": "0.00" }, "timestamp": "2026-06-19T10:39:51.990280895Z" } }, "list": { "summary": "All rates for a base (?base=USDT)", "value": { "success": true, "message": "Exchange rates retrieved", "data": { "base_currency": "USDT", "rates": [ { "target_currency": "USDC", "buy_rate": "1.00324756", "sell_rate": "0.99525356", "inverse_rate": "1.00476908", "percent_change_24h": "0.00" }, { "target_currency": "USD", "buy_rate": "1.00400000", "sell_rate": "0.99600000", "inverse_rate": "1.00401606", "percent_change_24h": "0.00" }, { "target_currency": "NGN", "buy_rate": "1389.41998218", "sell_rate": "1375.59771120", "inverse_rate": "0.00072696", "percent_change_24h": "0.00" }, { "target_currency": "RWF", "buy_rate": "1435.21578016", "sell_rate": "1420.93792200", "inverse_rate": "0.00070376", "percent_change_24h": "0.00" }, { "target_currency": "MWK", "buy_rate": "1881.23496000", "sell_rate": "1862.52000000", "inverse_rate": "0.00053691", "percent_change_24h": "0.00" }, { "target_currency": "MAD", "buy_rate": "9.15527640", "sell_rate": "9.06419760", "inverse_rate": "0.11032416", "percent_change_24h": "0.00" }, { "target_currency": "BTC", "buy_rate": "0.00001608", "sell_rate": "0.00001595", "inverse_rate": "62686.19477895", "percent_change_24h": "0.00" }, { "target_currency": "KES", "buy_rate": "129.51548194", "sell_rate": "128.22703200", "inverse_rate": "0.00779867", "percent_change_24h": "0.00" }, { "target_currency": "UGX", "buy_rate": "3603.47669345", "sell_rate": "3567.62847480", "inverse_rate": "0.00028030", "percent_change_24h": "0.00" }, { "target_currency": "GHS", "buy_rate": "12.04101035", "sell_rate": "11.92122360", "inverse_rate": "0.08388401", "percent_change_24h": "0.00" }, { "target_currency": "ZAR", "buy_rate": "16.49702219", "sell_rate": "16.33290600", "inverse_rate": "0.06122609", "percent_change_24h": "0.00" }, { "target_currency": "TZS", "buy_rate": "2674.77407040", "sell_rate": "2648.16480000", "inverse_rate": "0.00037762", "percent_change_24h": "0.00" }, { "target_currency": "GNF", "buy_rate": "9563.11204800", "sell_rate": "9467.97600000", "inverse_rate": "0.00010562", "percent_change_24h": "0.00" }, { "target_currency": "CFA", "buy_rate": "567.67421827", "sell_rate": "562.02686400", "inverse_rate": "0.00177927", "percent_change_24h": "0.00" }, { "target_currency": "XAF", "buy_rate": "587.50867200", "sell_rate": "581.66400000", "inverse_rate": "0.00171921", "percent_change_24h": "0.00" }, { "target_currency": "ZMW", "buy_rate": "18.59434767", "sell_rate": "18.40936680", "inverse_rate": "0.05432017", "percent_change_24h": "0.00" }, { "target_currency": "GMD", "buy_rate": "72.54021886", "sell_rate": "71.81857200", "inverse_rate": "0.01392397", "percent_change_24h": "0.00" }, { "target_currency": "CDF", "buy_rate": "2306.72996703", "sell_rate": "2283.78208440", "inverse_rate": "0.00043787", "percent_change_24h": "0.00" }, { "target_currency": "XOF", "buy_rate": "580.74829824", "sell_rate": "574.97088000", "inverse_rate": "0.00173922", "percent_change_24h": "0.00" }, { "target_currency": "EGP", "buy_rate": "48.41624762", "sell_rate": "47.93459160", "inverse_rate": "0.02086176", "percent_change_24h": "0.00" }, { "target_currency": "SLE", "buy_rate": "23.46413059", "sell_rate": "23.23070400", "inverse_rate": "0.04304648", "percent_change_24h": "0.00" }, { "target_currency": "ETB", "buy_rate": "150.54135094", "sell_rate": "149.04373080", "inverse_rate": "0.00670944", "percent_change_24h": "0.00" } ], "timestamp": "2026-06-19T10:39:17Z", "skipped_currencies": [ "GBP: rate not available: GBP", "EUR: rate not available: EUR" ] }, "timestamp": "2026-06-19T10:39:52.616058133Z" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/exchange-rates/convert": { "get": { "tags": [ "Exchange rates" ], "summary": "Convert amount", "description": "Applies the current rate to `amount` (in `from` display units) and returns the converted value + effective rate.", "operationId": "get_api_exchange_rates_convert", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "USDT" }, "description": "" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "example": "NGN" }, "description": "" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "example": "100" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Amount converted", "data": { "from_currency": "USDT", "to_currency": "NGN", "from_amount": "100", "to_amount": "137559.77112", "rate_used": "1375.59771120", "timestamp": "2026-06-19T10:39:17Z" }, "timestamp": "2026-06-19T10:39:53.318011355Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/prices": { "get": { "tags": [ "Trading" ], "summary": "List all prices", "description": "Returns every available pair with its current mid-price.", "operationId": "get_api_trading_prices", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "examples": { "all_prices": { "summary": "All prices (no query)", "value": { "success": true, "message": "Prices retrieved successfully", "data": { "prices": [ { "base_currency": "BTC", "quote_currency": "USDT", "price": "62417.750", "as_of": "2026-06-19T10:46:51.580595150Z" }, { "base_currency": "USDC", "quote_currency": "USDT", "price": "1.000650", "as_of": "2026-06-19T10:46:51.577466470Z" }, { "base_currency": "BTC", "quote_currency": "USDC", "price": "62376.84500000", "as_of": "2026-06-19T10:46:51.670952569Z" } ] }, "timestamp": "2026-06-19T10:46:51.705593374Z" } }, "by_pair": { "summary": "Single pair (?base_currency=BTC"e_currency=USDT)", "value": { "success": true, "message": "Price retrieved successfully", "data": { "price": { "base_currency": "BTC", "quote_currency": "USDT", "price": "62460.650", "as_of": "2026-06-19T10:50:02.880752101Z" } }, "timestamp": "2026-06-19T10:50:02.922017174Z" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/prices/{pair}": { "get": { "tags": [ "Trading" ], "summary": "Get price by pair", "description": "Spot price for a single pair (e.g. `BTCUSD`, `ETHUSD`).", "operationId": "get_api_trading_prices_pair", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pair identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/quotes": { "post": { "tags": [ "Trading" ], "summary": "Create quote", "description": "Requests a locked quote for a BUY or SELL. The returned `quote_id` must be submitted with a matching order before it expires. NGN (Fiat Trading) pairs are supported; see the fiatTradingNgn example.", "operationId": "post_api_trading_quotes", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Quote retrieved successfully", "data": { "quote": { "id": "ebdb4c91-9180-4cee-8e45-08ca96561d45", "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.001", "price": "62502.397625", "expires_at": "2026-06-19T10:51:49.848650039Z", "created_at": "2026-06-19T10:46:52.848650229Z", "original_quantity": "0.001", "consumed_quantity": "0", "remaining_quantity": "0.001", "is_exhausted": false, "exchange": { "send_quantity": "62.502398", "send_currency": "USDT", "receive_quantity": "0.001", "receive_currency": "BTC" } } }, "timestamp": "2026-06-19T10:46:52.85245707Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.05" }, "quantity_in_base_units": { "type": "boolean" } }, "required": [ "base_currency", "quote_currency", "side", "quantity" ] }, "examples": { "crypto": { "summary": "Crypto pair (BTC/USDT)", "value": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.001" } }, "fiatTradingNgn": { "summary": "Fiat Trading — NGN → USDT", "value": { "base_currency": "NGN", "quote_currency": "USDT", "side": "SELL", "quantity": "500" } } } } } } } }, "/api/trading/quotes/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get quote status", "description": "Check remaining TTL and fulfilment state for an outstanding quote.", "operationId": "get_api_trading_quotes_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Quote status retrieved successfully", "data": { "quote_id": "7c89c962-535b-4860-9b77-499580523299", "original_quantity": "0.00002000", "consumed_quantity": "0", "remaining_quantity": "0.00002000", "price": "62701.15567500", "expires_at": "2026-06-19T11:58:20.346923000Z", "is_expired": false, "is_exhausted": false, "consumption_count": "0" }, "timestamp": "2026-06-19T11:53:21.142152573Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/orders": { "post": { "tags": [ "Trading" ], "summary": "Submit order", "description": "Execute a BUY or SELL. Supply the `quote_id` from a fresh quote for best pricing. NGN (Fiat Trading) pairs are supported; see the fiatTradingNgn example.", "operationId": "post_api_trading_orders", "responses": { "200": { "description": "Successful response" }, "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Order submitted successfully", "data": { "order": { "id": "19f1a289-ee9a-4ea4-a305-9bbeef5d65d6", "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "order_type": "limit", "quantity": "0.00002", "price": "62732.69662500", "status": "pending", "created_at": "2026-06-19T11:24:37.773209979Z", "updated_at": "2026-06-19T11:24:37.773209979Z", "filled_quantity": "0.00002", "remaining_quantity": "0", "quote_id": "fd4e18d5-7075-458f-b333-cab9ae490b03", "reference": "order-1781868277" }, "fills": [ { "id": "6ad2659c-b94d-4a97-abf0-87d829acef04", "order_id": "19f1a289-ee9a-4ea4-a305-9bbeef5d65d6", "counterparty_order_id": "", "quantity": "0.00002", "created_at": "2026-06-19T11:24:38.491864071Z" } ], "quote_consumption": { "quote_id": "fd4e18d5-7075-458f-b333-cab9ae490b03", "consumed_quantity": "0.00002", "remaining_quantity": "0", "is_exhausted": true } }, "timestamp": "2026-06-19T11:24:38.520718534Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.05" }, "quote_id": { "type": "string", "example": "{{quote_id}}" }, "reference": { "type": "string", "example": "order-ref-001" }, "price": { "type": "string", "example": "0.00071644" }, "quantity_in_base_units": { "type": "boolean", "example": false } }, "required": [ "base_currency", "quote_currency", "side", "quantity", "quote_id", "reference" ] }, "examples": { "crypto": { "summary": "Crypto pair (BTC/USDT)", "value": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.00002", "quote_id": "fd4e18d5-7075-458f-b333-cab9ae490b03", "reference": "order-1781868277" } }, "fiatTradingNgn": { "summary": "Fiat Trading — NGN → USDT", "value": { "base_currency": "NGN", "quote_currency": "USDT", "side": "SELL", "quantity": "500", "price": "0.00071644", "quote_id": "019f90ed-d7da-7e55-b4ca-9b26b4a75a13", "quantity_in_base_units": false, "reference": "SWAP_HR8407809450082600756" } } } } } } }, "get": { "tags": [ "Trading" ], "summary": "List orders", "description": "Paginated order history with optional filters.", "operationId": "get_api_trading_orders", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "example": "filled" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Orders retrieved successfully", "data": { "orders": [ { "id": "16183126-3dd5-408a-88ca-8058a4deec17", "base_currency": "USDT", "quote_currency": "USDC", "side": "SELL", "order_type": "limit", "quantity": "5", "price": "1.00093517", "status": "cancelled", "created_at": "2026-05-25T14:52:18.904607000Z", "updated_at": "2026-06-18T15:55:39.211899000Z", "filled_quantity": "4.9999994808857600", "remaining_quantity": "0", "quote_id": "", "reference": "16183126-3dd5-408a-88ca-8058a4deec17" }, { "id": "d9c20515-0329-444c-9a67-e84f89f42e0a", "base_currency": "USDT", "quote_currency": "USDC", "side": "SELL", "order_type": "limit", "quantity": "10", "price": "1.00093517", "status": "filled", "created_at": "2026-05-25T14:44:30.992400000Z", "updated_at": "2026-05-25T14:44:32.251005000Z", "filled_quantity": "9.0084165300000000", "remaining_quantity": "0.9915834327066900", "quote_id": "c80918d8-964e-4c8a-af17-9b4f5a0523e0", "reference": "d9c20515-0329-444c-9a67-e84f89f42e0a" }, { "id": "54c354ba-cb3a-4cff-a995-5eff9feee37d", "base_currency": "USDC", "quote_currency": "USDT", "side": "SELL", "order_type": "limit", "quantity": "20.00000000", "price": "1.00061478", "status": "filled", "created_at": "2026-05-23T18:18:06.404310000Z", "updated_at": "2026-05-23T18:18:07.377607000Z", "filled_quantity": "20.00000000", "remaining_quantity": "0", "quote_id": "19c44dc8-b0d5-4777-a452-ed2a0fe84549", "reference": "54c354ba-cb3a-4cff-a995-5eff9feee37d" } ], "total_count": "3", "has_more": false, "next_cursor": "" }, "timestamp": "2026-06-19T10:46:53.757762926Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get order by id or reference", "description": "Fetch an individual order by its id or your supplied reference.", "operationId": "get_api_trading_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Order retrieved successfully", "data": { "order": { "id": "19f1a289-ee9a-4ea4-a305-9bbeef5d65d6", "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "order_type": "limit", "quantity": "0.00002000", "price": "62732.69662500", "status": "pending", "created_at": "2026-06-19T11:24:37.773209000Z", "updated_at": "2026-06-19T11:24:38.515528000Z", "filled_quantity": "0.00002000", "remaining_quantity": "0", "quote_id": "fd4e18d5-7075-458f-b333-cab9ae490b03", "reference": "order-1781868277" } }, "timestamp": "2026-06-19T11:24:39.086668061Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Trading" ], "summary": "Cancel order", "description": "Cancel an open order by its ID or reference.", "operationId": "cancelTradingOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Order cancelled", "content": { "application/json": { "example": { "success": true, "message": "Order cancelled successfully", "data": { "order": { "id": "19f1a289-ee9a-4ea4-a305-9bbeef5d65d6", "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "order_type": "limit", "quantity": "0.00002000", "price": "62732.69662500", "status": "cancelled", "created_at": "2026-06-19T11:24:37.773209000Z", "updated_at": "2026-06-19T11:24:40.418249000Z", "filled_quantity": "0.00002000", "remaining_quantity": "0", "quote_id": "", "reference": "order-1781868277" } }, "timestamp": "2026-06-19T11:24:40.444335629Z" } } } } } } }, "/api/trading/scheduled-orders": { "post": { "tags": [ "Trading" ], "summary": "Create scheduled order", "description": "Creates a recurring buy/sell on a `daily`, `weekly`, or `monthly` cadence.", "operationId": "post_api_trading_scheduled_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "amount": { "type": "string", "example": "50000000" }, "frequency": { "type": "string", "example": "weekly" }, "day_of_week": { "type": "integer" }, "execution_time": { "type": "string", "example": "09:00" }, "reference": { "type": "string", "example": "dca-ref-001" } }, "required": [ "currency", "quote_currency", "amount", "frequency", "day_of_week", "execution_time", "reference" ] }, "example": { "currency": "BTC", "quote_currency": "USDT", "amount": "50000000", "frequency": "weekly", "day_of_week": 1, "execution_time": "09:00", "reference": "dca-ref-001" } } } } }, "get": { "tags": [ "Trading" ], "summary": "List scheduled orders", "description": "All scheduled orders for the workspace.", "operationId": "get_api_trading_scheduled_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/scheduled-orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get scheduled order", "description": "Details for a single recurring order.", "operationId": "get_api_trading_scheduled_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Trading" ], "summary": "Update scheduled order", "description": "Mutate amount, cadence, or status. Pass `status: paused` to halt future executions without cancelling.", "operationId": "put_api_trading_scheduled_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "example": "200000000" }, "status": { "type": "string", "example": "paused" }, "execution_time": { "type": "string", "example": "10:00" } }, "required": [ "amount", "status", "execution_time" ] }, "example": { "amount": "200000000", "status": "paused", "execution_time": "10:00" } } } } } }, "/api/trading/scheduled-orders/{id}/executions": { "get": { "tags": [ "Trading" ], "summary": "List scheduled-order executions", "description": "Execution log for a scheduled order.", "operationId": "get_api_trading_scheduled_orders_id_executions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/target-orders": { "post": { "tags": [ "Trading" ], "summary": "Create target order", "description": "Creates a target order that fires when `target_price` is met. Optionally set `expires_at` to auto-cancel.", "operationId": "post_api_trading_target_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_currency": { "type": "string", "example": "BTC" }, "quote_currency": { "type": "string", "example": "USDT" }, "side": { "type": "string", "example": "BUY" }, "quantity": { "type": "string", "example": "0.10" }, "target_price": { "type": "string", "example": "60000.00" }, "expires_at": { "type": "string", "example": "" }, "reference": { "type": "string", "example": "target-ref-001" } }, "required": [ "base_currency", "quote_currency", "side", "quantity", "target_price", "reference" ] }, "example": { "base_currency": "BTC", "quote_currency": "USDT", "side": "BUY", "quantity": "0.10", "target_price": "60000.00", "expires_at": "", "reference": "target-ref-001" } } } } }, "get": { "tags": [ "Trading" ], "summary": "List target orders", "description": "All target orders, filterable by status.", "operationId": "get_api_trading_target_orders", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/trading/target-orders/{id}": { "get": { "tags": [ "Trading" ], "summary": "Get target order", "description": "Details for a single target order.", "operationId": "get_api_trading_target_orders_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers": { "post": { "tags": [ "Bulk transfers" ], "summary": "Create draft batch", "description": "Creates a draft with inline items. Amounts are in base units.", "operationId": "post_api_bulk_transfers", "responses": { "200": { "description": "Successful response" }, "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer draft created successfully", "data": { "batch": { "id": "019edf7e-e18d-75e5-a339-3c58967a37a3", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "March payroll batch", "status": "draft", "total_items": 1, "success_count": 0, "failed_count": 0, "created_at": "2026-06-19T10:48:14.991283525Z", "submitted_at": "", "completed_at": "" }, "items": [ { "id": "019edf7e-e18d-75ef-8f44-43de117656ab", "batch_id": "019edf7e-e18d-75e5-a339-3c58967a37a3", "row_index": 1, "chain": "ethereum", "currency": "USDT", "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "1", "description": "payout", "status": "pending", "failure_reason": "", "retries": 0, "withdrawal_id": "" } ] }, "timestamp": "2026-06-19T10:48:15.001010438Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "March payroll batch" }, "items": { "type": "array", "items": { "type": "object", "properties": { "row_index": { "type": "integer" }, "chain": { "type": "string", "example": "ethereum" }, "currency": { "type": "string", "example": "USDT" }, "address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "amount": { "type": "string", "example": "100000000" }, "reference": { "type": "string", "example": "bulk-item-1" } }, "required": [ "row_index", "chain", "currency", "address", "amount", "reference" ] } } }, "required": [ "description", "items" ] }, "example": { "description": "March payroll batch", "items": [ { "row_index": 1, "chain": "ethereum", "currency": "USDT", "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "1", "description": "payout" } ] } } } } }, "get": { "tags": [ "Bulk transfers" ], "summary": "List batches", "description": "Paginated batch history.", "operationId": "get_api_bulk_transfers", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfers retrieved successfully", "data": { "batches": [ { "id": "019edbc7-445b-724e-93a0-3e903e14d6ee", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "Docs sample batch", "status": "draft", "total_items": 1, "success_count": 0, "failed_count": 0, "created_at": "2026-06-18T17:28:50.016413Z", "submitted_at": "", "completed_at": "" }, { "id": "019edbba-a534-7c1a-9f32-c0be4b403516", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "audit draft", "status": "draft", "total_items": 1, "success_count": 0, "failed_count": 0, "created_at": "2026-06-18T17:15:02.84441Z", "submitted_at": "", "completed_at": "" }, { "id": "019edb3b-3c7a-7875-be2e-043fd58cfa79", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "March payroll batch", "status": "draft", "total_items": 2, "success_count": 0, "failed_count": 0, "created_at": "2026-06-18T14:55:52.963515Z", "submitted_at": "", "completed_at": "" } ], "next_page_token": "" }, "timestamp": "2026-06-19T10:46:57.751333739Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/upload-urls": { "post": { "tags": [ "Bulk transfers" ], "summary": "Get upload URL (S3 presigned)", "description": "Returns a presigned PUT URL for uploading a CSV. Upload directly to S3, then call **Preview uploaded file** with the returned `upload_id`.", "operationId": "post_api_bulk_transfers_upload_urls", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "example": "payroll.csv" } }, "required": [ "filename" ] }, "example": { "filename": "payroll.csv" } } } } } }, "/api/bulk-transfers/previews": { "post": { "tags": [ "Bulk transfers" ], "summary": "Preview uploaded file", "description": "Parses and validates the uploaded CSV, returning row-level status before confirmation.", "operationId": "post_api_bulk_transfers_previews", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string", "example": "{{upload_id}}" } }, "required": [ "upload_id" ] }, "example": { "upload_id": "{{upload_id}}" } } } } } }, "/api/bulk-transfers/{batchId}": { "get": { "tags": [ "Bulk transfers" ], "summary": "Get batch", "description": "Single batch with per-item status.", "operationId": "get_api_bulk_transfers_batchId", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer retrieved successfully", "data": { "batch": { "id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "Docs verified batch", "status": "processing", "total_items": 1, "success_count": 0, "failed_count": 0, "created_at": "2026-06-19T11:23:12.045402Z", "submitted_at": "2026-06-19T11:23:12.851565Z", "completed_at": "" }, "items": [ { "id": "019edf9e-e12b-735c-85ea-7ebd7f76f778", "batch_id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "row_index": 1, "chain": "ethereum", "currency": "USDT", "address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "amount": "1", "description": "verify", "status": "pending", "failure_reason": "", "retries": 0, "withdrawal_id": "" } ] }, "timestamp": "2026-06-19T11:23:13.665366937Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/{batchId}/confirm": { "post": { "tags": [ "Bulk transfers" ], "summary": "Confirm batch", "description": "Promotes a draft batch to execution. Irreversible — funds are debited.", "operationId": "post_api_bulk_transfers_batchId_confirm", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer confirmed successfully", "data": { "batch": { "id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "description": "Docs verified batch", "status": "processing", "total_items": 1, "success_count": 0, "failed_count": 0, "created_at": "2026-06-19T11:23:12.045402Z", "submitted_at": "2026-06-19T11:23:12.851565556Z", "completed_at": "" } }, "timestamp": "2026-06-19T11:23:12.856906512Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/bulk-transfers/{batchId}/retry": { "post": { "tags": [ "Bulk transfers" ], "summary": "Retry failed items", "description": "Retries only the listed item ids within a partially-failed batch.", "operationId": "post_api_bulk_transfers_batchId_retry", "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "batchId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item_ids": { "type": "array", "items": { "type": "string", "example": "item-uuid-1" } } }, "required": [ "item_ids" ] }, "example": { "item_ids": [ "item-uuid-1", "item-uuid-2" ] } } } } } }, "/api/bulk-transfers/schedules": { "post": { "tags": [ "Bulk transfers" ], "summary": "Create schedule", "description": "Clones `template_batch_id` on the given cadence. Leave `end_date` empty for open-ended.", "operationId": "post_api_bulk_transfers_schedules", "responses": { "200": { "description": "Successful response" }, "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer schedule created successfully", "data": { "schedule": { "id": "019edfba-a069-71bc-992f-d778a4a3f685", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "template_batch_id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "frequency": "weekly", "execution_time": "09:00", "day_of_week": 1, "day_of_month": 0, "start_date": "2026-07-01", "end_date": "", "next_run_at": "2026-07-01T09:00:00Z", "status": "active", "created_at": "2026-06-19T11:53:30.473116012Z", "updated_at": "2026-06-19T11:53:30.473116012Z" } }, "timestamp": "2026-06-19T11:53:30.482716971Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_batch_id": { "type": "string", "example": "batch_template_1" }, "frequency": { "type": "string", "example": "weekly" }, "execution_time": { "type": "string", "example": "09:00" }, "day_of_week": { "type": "integer" }, "day_of_month": { "type": "integer" }, "start_date": { "type": "string", "format": "date", "example": "2026-05-01" }, "end_date": { "type": "string", "example": "" } }, "required": [ "template_batch_id", "frequency", "execution_time", "day_of_week", "start_date" ] }, "example": { "template_batch_id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "frequency": "weekly", "execution_time": "09:00", "day_of_week": 1, "day_of_month": 0, "start_date": "2026-07-01", "end_date": "" } } } } }, "get": { "tags": [ "Bulk transfers" ], "summary": "List schedules", "description": "All active and paused schedules.", "operationId": "get_api_bulk_transfers_schedules", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/schedules/{scheduleId}": { "put": { "tags": [ "Bulk transfers" ], "summary": "Update schedule", "description": "Mutate cadence, execution window, or pause/resume via `status`.", "operationId": "put_api_bulk_transfers_schedules_scheduleId", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "scheduleId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer schedule updated successfully", "data": { "schedule": { "id": "019edfba-a069-71bc-992f-d778a4a3f685", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "template_batch_id": "019edf9e-e12b-734d-abb3-a9377dd2bd0d", "frequency": "weekly", "execution_time": "10:00", "day_of_week": 1, "day_of_month": 0, "start_date": "2026-07-01", "end_date": "", "next_run_at": "2026-07-01T09:00:00Z", "status": "paused", "created_at": "2026-06-19T11:53:30.473116Z", "updated_at": "2026-06-19T11:54:11.749895763Z" } }, "timestamp": "2026-06-19T11:54:11.755260825Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "paused" }, "execution_time": { "type": "string", "example": "10:00" }, "day_of_week": { "type": "integer" }, "day_of_month": { "type": "integer" }, "end_date": { "type": "string", "example": "" } }, "required": [ "status", "execution_time", "day_of_week" ] }, "example": { "status": "paused", "execution_time": "10:00", "day_of_week": 1, "day_of_month": 0, "end_date": "" } } } } } }, "/api/bulk-transfers/schedules/{scheduleId}/executions": { "get": { "tags": [ "Bulk transfers" ], "summary": "List schedule executions", "description": "Execution history for a schedule. Each execution resolves to a concrete batch id.", "operationId": "get_api_bulk_transfers_schedules_scheduleId_executions", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "scheduleId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Bulk transfer executions retrieved successfully", "data": { "executions": [], "next_page_token": "" }, "timestamp": "2026-06-19T11:54:12.481462097Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/bulk-transfers/executions/{executionId}/retry": { "post": { "tags": [ "Bulk transfers" ], "summary": "Retry failed execution", "description": "Retries an execution that failed partway. No-op if already completed.", "operationId": "post_api_bulk_transfers_executions_executionId_retry", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "executionId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/virtual-accounts": { "post": { "tags": [ "Virtual accounts" ], "summary": "Create virtual account", "description": "Issues a dedicated Nigerian bank account number for a customer. Deposits into it credit your NGN balance. `reference` is the idempotency key: reusing a value returns the existing account rather than issuing a second one. The customer must already carry a BVN (`id_type` of `bvn`), date of birth and contact details, or the call fails with a validation error naming every missing field at once.", "operationId": "post_api_virtual_accounts", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Virtual account created successfully", "data": { "virtual_account": { "id": "019fe85f-86dc-7552-ba26-fe68591893a4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900007492815", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_1786310001", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Optional display name", "account_type": "individual", "created_at": "2026-08-09T21:13:22Z", "updated_at": "2026-08-09T21:13:22Z" } }, "timestamp": "2026-08-09T21:13:22.411398413Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "example": "NGN_ACCT_0f3a9c21" }, "currency": { "type": "string", "example": "NGN" }, "customer_id": { "type": "string", "example": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f" }, "account_alias": { "type": "string", "example": "Optional display name" } }, "required": [ "reference", "currency", "customer_id" ] }, "example": { "reference": "NGN_ACCT_0f3a9c21", "currency": "NGN", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "account_alias": "Optional display name" } } } } }, "get": { "tags": [ "Virtual accounts" ], "summary": "List virtual accounts", "description": "Every virtual account issued under your company. Paging is nested under `page_info`.", "operationId": "get_api_virtual_accounts", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Virtual accounts retrieved successfully", "data": { "virtual_accounts": [ { "id": "019fe85f-86dc-7552-ba26-fe68591893a4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900007492815", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_1786310001", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Payments Collection", "account_type": "individual", "created_at": "2026-08-09T21:13:22Z", "updated_at": "2026-08-09T21:13:24Z" }, { "id": "019fe85e-cc2f-7ca3-b286-42e74347589d", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900091471973", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PM_1786309953", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Postman test", "account_type": "individual", "created_at": "2026-08-09T21:12:34Z", "updated_at": "2026-08-09T21:12:34Z" }, { "id": "019fe832-132e-76a4-824b-bb50569add17", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900007462489", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_BVN_1786307019", "customer_id": "019fe832-10cf-7242-9ec7-3d688e97e8ee", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:43Z", "updated_at": "2026-08-09T20:23:43Z" }, { "id": "019fe831-846f-7847-a026-50572d4585c5", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900065726089", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH6_1786306983", "customer_id": "019fe831-21f8-7c59-81b1-5322271b4afe", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:07Z", "updated_at": "2026-08-09T20:23:07Z" }, { "id": "019fe831-81cf-7975-bff2-54541baa9889", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900099084215", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH5_1786306983", "customer_id": "019fe831-1f9c-71e1-9d41-d20894cbff09", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:06Z", "updated_at": "2026-08-09T20:23:06Z" }, { "id": "019fe831-7ee3-74b0-b346-a734ed71db10", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900095366249", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH4_1786306983", "customer_id": "019fe831-1ccc-7a58-ad58-f9207cab7896", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:05Z", "updated_at": "2026-08-09T20:23:05Z" }, { "id": "019fe831-7c8d-7411-8183-b91bcb6f3145", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900048099423", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH3_1786306983", "customer_id": "019fe831-1a79-7248-ad4b-b40e66dde325", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:05Z", "updated_at": "2026-08-09T20:23:05Z" }, { "id": "019fe831-7a1a-7554-9951-d71c885bf2f2", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900067447903", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH2_1786306983", "customer_id": "019fe831-17fe-7f2f-be6c-b72dd4591d84", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:04Z", "updated_at": "2026-08-09T20:23:04Z" }, { "id": "019fe831-7780-70df-b0d0-1367f61680ce", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900081268174", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_PH1_1786306983", "customer_id": "019fe831-1507-7897-baf1-c3d9ada9f138", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:23:03Z", "updated_at": "2026-08-09T20:23:03Z" }, { "id": "019fe82c-9417-75e3-adcf-02332b93e00e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900035297373", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_noalias_1786306662", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Ada Okafor", "account_type": "individual", "created_at": "2026-08-09T20:17:43Z", "updated_at": "2026-08-09T20:17:43Z" }, { "id": "019fe82c-8ede-794a-bf33-6cff4c222743", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900053614803", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_retest_1786306661", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Renamed via Postman", "account_type": "individual", "created_at": "2026-08-09T20:17:42Z", "updated_at": "2026-08-09T21:12:35Z" }, { "id": "019fe827-ca09-7ed3-b9f1-041f03ed12a9", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900024920451", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_flowtest_1786306348", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Optional display name", "account_type": "individual", "created_at": "2026-08-09T20:12:29Z", "updated_at": "2026-08-09T20:12:29Z" }, { "id": "019fe7d6-1e02-7235-a711-a11b41fe3a5a", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900001343855", "account_name": "Emmanuel Daniels", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_doctest_1786300996_019fd194", "customer_id": "019fd194-7c16-74a2-899a-a5f07336560e", "currency": "NGN", "status": "active", "account_alias": "Payments Collection", "account_type": "individual", "created_at": "2026-08-09T18:43:17Z", "updated_at": "2026-08-09T18:43:49Z" } ], "page_info": { "has_next_page": false, "has_previous_page": false, "total": 13 } }, "timestamp": "2026-08-09T21:13:25.479924666Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/virtual-accounts/supported-currencies": { "get": { "tags": [ "Virtual accounts" ], "summary": "Supported currencies", "description": "Currencies you can currently issue virtual accounts in. Returns NGN only today.", "operationId": "get_api_virtual_accounts_supported_currencies", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Supported currencies retrieved successfully", "data": { "currencies": [ "NGN" ], "total": 1, "limit": 20, "offset": 0 }, "timestamp": "2026-08-09T21:13:26.03958539Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/virtual-accounts/{id}": { "get": { "tags": [ "Virtual accounts" ], "summary": "Get virtual account", "description": "Fetches a single virtual account by its id.", "operationId": "get_api_virtual_accounts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "virtual account identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Virtual account retrieved successfully", "data": { "virtual_account": { "id": "019fe85f-86dc-7552-ba26-fe68591893a4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900007492815", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_1786310001", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Payments Collection", "account_type": "individual", "created_at": "2026-08-09T21:13:22Z", "updated_at": "2026-08-09T21:13:24Z" } }, "timestamp": "2026-08-09T21:13:24.942852888Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/virtual-accounts/{id}/transactions": { "get": { "tags": [ "Virtual accounts" ], "summary": "Get account transactions", "description": "Deposits paid into one account. Paging is flat (`total`, `limit`, `offset`), unlike List which nests `page_info`.", "operationId": "get_api_virtual_accounts_id_transactions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "virtual account identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Transactions retrieved successfully", "data": { "transactions": [ { "id": "019fe85f-89cc-7b9e-a42b-07fc78089499", "virtual_account_id": "019fe85f-86dc-7552-ba26-fe68591893a4", "provider_transaction_id": "sbx-tx-019fe85f-89cc-7b8f-bddb-c6600777eabf", "ledger_transaction_id": "8e79fc58-f532-4253-bd6e-73e38efa77d2", "amount": "100000", "currency": "NGN", "type": "credit", "status": "completed", "reference": "sbx-dep-019fe85f-89cc-7b8f-bddb-c6600777eabf", "metadata": "{}", "created_at": "2026-08-09T21:13:23Z", "updated_at": "2026-08-09T21:13:23Z" } ], "total": 1, "limit": 20, "offset": 0 }, "timestamp": "2026-08-09T21:13:23.822837247Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/virtual-accounts/{id}/alias": { "patch": { "tags": [ "Virtual accounts" ], "summary": "Update account alias", "description": "Changes the display name on an account. Only `account_alias` and `updated_at` change; the account number, bank and customer are untouched.", "operationId": "patch_api_virtual_accounts_id_alias", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "virtual account identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Virtual account alias updated successfully", "data": { "virtual_account": { "id": "019fe85f-86dc-7552-ba26-fe68591893a4", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "account_number": "900007492815", "account_name": "Ada Okafor", "bank_name": "Sandbox Bank", "reference": "NGN_ACCT_1786310001", "customer_id": "019faa0e-cc2d-76f6-aa61-ddd899b26e2f", "currency": "NGN", "status": "active", "account_alias": "Payments Collection", "account_type": "individual", "created_at": "2026-08-09T21:13:22Z", "updated_at": "2026-08-09T21:13:24Z" } }, "timestamp": "2026-08-09T21:13:24.388662373Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_alias": { "type": "string", "example": "Payments Collection" } }, "required": [ "account_alias" ] }, "example": { "account_alias": "Payments Collection" } } } } } }, "/api/virtual-accounts/{id}/simulate-deposit": { "post": { "tags": [ "Virtual accounts" ], "summary": "Simulate deposit (sandbox)", "description": "Fakes an inbound transfer so you can test the deposit flow without moving real money. Sandbox only — rejected in production. No request body is needed.", "operationId": "post_api_virtual_accounts_id_simulate_deposit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "virtual account identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Virtual account deposit simulated", "data": { "transaction": { "id": "019fe85f-89cc-7b9e-a42b-07fc78089499", "virtual_account_id": "019fe85f-86dc-7552-ba26-fe68591893a4", "provider_transaction_id": "sbx-tx-019fe85f-89cc-7b8f-bddb-c6600777eabf", "ledger_transaction_id": "8e79fc58-f532-4253-bd6e-73e38efa77d2", "amount": "100000", "currency": "NGN", "type": "credit", "status": "completed", "reference": "sbx-dep-019fe85f-89cc-7b8f-bddb-c6600777eabf", "metadata": "{}", "created_at": "2026-08-09T21:13:23Z", "updated_at": "2026-08-09T21:13:23Z" }, "new_balance": "800000" }, "timestamp": "2026-08-09T21:13:23.264249227Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards": { "post": { "tags": [ "Cards" ], "summary": "Create card (embedded customer)", "description": "Issues a new card and creates the customer in the same call. For existing customers, pass `customer_id` instead of the nested `customer` block.", "operationId": "post_api_cards", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card created successfully", "data": { "card": { "id": "019eeff9-d55e-79a4-9ca3-b86db3b3f7fb", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "019edfe3-ec39-70a9-aa57-c8af06475491", "card_type": "virtual", "status": "pending", "created_status": "processing", "card_brand": "visa", "name": "Chinedu Okafor", "preferred_name": "Chinedu Okafor", "masked_pan": "", "balance_amount": "0", "balance_currency": "USD", "display_amount": 0, "contactless_payment": false, "card_limits": {}, "reference": "CARD_CREATE_0e42b068-53d3-4683-86d3-8d873a5b0437", "webhook_url": "https://rgod.top/webhook/tough-urban-wheel", "user_metadata": "{}", "billing_address": { "line1": "3401 N. Miami, Ave. Ste 230", "line2": "", "city": "Miami", "state": "Florida", "postal_code": "33127", "country": "United States" }, "created_by": "2c9f5b61-8b1a-4c3d-a4f7-6d9e12b4c890", "created_at": "2026-06-22T15:36:28Z", "updated_at": "2026-06-22T15:36:28Z" } }, "timestamp": "2026-06-22T15:36:28.262981966Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card_type": { "type": "string", "example": "virtual" }, "name": { "type": "string", "example": "Ifeoma Okafor" }, "currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer" }, "webhook_url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/cards" }, "created_by": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "contactless_payment": { "type": "boolean" }, "customer": { "type": "object", "properties": { "customer_type": { "type": "string", "example": "individual" }, "first_name": { "type": "string", "example": "Ifeoma" }, "last_name": { "type": "string", "example": "Okafor" }, "date_of_birth": { "type": "string", "format": "date", "example": "1993-07-08" }, "id_type": { "type": "string", "example": "national_id" }, "id_number": { "type": "string", "example": "NIN12345678901" }, "email": { "type": "string", "example": "ifeoma.okafor@example.com" }, "phone_number": { "type": "string", "example": "8034567890" }, "dial_code": { "type": "string", "example": "+234" }, "line1": { "type": "string", "example": "18 Wuse Zone 4" }, "city": { "type": "string", "example": "Abuja" }, "state": { "type": "string", "example": "FCT" }, "postal_code": { "type": "string", "example": "900271" }, "country": { "type": "string", "example": "NGA" } }, "required": [ "customer_type", "first_name", "last_name", "date_of_birth", "id_type", "id_number", "email", "phone_number", "dial_code", "line1", "city", "state", "postal_code", "country" ] }, "card_limits": { "type": "object", "properties": { "transaction_limit": { "type": "integer", "example": 19200000000 }, "daily_limit": { "type": "integer", "example": 300000000 }, "weekly_limit": { "type": "integer", "example": 6300000000 }, "monthly_limit": { "type": "integer", "example": 3000000 }, "yearly_limit": { "type": "integer", "example": 5100000000 }, "all_time_limit": { "type": "integer", "example": 360000000 } }, "required": [ "transaction_limit", "daily_limit", "weekly_limit", "monthly_limit", "yearly_limit" ] }, "card_brand": { "type": "string", "example": "visa" }, "reference": { "type": "string", "example": "CARD_CREATE_3e096ff5-0c94-4653-adcc-b232676c84e7" } }, "required": [ "card_type", "name", "currency", "amount", "webhook_url", "created_by", "customer", "card_limits" ] }, "example": { "card_type": "virtual", "name": "Chinedu Okafor", "created_by": "2c9f5b61-8b1a-4c3d-a4f7-6d9e12b4c890", "reference": "CARD_CREATE_3e096ff5-0c94-4653-adcc-b232676c84e7", "currency": "USD", "amount": 2000000, "card_brand": "visa", "webhook_url": "https://rgod.top/webhook/tough-urban-wheel", "customer": { "customer_type": "individual", "first_name": "Ifeoma", "last_name": "Okafor", "date_of_birth": "1993-07-08", "id_type": "national_id", "id_number": "NIN12347460901", "email": "ifeoma.okafor@example.com", "phone_number": "803456990", "dial_code": "+234", "line1": "18 Wuse Zone 4", "city": "Abuja", "state": "FCT", "postal_code": "900271", "country": "NGA" }, "card_limits": { "transaction_limit": 19200000000, "daily_limit": 300000000, "weekly_limit": 6300000000, "monthly_limit": 3000000, "yearly_limit": 5100000000, "all_time_limit": 360000000 } } } } } }, "get": { "tags": [ "Cards" ], "summary": "List cards", "description": "Paginated card inventory for the workspace.", "operationId": "get_api_cards", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Cards retrieved successfully", "data": { "cards": [ { "id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "3d470828-daf9-43c5-ba33-77b4d699363a", "card_type": "virtual", "status": "active", "created_status": "completed", "card_brand": "visa", "name": "Garry Bartell", "preferred_name": "Garry Bartell", "first_six_digit": "400000", "last_four_digit": "8412", "masked_pan": "400000******8412", "balance_amount": "10000000000", "balance_currency": "USD", "display_amount": 10000, "contactless_payment": false, "card_limits": {}, "reference": "CARD_CREATE_DA10BC433B73", "user_metadata": "{\"skin_id\":\"skin-01\"}", "billing_address": { "line1": "3401 N. Miami, Ave. Ste 230", "line2": "", "city": "Miami", "state": "Florida", "postal_code": "33127", "country": "United States" }, "created_by": "ada875d3-25de-4cde-9a2e-3824d70a7651", "created_at": "2026-05-25T14:45:37Z", "updated_at": "2026-05-26T11:52:46Z" } ], "page_info": { "has_next_page": false, "has_previous_page": false, "previous_cursor": "eyJpZCI6ImE1NTYwOWIyLThiNjItNDI1MS04ZWM3LWI3YzBjMjVmM2U4NSIsInRpbWVzdGFtcCI6IjIwMjYtMDUtMjVUMTQ6NDU6MzcuNDE4ODgyWiJ9", "next_cursor": "eyJpZCI6ImE1NTYwOWIyLThiNjItNDI1MS04ZWM3LWI3YzBjMjVmM2U4NSIsInRpbWVzdGFtcCI6IjIwMjYtMDUtMjVUMTQ6NDU6MzcuNDE4ODgyWiJ9", "total": 1 } }, "timestamp": "2026-06-19T10:46:58.655780895Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/lite": { "post": { "tags": [ "Cards" ], "summary": "Create lite card", "description": "Issues a lite card with a lightweight customer profile — only the cardholder's basic contact details are needed. The `customer` block creates the customer record as part of issuance. Lite cards can be spent and terminated but not funded, and the maximum top-up is $250.", "operationId": "post_api_cards_lite", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Lite card created successfully", "data": { "card": { "id": "019ef004-c182-78c0-a265-6f9c5ea3e547", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "019eeebe-5838-7a52-b94a-4784f6557da2", "card_type": "lite", "status": "pending", "created_status": "processing", "name": "Alice Quick Card", "preferred_name": "Alice Quick Card", "masked_pan": "", "balance_amount": "0", "balance_currency": "USD", "display_amount": 0, "contactless_payment": false, "card_limits": {}, "reference": "CARD_CREATE_019EF004C182", "webhook_url": "https://rgod.top/webhook/tough-urban-wheel", "user_metadata": "{}", "billing_address": { "line1": "3401 N. Miami, Ave. Ste 230", "line2": "", "city": "Miami", "state": "Florida", "postal_code": "33127", "country": "United States" }, "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-22T15:48:24Z", "updated_at": "2026-06-22T15:48:24Z" } }, "timestamp": "2026-06-22T15:48:24.073616886Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "lite" }, "amount": { "type": "integer", "example": 2000000 }, "currency": { "type": "string", "example": "USD" }, "name": { "type": "string", "example": "Alice Quick Card" }, "webhook_url": { "type": "string", "example": "https://rgod.top/webhook/tough-urban-wheel" }, "customer": { "type": "object" } }, "required": [ "type", "amount", "currency", "name", "customer" ] }, "example": { "type": "lite", "webhook_url": "https://rgod.top/webhook/tough-urban-wheel", "customer": { "customer_type": "individual", "first_name": "Alice", "last_name": "Johnson", "email": "alicejo@gmail.com", "phone_number": "08012345678", "dial_code": "+234" }, "currency": "USD", "name": "Alice Quick Card", "amount": 2000000 } } } } } }, "/api/cards/transactions": { "get": { "tags": [ "Cards" ], "summary": "List all card transactions", "description": "Workspace-wide card transaction feed across every card.", "operationId": "get_api_cards_transactions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card transactions retrieved successfully", "data": { "transactions": [ { "id": "078e0597-625f-44d5-b07f-51e0df130933", "card_id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "funding", "status": "completed", "amount": "3000000", "currency": "USD", "reference": "8684473f-5493-4df0-8a4f-2a9e0ec28cc8", "display_amount": 3, "provider_transaction_id": "mock_tx_824bcbf5-17e7-4acb-b62a-adb996d7abcd", "balance_before": "5000000", "balance_after": "8000000", "fee_amount": "1000000", "fee_type": "funding_fee", "description": "Card funding", "metadata": "{}", "created_by": "ada875d3-25de-4cde-9a2e-3824d70a7651", "created_at": "2026-05-25T14:52:50.391169Z", "updated_at": "2026-05-25T14:52:50.532668Z", "transaction_date": "2026-05-25T14:52:50.391154Z", "cardholder_name": "Garry Bartell", "last_four_digit": "8412" }, { "id": "4303bc93-2235-47ef-b4ac-e8f1c4a1eb33", "card_id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "fee", "status": "completed", "amount": "1000000", "currency": "USD", "reference": "CARD_CREATE_DA10BC433B73-creation_fee", "display_amount": 1, "balance_before": "0", "balance_after": "0", "fee_amount": "1000000", "fee_type": "CARD_CREATION_FEE", "description": "Card creation fee", "metadata": "{}", "created_by": "ada875d3-25de-4cde-9a2e-3824d70a7651", "created_at": "2026-05-25T14:45:37.946161Z", "updated_at": "2026-05-25T14:45:38.725202Z", "transaction_date": "2026-05-25T14:45:37.946145Z", "cardholder_name": "Garry Bartell" }, { "id": "6c03d51b-8bd6-4501-8cfd-e5c03dc2afe8", "card_id": "a55609b2-8b62-4251-8ec7-b7c0c25f3e85", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "funding", "status": "completed", "amount": "5000000", "currency": "USD", "reference": "CARD_CREATE_DA10BC433B73", "display_amount": 5, "balance_before": "0", "balance_after": "5000000", "fee_amount": "1000000", "fee_type": "CARD_TOPUP_FEE", "description": "Initial card funding", "metadata": "{}", "created_by": "ada875d3-25de-4cde-9a2e-3824d70a7651", "created_at": "2026-05-25T14:45:37.428749Z", "updated_at": "2026-05-25T14:45:38.610019Z", "transaction_date": "2026-05-25T14:45:37.428711Z", "cardholder_name": "Garry Bartell" } ], "page_info": { "has_next_page": false, "has_previous_page": false, "previous_cursor": "eyJpZCI6IjA3OGUwNTk3LTYyNWYtNDRkNS1iMDdmLTUxZTBkZjEzMDkzMyIsInRpbWVzdGFtcCI6IjIwMjYtMDUtMjVUMTQ6NTI6NTAuMzkxMTY5WiJ9", "next_cursor": "eyJpZCI6IjZjMDNkNTFiLThiZDYtNDUwMS04Y2ZkLWU1YzAzZGMyYWZlOCIsInRpbWVzdGFtcCI6IjIwMjYtMDUtMjVUMTQ6NDU6MzcuNDI4NzQ5WiJ9", "total": 3 } }, "timestamp": "2026-06-19T10:46:59.926822816Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}": { "get": { "tags": [ "Cards" ], "summary": "Get card", "description": "Card metadata (masked PAN, status, balances, limits).", "operationId": "get_api_cards_cardId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card retrieved successfully", "data": { "card": { "id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "019edfe3-ec39-70a9-aa57-c8af06475491", "card_type": "virtual", "status": "active", "created_status": "completed", "card_brand": "visa", "name": "Ifeoma Okafor", "preferred_name": "Ifeoma Okafor", "first_six_digit": "400000", "last_four_digit": "9781", "masked_pan": "400000******9781", "balance_amount": "2000000", "balance_currency": "USD", "display_amount": 2, "contactless_payment": true, "card_limits": {}, "reference": "CARD_CREATE_019EDFE3EC3F", "user_metadata": "{}", "billing_address": { "line1": "3401 N. Miami, Ave. Ste 230", "line2": "", "city": "Miami", "state": "Florida", "postal_code": "33127", "country": "United States" }, "topup_current_month": "2000000", "display_topup_current_month": 2, "spent_current_month": "0", "display_spent_current_month": 0, "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T12:38:36Z", "updated_at": "2026-06-19T12:38:37Z" } }, "timestamp": "2026-06-19T12:38:37.529102254Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Cards" ], "summary": "Terminate card", "description": "Permanently terminates the card. Remaining balance sweeps back to the workspace wallet.", "operationId": "delete_api_cards_cardId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "Card no longer needed" } }, "required": [ "reason" ] }, "example": { "reason": "Card no longer needed" } } } } } }, "/api/cards/{cardId}/secure": { "get": { "tags": [ "Cards" ], "summary": "Get secure card details", "description": "Full PAN, CVV and expiry returned as plain JSON. Treat the response as PCI-regulated.", "operationId": "get_api_cards_cardId_secure", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card details retrieved successfully", "data": { "details": { "card_id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "card_number": "4000005522209781", "cvv": "768", "expiry_month": "03", "expiry_year": "2033", "name": "Ifeoma Okafor" } }, "timestamp": "2026-06-19T12:38:37.991298572Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/transactions": { "get": { "tags": [ "Cards" ], "summary": "List card transactions (by card)", "description": "Transactions scoped to one card.", "operationId": "get_api_cards_cardId_transactions", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card transactions retrieved successfully", "data": { "transactions": [ { "id": "019edfe3-ecee-714f-8489-8b8d3568ce82", "card_id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "fee", "status": "completed", "amount": "1000000", "currency": "USD", "reference": "CARD_CREATE_019EDFE3EC3F-creation_fee", "display_amount": 1, "balance_before": "0", "balance_after": "0", "fee_amount": "1000000", "fee_type": "CARD_CREATION_FEE", "description": "Card creation fee", "metadata": "{}", "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T12:38:37.038099Z", "updated_at": "2026-06-19T12:38:37.269781Z", "transaction_date": "2026-06-19T12:38:37.038082Z", "cardholder_name": "Ifeoma Okafor" }, { "id": "019edfe3-ec45-73be-80c7-f11e3b140ee3", "card_id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "funding", "status": "completed", "amount": "2000000", "currency": "USD", "reference": "CARD_CREATE_019EDFE3EC3F", "display_amount": 2, "balance_before": "0", "balance_after": "2000000", "fee_amount": "1000000", "fee_type": "CARD_TOPUP_FEE", "description": "Initial card funding", "metadata": "{}", "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T12:38:36.869276Z", "updated_at": "2026-06-19T12:38:37.241906Z", "transaction_date": "2026-06-19T12:38:36.869243Z", "cardholder_name": "Ifeoma Okafor" } ], "page_info": { "has_next_page": false, "has_previous_page": false, "previous_cursor": "eyJpZCI6IjAxOWVkZmUzLWVjZWUtNzE0Zi04NDg5LThiOGQzNTY4Y2U4MiIsInRpbWVzdGFtcCI6IjIwMjYtMDYtMTlUMTI6Mzg6MzcuMDM4MDk5WiJ9", "next_cursor": "eyJpZCI6IjAxOWVkZmUzLWVjNDUtNzNiZS04MGM3LWYxMWUzYjE0MGVlMyIsInRpbWVzdGFtcCI6IjIwMjYtMDYtMTlUMTI6Mzg6MzYuODY5Mjc2WiJ9", "total": 2 } }, "timestamp": "2026-06-19T12:38:46.314683543Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/transactions/{transactionId}": { "get": { "tags": [ "Cards" ], "summary": "Get single card transaction", "description": "Single transaction with clearing, settlement, and dispute metadata.", "operationId": "get_api_cards_cardId_transactions_transactionId", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "transactionId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card transaction retrieved successfully", "data": { "transaction": { "id": "019edfe3-ecee-714f-8489-8b8d3568ce82", "card_id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "fee", "status": "completed", "amount": "1000000", "currency": "USD", "reference": "CARD_CREATE_019EDFE3EC3F-creation_fee", "display_amount": 1, "balance_before": "0", "balance_after": "0", "fee_amount": "1000000", "fee_type": "CARD_CREATION_FEE", "description": "Card creation fee", "metadata": "{}", "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T12:38:37.038099Z", "updated_at": "2026-06-19T12:38:37.269781Z", "transaction_date": "2026-06-19T12:38:37.038082Z", "cardholder_name": "Ifeoma Okafor" } }, "timestamp": "2026-06-19T12:38:46.788722789Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cards/{cardId}/balance": { "post": { "tags": [ "Cards" ], "summary": "Fund or withdraw balance", "description": "`type: fund` debits the workspace balance and credits the card. `type: withdraw` reverses it. `amount` is in micro-units of the card currency (1 whole unit = 1,000,000).", "operationId": "post_api_cards_cardId_balance", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card funded successfully", "data": { "success": false, "message": "Card funding processing", "transaction": { "id": "019edfe8-06e6-73dd-a584-b4afd0457ea2", "card_id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "funding", "status": "pending", "amount": "2000000", "currency": "USD", "reference": "fund-1781872985", "display_amount": 2, "balance_before": "2000000", "balance_after": "2000000", "fee_amount": "1000000", "fee_type": "funding_fee", "description": "Card funding", "metadata": "{}", "created_by": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T12:43:05.830262564Z", "updated_at": "2026-06-19T12:43:05.905446930Z", "transaction_date": "2026-06-19T12:43:05.830247853Z", "cardholder_name": "Ifeoma Okafor", "last_four_digit": "9781" } }, "timestamp": "2026-06-19T12:43:05.912774441Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "fund" }, "amount": { "type": "integer" }, "reference": { "type": "string", "example": "fund-ref-001" } }, "required": [ "type", "amount", "reference" ] }, "example": { "type": "fund", "amount": 2000000, "reference": "fund-1781872985" } } } } } }, "/api/cards/{cardId}/status": { "post": { "tags": [ "Cards" ], "summary": "Freeze or unfreeze", "description": "Set `status: frozen` to block authorisations, `status: active` to resume.", "operationId": "post_api_cards_cardId_status", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card frozen successfully", "data": { "success": true, "message": "Card frozen successfully", "card": { "id": "019edfe3-ec3f-7bd4-bb44-64f8f59ad90e", "customer_id": "019edfe3-ec39-70a9-aa57-c8af06475491", "card_type": "virtual", "status": "active", "masked_pan": "400000******9781", "balance_amount": "2000000", "balance_currency": "USD", "card_brand": "visa", "name": "Ifeoma Okafor", "reference": "CARD_CREATE_019EDFE3EC3F", "display_amount": 2 } }, "timestamp": "2026-06-19T12:38:47.407353587Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "frozen" } }, "required": [ "status" ] }, "example": { "status": "frozen" } } } } } }, "/api/cards/{cardId}/spend-limits": { "put": { "tags": [ "Cards" ], "summary": "Update spend limits", "description": "Mutate transaction/daily/weekly/monthly/yearly/all-time limits. Values are integers in micro-units (1 unit = 1,000,000).", "operationId": "put_api_cards_cardId_spend_limits", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Spending limits updated successfully", "data": { "success": true, "message": "Spending limits updated successfully" }, "timestamp": "2026-06-19T12:39:38.453369897Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spending_limits": { "type": "object", "properties": { "transaction_limit": { "type": "integer" }, "daily_limit": { "type": "integer" }, "weekly_limit": { "type": "integer" }, "monthly_limit": { "type": "integer" }, "yearly_limit": { "type": "integer" }, "all_time_limit": { "type": "integer" } }, "required": [ "transaction_limit", "daily_limit", "weekly_limit", "monthly_limit", "yearly_limit" ] } }, "required": [ "spending_limits" ] }, "example": { "spending_limits": { "transaction_limit": 10000000, "daily_limit": 50000000, "weekly_limit": 200000000, "monthly_limit": 500000000, "yearly_limit": 6000000000, "all_time_limit": 10000000000 } } } } } } }, "/api/cards/{cardId}/contact": { "patch": { "tags": [ "Cards" ], "summary": "Update card contact", "description": "Update the contact details (email and mobile) associated with a card. Both fields are optional; send only the fields you want to change.", "operationId": "patch_api_cards_cardId_contact", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card contact updated successfully", "data": { "success": true, "message": "Card contact updated successfully" }, "timestamp": "2026-06-21T22:14:07.464989465Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "mobile": { "type": "string" } } }, "example": { "email": "admin@co.com", "mobile": "0249024564" } } } } } }, "/api/cards/{cardId}/simulate-webhook": { "post": { "tags": [ "Cards" ], "summary": "Simulate card webhook (sandbox)", "description": "Fires a synthetic card webhook at the card's configured callback URL so receivers can be verified end-to-end without real card activity. Sandbox only — the route is pinned to sandbox by middleware and the downstream org-service refuses non-sandbox requests.", "operationId": "post_api_cards_cardId_simulate_webhook", "parameters": [ { "name": "cardId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "cardId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Card webhook simulated", "data": { "event_type": "virtualcard.transaction.authorization", "reference": "SIMULATE_AUTH_9afbc353-6ead-41d4-b046-78fa23b1cf03", "callback_url": ":///***", "dispatched": false, "skip_reason": "no callback URL configured on card and no provider URL resolved" }, "timestamp": "2026-05-26T11:58:59.285804528Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (called outside sandbox)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "card_id": { "type": "string", "example": "62052bee-f20e-4b59-8a5d-d0c50f16d" }, "event_type": { "type": "string", "enum": [ "authorization", "settlement", "reversal", "decline" ], "example": "authorization" } }, "required": [ "card_id", "event_type" ] }, "example": { "card_id": "62052bee-f20e-4b59-8a5d-d0c50f16d", "event_type": "authorization" } } } } } }, "/api/lightning/invoices": { "post": { "tags": [ "Lightning" ], "summary": "Create invoice", "description": "Issues a BOLT11 invoice for the given customer. Amount is in satoshis.", "operationId": "post_api_lightning_invoices", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "cust_abc123" }, "amount": { "type": "integer" }, "description": { "type": "string", "example": "Payment for invoice #1234" }, "expiry": { "type": "integer" }, "reference": { "type": "string", "example": "ln-inv-001" } }, "required": [ "customer_id", "amount", "description", "expiry", "reference" ] }, "example": { "customer_id": "cust_abc123", "amount": 50000, "description": "Payment for invoice #1234", "expiry": 3600, "reference": "ln-inv-001" } } } } }, "get": { "tags": [ "Lightning" ], "summary": "List invoices", "description": "Invoice history with filters.", "operationId": "get_api_lightning_invoices", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Lightning invoices retrieved successfully", "data": { "invoices": [], "total_count": "0", "page": 1, "page_size": 20 }, "timestamp": "2026-06-19T10:47:00.859028243Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lightning/invoices/{id}": { "get": { "tags": [ "Lightning" ], "summary": "Get invoice", "description": "Invoice by id, including payment status.", "operationId": "get_api_lightning_invoices_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lightning/decode": { "post": { "tags": [ "Lightning" ], "summary": "Decode BOLT11", "description": "Structurally decodes a BOLT11 string into amount, expiry, description, routing hints, etc. Does not initiate payment.", "operationId": "post_api_lightning_decode", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." } }, "required": [ "request" ] }, "example": { "request": "lnbc500u1pj9qk7pp5..." } } } } } }, "/api/lightning/preview": { "post": { "tags": [ "Lightning" ], "summary": "Preview payment", "description": "Simulates routing and fee discovery for a BOLT11 without actually paying. Returns estimated fees + path.", "operationId": "post_api_lightning_preview", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." } }, "required": [ "request" ] }, "example": { "request": "lnbc500u1pj9qk7pp5..." } } } } } }, "/api/lightning/pay": { "post": { "tags": [ "Lightning" ], "summary": "Send payment", "description": "Pays a BOLT11. Bounded by `max_fee` (sats). Idempotent on `reference`.", "operationId": "post_api_lightning_pay", "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "cust_abc123" }, "request": { "type": "string", "example": "lnbc500u1pj9qk7pp5..." }, "reference": { "type": "string", "example": "ln-pay-001" }, "max_fee": { "type": "integer" } }, "required": [ "customer_id", "request", "reference", "max_fee" ] }, "example": { "customer_id": "cust_abc123", "request": "lnbc500u1pj9qk7pp5...", "reference": "ln-pay-001", "max_fee": 1000 } } } } } }, "/api/customers/{customerId}/cards": { "get": { "tags": [ "Cards" ], "summary": "Get cards by customer", "description": "Retrieve all cards belonging to a specific customer.", "operationId": "get_api_customers_customerId_cards", "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "UUID of the customer whose cards to retrieve." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Customer cards retrieved successfully", "data": { "cards": [], "page_info": { "has_next_page": false, "has_previous_page": false, "total": 0 } }, "timestamp": "2026-06-19T10:55:57.185801894Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers/countries": { "get": { "tags": [ "Customers" ], "summary": "List countries", "description": "Countries accepted for customer registration.", "operationId": "get_api_customers_countries", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Countries retrieved successfully", "data": { "countries": [ { "name": "Afghanistan", "code": "AF", "code3": "AFG", "currency_code": "AFN", "currency_name": "Afghan afghani", "dial_code": "+93", "flag": "🇦🇫" }, { "name": "Albania", "code": "AL", "code3": "ALB", "currency_code": "ALL", "currency_name": "Albanian lek", "dial_code": "+355", "flag": "🇦🇱" }, { "name": "Algeria", "code": "DZ", "code3": "DZA", "currency_code": "DZD", "currency_name": "Algerian dinar", "dial_code": "+213", "flag": "🇩🇿" }, { "name": "Andorra", "code": "AD", "code3": "AND", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+376", "flag": "🇦🇩" }, { "name": "Angola", "code": "AO", "code3": "AGO", "currency_code": "AOA", "currency_name": "Angolan kwanza", "dial_code": "+244", "flag": "🇦🇴" }, { "name": "Argentina", "code": "AR", "code3": "ARG", "currency_code": "ARS", "currency_name": "Argentine peso", "dial_code": "+54", "flag": "🇦🇷" }, { "name": "Armenia", "code": "AM", "code3": "ARM", "currency_code": "AMD", "currency_name": "Armenian dram", "dial_code": "+374", "flag": "🇦🇲" }, { "name": "Australia", "code": "AU", "code3": "AUS", "currency_code": "AUD", "currency_name": "Australian dollar", "dial_code": "+61", "flag": "🇦🇺" }, { "name": "Austria", "code": "AT", "code3": "AUT", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+43", "flag": "🇦🇹" }, { "name": "Azerbaijan", "code": "AZ", "code3": "AZE", "currency_code": "AZN", "currency_name": "Azerbaijani manat", "dial_code": "+994", "flag": "🇦🇿" }, { "name": "Bahamas", "code": "BS", "code3": "BHS", "currency_code": "BSD", "currency_name": "Bahamian dollar", "dial_code": "+1-242", "flag": "🇧🇸" }, { "name": "Bahrain", "code": "BH", "code3": "BHR", "currency_code": "BHD", "currency_name": "Bahraini dinar", "dial_code": "+973", "flag": "🇧🇭" }, { "name": "Bangladesh", "code": "BD", "code3": "BGD", "currency_code": "BDT", "currency_name": "Bangladeshi taka", "dial_code": "+880", "flag": "🇧🇩" }, { "name": "Barbados", "code": "BB", "code3": "BRB", "currency_code": "BBD", "currency_name": "Barbadian dollar", "dial_code": "+1-246", "flag": "🇧🇧" }, { "name": "Belarus", "code": "BY", "code3": "BLR", "currency_code": "BYN", "currency_name": "Belarusian ruble", "dial_code": "+375", "flag": "🇧🇾" }, { "name": "Belgium", "code": "BE", "code3": "BEL", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+32", "flag": "🇧🇪" }, { "name": "Belize", "code": "BZ", "code3": "BLZ", "currency_code": "BZD", "currency_name": "Belize dollar", "dial_code": "+501", "flag": "🇧🇿" }, { "name": "Benin", "code": "BJ", "code3": "BEN", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+229", "flag": "🇧🇯" }, { "name": "Bhutan", "code": "BT", "code3": "BTN", "currency_code": "BTN", "currency_name": "Bhutanese ngultrum", "dial_code": "+975", "flag": "🇧🇹" }, { "name": "Bolivia", "code": "BO", "code3": "BOL", "currency_code": "BOB", "currency_name": "Bolivian boliviano", "dial_code": "+591", "flag": "🇧🇴" }, { "name": "Bosnia and Herzegovina", "code": "BA", "code3": "BIH", "currency_code": "BAM", "currency_name": "Bosnia and Herzegovina convertible mark", "dial_code": "+387", "flag": "🇧🇦" }, { "name": "Botswana", "code": "BW", "code3": "BWA", "currency_code": "BWP", "currency_name": "Botswana pula", "dial_code": "+267", "flag": "🇧🇼" }, { "name": "Brazil", "code": "BR", "code3": "BRA", "currency_code": "BRL", "currency_name": "Brazilian real", "dial_code": "+55", "flag": "🇧🇷" }, { "name": "Brunei", "code": "BN", "code3": "BRN", "currency_code": "BND", "currency_name": "Brunei dollar", "dial_code": "+673", "flag": "🇧🇳" }, { "name": "Bulgaria", "code": "BG", "code3": "BGR", "currency_code": "BGN", "currency_name": "Bulgarian lev", "dial_code": "+359", "flag": "🇧🇬" }, { "name": "Burkina Faso", "code": "BF", "code3": "BFA", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+226", "flag": "🇧🇫" }, { "name": "Burundi", "code": "BI", "code3": "BDI", "currency_code": "BIF", "currency_name": "Burundian franc", "dial_code": "+257", "flag": "🇧🇮" }, { "name": "Cabo Verde", "code": "CV", "code3": "CPV", "currency_code": "CVE", "currency_name": "Cape Verdean escudo", "dial_code": "+238", "flag": "🇨🇻" }, { "name": "Cambodia", "code": "KH", "code3": "KHM", "currency_code": "KHR", "currency_name": "Cambodian riel", "dial_code": "+855", "flag": "🇰🇭" }, { "name": "Cameroon", "code": "CM", "code3": "CMR", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+237", "flag": "🇨🇲" }, { "name": "Canada", "code": "CA", "code3": "CAN", "currency_code": "CAD", "currency_name": "Canadian dollar", "dial_code": "+1", "flag": "🇨🇦" }, { "name": "Central African Republic", "code": "CF", "code3": "CAF", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+236", "flag": "🇨🇫" }, { "name": "Chad", "code": "TD", "code3": "TCD", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+235", "flag": "🇹🇩" }, { "name": "Chile", "code": "CL", "code3": "CHL", "currency_code": "CLP", "currency_name": "Chilean peso", "dial_code": "+56", "flag": "🇨🇱" }, { "name": "China", "code": "CN", "code3": "CHN", "currency_code": "CNY", "currency_name": "Chinese yuan", "dial_code": "+86", "flag": "🇨🇳" }, { "name": "Colombia", "code": "CO", "code3": "COL", "currency_code": "COP", "currency_name": "Colombian peso", "dial_code": "+57", "flag": "🇨🇴" }, { "name": "Comoros", "code": "KM", "code3": "COM", "currency_code": "KMF", "currency_name": "Comorian franc", "dial_code": "+269", "flag": "🇰🇲" }, { "name": "Congo", "code": "CG", "code3": "COG", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+242", "flag": "🇨🇬" }, { "name": "Congo (Democratic Republic)", "code": "CD", "code3": "COD", "currency_code": "CDF", "currency_name": "Congolese franc", "dial_code": "+243", "flag": "🇨🇩" }, { "name": "Costa Rica", "code": "CR", "code3": "CRI", "currency_code": "CRC", "currency_name": "Costa Rican colon", "dial_code": "+506", "flag": "🇨🇷" }, { "name": "Croatia", "code": "HR", "code3": "HRV", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+385", "flag": "🇭🇷" }, { "name": "Cuba", "code": "CU", "code3": "CUB", "currency_code": "CUP", "currency_name": "Cuban peso", "dial_code": "+53", "flag": "🇨🇺" }, { "name": "Cyprus", "code": "CY", "code3": "CYP", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+357", "flag": "🇨🇾" }, { "name": "Czechia", "code": "CZ", "code3": "CZE", "currency_code": "CZK", "currency_name": "Czech koruna", "dial_code": "+420", "flag": "🇨🇿" }, { "name": "Denmark", "code": "DK", "code3": "DNK", "currency_code": "DKK", "currency_name": "Danish krone", "dial_code": "+45", "flag": "🇩🇰" }, { "name": "Djibouti", "code": "DJ", "code3": "DJI", "currency_code": "DJF", "currency_name": "Djiboutian franc", "dial_code": "+253", "flag": "🇩🇯" }, { "name": "Dominica", "code": "DM", "code3": "DMA", "currency_code": "XCD", "currency_name": "East Caribbean dollar", "dial_code": "+1-767", "flag": "🇩🇲" }, { "name": "Dominican Republic", "code": "DO", "code3": "DOM", "currency_code": "DOP", "currency_name": "Dominican peso", "dial_code": "+1-809", "flag": "🇩🇴" }, { "name": "Ecuador", "code": "EC", "code3": "ECU", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+593", "flag": "🇪🇨" }, { "name": "Egypt", "code": "EG", "code3": "EGY", "currency_code": "EGP", "currency_name": "Egyptian pound", "dial_code": "+20", "flag": "🇪🇬" }, { "name": "El Salvador", "code": "SV", "code3": "SLV", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+503", "flag": "🇸🇻" }, { "name": "Equatorial Guinea", "code": "GQ", "code3": "GNQ", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+240", "flag": "🇬🇶" }, { "name": "Eritrea", "code": "ER", "code3": "ERI", "currency_code": "ERN", "currency_name": "Eritrean nakfa", "dial_code": "+291", "flag": "🇪🇷" }, { "name": "Estonia", "code": "EE", "code3": "EST", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+372", "flag": "🇪🇪" }, { "name": "Eswatini", "code": "SZ", "code3": "SWZ", "currency_code": "SZL", "currency_name": "Swazi lilangeni", "dial_code": "+268", "flag": "🇸🇿" }, { "name": "Ethiopia", "code": "ET", "code3": "ETH", "currency_code": "ETB", "currency_name": "Ethiopian birr", "dial_code": "+251", "flag": "🇪🇹" }, { "name": "Fiji", "code": "FJ", "code3": "FJI", "currency_code": "FJD", "currency_name": "Fijian dollar", "dial_code": "+679", "flag": "🇫🇯" }, { "name": "Finland", "code": "FI", "code3": "FIN", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+358", "flag": "🇫🇮" }, { "name": "France", "code": "FR", "code3": "FRA", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+33", "flag": "🇫🇷" }, { "name": "Gabon", "code": "GA", "code3": "GAB", "currency_code": "XAF", "currency_name": "Central African CFA franc", "dial_code": "+241", "flag": "🇬🇦" }, { "name": "Gambia", "code": "GM", "code3": "GMB", "currency_code": "GMD", "currency_name": "Gambian dalasi", "dial_code": "+220", "flag": "🇬🇲" }, { "name": "Georgia", "code": "GE", "code3": "GEO", "currency_code": "GEL", "currency_name": "Georgian lari", "dial_code": "+995", "flag": "🇬🇪" }, { "name": "Germany", "code": "DE", "code3": "DEU", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+49", "flag": "🇩🇪" }, { "name": "Ghana", "code": "GH", "code3": "GHA", "currency_code": "GHS", "currency_name": "Ghanaian cedi", "dial_code": "+233", "flag": "🇬🇭" }, { "name": "Greece", "code": "GR", "code3": "GRC", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+30", "flag": "🇬🇷" }, { "name": "Grenada", "code": "GD", "code3": "GRD", "currency_code": "XCD", "currency_name": "East Caribbean dollar", "dial_code": "+1-473", "flag": "🇬🇩" }, { "name": "Guatemala", "code": "GT", "code3": "GTM", "currency_code": "GTQ", "currency_name": "Guatemalan quetzal", "dial_code": "+502", "flag": "🇬🇹" }, { "name": "Guinea", "code": "GN", "code3": "GIN", "currency_code": "GNF", "currency_name": "Guinean franc", "dial_code": "+224", "flag": "🇬🇳" }, { "name": "Guinea-Bissau", "code": "GW", "code3": "GNB", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+245", "flag": "🇬🇼" }, { "name": "Guyana", "code": "GY", "code3": "GUY", "currency_code": "GYD", "currency_name": "Guyanese dollar", "dial_code": "+592", "flag": "🇬🇾" }, { "name": "Haiti", "code": "HT", "code3": "HTI", "currency_code": "HTG", "currency_name": "Haitian gourde", "dial_code": "+509", "flag": "🇭🇹" }, { "name": "Honduras", "code": "HN", "code3": "HND", "currency_code": "HNL", "currency_name": "Honduran lempira", "dial_code": "+504", "flag": "🇭🇳" }, { "name": "Hungary", "code": "HU", "code3": "HUN", "currency_code": "HUF", "currency_name": "Hungarian forint", "dial_code": "+36", "flag": "🇭🇺" }, { "name": "Iceland", "code": "IS", "code3": "ISL", "currency_code": "ISK", "currency_name": "Icelandic krona", "dial_code": "+354", "flag": "🇮🇸" }, { "name": "India", "code": "IN", "code3": "IND", "currency_code": "INR", "currency_name": "Indian rupee", "dial_code": "+91", "flag": "🇮🇳" }, { "name": "Indonesia", "code": "ID", "code3": "IDN", "currency_code": "IDR", "currency_name": "Indonesian rupiah", "dial_code": "+62", "flag": "🇮🇩" }, { "name": "Iran", "code": "IR", "code3": "IRN", "currency_code": "IRR", "currency_name": "Iranian rial", "dial_code": "+98", "flag": "🇮🇷" }, { "name": "Iraq", "code": "IQ", "code3": "IRQ", "currency_code": "IQD", "currency_name": "Iraqi dinar", "dial_code": "+964", "flag": "🇮🇶" }, { "name": "Ireland", "code": "IE", "code3": "IRL", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+353", "flag": "🇮🇪" }, { "name": "Israel", "code": "IL", "code3": "ISR", "currency_code": "ILS", "currency_name": "Israeli new shekel", "dial_code": "+972", "flag": "🇮🇱" }, { "name": "Italy", "code": "IT", "code3": "ITA", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+39", "flag": "🇮🇹" }, { "name": "Ivory Coast", "code": "CI", "code3": "CIV", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+225", "flag": "🇨🇮" }, { "name": "Jamaica", "code": "JM", "code3": "JAM", "currency_code": "JMD", "currency_name": "Jamaican dollar", "dial_code": "+1-876", "flag": "🇯🇲" }, { "name": "Japan", "code": "JP", "code3": "JPN", "currency_code": "JPY", "currency_name": "Japanese yen", "dial_code": "+81", "flag": "🇯🇵" }, { "name": "Jordan", "code": "JO", "code3": "JOR", "currency_code": "JOD", "currency_name": "Jordanian dinar", "dial_code": "+962", "flag": "🇯🇴" }, { "name": "Kazakhstan", "code": "KZ", "code3": "KAZ", "currency_code": "KZT", "currency_name": "Kazakhstani tenge", "dial_code": "+7", "flag": "🇰🇿" }, { "name": "Kenya", "code": "KE", "code3": "KEN", "currency_code": "KES", "currency_name": "Kenyan shilling", "dial_code": "+254", "flag": "🇰🇪" }, { "name": "Kiribati", "code": "KI", "code3": "KIR", "currency_code": "AUD", "currency_name": "Australian dollar", "dial_code": "+686", "flag": "🇰🇮" }, { "name": "North Korea", "code": "KP", "code3": "PRK", "currency_code": "KPW", "currency_name": "North Korean won", "dial_code": "+850", "flag": "🇰🇵" }, { "name": "South Korea", "code": "KR", "code3": "KOR", "currency_code": "KRW", "currency_name": "South Korean won", "dial_code": "+82", "flag": "🇰🇷" }, { "name": "Kuwait", "code": "KW", "code3": "KWT", "currency_code": "KWD", "currency_name": "Kuwaiti dinar", "dial_code": "+965", "flag": "🇰🇼" }, { "name": "Kyrgyzstan", "code": "KG", "code3": "KGZ", "currency_code": "KGS", "currency_name": "Kyrgyzstani som", "dial_code": "+996", "flag": "🇰🇬" }, { "name": "Laos", "code": "LA", "code3": "LAO", "currency_code": "LAK", "currency_name": "Lao kip", "dial_code": "+856", "flag": "🇱🇦" }, { "name": "Latvia", "code": "LV", "code3": "LVA", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+371", "flag": "🇱🇻" }, { "name": "Lebanon", "code": "LB", "code3": "LBN", "currency_code": "LBP", "currency_name": "Lebanese pound", "dial_code": "+961", "flag": "🇱🇧" }, { "name": "Lesotho", "code": "LS", "code3": "LSO", "currency_code": "LSL", "currency_name": "Lesotho loti", "dial_code": "+266", "flag": "🇱🇸" }, { "name": "Liberia", "code": "LR", "code3": "LBR", "currency_code": "LRD", "currency_name": "Liberian dollar", "dial_code": "+231", "flag": "🇱🇷" }, { "name": "Libya", "code": "LY", "code3": "LBY", "currency_code": "LYD", "currency_name": "Libyan dinar", "dial_code": "+218", "flag": "🇱🇾" }, { "name": "Liechtenstein", "code": "LI", "code3": "LIE", "currency_code": "CHF", "currency_name": "Swiss franc", "dial_code": "+423", "flag": "🇱🇮" }, { "name": "Lithuania", "code": "LT", "code3": "LTU", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+370", "flag": "🇱🇹" }, { "name": "Luxembourg", "code": "LU", "code3": "LUX", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+352", "flag": "🇱🇺" }, { "name": "Madagascar", "code": "MG", "code3": "MDG", "currency_code": "MGA", "currency_name": "Malagasy ariary", "dial_code": "+261", "flag": "🇲🇬" }, { "name": "Malawi", "code": "MW", "code3": "MWI", "currency_code": "MWK", "currency_name": "Malawian kwacha", "dial_code": "+265", "flag": "🇲🇼" }, { "name": "Malaysia", "code": "MY", "code3": "MYS", "currency_code": "MYR", "currency_name": "Malaysian ringgit", "dial_code": "+60", "flag": "🇲🇾" }, { "name": "Maldives", "code": "MV", "code3": "MDV", "currency_code": "MVR", "currency_name": "Maldivian rufiyaa", "dial_code": "+960", "flag": "🇲🇻" }, { "name": "Mali", "code": "ML", "code3": "MLI", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+223", "flag": "🇲🇱" }, { "name": "Malta", "code": "MT", "code3": "MLT", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+356", "flag": "🇲🇹" }, { "name": "Marshall Islands", "code": "MH", "code3": "MHL", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+692", "flag": "🇲🇭" }, { "name": "Mauritania", "code": "MR", "code3": "MRT", "currency_code": "MRU", "currency_name": "Mauritanian ouguiya", "dial_code": "+222", "flag": "🇲🇷" }, { "name": "Mauritius", "code": "MU", "code3": "MUS", "currency_code": "MUR", "currency_name": "Mauritian rupee", "dial_code": "+230", "flag": "🇲🇺" }, { "name": "Mexico", "code": "MX", "code3": "MEX", "currency_code": "MXN", "currency_name": "Mexican peso", "dial_code": "+52", "flag": "🇲🇽" }, { "name": "Micronesia", "code": "FM", "code3": "FSM", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+691", "flag": "🇫🇲" }, { "name": "Moldova", "code": "MD", "code3": "MDA", "currency_code": "MDL", "currency_name": "Moldovan leu", "dial_code": "+373", "flag": "🇲🇩" }, { "name": "Monaco", "code": "MC", "code3": "MCO", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+377", "flag": "🇲🇨" }, { "name": "Mongolia", "code": "MN", "code3": "MNG", "currency_code": "MNT", "currency_name": "Mongolian togrog", "dial_code": "+976", "flag": "🇲🇳" }, { "name": "Montenegro", "code": "ME", "code3": "MNE", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+382", "flag": "🇲🇪" }, { "name": "Morocco", "code": "MA", "code3": "MAR", "currency_code": "MAD", "currency_name": "Moroccan dirham", "dial_code": "+212", "flag": "🇲🇦" }, { "name": "Mozambique", "code": "MZ", "code3": "MOZ", "currency_code": "MZN", "currency_name": "Mozambican metical", "dial_code": "+258", "flag": "🇲🇿" }, { "name": "Myanmar", "code": "MM", "code3": "MMR", "currency_code": "MMK", "currency_name": "Myanmar kyat", "dial_code": "+95", "flag": "🇲🇲" }, { "name": "Namibia", "code": "NA", "code3": "NAM", "currency_code": "NAD", "currency_name": "Namibian dollar", "dial_code": "+264", "flag": "🇳🇦" }, { "name": "Nauru", "code": "NR", "code3": "NRU", "currency_code": "AUD", "currency_name": "Australian dollar", "dial_code": "+674", "flag": "🇳🇷" }, { "name": "Nepal", "code": "NP", "code3": "NPL", "currency_code": "NPR", "currency_name": "Nepalese rupee", "dial_code": "+977", "flag": "🇳🇵" }, { "name": "Netherlands", "code": "NL", "code3": "NLD", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+31", "flag": "🇳🇱" }, { "name": "New Zealand", "code": "NZ", "code3": "NZL", "currency_code": "NZD", "currency_name": "New Zealand dollar", "dial_code": "+64", "flag": "🇳🇿" }, { "name": "Nicaragua", "code": "NI", "code3": "NIC", "currency_code": "NIO", "currency_name": "Nicaraguan cordoba", "dial_code": "+505", "flag": "🇳🇮" }, { "name": "Niger", "code": "NE", "code3": "NER", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+227", "flag": "🇳🇪" }, { "name": "Nigeria", "code": "NG", "code3": "NGA", "currency_code": "NGN", "currency_name": "Nigerian naira", "dial_code": "+234", "flag": "🇳🇬" }, { "name": "North Macedonia", "code": "MK", "code3": "MKD", "currency_code": "MKD", "currency_name": "Macedonian denar", "dial_code": "+389", "flag": "🇲🇰" }, { "name": "Norway", "code": "NO", "code3": "NOR", "currency_code": "NOK", "currency_name": "Norwegian krone", "dial_code": "+47", "flag": "🇳🇴" }, { "name": "Oman", "code": "OM", "code3": "OMN", "currency_code": "OMR", "currency_name": "Omani rial", "dial_code": "+968", "flag": "🇴🇲" }, { "name": "Pakistan", "code": "PK", "code3": "PAK", "currency_code": "PKR", "currency_name": "Pakistani rupee", "dial_code": "+92", "flag": "🇵🇰" }, { "name": "Palau", "code": "PW", "code3": "PLW", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+680", "flag": "🇵🇼" }, { "name": "Palestine", "code": "PS", "code3": "PSE", "currency_code": "ILS", "currency_name": "Israeli new shekel", "dial_code": "+970", "flag": "🇵🇸" }, { "name": "Panama", "code": "PA", "code3": "PAN", "currency_code": "PAB", "currency_name": "Panamanian balboa", "dial_code": "+507", "flag": "🇵🇦" }, { "name": "Papua New Guinea", "code": "PG", "code3": "PNG", "currency_code": "PGK", "currency_name": "Papua New Guinean kina", "dial_code": "+675", "flag": "🇵🇬" }, { "name": "Paraguay", "code": "PY", "code3": "PRY", "currency_code": "PYG", "currency_name": "Paraguayan guarani", "dial_code": "+595", "flag": "🇵🇾" }, { "name": "Peru", "code": "PE", "code3": "PER", "currency_code": "PEN", "currency_name": "Peruvian sol", "dial_code": "+51", "flag": "🇵🇪" }, { "name": "Philippines", "code": "PH", "code3": "PHL", "currency_code": "PHP", "currency_name": "Philippine peso", "dial_code": "+63", "flag": "🇵🇭" }, { "name": "Poland", "code": "PL", "code3": "POL", "currency_code": "PLN", "currency_name": "Polish zloty", "dial_code": "+48", "flag": "🇵🇱" }, { "name": "Portugal", "code": "PT", "code3": "PRT", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+351", "flag": "🇵🇹" }, { "name": "Qatar", "code": "QA", "code3": "QAT", "currency_code": "QAR", "currency_name": "Qatari riyal", "dial_code": "+974", "flag": "🇶🇦" }, { "name": "Romania", "code": "RO", "code3": "ROU", "currency_code": "RON", "currency_name": "Romanian leu", "dial_code": "+40", "flag": "🇷🇴" }, { "name": "Russia", "code": "RU", "code3": "RUS", "currency_code": "RUB", "currency_name": "Russian ruble", "dial_code": "+7", "flag": "🇷🇺" }, { "name": "Rwanda", "code": "RW", "code3": "RWA", "currency_code": "RWF", "currency_name": "Rwandan franc", "dial_code": "+250", "flag": "🇷🇼" }, { "name": "Saint Kitts and Nevis", "code": "KN", "code3": "KNA", "currency_code": "XCD", "currency_name": "East Caribbean dollar", "dial_code": "+1-869", "flag": "🇰🇳" }, { "name": "Saint Lucia", "code": "LC", "code3": "LCA", "currency_code": "XCD", "currency_name": "East Caribbean dollar", "dial_code": "+1-758", "flag": "🇱🇨" }, { "name": "Saint Vincent and the Grenadines", "code": "VC", "code3": "VCT", "currency_code": "XCD", "currency_name": "East Caribbean dollar", "dial_code": "+1-784", "flag": "🇻🇨" }, { "name": "Samoa", "code": "WS", "code3": "WSM", "currency_code": "WST", "currency_name": "Samoan tala", "dial_code": "+685", "flag": "🇼🇸" }, { "name": "San Marino", "code": "SM", "code3": "SMR", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+378", "flag": "🇸🇲" }, { "name": "Sao Tome and Principe", "code": "ST", "code3": "STP", "currency_code": "STN", "currency_name": "Sao Tome and Principe dobra", "dial_code": "+239", "flag": "🇸🇹" }, { "name": "Saudi Arabia", "code": "SA", "code3": "SAU", "currency_code": "SAR", "currency_name": "Saudi riyal", "dial_code": "+966", "flag": "🇸🇦" }, { "name": "Senegal", "code": "SN", "code3": "SEN", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+221", "flag": "🇸🇳" }, { "name": "Serbia", "code": "RS", "code3": "SRB", "currency_code": "RSD", "currency_name": "Serbian dinar", "dial_code": "+381", "flag": "🇷🇸" }, { "name": "Seychelles", "code": "SC", "code3": "SYC", "currency_code": "SCR", "currency_name": "Seychellois rupee", "dial_code": "+248", "flag": "🇸🇨" }, { "name": "Sierra Leone", "code": "SL", "code3": "SLE", "currency_code": "SLL", "currency_name": "Sierra Leonean leone", "dial_code": "+232", "flag": "🇸🇱" }, { "name": "Singapore", "code": "SG", "code3": "SGP", "currency_code": "SGD", "currency_name": "Singapore dollar", "dial_code": "+65", "flag": "🇸🇬" }, { "name": "Slovakia", "code": "SK", "code3": "SVK", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+421", "flag": "🇸🇰" }, { "name": "Slovenia", "code": "SI", "code3": "SVN", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+386", "flag": "🇸🇮" }, { "name": "Solomon Islands", "code": "SB", "code3": "SLB", "currency_code": "SBD", "currency_name": "Solomon Islands dollar", "dial_code": "+677", "flag": "🇸🇧" }, { "name": "Somalia", "code": "SO", "code3": "SOM", "currency_code": "SOS", "currency_name": "Somali shilling", "dial_code": "+252", "flag": "🇸🇴" }, { "name": "South Africa", "code": "ZA", "code3": "ZAF", "currency_code": "ZAR", "currency_name": "South African rand", "dial_code": "+27", "flag": "🇿🇦" }, { "name": "South Sudan", "code": "SS", "code3": "SSD", "currency_code": "SSP", "currency_name": "South Sudanese pound", "dial_code": "+211", "flag": "🇸🇸" }, { "name": "Spain", "code": "ES", "code3": "ESP", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+34", "flag": "🇪🇸" }, { "name": "Sri Lanka", "code": "LK", "code3": "LKA", "currency_code": "LKR", "currency_name": "Sri Lankan rupee", "dial_code": "+94", "flag": "🇱🇰" }, { "name": "Sudan", "code": "SD", "code3": "SDN", "currency_code": "SDG", "currency_name": "Sudanese pound", "dial_code": "+249", "flag": "🇸🇩" }, { "name": "Suriname", "code": "SR", "code3": "SUR", "currency_code": "SRD", "currency_name": "Surinamese dollar", "dial_code": "+597", "flag": "🇸🇷" }, { "name": "Sweden", "code": "SE", "code3": "SWE", "currency_code": "SEK", "currency_name": "Swedish krona", "dial_code": "+46", "flag": "🇸🇪" }, { "name": "Switzerland", "code": "CH", "code3": "CHE", "currency_code": "CHF", "currency_name": "Swiss franc", "dial_code": "+41", "flag": "🇨🇭" }, { "name": "Syria", "code": "SY", "code3": "SYR", "currency_code": "SYP", "currency_name": "Syrian pound", "dial_code": "+963", "flag": "🇸🇾" }, { "name": "Taiwan", "code": "TW", "code3": "TWN", "currency_code": "TWD", "currency_name": "New Taiwan dollar", "dial_code": "+886", "flag": "🇹🇼" }, { "name": "Tajikistan", "code": "TJ", "code3": "TJK", "currency_code": "TJS", "currency_name": "Tajikistani somoni", "dial_code": "+992", "flag": "🇹🇯" }, { "name": "Tanzania", "code": "TZ", "code3": "TZA", "currency_code": "TZS", "currency_name": "Tanzanian shilling", "dial_code": "+255", "flag": "🇹🇿" }, { "name": "Thailand", "code": "TH", "code3": "THA", "currency_code": "THB", "currency_name": "Thai baht", "dial_code": "+66", "flag": "🇹🇭" }, { "name": "Timor-Leste", "code": "TL", "code3": "TLS", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+670", "flag": "🇹🇱" }, { "name": "Togo", "code": "TG", "code3": "TGO", "currency_code": "XOF", "currency_name": "West African CFA franc", "dial_code": "+228", "flag": "🇹🇬" }, { "name": "Tonga", "code": "TO", "code3": "TON", "currency_code": "TOP", "currency_name": "Tongan pa'anga", "dial_code": "+676", "flag": "🇹🇴" }, { "name": "Trinidad and Tobago", "code": "TT", "code3": "TTO", "currency_code": "TTD", "currency_name": "Trinidad and Tobago dollar", "dial_code": "+1-868", "flag": "🇹🇹" }, { "name": "Tunisia", "code": "TN", "code3": "TUN", "currency_code": "TND", "currency_name": "Tunisian dinar", "dial_code": "+216", "flag": "🇹🇳" }, { "name": "Turkey", "code": "TR", "code3": "TUR", "currency_code": "TRY", "currency_name": "Turkish lira", "dial_code": "+90", "flag": "🇹🇷" }, { "name": "Turkmenistan", "code": "TM", "code3": "TKM", "currency_code": "TMT", "currency_name": "Turkmenistan manat", "dial_code": "+993", "flag": "🇹🇲" }, { "name": "Tuvalu", "code": "TV", "code3": "TUV", "currency_code": "AUD", "currency_name": "Australian dollar", "dial_code": "+688", "flag": "🇹🇻" }, { "name": "Uganda", "code": "UG", "code3": "UGA", "currency_code": "UGX", "currency_name": "Ugandan shilling", "dial_code": "+256", "flag": "🇺🇬" }, { "name": "Ukraine", "code": "UA", "code3": "UKR", "currency_code": "UAH", "currency_name": "Ukrainian hryvnia", "dial_code": "+380", "flag": "🇺🇦" }, { "name": "United Arab Emirates", "code": "AE", "code3": "ARE", "currency_code": "AED", "currency_name": "United Arab Emirates dirham", "dial_code": "+971", "flag": "🇦🇪" }, { "name": "United Kingdom", "code": "GB", "code3": "GBR", "currency_code": "GBP", "currency_name": "British pound sterling", "dial_code": "+44", "flag": "🇬🇧" }, { "name": "United States", "code": "US", "code3": "USA", "currency_code": "USD", "currency_name": "United States dollar", "dial_code": "+1", "flag": "🇺🇸" }, { "name": "Uruguay", "code": "UY", "code3": "URY", "currency_code": "UYU", "currency_name": "Uruguayan peso", "dial_code": "+598", "flag": "🇺🇾" }, { "name": "Uzbekistan", "code": "UZ", "code3": "UZB", "currency_code": "UZS", "currency_name": "Uzbekistani som", "dial_code": "+998", "flag": "🇺🇿" }, { "name": "Vanuatu", "code": "VU", "code3": "VUT", "currency_code": "VUV", "currency_name": "Vanuatu vatu", "dial_code": "+678", "flag": "🇻🇺" }, { "name": "Vatican City", "code": "VA", "code3": "VAT", "currency_code": "EUR", "currency_name": "Euro", "dial_code": "+379", "flag": "🇻🇦" }, { "name": "Venezuela", "code": "VE", "code3": "VEN", "currency_code": "VES", "currency_name": "Venezuelan bolivar soberano", "dial_code": "+58", "flag": "🇻🇪" }, { "name": "Vietnam", "code": "VN", "code3": "VNM", "currency_code": "VND", "currency_name": "Vietnamese dong", "dial_code": "+84", "flag": "🇻🇳" }, { "name": "Yemen", "code": "YE", "code3": "YEM", "currency_code": "YER", "currency_name": "Yemeni rial", "dial_code": "+967", "flag": "🇾🇪" }, { "name": "Zambia", "code": "ZM", "code3": "ZMB", "currency_code": "ZMW", "currency_name": "Zambian kwacha", "dial_code": "+260", "flag": "🇿🇲" }, { "name": "Zimbabwe", "code": "ZW", "code3": "ZWE", "currency_code": "ZWL", "currency_name": "Zimbabwean dollar", "dial_code": "+263", "flag": "🇿🇼" } ] }, "timestamp": "2026-06-19T10:39:53.938116026Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers/countries/{countryCode}/states": { "get": { "tags": [ "Customers" ], "summary": "List states for country", "description": "State / province list for a country. Used to populate KYC address forms.", "operationId": "get_api_customers_countries_countryCode_states", "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "countryCode identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "States retrieved successfully", "data": { "states": [] }, "timestamp": "2026-06-19T10:39:54.603810092Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers": { "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "Create a customer record. KYC fields (`id_type`, `id_number`) are required for card issuance in most regions.", "operationId": "post_api_customers", "responses": { "200": { "description": "Successful response" }, "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Customer created successfully", "data": { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-18T20:21:55.397813Z", "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "customer_type": "individual", "email": "jane.doe@example.com", "first_name": "Jane", "id": "019edc65-bc3f-7bc4-980b-e328a940ef5d", "is_active": true, "last_name": "Doe", "metadata": "{}", "phone_number": "+2348012345678", "updated_at": "2026-06-18T20:21:55.397813Z" }, "timestamp": "2026-06-19T10:39:55.355654126Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "alice@example.com" }, "customer_type": { "type": "string", "example": "individual" }, "first_name": { "type": "string", "example": "Alice" }, "last_name": { "type": "string", "example": "Johnson" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-05-15" }, "id_type": { "type": "string", "example": "passport" }, "id_number": { "type": "string", "example": "A12345678" }, "country": { "type": "string", "example": "USA" } }, "required": [ "email", "customer_type" ] }, "example": { "email": "pg-1781865594@test.invalid", "first_name": "Jane", "last_name": "Doe", "phone_number": "+2348012345678", "country_code": "NGA", "customer_type": "individual", "reference": "ref-1781865594" } } } } }, "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Paginated customers.", "operationId": "get_api_customers", "parameters": [ { "name": "first_name", "in": "query", "required": false, "schema": { "type": "string", "example": "alice" }, "description": "" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Customers retrieved successfully", "data": { "customers": [ { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-18T20:21:55.397813Z", "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "customer_type": "individual", "email": "jane.doe@example.com", "first_name": "Jane", "id": "019edc65-bc3f-7bc4-980b-e328a940ef5d", "is_active": true, "last_name": "Doe", "metadata": "{}", "phone_number": "+2348012345678", "updated_at": "2026-06-18T20:21:55.397813Z" }, { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-18T17:06:46.557402Z", "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "customer_type": "individual", "email": "test-1774119813@test.invalid", "first_name": "Updated", "id": "019edbb3-129a-7085-96c2-da7186826490", "is_active": true, "last_name": "Name", "metadata": "{}", "phone_number": "+0000000000000", "updated_at": "2026-06-18T17:55:14.865147Z" }, { "city": "Accra", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "country": "GHA", "created_at": "2026-05-23T18:24:27.843404Z", "created_by": "ada875d3-25de-4cde-9a2e-3824d70a7651", "customer_type": "individual", "date_of_birth": "1920-01-15", "dial_code": "+234", "email": "garry-bartell@rgod.top", "first_name": "Garry", "id": "3d470828-daf9-43c5-ba33-77b4d699363a", "id_number": "343546576654", "id_type": "national_id", "is_active": true, "last_name": "Bartell", "line1": "Accra Ghana", "metadata": "{}", "phone_number": "2345678954", "postal_code": "233", "state": "Greater Accra Region", "updated_at": "2026-05-25T14:45:38.232506Z" } ], "page": 1, "page_size": 20, "total": 3 }, "timestamp": "2026-06-19T10:39:55.895559697Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/customers/{customerId}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "description": "Single customer with KYC status.", "operationId": "get_api_customers_customerId", "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "customerId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Customer retrieved successfully", "data": { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-18T20:21:55.397813Z", "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "customer_type": "individual", "email": "jane.doe@example.com", "first_name": "Jane", "id": "019edc65-bc3f-7bc4-980b-e328a940ef5d", "is_active": true, "last_name": "Doe", "metadata": "{}", "phone_number": "+2348012345678", "updated_at": "2026-06-18T20:21:55.397813Z" }, "timestamp": "2026-06-19T10:39:56.678282817Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Mutate customer fields or toggle active status.", "operationId": "put_api_customers_customerId", "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "customerId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Customer updated successfully", "data": { "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "created_at": "2026-06-19T15:02:38.387536Z", "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "customer_type": "individual", "email": "test-1774119813@test.com", "first_name": "Alice", "id": "019ee067-c830-7226-a49c-f3eb1fda138e", "is_active": true, "last_name": "Smith", "metadata": "{}", "phone_number": "+00000000000", "updated_at": "2026-06-19T15:10:02.664939383Z" }, "timestamp": "2026-06-19T15:10:02.670980824Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Alice" }, "last_name": { "type": "string", "example": "Smith" }, "is_active": { "type": "boolean" } }, "required": [ "first_name", "last_name", "is_active" ] }, "example": { "first_name": "Alice", "last_name": "Smith", "is_active": true } } } } } }, "/api/beneficiaries": { "post": { "tags": [ "Beneficiaries" ], "summary": "Create beneficiary", "description": "Save a recipient for reuse. Crypto beneficiaries require `wallet_address`, `currency`, and `network`.", "operationId": "post_api_beneficiaries", "responses": { "200": { "description": "Successful response" }, "201": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Beneficiary created successfully", "data": { "id": "019edbed-e3b9-7e01-9fde-049cab0cac0f", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "crypto", "name": "Updated Wallet", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum", "destination": "{}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:11:01.180899Z", "updated_at": "2026-06-18T18:11:38.825552Z" }, "timestamp": "2026-06-19T10:39:57.956753903Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Alice Ethereum Wallet" }, "type": { "type": "string", "example": "CRYPTO" }, "wallet_address": { "type": "string", "example": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b" }, "currency": { "type": "string", "example": "USDT" }, "network": { "type": "string", "example": "ethereum" } }, "required": [ "name", "type", "wallet_address", "currency", "network" ] }, "example": { "name": "Alice Ethereum Wallet", "type": "crypto", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum" } } } } }, "get": { "tags": [ "Beneficiaries" ], "summary": "List beneficiaries", "description": "Paginated list of saved recipients.", "operationId": "get_api_beneficiaries", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Beneficiaries retrieved successfully", "data": { "beneficiaries": [ { "id": "019edf3c-cfc6-78ea-8b23-ab15944430d0", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "bank", "name": "John Doe Bank", "destination": "{\"account_name\":\"John Doe\",\"account_number\":\"0000611418\",\"bank_code\":\"058\"}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-19T09:36:05.065328Z", "updated_at": "2026-06-19T09:36:05.065328Z" }, { "id": "019edbf5-0da3-7b9a-89ac-55704a8c7f45", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "bank", "name": "Bank Beneficiary", "destination": "{\"account_name\":\"John Doe\",\"account_number\":\"0123456789\",\"bank_code\":\"058\"}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:18:50.662197Z", "updated_at": "2026-06-18T18:18:50.662197Z" }, { "id": "019edbf0-d473-7678-a660-a7d8638c3d78", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "bank", "name": "Bank Ben", "wallet_address": "1234567890", "currency": "NGN", "network": "bank", "destination": "{\"account_name\":\"John Doe\",\"account_number\":\"1234567890\",\"bank_code\":\"058\"}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:14:13.898256Z", "updated_at": "2026-06-18T18:14:13.898256Z" }, { "id": "019edbed-e3b9-7e01-9fde-049cab0cac0f", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "crypto", "name": "Updated Wallet", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum", "destination": "{}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:11:01.180899Z", "updated_at": "2026-06-18T18:11:38.825552Z" }, { "id": "019edbe9-5eab-73cf-9827-4aa03c3f9953", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "crypto", "name": "Alice Tron Wallet", "wallet_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9", "currency": "USDT", "network": "tron", "destination": "{}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:06:04.975252Z", "updated_at": "2026-06-18T18:06:04.975252Z" } ], "limit": 10, "offset": 0, "total": 5 }, "timestamp": "2026-06-19T10:39:58.652709368Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/beneficiaries/{beneficiaryId}": { "get": { "tags": [ "Beneficiaries" ], "summary": "Get beneficiary", "description": "Single beneficiary.", "operationId": "get_api_beneficiaries_beneficiaryId", "parameters": [ { "name": "beneficiaryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "beneficiaryId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Beneficiary retrieved successfully", "data": { "id": "019edbed-e3b9-7e01-9fde-049cab0cac0f", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "crypto", "name": "Updated Wallet", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum", "destination": "{}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:11:01.180899Z", "updated_at": "2026-06-18T18:11:38.825552Z" }, "timestamp": "2026-06-19T10:39:59.395686981Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Beneficiaries" ], "summary": "Update beneficiary", "description": "Mutate name or active status.", "operationId": "put_api_beneficiaries_beneficiaryId", "parameters": [ { "name": "beneficiaryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "beneficiaryId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Beneficiary updated successfully", "data": { "id": "019edbed-e3b9-7e01-9fde-049cab0cac0f", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "type": "crypto", "name": "Updated Wallet", "wallet_address": "0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b", "currency": "USDT", "network": "ethereum", "destination": "{}", "is_blacklisted": false, "is_active": true, "created_by": "86f1b05e-2e35-40bf-a85d-fd3de44d216b", "created_at": "2026-06-18T18:11:01.180899Z", "updated_at": "2026-06-19T10:40:00.20999369Z" }, "timestamp": "2026-06-19T10:40:00.217004617Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated Wallet" }, "is_active": { "type": "boolean" } }, "required": [ "name", "is_active" ] }, "example": { "name": "Updated Wallet", "is_active": true } } } } } }, "/api/payouts/quotes": { "post": { "tags": [ "Payouts" ], "summary": "Create quote", "description": "Requests a rate + fee quote. Returns `quoteId` required by Initialize. Quotes expire quickly (seconds to minutes).", "operationId": "post_api_payouts_quotes", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Quote created successfully", "data": { "payout": { "id": "019f2f22-2dad-792b-900d-ccc1c3731874", "quote_id": "QT2_21015643", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "status": "QUOTE", "source": "OFFCHAIN", "from_asset": "USDT", "to_currency": "NGN", "sat_amount": "1144", "btc_amount": "0.00001144", "cent_amount": "100000", "amount": "0.724761", "settlement_amount": "1000", "cent_fees": "0", "fees": "0", "exchange_rate": { "rate": "1382.5294", "btc_rate": "63327.05", "currency": "ngn", "effective_rate": "1379.7651915597003702" }, "trip": { "quote_at": "2026-07-04T21:56:36.909598538Z" }, "payment_reason": "Invoice payment", "reference": "your-unique-ref-123", "country": "NG", "expires_at": "2026-07-04T22:12:36.909609058Z", "created_at": "2026-07-04T21:56:36.911340825Z", "updated_at": "2026-07-04T21:56:36.911340825Z" } }, "timestamp": "2026-07-04T21:56:36.919134356Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_asset": { "type": "string", "example": "USDT" }, "to_currency": { "type": "string", "example": "NGN" }, "source": { "type": "string", "example": "offchain" }, "chain": { "type": "string", "example": "" }, "amount": { "type": "string", "example": "100000000" }, "payment_reason": { "type": "string", "example": "vendor_payment" }, "reference": { "type": "string", "example": "payout-ref-001" }, "country": { "type": "string", "example": "NG" } }, "required": [ "from_asset", "to_currency", "source", "amount", "payment_reason", "reference", "country" ] }, "example": { "from_asset": "USDT", "to_currency": "NGN", "source": "offchain", "country": "NG", "settlement_amount": "1000", "payment_reason": "Invoice payment", "reference": "your-unique-ref-123" } } } } } }, "/api/payouts/{quoteId}/initialize": { "post": { "tags": [ "Payouts" ], "summary": "Initialize payout", "description": "Locks the quote and creates the payout intent with the beneficiary. The response includes an id used by Finalize.", "operationId": "post_api_payouts_quoteId_initialize", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "quoteId identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Payout initialized successfully", "data": { "payout": { "id": "019f2f22-2dad-792b-900d-ccc1c3731874", "quote_id": "QT2_21015643", "company_id": "", "status": "INITIATED", "source": "SOURCE_UNSET", "from_asset": "USDT", "to_currency": "NGN", "sat_amount": "1144", "btc_amount": "0.000011", "amount": "0.724761", "settlement_amount": "1000.000000", "cent_fees": "0", "fees": "0.000000", "exchange_rate": { "rate": "1382.529400", "btc_rate": "63327.050000", "currency": "", "effective_rate": "1379.7651915597003702" }, "beneficiary": { "account_name": "OKEY JOY CHIDIMMA", "account_number": "0123456789", "bank_code": "058", "country": "NG", "destination_type": "bank" }, "payment_reason": "vendor_payment", "reference": "your-unique-ref-123", "country": "", "expires_at": "2026-07-04T22:12:36Z", "created_at": null, "updated_at": null }, "data": null }, "timestamp": "2026-07-04T21:56:37.105232508Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "" }, "beneficiary": { "type": "object", "properties": { "destination_type": { "type": "string", "example": "bank" }, "country": { "type": "string", "example": "NG" }, "account_name": { "type": "string", "example": "OKEY JOY CHIDIMMA" }, "account_number": { "type": "string", "example": "0123456789" }, "bank_code": { "type": "string", "example": "058" } }, "required": [ "destination_type", "country", "account_name", "account_number", "bank_code" ] }, "reference": { "type": "string", "example": "init-ref-001" }, "callback_url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/payouts" } }, "required": [ "beneficiary", "reference", "callback_url" ] }, "example": { "quote_id": "QT2_21015643", "payment_reason": "vendor_payment", "callback_url": "https://example.com/webhooks/payouts", "reference": "your-unique-ref-123", "beneficiary": { "destination_type": "bank", "country": "NG", "account_name": "OKEY JOY CHIDIMMA", "account_number": "0123456789", "bank_code": "058" } } } } }, "callbacks": { "payoutEvents": { "{$request.body#/callback_url}": { "post": { "summary": "Payout webhook", "description": "Sent to the callback_url supplied on initialize (or your account-level webhook URL) as the payout changes state. Verify the x-bitnob-signature header (HMAC-SHA512 of the raw body, keyed with your secret) and return 200. Non-200 responses are retried 3 times after the first failure.", "operationId": "payoutWebhookEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutWebhookEvent" }, "examples": { "payouts.initialized": { "summary": "payouts.initialized", "value": { "event": "payouts.initialized", "event_id": "802561d3-78fa-4436-a3cc-fdbebe4772ed", "data": { "id": "019f8132-4969-7e63-a2da-c439ace1613d", "quote_id": "QT2_21434859", "company_id": "8263c9991-6c68-477b-bd12-c759rjtg", "reference": "6c9ace6b-891a-4b91-bff4-8bfdh784jc3f", "status": "initiated", "from_asset": "btc", "to_currency": "ngn", "amount": "0.00018555", "settlement_amount": "16823.2", "fees": "0", "beneficiary": { "country": "ng", "bank_code": "100004", "account_number": "****3123" }, "created_at": "2026-07-20T20:23:04.297953Z", "updated_at": "2026-07-20T20:23:25.444269082Z" } } }, "payouts.processing": { "summary": "payouts.processing", "value": { "event": "payouts.processing", "event_id": "51ff21dc-9629-41b5-8771-9cbc0d670000", "data": { "id": "019f8330-71e6-7649-a382-2209fd73b56f", "quote_id": "QT2_21439667", "company_id": "9876543-6c68-477b-bd95-769nn698", "reference": "4fb1e02e-1234-467a-b91b-3a18dc000000", "status": "processing", "from_asset": "usdt", "to_currency": "ngn", "amount": "1.801875", "settlement_amount": "2500", "fees": "0", "beneficiary": { "country": "ng", "bank_code": "100004", "account_number": "****4000" }, "created_at": "2026-07-21T05:40:18.02242Z", "updated_at": "2026-07-21T05:40:47.522051588Z" } } }, "payouts.withdrawal.success": { "summary": "payouts.withdrawal.success", "value": { "event": "payouts.withdrawal.success", "event_id": "d9c4758ub-5e93-4cdf-bb123-frt474865", "data": { "id": "019f812d-ed2c-7f17-a2e9-12435e670813", "quote_id": "QT2_21434859", "company_id": "9876543-6c68-477b-bd95-769nn698", "reference": "76543-1234-4304-869j-3a98e85f0812", "status": "success", "from_asset": "usdt", "to_currency": "ngn", "amount": "100.988948", "settlement_amount": "140174.8", "fees": "0", "beneficiary": { "country": "ng", "bank_code": "100004", "account_number": "****3001" }, "created_at": "2026-07-20T20:18:18.541002Z", "updated_at": "2026-07-20T20:18:39.515031203Z", "completed_at": "2026-07-20T20:18:39.515031203Z" } } }, "payouts.withdrawal.expired": { "summary": "payouts.withdrawal.expired", "value": { "event": "payouts.withdrawal.expired", "event_id": "0756585e-8oa1-4eb8-a9aa-85957450", "data": { "id": "08565964-01b9-8801-b123-123456789", "quote_id": "QT2_21434706", "company_id": "c234567-4117-45be-456-123456789", "reference": "12345678-c888-0987-1234-2435464844", "status": "expired", "from_asset": "usdc", "to_currency": "ngn", "amount": "25.795811", "settlement_amount": "35804.11", "fees": "0", "payment_reason": "Crypto offramp", "created_at": "2026-07-20T20:05:17.371329Z", "updated_at": "2026-07-20T20:24:01.352781396Z", "completed_at": "2026-07-20T20:24:01.352781396Z" } } } } } } }, "responses": { "200": { "description": "Acknowledged. Return 200 to stop redelivery." } } } } } } } }, "/api/payouts/{quoteId}/finalize": { "post": { "tags": [ "Payouts" ], "summary": "Finalize payout", "description": "Commits the debit and releases the payout to the rails. Irreversible.", "operationId": "post_api_payouts_quoteId_finalize", "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "quoteId identifier" } ], "responses": { "200": { "description": "Successful response" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } } } }, "/api/payouts/account-lookup": { "get": { "tags": [ "Payouts" ], "summary": "Account lookup", "description": "Name-resolves a bank account so the UI can show the account holder before the user confirms.", "operationId": "get_api_payouts_account_lookup", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "example": "NG" }, "description": "" }, { "name": "bank_code", "in": "query", "required": true, "schema": { "type": "string", "example": "000014" }, "description": "" }, { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string", "example": "1421795566" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Beneficiary lookup completed", "data": { "account_name": "CHIAMAKA JENNIFER EZEOBI", "account_number": "1421795566", "bank_code": "000014", "bank_name": "ACCESS BANK", "country": "NG", "is_verified": true }, "timestamp": "2026-06-19T10:47:03.950149804Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/supported-countries": { "get": { "tags": [ "Payouts" ], "summary": "Supported countries", "description": "Countries with live payout rails, including display metadata.", "operationId": "get_api_payouts_supported_countries", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Supported countries retrieved successfully", "data": { "countries": [ { "code": "AD", "name": "Andorra", "flag": "🇦🇩", "dial_code": "376", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "AE", "name": "United Arab Emirates", "flag": "🇦🇪", "dial_code": "971", "corridors": [ { "currency": "AED", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "AO", "name": "Angola", "flag": "🇦🇴", "dial_code": "244", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "AR", "name": "Argentina", "flag": "🇦🇷", "dial_code": "54", "corridors": [ { "currency": "ARS", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "AT", "name": "Austria", "flag": "🇦🇹", "dial_code": "43", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "AU", "name": "Australia", "flag": "🇦🇺", "dial_code": "61", "corridors": [ { "currency": "AUD", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "BE", "name": "Belgium", "flag": "🇧🇪", "dial_code": "32", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "BG", "name": "Bulgaria", "flag": "🇧🇬", "dial_code": "359", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "BO", "name": "Bolivia", "flag": "🇧🇴", "dial_code": "591", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "BS", "name": "Bahamas", "flag": "🇧🇸", "dial_code": "1242", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "BW", "name": "Botswana", "flag": "🇧🇼", "dial_code": "267", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "CD", "name": "Democratic Republic of the Congo", "flag": "🇨🇩", "dial_code": "243", "corridors": [ { "currency": "CDF", "destination_types": [ "mobile_money" ] } ] }, { "code": "CH", "name": "Switzerland", "flag": "🇨🇭", "dial_code": "41", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "CI", "name": "Ivory Coast", "flag": "🇨🇮", "dial_code": "225", "corridors": [ { "currency": "XOF", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "CL", "name": "Chile", "flag": "🇨🇱", "dial_code": "56", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "CM", "name": "Cameroon", "flag": "🇨🇲", "dial_code": "237", "corridors": [ { "currency": "XAF", "destination_types": [ "mobile_money" ] } ] }, { "code": "CN", "name": "China", "flag": "🇨🇳", "dial_code": "86", "corridors": [ { "currency": "CNY", "destination_types": [ "bank", "swift", "alipay", "wechatpay" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "CR", "name": "Costa Rica", "flag": "🇨🇷", "dial_code": "506", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "CY", "name": "Cyprus", "flag": "🇨🇾", "dial_code": "357", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "CZ", "name": "Czech Republic", "flag": "🇨🇿", "dial_code": "420", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "DE", "name": "Germany", "flag": "🇩🇪", "dial_code": "49", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "DK", "name": "Denmark", "flag": "🇩🇰", "dial_code": "45", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "DM", "name": "Dominica", "flag": "🇩🇲", "dial_code": "1767", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "DO", "name": "Dominican Republic", "flag": "🇩🇴", "dial_code": "1809,1829,1849", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "DZ", "name": "Algeria", "flag": "🇩🇿", "dial_code": "213", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "EC", "name": "Ecuador", "flag": "🇪🇨", "dial_code": "593", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "EE", "name": "Estonia", "flag": "🇪🇪", "dial_code": "372", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "ES", "name": "Spain", "flag": "🇪🇸", "dial_code": "34", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "ET", "name": "Ethiopia", "flag": "🇪🇹", "dial_code": "251", "corridors": [ { "currency": "ETB", "destination_types": [ "mobile_money" ] } ] }, { "code": "FI", "name": "Finland", "flag": "🇫🇮", "dial_code": "358", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "FM", "name": "Micronesia", "flag": "🇫🇲", "dial_code": "691", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "FR", "name": "France", "flag": "🇫🇷", "dial_code": "33", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "GA", "name": "Gabon", "flag": "🇬🇦", "dial_code": "241", "corridors": [ { "currency": "XAF", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GB", "name": "United Kingdom", "flag": "🇬🇧", "dial_code": "44", "corridors": [ { "currency": "GBP", "destination_types": [ "domestic_gbp" ] }, { "currency": "EUR", "destination_types": [ "sepa_eur" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GD", "name": "Grenada", "flag": "🇬🇩", "dial_code": "1473", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GE", "name": "Georgia", "flag": "🇬🇪", "dial_code": "995", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GG", "name": "Guernsey", "flag": "🇬🇬", "dial_code": "44", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GH", "name": "Ghana", "flag": "🇬🇭", "dial_code": "233", "corridors": [ { "currency": "GHS", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GL", "name": "Greenland", "flag": "🇬🇱", "dial_code": "299", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GM", "name": "Gambia", "flag": "🇬🇲", "dial_code": "220", "corridors": [ { "currency": "GMD", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GP", "name": "Guadeloupe", "flag": "🇬🇵", "dial_code": "590", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GR", "name": "Greece", "flag": "🇬🇷", "dial_code": "30", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "GT", "name": "Guatemala", "flag": "🇬🇹", "dial_code": "502", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "GY", "name": "Guyana", "flag": "🇬🇾", "dial_code": "592", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "HK", "name": "Hong Kong", "flag": "🇭🇰", "dial_code": "852", "corridors": [ { "currency": "HKD", "destination_types": [ "bank", "swift" ] }, { "currency": "CNY", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "HN", "name": "Honduras", "flag": "🇭🇳", "dial_code": "504", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "HR", "name": "Croatia", "flag": "🇭🇷", "dial_code": "385", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "HT", "name": "Haiti", "flag": "🇭🇹", "dial_code": "509", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "HU", "name": "Hungary", "flag": "🇭🇺", "dial_code": "36", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "ID", "name": "Indonesia", "flag": "🇮🇩", "dial_code": "62", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "IE", "name": "Ireland", "flag": "🇮🇪", "dial_code": "353", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "IN", "name": "India", "flag": "🇮🇳", "dial_code": "91", "corridors": [ { "currency": "INR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "IS", "name": "Iceland", "flag": "🇮🇸", "dial_code": "354", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "IT", "name": "Italy", "flag": "🇮🇹", "dial_code": "39", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "JE", "name": "Jersey", "flag": "🇯🇪", "dial_code": "44", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "JM", "name": "Jamaica", "flag": "🇯🇲", "dial_code": "1876", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "JP", "name": "Japan", "flag": "🇯🇵", "dial_code": "81", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "KE", "name": "Kenya", "flag": "🇰🇪", "dial_code": "254", "corridors": [ { "currency": "KES", "destination_types": [ "mobile_money", "paybill", "paytill" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "KH", "name": "Cambodia", "flag": "🇰🇭", "dial_code": "855", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "KR", "name": "South Korea", "flag": "🇰🇷", "dial_code": "82", "corridors": [ { "currency": "KRW", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "KW", "name": "Kuwait", "flag": "🇰🇼", "dial_code": "965", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "LB", "name": "Lebanon", "flag": "🇱🇧", "dial_code": "961", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "LI", "name": "Liechtenstein", "flag": "🇱🇮", "dial_code": "423", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "LT", "name": "Lithuania", "flag": "🇱🇹", "dial_code": "370", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "LU", "name": "Luxembourg", "flag": "🇱🇺", "dial_code": "352", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "LV", "name": "Latvia", "flag": "🇱🇻", "dial_code": "371", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "MC", "name": "Monaco", "flag": "🇲🇨", "dial_code": "377", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "ME", "name": "Montenegro", "flag": "🇲🇪", "dial_code": "382", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MK", "name": "North Macedonia", "flag": "🇲🇰", "dial_code": "389", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MN", "name": "Mongolia", "flag": "🇲🇳", "dial_code": "976", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MO", "name": "Macao", "flag": "🇲🇴", "dial_code": "853", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MR", "name": "Mauritania", "flag": "🇲🇷", "dial_code": "222", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MS", "name": "Montserrat", "flag": "🇲🇸", "dial_code": "1664", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MT", "name": "Malta", "flag": "🇲🇹", "dial_code": "356", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "MU", "name": "Mauritius", "flag": "🇲🇺", "dial_code": "230", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MX", "name": "Mexico", "flag": "🇲🇽", "dial_code": "52", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "MY", "name": "Malaysia", "flag": "🇲🇾", "dial_code": "60", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "NA", "name": "Namibia", "flag": "🇳🇦", "dial_code": "264", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "NE", "name": "Niger", "flag": "🇳🇪", "dial_code": "227", "corridors": [ { "currency": "XOF", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "NG", "name": "Nigeria", "flag": "🇳🇬", "dial_code": "234", "corridors": [ { "currency": "NGN", "destination_types": [ "bank" ] } ] }, { "code": "NL", "name": "Netherlands", "flag": "🇳🇱", "dial_code": "31", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "NO", "name": "Norway", "flag": "🇳🇴", "dial_code": "47", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "NZ", "name": "New Zealand", "flag": "🇳🇿", "dial_code": "64", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "PE", "name": "Peru", "flag": "🇵🇪", "dial_code": "51", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "PH", "name": "Philippines", "flag": "🇵🇭", "dial_code": "63", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "PL", "name": "Poland", "flag": "🇵🇱", "dial_code": "48", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "PT", "name": "Portugal", "flag": "🇵🇹", "dial_code": "351", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "PY", "name": "Paraguay", "flag": "🇵🇾", "dial_code": "595", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "RO", "name": "Romania", "flag": "🇷🇴", "dial_code": "40", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "RS", "name": "Serbia", "flag": "🇷🇸", "dial_code": "381", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "RW", "name": "Rwanda", "flag": "🇷🇼", "dial_code": "250", "corridors": [ { "currency": "RWF", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "SC", "name": "Seychelles", "flag": "🇸🇨", "dial_code": "248", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "SE", "name": "Sweden", "flag": "🇸🇪", "dial_code": "46", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "SG", "name": "Singapore", "flag": "🇸🇬", "dial_code": "65", "corridors": [ { "currency": "SGD", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "SI", "name": "Slovenia", "flag": "🇸🇮", "dial_code": "386", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "SK", "name": "Slovakia", "flag": "🇸🇰", "dial_code": "421", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "SL", "name": "Sierra Leone", "flag": "🇸🇱", "dial_code": "232", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "SM", "name": "San Marino", "flag": "🇸🇲", "dial_code": "378", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "SN", "name": "Senegal", "flag": "🇸🇳", "dial_code": "221", "corridors": [ { "currency": "XOF", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "SV", "name": "El Salvador", "flag": "🇸🇻", "dial_code": "503", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "TH", "name": "Thailand", "flag": "🇹🇭", "dial_code": "66", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "TN", "name": "Tunisia", "flag": "🇹🇳", "dial_code": "216", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "TR", "name": "Turkey", "flag": "🇹🇷", "dial_code": "90", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "TW", "name": "Taiwan", "flag": "🇹🇼", "dial_code": "886", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "UG", "name": "Uganda", "flag": "🇺🇬", "dial_code": "256", "corridors": [ { "currency": "UGX", "destination_types": [ "mobile_money" ] }, { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "US", "name": "United States", "flag": "🇺🇸", "dial_code": "1", "corridors": [ { "currency": "USD", "destination_types": [ "wire", "ach" ] } ] }, { "code": "VA", "name": "Vatican City", "flag": "🇻🇦", "dial_code": "379", "corridors": [ { "currency": "EUR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] }, { "code": "VN", "name": "Vietnam", "flag": "🇻🇳", "dial_code": "84", "corridors": [ { "currency": "USD", "destination_types": [ "swift" ] } ] }, { "code": "ZA", "name": "South Africa", "flag": "🇿🇦", "dial_code": "27", "corridors": [ { "currency": "ZAR", "destination_types": [ "bank", "swift" ] }, { "currency": "USD", "destination_types": [ "bank", "swift" ] } ] } ] }, "timestamp": "2026-06-19T10:47:01.371886375Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/supported-countries/{country}": { "get": { "tags": [ "Payouts" ], "summary": "Country requirements", "description": "Per-country beneficiary-field requirements (which fields are required, their validation rules, etc.).", "operationId": "get_api_payouts_supported_countries_country", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "description": "country identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Country requirements retrieved successfully", "data": { "code": "NG", "name": "Nigeria", "flag": "🇳🇬", "dial_code": "234", "destination_types": { "bank": { "key": "bank", "label": "Bank Transfer", "fields": [ { "key": "bank_code", "label": "Bank Name", "type": "string", "required": true, "component": "select", "options": [], "options_ref": "banks", "fields": [], "variants": {} }, { "key": "account_number", "label": "Account Number", "type": "string", "required": true, "component": "text", "pattern": "^\\d{10}$", "description": "Nigerian bank account number (10 digits)", "placeholder": "e.g. 0123456789", "options": [], "fields": [], "variants": {} } ], "banks": [ { "name": "78 FINANCE COMPANY LIMITED", "code": "110072" }, { "name": "9JAPAY MICROFINANCE BANK", "code": "090629" }, { "name": "9 PAYMENT SERVICE BANK", "code": "120001" }, { "name": "ABBEY MORTGAGE BANK", "code": "070010" }, { "name": "AB MICROFINANCE BANK ", "code": "090270" }, { "name": "ABOVE ONLY MICROFINANCE BANK ", "code": "090260" }, { "name": "ABU MICROFINANCE BANK ", "code": "090197" }, { "name": "Access bank", "code": "000014" }, { "name": "ACCESS MONEY", "code": "100013" }, { "name": "ACCESS YELLO & BETA", "code": "100052" }, { "name": "ACCION MICROFINANCE BANK", "code": "090134" }, { "name": "ADA MICROFINANCE BANK", "code": "090483" }, { "name": "ADDOSSER MICROFINANCE BANK", "code": "090160" }, { "name": "ADEYEMI COLLEGE STAFF MICROFINANCE BANK", "code": "090268" }, { "name": "ADVANCLY MFB", "code": "50134" }, { "name": "AELLA MFB", "code": "090614" }, { "name": "AFEKHAFE MICROFINANCE BANK", "code": "090292" }, { "name": "AG MORTGAGE BANK", "code": "100028" }, { "name": "AKALABO MFB", "code": "090698" }, { "name": "AKU Microfinance Bank", "code": "090531" }, { "name": "AL-BARAKAH MICROFINANCE BANK", "code": "090133" }, { "name": "ALEKUN MICROFINANCE BANK", "code": "090259" }, { "name": "ALERT MICROFINANCE BANK", "code": "090297" }, { "name": "ALLWORKERS MICROFINANCE BANK", "code": "090131" }, { "name": "ALPHA KAPITAL MICROFINANCE BANK ", "code": "090169" }, { "name": "AMML MICROFINANCE BANK ", "code": "090116" }, { "name": "Amucha Microfinance Bank", "code": "090645" }, { "name": "APEKS MICROFINANCE BANK", "code": "090143" }, { "name": "ARISE MICROFINANCE BANK", "code": "090282" }, { "name": "ASO SAVINGS", "code": "090001" }, { "name": "ASSETMATRIX MICROFINANCE BANK", "code": "090287" }, { "name": "ASSETS MFB", "code": "090473" }, { "name": "ASTRAPOLARIS MICROFINANCE BANK", "code": "090172" }, { "name": "AUCHI MICROFINANCE BANK ", "code": "090264" }, { "name": "AVUENEGBE MICROFINANCE BANK", "code": "090478" }, { "name": "AWACASH MICROFINANCE BANK", "code": "090633" }, { "name": "BAINES CREDIT MICROFINANCE BANK", "code": "090188" }, { "name": "BALOGUN GAMBARI MICROFINANCE BANK", "code": "090326" }, { "name": "BAM MICROFINANCE BANK", "code": "090651" }, { "name": "BANKLY MFB", "code": "090529" }, { "name": "BAOBAB MICROFINANCE BANK", "code": "090136" }, { "name": "BC KASH MICROFINANCE BANK", "code": "090127" }, { "name": "Beststar MFB", "code": "090615" }, { "name": "BETHEL MICROFINANCE BANK", "code": "090683" }, { "name": "BIPC MICROFINANCE BANK", "code": "090336" }, { "name": "BOCTRUST MICROFINANCE BANK LIMITED", "code": "090117" }, { "name": "BOKKOS MFB", "code": "090703" }, { "name": "BOROMU MICROFINANCE BANK", "code": "090501" }, { "name": "BOSAK MICROFINANCE BANK", "code": "090176" }, { "name": "Bowen Microfinance Bank", "code": "090148" }, { "name": "Branch International Financial Services", "code": "050006" }, { "name": "BRENT MORTGAGE BANK", "code": "070015" }, { "name": "BRIGHTWAY MICROFINANCE BANK", "code": "090308" }, { "name": "BUILD MICROFINANCE BANK", "code": "090613" }, { "name": "BUYPOWER MICROFINANCE BANK", "code": "090682" }, { "name": "CAPITALMETRIQ", "code": "51319" }, { "name": "CARBON", "code": "100026" }, { "name": "CASHBRIDGE MICROFINANCE BANK", "code": "090634" }, { "name": "CASHCONNECT MICROFINANCE BANK", "code": "090360" }, { "name": "CELLULANT", "code": "100005" }, { "name": "CEMCS Microfinance Bank", "code": "090154" }, { "name": "CHAMS MOBILE", "code": "100015" }, { "name": "CHIKUM MICROFINANCE BANK", "code": "090141" }, { "name": "Citibank Nigeria", "code": "000009" }, { "name": "CITYCODE MORTGAGE BANK", "code": "070027" }, { "name": "Clearpay Microfinance Bank", "code": "090482" }, { "name": "COASTLINE MICROFINANCE BANK", "code": "090374" }, { "name": "CONPRO MICROFINANCE BANK", "code": "090380" }, { "name": "CONSUMER MICROFINANCE BANK", "code": "090130" }, { "name": "CONTEC GLOBAL INFOTECH LIMITED(NOWNOW)", "code": "100032" }, { "name": "CORESTEP MICROFINANCE BANK", "code": "090365" }, { "name": "Coronation Bank", "code": "060001" }, { "name": "County Finance Limited", "code": "050001" }, { "name": "COVENANT MFB", "code": "070006" }, { "name": "CREDIT AFRIQUE MICROFINANCE BANK", "code": "090159" }, { "name": "CRUST MICROFINANCE BANK", "code": "090560" }, { "name": "CRUTECH  MFB", "code": "090414" }, { "name": "CSD MICROFINANCE BANK", "code": "090686" }, { "name": "DAL MFB", "code": "090596" }, { "name": "DAVENPORT MICROFINANCE BANK", "code": "090673" }, { "name": "DAVODANI MICROFINANCE BANK", "code": "090391" }, { "name": "DAYLIGHT MICROFINANCE BANK", "code": "090167" }, { "name": "DESTINY MFB", "code": "090723" }, { "name": "Diamond bank", "code": "000005" }, { "name": "DOJE Microfinance Bank Limited", "code": "090404" }, { "name": "DW MFB", "code": "090721" }, { "name": "EAGLE FLIGHT MICROFINANCE BANK", "code": "090294" }, { "name": "Earnwell MICROFINANCE BANK", "code": "090674" }, { "name": "EARTHOLEUM", "code": "100021" }, { "name": "E-BARCS MICROFINANCE BANK", "code": "090156" }, { "name": "Ecobank Nigeria Plc", "code": "000010" }, { "name": "ECOBANK XPRESS ACCOUNT", "code": "100008" }, { "name": "ECOMOBILE", "code": "100030" }, { "name": "EJINDU MFB", "code": "090694" }, { "name": "EKIMOGUN MFB", "code": "090552" }, { "name": "EKONDO MICROFINANCE BANK", "code": "090097" }, { "name": "EK-RELIABLE MICROFINANCE BANK", "code": "090389" }, { "name": "EMERALD MICROFINANCE BANK", "code": "090273" }, { "name": "EMPIRE TRUST MICROFINANCE BANK", "code": "090114" }, { "name": "ENTERPRISE BANK", "code": "000019" }, { "name": "ESO-E MICROFINANCE BANK", "code": "090166" }, { "name": "eTRANZACT", "code": "100006" }, { "name": "EVANGEL MICROFINANCE BANK ", "code": "090304" }, { "name": "EVERGREEN MICROFINANCE BANK", "code": "090332" }, { "name": "EXCEL MICROFINANCE BANK", "code": "090678" }, { "name": "Eyowo", "code": "090328" }, { "name": "FairMoney", "code": "090551" }, { "name": "FAST MICROFINANCE BANK", "code": "090179" }, { "name": "FBNQUEST MERCHANT BANK", "code": "060002" }, { "name": "FCMB MOBILE", "code": "100031" }, { "name": "FCT MICROFINANCE BANK", "code": "090290" }, { "name": "Federal Polytechnic Nekede Microfinance Bank", "code": "090398" }, { "name": "FEDPOLY NASARAWA MICROFINANCE BANK", "code": "090298" }, { "name": "FETS", "code": "100001" }, { "name": "FEWCHORE FINANCE COMAPNY LIMITED", "code": "050002" }, { "name": "FFS MICROFINANCE BANK", "code": "090153" }, { "name": "Fidelity bank", "code": "000007" }, { "name": "FIDELITY MOBILE", "code": "100019" }, { "name": "FIDFUND MICROFINANCE Bank", "code": "090126" }, { "name": "FINATRUST MICROFINANCE BANK", "code": "090111" }, { "name": "FINCA MICROFINANCE BANK", "code": "090400" }, { "name": "FIRMUS MICROFINANCE BANK", "code": "090366" }, { "name": "First bank", "code": "000016" }, { "name": "First City Monument Bank Plc", "code": "000003" }, { "name": "FIRST GENERATION MORTGAGE BANK", "code": "070014" }, { "name": "FIRSTMONIE WALLET", "code": "100014" }, { "name": "FIRST OPTION MICROFINANCE BANK", "code": "090285" }, { "name": "FIRST ROYAL MICROFINANCE BANK", "code": "090164" }, { "name": "FIRST TRUST MORTGAGE BANK PLC", "code": "090107" }, { "name": "FLUTTERWAVE TECHNOLOGY SOLUTIONS LIMITED", "code": "110002" }, { "name": "FOCUS MFB", "code": "090709" }, { "name": "FORTIS MICROFINANCE BANK", "code": "070002" }, { "name": "FORTIS MOBILE", "code": "100016" }, { "name": "FSDH", "code": "400001" }, { "name": "FULLRANGE MICROFINANCE BANK", "code": "090145" }, { "name": "FUTO MICROFINANCE BANK", "code": "090158" }, { "name": "Gabsyn Microfinance Bank Limited", "code": "090591" }, { "name": "Garun Mallam MFB", "code": "090691" }, { "name": "GATEWAY MORTGAGE BANK", "code": "070009" }, { "name": "GDL FINANCE", "code": "050026" }, { "name": "Globus Bank", "code": "000027" }, { "name": "GLORY MICROFINANCE BANK", "code": "090278" }, { "name": "GOLDMAN MICROFINANCE BANK", "code": "090574" }, { "name": "GOODNEWS MICROFINANCE BANK", "code": "090495" }, { "name": "GOOD SHEPHERD MICROFINANCE BANK", "code": "090664" }, { "name": "GOSIFECHUKWU MFB", "code": "090687" }, { "name": "GOWANS MICROFINANCE BANK", "code": "090122" }, { "name": "GRANTS MICROFINANCE BANK", "code": "090335" }, { "name": "Greenacres MFB", "code": "090599" }, { "name": "GREENBANK MICROFINANCE BANK", "code": "090178" }, { "name": "Greenwich Merchant Bank", "code": "060004" }, { "name": "GROOMING MICROFINANCE BANK", "code": "090195" }, { "name": "GTBank", "code": "000013" }, { "name": "GTI MICROFINANCE BANK", "code": "090385" }, { "name": "GT MOBILE", "code": "100009" }, { "name": "Hackman Microfinance Bank", "code": "090147" }, { "name": "HAGGAI MORTGAGE BANK LIMITED", "code": "070017" }, { "name": "HALO MICROFINANCE BANK", "code": "090539" }, { "name": "Hasal Microfinance Bank", "code": "090121" }, { "name": "HEADWAY MICROFINANCE BANK", "code": "090363" }, { "name": "HEDONMARK", "code": "100017" }, { "name": "Heritage bank", "code": "000020" }, { "name": "HopePSB", "code": "120002" }, { "name": "Ibile Microfinance Bank", "code": "090118" }, { "name": "IHIALA MFB", "code": "090725" }, { "name": "IKENNE MICROFINANCE BANK", "code": "090324" }, { "name": "IKIRE MICROFINANCE BANK", "code": "090279" }, { "name": "IKOYI ILE MICROFINANCE BANK", "code": "090681" }, { "name": "ILISAN MICROFINANCE BANK", "code": "090370" }, { "name": "IMO STATE MICROFINANCE BANK", "code": "090258" }, { "name": "IMPERIAL HOMES MORTGAGE BANK", "code": "100024" }, { "name": "IMSU MICROFINANCE BANK", "code": "090670" }, { "name": "Infinity MFB", "code": "090157" }, { "name": "INFINITY TRUST MORTGAGE BANK", "code": "070016" }, { "name": "INNOVECTIVES KESH", "code": "100029" }, { "name": "INSIGHT MICROFINANCE BANK", "code": "090434" }, { "name": "INTELLFIN", "code": "100027" }, { "name": "INTERLAND MICROFINANCE BANK", "code": "090386" }, { "name": "IRL MICROFINANCE BANK", "code": "090149" }, { "name": "ISALEOYO MICROFINANCE BANK", "code": "090377" }, { "name": "ISUA MFB", "code": "090701" }, { "name": "ISUOFIA MICROFINANCE BANK", "code": "090353" }, { "name": "JAIZ BANK", "code": "000006" }, { "name": "JUBILEE LIFE", "code": "090003" }, { "name": "KADPOLY MICROFINANCE BANK", "code": "090320" }, { "name": "KADUPE MICROFINANCE BANK", "code": "090669" }, { "name": "KAYI MICROFINANCE BANK", "code": "090667" }, { "name": "Kayvee MICROFINANCE BANK", "code": "090554" }, { "name": "Kenechukwu microfinance bank", "code": "090602" }, { "name": "Keystone bank", "code": "000002" }, { "name": "KONTAGORA MICROFINANCE BANK", "code": "090299" }, { "name": "Kuda Microfinance Bank", "code": "090267" }, { "name": "LAGOS BUILDING AND INVESTMENT COMPANY", "code": "070012" }, { "name": "LAPO MICROFINANCE BANK", "code": "090177" }, { "name": "LAVENDER MICROFINANCE BANK", "code": "090271" }, { "name": "LEGEND MICROFINANCE BANK", "code": "090372" }, { "name": "Letshego MFB", "code": "090420" }, { "name": "Links Microfinance Bank", "code": "090435" }, { "name": "LOMA MICROFINANCE BANK", "code": "090620" }, { "name": "LOTUS Bank", "code": "000029" }, { "name": "LOVONUS MICROFINANCE BANK", "code": "090265" }, { "name": "M36", "code": "100035" }, { "name": "Madobi MFB", "code": "090605" }, { "name": "MAINSTREET MICROFINANCE BANK", "code": "090171" }, { "name": "MANNY MICROFINANCE BANK", "code": "090383" }, { "name": "MAYFAIR MICROFINANCE BANK", "code": "090321" }, { "name": "MAYFRESH MORTGAGE BANK", "code": "070019" }, { "name": "MEGAPRAISE MICROFINANCE BANK", "code": "090280" }, { "name": "MICROVIS MICROFINANCE BANK ", "code": "090113" }, { "name": "MINT-FINEX MFB", "code": "090281" }, { "name": "Mint Microfinance Bank", "code": "090763" }, { "name": "M&M MICROFINANCE BANK", "code": "090685" }, { "name": "MOLUSI MICROFINANCE BANK", "code": "090362" }, { "name": "MoMo PSB", "code": "120003" }, { "name": "MONEY BOX", "code": "100020" }, { "name": "MONEYFIELD MICROFINANCE BANK", "code": "090144" }, { "name": "Moneymaster PSB", "code": "120005" }, { "name": "MONEY TRUST MICROFINANCE BANK", "code": "090129" }, { "name": "Moniepoint Microfinance Bank", "code": "090405" }, { "name": "MOZFIN MICROFINANCE BANK", "code": "090392" }, { "name": "MUTUAL ALLIANCE MORTGAGE BANK", "code": "070028" }, { "name": "MUTUAL BENEFITS MFB", "code": "090190" }, { "name": "MUTUAL TRUST MICROFINANCE BANK", "code": "090151" }, { "name": "NDDC MICROFINANCE BANK", "code": "90679" }, { "name": "NDIORAH MICROFINANCE BANK", "code": "090128" }, { "name": "NEPTUNE MICROFINANCE BANK", "code": "090329" }, { "name": "NET MFB", "code": "090675" }, { "name": "NEW DAWN MICROFINANCE BANK", "code": "090205" }, { "name": "NEW GOLDEN PASTURES MICROFINANCE BANK", "code": "090378" }, { "name": "NIGERIAN NAVY MICROFINANCE BANK ", "code": "090263" }, { "name": "NIRSAL NATIONAL MICROFINANCE BANK", "code": "090194" }, { "name": "NNEW WOMEN MICROFINANCE BANK", "code": "090283" }, { "name": "NOVA MERCHANT BANK", "code": "060003" }, { "name": "NOVUS MFB", "code": "090734" }, { "name": "NPF MICROFINANCE BANK", "code": "070001" }, { "name": "NUGGETS MFB", "code": "090676" }, { "name": "NUTURE MICROFINANCE BANK", "code": "090364" }, { "name": "NWANNEGADI MICROFINANCE BANK", "code": "090399" }, { "name": "OCHE MICROFINANCE BANK", "code": "090333" }, { "name": "OCTOPUS MICROFINANCE BANK", "code": "090576" }, { "name": "OHAFIA MICROFINANCE BANK", "code": "090119" }, { "name": "OKENGWE MICROFINANCE BANK", "code": "090646" }, { "name": "OK MICROFINANCE BANK", "code": "090567" }, { "name": "OKPOGA MICROFINANCE BANK", "code": "090161" }, { "name": "OLABISI ONABANJO UNIVERSITY MICROFINANCE ", "code": "090272" }, { "name": "OLIVE MFB", "code": "090696" }, { "name": "OMIYE MICROFINANCE BANK", "code": "090295" }, { "name": "OMOLUABI", "code": "070007" }, { "name": "OPAY", "code": "100004" }, { "name": "OPTIMUS BANK", "code": "000036" }, { "name": "OSCOTECH MICROFINANCE BANK", "code": "090396" }, { "name": "OTUO MICROFINANCE BANK", "code": "090542" }, { "name": "PAGA", "code": "100002" }, { "name": "PAGE MFBank", "code": "070008" }, { "name": "PALMPAY", "code": "100033" }, { "name": "PARALLEX", "code": "000030" }, { "name": "Parkway Microfinance Bank", "code": "090390" }, { "name": "PARKWAY-READYCASH", "code": "100003" }, { "name": "PATHFINDER MICROFINANACE BANK LIMITED", "code": "090680" }, { "name": "PATRICKGOLD MICROFINANCE BANK", "code": "090317" }, { "name": "PAYATTITUDE ONLINE", "code": "110001" }, { "name": "PAYSTACK PAYMENTS LIMITED", "code": "110006" }, { "name": "PECANTRUST MICROFINANCE BANK", "code": "090137" }, { "name": "PENNYWISE MICROFINANCE BANK ", "code": "090196" }, { "name": "PERSONAL TRUST MICROFINANCE BANK", "code": "090135" }, { "name": "Petra Mircofinance Bank Plc", "code": "090165" }, { "name": "PFI FINANCE COMPANY LIMITED", "code": "050021" }, { "name": "PILLAR MICROFINANCE BANK", "code": "090289" }, { "name": "PLATINUM MORTGAGE BANK", "code": "070013" }, { "name": "Polaris Bank", "code": "000008" }, { "name": "POLYIBADAN MFB", "code": "090534" }, { "name": "POLYUNWANA MICROFINANCE BANK", "code": "090296" }, { "name": "Premier Microfinance Bank", "code": "090779" }, { "name": "Premium Trust Bank", "code": "000031" }, { "name": "PRESTIGE MICROFINANCE BANK", "code": "090274" }, { "name": "PROSPECTS MFB", "code": "090689" }, { "name": "PROSPERITY MFB", "code": "090642" }, { "name": "Providus Bank", "code": "000023" }, { "name": "PRUDENT MICROFINANCE BANK", "code": "090690" }, { "name": "PURPLEMONEY MICROFINANCE BANK", "code": "090303" }, { "name": "Qube Microfinance Bank", "code": "090569" }, { "name": "QUICKFUND MICROFINANCE BANK", "code": "090261" }, { "name": "Randalpha Microfinance Bank", "code": "090496" }, { "name": "RAND MERCHANT BANK", "code": "000024" }, { "name": "REFUGE MORTGAGE BANK", "code": "070011" }, { "name": "REGENT MICROFINANCE BANK", "code": "090125" }, { "name": "Rehoboth Microfinance bank", "code": "090463" }, { "name": "RENMONEY MICROFINANCE BANK ", "code": "090198" }, { "name": "REPHIDIM MICROFINANCE BANK", "code": "090322" }, { "name": "REX Microfinance Bank", "code": "090449" }, { "name": "RICHWAY MICROFINANCE BANK", "code": "090132" }, { "name": "ROCKSHIELD MICROFINANCE BANK", "code": "090547" }, { "name": "ROYAL EXCHANGE MICROFINANCE BANK", "code": "090138" }, { "name": "RSU MICROFINANCE BANK", "code": "090535" }, { "name": "RUBIES MICROFINANCE BANK", "code": "090175" }, { "name": "SAFE HAVEN MICROFINANCE BANK", "code": "090286" }, { "name": "SAFETRUST", "code": "090006" }, { "name": "SAGAMU MICROFINANCE BANK", "code": "090140" }, { "name": "SEAP Microfinance Bank", "code": "090513" }, { "name": "SEED CAPITAL MICROFINANCE BANK", "code": "090112" }, { "name": "SEEDVEST MICROFINANCE BANK", "code": "090369" }, { "name": "SHALOM MFB", "code": "090502" }, { "name": "Signature Bank", "code": "000034" }, { "name": "SmartCash", "code": "120004" }, { "name": "Sparkle Microfinance Bank", "code": "090325" }, { "name": "Stanbic IBTC Bank Ltd.", "code": "000012" }, { "name": "STANBIC IBTC @Ease WALLET", "code": "100007" }, { "name": "Standard Chartered Bank Nigeria Ltd.", "code": "000021" }, { "name": "STANFORD MICROFINANACE BANK", "code": "090162" }, { "name": "STELLAS MICROFINANCE BANK ", "code": "090262" }, { "name": "Sterling bank", "code": "000001" }, { "name": "STERLING MOBILE", "code": "100022" }, { "name": "SULSPAP MICROFINANCE BANK", "code": "090305" }, { "name": "Suntrust Bank Nigeria Limited", "code": "000022" }, { "name": "TAGPAY", "code": "100023" }, { "name": "Taj Bank", "code": "000026" }, { "name": "Taj_Pinspay", "code": "080002" }, { "name": "TCF MFB", "code": "090115" }, { "name": "TEASY INTERNATIONAL", "code": "100010" }, { "name": "THINK FINANCE MICROFINANCE BANK", "code": "090373" }, { "name": "Titan Bank", "code": "000025" }, { "name": "TITAN-PAYSTACK MICROFINANCE BANK", "code": "100039" }, { "name": "TREASURES MICROFINANCE BANK", "code": "090663" }, { "name": "TRIDENT MICROFINANCE BANK", "code": "090146" }, { "name": "TRIVES FINANCE COMPANY LTD", "code": "050023" }, { "name": "TRUSTBANC J6 MICROFINANCE BANK LIMITED", "code": "090123" }, { "name": "TRUSTFUND MICROFINANCE BANK ", "code": "090276" }, { "name": "TRUST MICROFINANCE BANK", "code": "090327" }, { "name": "TSANYAWA MICROFINANCE BANK", "code": "090672" }, { "name": "UCEE MFB", "code": "090706" }, { "name": "U & C MICROFINANCE BANK", "code": "090315" }, { "name": "UMUCHINEMERE PROCREDIT MICROFINANCE BANK", "code": "090514" }, { "name": "UNAAB MICROFINANCE BANK", "code": "090331" }, { "name": "Unical Microfinance Bank", "code": "090193" }, { "name": "Union bank", "code": "000018" }, { "name": "United Bank For Africa Plc", "code": "000004" }, { "name": "Unity Bank Plc", "code": "000011" }, { "name": "UNIUYO MICROFINANCE BANK", "code": "090338" }, { "name": "UNIVERSITY OF NIGERIA, NSUKKA MICROFINANCE BANK", "code": "090251" }, { "name": "URE MICROFINANCE BANK", "code": "090619" }, { "name": "VENTURE GARDEN NIGERIA LIMITED", "code": "110009" }, { "name": "VFD microfinance bank", "code": "090110" }, { "name": "VIRTUE MICROFINANCE BANK", "code": "090150" }, { "name": "VISA MICROFINANCE BANK", "code": "090139" }, { "name": "VT NETWORKS", "code": "100012" }, { "name": "Wema bank", "code": "000017" }, { "name": "WESLEY MFB", "code": "090699" }, { "name": "Wetland Microfinance Bank Limited", "code": "090120" }, { "name": "WRA MFB", "code": "090631" }, { "name": "WUDIL MICROFINANCE BANK", "code": "090253" }, { "name": "Xpress Wallet", "code": "100040" }, { "name": "XSLNCE MICROFINANCE BANK", "code": "090124" }, { "name": "YES MICROFINANCE BANK", "code": "090142" }, { "name": "YOBE MICROFINANCE BANK", "code": "090252" }, { "name": "Zenith bank", "code": "000015" }, { "name": "ZENITH MOBILE", "code": "100018" }, { "name": "ZINTERNET - KONGAPAY", "code": "100025" }, { "name": "Zitra MfB", "code": "090718" } ], "limits": { "min_amount": "500", "max_amount": "500000000", "currency": "NGN" }, "lookup_fields": [ "bank_code", "account_number" ], "receipt_fields": [ "bank_code", "account_number" ] } } }, "timestamp": "2026-06-19T10:47:01.987567118Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/limits": { "get": { "tags": [ "Payouts" ], "summary": "Payout limits", "description": "Workspace-level min/max payout amounts per currency and per rail.", "operationId": "get_api_payouts_limits", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Limits retrieved successfully", "data": { "limits": [ { "country": "AD", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "AE", "currency": "AED", "min_amount": "10", "max_amount": "750000" }, { "country": "AR", "currency": "ARS", "min_amount": "200", "max_amount": "10000000" }, { "country": "AT", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "AU", "currency": "AUD", "min_amount": "5", "max_amount": "155000" }, { "country": "BE", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "BG", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "CD", "currency": "CDF", "min_amount": "100", "max_amount": "1000000", "min_amount_usd": "0.04", "max_amount_usd": "436.12" }, { "country": "CH", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "CI", "currency": "XOF", "min_amount": "100", "max_amount": "2000000", "min_amount_usd": "0.17", "max_amount_usd": "3464.76" }, { "country": "CM", "currency": "XAF", "min_amount": "100", "max_amount": "1000000", "min_amount_usd": "0.17", "max_amount_usd": "1712.33" }, { "country": "CN", "currency": "CNY", "min_amount": "15", "max_amount": "750000" }, { "country": "CZ", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "DE", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "DK", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "EE", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "ES", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "ET", "currency": "ETB", "min_amount": "200", "max_amount": "50000", "min_amount_usd": "1.34", "max_amount_usd": "334.13" }, { "country": "FI", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "FR", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "GA", "currency": "XAF", "min_amount": "200", "max_amount": "500000", "min_amount_usd": "0.34", "max_amount_usd": "856.16" }, { "country": "GB", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "GB", "currency": "GBP", "min_amount": "10", "max_amount": "80000" }, { "country": "GH", "currency": "GHS", "min_amount": "20", "max_amount": "15000", "min_amount_usd": "1.67", "max_amount_usd": "1254.26" }, { "country": "GM", "currency": "GMD", "min_amount": "10", "max_amount": "50000", "min_amount_usd": "0.14", "max_amount_usd": "693.41" }, { "country": "GR", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "HK", "currency": "CNY", "min_amount": "10", "max_amount": "750000" }, { "country": "HK", "currency": "HKD", "min_amount": "10", "max_amount": "1000000" }, { "country": "HR", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "HU", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "IE", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "IN", "currency": "INR", "min_amount": "1", "max_amount": "8850000" }, { "country": "IS", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "IT", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "KE", "currency": "KES", "min_amount": "20", "max_amount": "150000", "min_amount_usd": "0.16", "max_amount_usd": "1165.12" }, { "country": "KR", "currency": "KRW", "min_amount": "10000", "max_amount": "140000000" }, { "country": "LI", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "LT", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "LU", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "LV", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "MC", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "MT", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "NE", "currency": "XOF", "min_amount": "500", "max_amount": "500000000", "min_amount_usd": "0.87", "max_amount_usd": "866190.84" }, { "country": "NG", "currency": "NGN", "min_amount": "500", "max_amount": "500000000", "min_amount_usd": "0.36", "max_amount_usd": "362283.61" }, { "country": "NL", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "NO", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "PL", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "PT", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "RO", "currency": "EUR", "min_amount": "10", "max_amount": "100000" }, { "country": "RW", "currency": "RWF", "min_amount": "100", "max_amount": "10000000", "min_amount_usd": "0.07", "max_amount_usd": "7009.45" }, { "country": "SE", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "SG", "currency": "SGD", "min_amount": "1", "max_amount": "130000" }, { "country": "SI", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "SK", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "SM", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "SN", "currency": "XOF", "min_amount": "100", "max_amount": "200000", "min_amount_usd": "0.17", "max_amount_usd": "346.48" }, { "country": "UG", "currency": "UGX", "min_amount": "5500", "max_amount": "5000000", "min_amount_usd": "1.54", "max_amount_usd": "1395.89" }, { "country": "US", "currency": "USD", "min_amount": "1", "max_amount": "10000000", "min_amount_usd": "1", "max_amount_usd": "10000000" }, { "country": "VA", "currency": "EUR", "min_amount": "10", "max_amount": "86000" }, { "country": "ZA", "currency": "ZAR", "min_amount": "20", "max_amount": "1800000", "min_amount_usd": "1.22", "max_amount_usd": "109753.42" } ] }, "timestamp": "2026-06-19T10:47:02.758175719Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/banks/{countryCode}": { "get": { "tags": [ "Payouts" ], "summary": "Banks by country", "description": "Bank / mobile-money directory for a country. Use the returned `code` in Initialize's `bank_code`.", "operationId": "get_api_payouts_banks_countryCode", "parameters": [ { "name": "countryCode", "in": "path", "required": true, "schema": { "type": "string" }, "description": "countryCode identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Banks retrieved successfully", "data": { "banks": [ { "bank_name": "78 FINANCE COMPANY LIMITED", "bank_code": "110072" }, { "bank_name": "9JAPAY MICROFINANCE BANK", "bank_code": "090629" }, { "bank_name": "9 PAYMENT SERVICE BANK", "bank_code": "120001" }, { "bank_name": "ABBEY MORTGAGE BANK", "bank_code": "070010" }, { "bank_name": "AB MICROFINANCE BANK ", "bank_code": "090270" }, { "bank_name": "ABOVE ONLY MICROFINANCE BANK ", "bank_code": "090260" }, { "bank_name": "ABU MICROFINANCE BANK ", "bank_code": "090197" }, { "bank_name": "Access bank", "bank_code": "000014" }, { "bank_name": "ACCESS MONEY", "bank_code": "100013" }, { "bank_name": "ACCESS YELLO & BETA", "bank_code": "100052" }, { "bank_name": "ACCION MICROFINANCE BANK", "bank_code": "090134" }, { "bank_name": "ADA MICROFINANCE BANK", "bank_code": "090483" }, { "bank_name": "ADDOSSER MICROFINANCE BANK", "bank_code": "090160" }, { "bank_name": "ADEYEMI COLLEGE STAFF MICROFINANCE BANK", "bank_code": "090268" }, { "bank_name": "ADVANCLY MFB", "bank_code": "50134" }, { "bank_name": "AELLA MFB", "bank_code": "090614" }, { "bank_name": "AFEKHAFE MICROFINANCE BANK", "bank_code": "090292" }, { "bank_name": "AG MORTGAGE BANK", "bank_code": "100028" }, { "bank_name": "AKALABO MFB", "bank_code": "090698" }, { "bank_name": "AKU Microfinance Bank", "bank_code": "090531" }, { "bank_name": "AL-BARAKAH MICROFINANCE BANK", "bank_code": "090133" }, { "bank_name": "ALEKUN MICROFINANCE BANK", "bank_code": "090259" }, { "bank_name": "ALERT MICROFINANCE BANK", "bank_code": "090297" }, { "bank_name": "ALLWORKERS MICROFINANCE BANK", "bank_code": "090131" }, { "bank_name": "ALPHA KAPITAL MICROFINANCE BANK ", "bank_code": "090169" }, { "bank_name": "AMML MICROFINANCE BANK ", "bank_code": "090116" }, { "bank_name": "Amucha Microfinance Bank", "bank_code": "090645" }, { "bank_name": "APEKS MICROFINANCE BANK", "bank_code": "090143" }, { "bank_name": "ARISE MICROFINANCE BANK", "bank_code": "090282" }, { "bank_name": "ASO SAVINGS", "bank_code": "090001" }, { "bank_name": "ASSETMATRIX MICROFINANCE BANK", "bank_code": "090287" }, { "bank_name": "ASSETS MFB", "bank_code": "090473" }, { "bank_name": "ASTRAPOLARIS MICROFINANCE BANK", "bank_code": "090172" }, { "bank_name": "AUCHI MICROFINANCE BANK ", "bank_code": "090264" }, { "bank_name": "AVUENEGBE MICROFINANCE BANK", "bank_code": "090478" }, { "bank_name": "AWACASH MICROFINANCE BANK", "bank_code": "090633" }, { "bank_name": "BAINES CREDIT MICROFINANCE BANK", "bank_code": "090188" }, { "bank_name": "BALOGUN GAMBARI MICROFINANCE BANK", "bank_code": "090326" }, { "bank_name": "BAM MICROFINANCE BANK", "bank_code": "090651" }, { "bank_name": "BANKLY MFB", "bank_code": "090529" }, { "bank_name": "BAOBAB MICROFINANCE BANK", "bank_code": "090136" }, { "bank_name": "BC KASH MICROFINANCE BANK", "bank_code": "090127" }, { "bank_name": "Beststar MFB", "bank_code": "090615" }, { "bank_name": "BETHEL MICROFINANCE BANK", "bank_code": "090683" }, { "bank_name": "BIPC MICROFINANCE BANK", "bank_code": "090336" }, { "bank_name": "BOCTRUST MICROFINANCE BANK LIMITED", "bank_code": "090117" }, { "bank_name": "BOKKOS MFB", "bank_code": "090703" }, { "bank_name": "BOROMU MICROFINANCE BANK", "bank_code": "090501" }, { "bank_name": "BOSAK MICROFINANCE BANK", "bank_code": "090176" }, { "bank_name": "Bowen Microfinance Bank", "bank_code": "090148" }, { "bank_name": "Branch International Financial Services", "bank_code": "050006" }, { "bank_name": "BRENT MORTGAGE BANK", "bank_code": "070015" }, { "bank_name": "BRIGHTWAY MICROFINANCE BANK", "bank_code": "090308" }, { "bank_name": "BUILD MICROFINANCE BANK", "bank_code": "090613" }, { "bank_name": "BUYPOWER MICROFINANCE BANK", "bank_code": "090682" }, { "bank_name": "CAPITALMETRIQ", "bank_code": "51319" }, { "bank_name": "CARBON", "bank_code": "100026" }, { "bank_name": "CASHBRIDGE MICROFINANCE BANK", "bank_code": "090634" }, { "bank_name": "CASHCONNECT MICROFINANCE BANK", "bank_code": "090360" }, { "bank_name": "CELLULANT", "bank_code": "100005" }, { "bank_name": "CEMCS Microfinance Bank", "bank_code": "090154" }, { "bank_name": "CHAMS MOBILE", "bank_code": "100015" }, { "bank_name": "CHIKUM MICROFINANCE BANK", "bank_code": "090141" }, { "bank_name": "Citibank Nigeria", "bank_code": "000009" }, { "bank_name": "CITYCODE MORTGAGE BANK", "bank_code": "070027" }, { "bank_name": "Clearpay Microfinance Bank", "bank_code": "090482" }, { "bank_name": "COASTLINE MICROFINANCE BANK", "bank_code": "090374" }, { "bank_name": "CONPRO MICROFINANCE BANK", "bank_code": "090380" }, { "bank_name": "CONSUMER MICROFINANCE BANK", "bank_code": "090130" }, { "bank_name": "CONTEC GLOBAL INFOTECH LIMITED(NOWNOW)", "bank_code": "100032" }, { "bank_name": "CORESTEP MICROFINANCE BANK", "bank_code": "090365" }, { "bank_name": "Coronation Bank", "bank_code": "060001" }, { "bank_name": "County Finance Limited", "bank_code": "050001" }, { "bank_name": "COVENANT MFB", "bank_code": "070006" }, { "bank_name": "CREDIT AFRIQUE MICROFINANCE BANK", "bank_code": "090159" }, { "bank_name": "CRUST MICROFINANCE BANK", "bank_code": "090560" }, { "bank_name": "CRUTECH  MFB", "bank_code": "090414" }, { "bank_name": "CSD MICROFINANCE BANK", "bank_code": "090686" }, { "bank_name": "DAL MFB", "bank_code": "090596" }, { "bank_name": "DAVENPORT MICROFINANCE BANK", "bank_code": "090673" }, { "bank_name": "DAVODANI MICROFINANCE BANK", "bank_code": "090391" }, { "bank_name": "DAYLIGHT MICROFINANCE BANK", "bank_code": "090167" }, { "bank_name": "DESTINY MFB", "bank_code": "090723" }, { "bank_name": "Diamond bank", "bank_code": "000005" }, { "bank_name": "DOJE Microfinance Bank Limited", "bank_code": "090404" }, { "bank_name": "DW MFB", "bank_code": "090721" }, { "bank_name": "EAGLE FLIGHT MICROFINANCE BANK", "bank_code": "090294" }, { "bank_name": "Earnwell MICROFINANCE BANK", "bank_code": "090674" }, { "bank_name": "EARTHOLEUM", "bank_code": "100021" }, { "bank_name": "E-BARCS MICROFINANCE BANK", "bank_code": "090156" }, { "bank_name": "Ecobank Nigeria Plc", "bank_code": "000010" }, { "bank_name": "ECOBANK XPRESS ACCOUNT", "bank_code": "100008" }, { "bank_name": "ECOMOBILE", "bank_code": "100030" }, { "bank_name": "EJINDU MFB", "bank_code": "090694" }, { "bank_name": "EKIMOGUN MFB", "bank_code": "090552" }, { "bank_name": "EKONDO MICROFINANCE BANK", "bank_code": "090097" }, { "bank_name": "EK-RELIABLE MICROFINANCE BANK", "bank_code": "090389" }, { "bank_name": "EMERALD MICROFINANCE BANK", "bank_code": "090273" }, { "bank_name": "EMPIRE TRUST MICROFINANCE BANK", "bank_code": "090114" }, { "bank_name": "ENTERPRISE BANK", "bank_code": "000019" }, { "bank_name": "ESO-E MICROFINANCE BANK", "bank_code": "090166" }, { "bank_name": "eTRANZACT", "bank_code": "100006" }, { "bank_name": "EVANGEL MICROFINANCE BANK ", "bank_code": "090304" }, { "bank_name": "EVERGREEN MICROFINANCE BANK", "bank_code": "090332" }, { "bank_name": "EXCEL MICROFINANCE BANK", "bank_code": "090678" }, { "bank_name": "Eyowo", "bank_code": "090328" }, { "bank_name": "FairMoney", "bank_code": "090551" }, { "bank_name": "FAST MICROFINANCE BANK", "bank_code": "090179" }, { "bank_name": "FBNQUEST MERCHANT BANK", "bank_code": "060002" }, { "bank_name": "FCMB MOBILE", "bank_code": "100031" }, { "bank_name": "FCT MICROFINANCE BANK", "bank_code": "090290" }, { "bank_name": "Federal Polytechnic Nekede Microfinance Bank", "bank_code": "090398" }, { "bank_name": "FEDPOLY NASARAWA MICROFINANCE BANK", "bank_code": "090298" }, { "bank_name": "FETS", "bank_code": "100001" }, { "bank_name": "FEWCHORE FINANCE COMAPNY LIMITED", "bank_code": "050002" }, { "bank_name": "FFS MICROFINANCE BANK", "bank_code": "090153" }, { "bank_name": "Fidelity bank", "bank_code": "000007" }, { "bank_name": "FIDELITY MOBILE", "bank_code": "100019" }, { "bank_name": "FIDFUND MICROFINANCE Bank", "bank_code": "090126" }, { "bank_name": "FINATRUST MICROFINANCE BANK", "bank_code": "090111" }, { "bank_name": "FINCA MICROFINANCE BANK", "bank_code": "090400" }, { "bank_name": "FIRMUS MICROFINANCE BANK", "bank_code": "090366" }, { "bank_name": "First bank", "bank_code": "000016" }, { "bank_name": "First City Monument Bank Plc", "bank_code": "000003" }, { "bank_name": "FIRST GENERATION MORTGAGE BANK", "bank_code": "070014" }, { "bank_name": "FIRSTMONIE WALLET", "bank_code": "100014" }, { "bank_name": "FIRST OPTION MICROFINANCE BANK", "bank_code": "090285" }, { "bank_name": "FIRST ROYAL MICROFINANCE BANK", "bank_code": "090164" }, { "bank_name": "FIRST TRUST MORTGAGE BANK PLC", "bank_code": "090107" }, { "bank_name": "FLUTTERWAVE TECHNOLOGY SOLUTIONS LIMITED", "bank_code": "110002" }, { "bank_name": "FOCUS MFB", "bank_code": "090709" }, { "bank_name": "FORTIS MICROFINANCE BANK", "bank_code": "070002" }, { "bank_name": "FORTIS MOBILE", "bank_code": "100016" }, { "bank_name": "FSDH", "bank_code": "400001" }, { "bank_name": "FULLRANGE MICROFINANCE BANK", "bank_code": "090145" }, { "bank_name": "FUTO MICROFINANCE BANK", "bank_code": "090158" }, { "bank_name": "Gabsyn Microfinance Bank Limited", "bank_code": "090591" }, { "bank_name": "Garun Mallam MFB", "bank_code": "090691" }, { "bank_name": "GATEWAY MORTGAGE BANK", "bank_code": "070009" }, { "bank_name": "GDL FINANCE", "bank_code": "050026" }, { "bank_name": "Globus Bank", "bank_code": "000027" }, { "bank_name": "GLORY MICROFINANCE BANK", "bank_code": "090278" }, { "bank_name": "GOLDMAN MICROFINANCE BANK", "bank_code": "090574" }, { "bank_name": "GOODNEWS MICROFINANCE BANK", "bank_code": "090495" }, { "bank_name": "GOOD SHEPHERD MICROFINANCE BANK", "bank_code": "090664" }, { "bank_name": "GOSIFECHUKWU MFB", "bank_code": "090687" }, { "bank_name": "GOWANS MICROFINANCE BANK", "bank_code": "090122" }, { "bank_name": "GRANTS MICROFINANCE BANK", "bank_code": "090335" }, { "bank_name": "Greenacres MFB", "bank_code": "090599" }, { "bank_name": "GREENBANK MICROFINANCE BANK", "bank_code": "090178" }, { "bank_name": "Greenwich Merchant Bank", "bank_code": "060004" }, { "bank_name": "GROOMING MICROFINANCE BANK", "bank_code": "090195" }, { "bank_name": "GTBank", "bank_code": "000013" }, { "bank_name": "GTI MICROFINANCE BANK", "bank_code": "090385" }, { "bank_name": "GT MOBILE", "bank_code": "100009" }, { "bank_name": "Hackman Microfinance Bank", "bank_code": "090147" }, { "bank_name": "HAGGAI MORTGAGE BANK LIMITED", "bank_code": "070017" }, { "bank_name": "HALO MICROFINANCE BANK", "bank_code": "090539" }, { "bank_name": "Hasal Microfinance Bank", "bank_code": "090121" }, { "bank_name": "HEADWAY MICROFINANCE BANK", "bank_code": "090363" }, { "bank_name": "HEDONMARK", "bank_code": "100017" }, { "bank_name": "Heritage bank", "bank_code": "000020" }, { "bank_name": "HopePSB", "bank_code": "120002" }, { "bank_name": "Ibile Microfinance Bank", "bank_code": "090118" }, { "bank_name": "IHIALA MFB", "bank_code": "090725" }, { "bank_name": "IKENNE MICROFINANCE BANK", "bank_code": "090324" }, { "bank_name": "IKIRE MICROFINANCE BANK", "bank_code": "090279" }, { "bank_name": "IKOYI ILE MICROFINANCE BANK", "bank_code": "090681" }, { "bank_name": "ILISAN MICROFINANCE BANK", "bank_code": "090370" }, { "bank_name": "IMO STATE MICROFINANCE BANK", "bank_code": "090258" }, { "bank_name": "IMPERIAL HOMES MORTGAGE BANK", "bank_code": "100024" }, { "bank_name": "IMSU MICROFINANCE BANK", "bank_code": "090670" }, { "bank_name": "Infinity MFB", "bank_code": "090157" }, { "bank_name": "INFINITY TRUST MORTGAGE BANK", "bank_code": "070016" }, { "bank_name": "INNOVECTIVES KESH", "bank_code": "100029" }, { "bank_name": "INSIGHT MICROFINANCE BANK", "bank_code": "090434" }, { "bank_name": "INTELLFIN", "bank_code": "100027" }, { "bank_name": "INTERLAND MICROFINANCE BANK", "bank_code": "090386" }, { "bank_name": "IRL MICROFINANCE BANK", "bank_code": "090149" }, { "bank_name": "ISALEOYO MICROFINANCE BANK", "bank_code": "090377" }, { "bank_name": "ISUA MFB", "bank_code": "090701" }, { "bank_name": "ISUOFIA MICROFINANCE BANK", "bank_code": "090353" }, { "bank_name": "JAIZ BANK", "bank_code": "000006" }, { "bank_name": "JUBILEE LIFE", "bank_code": "090003" }, { "bank_name": "KADPOLY MICROFINANCE BANK", "bank_code": "090320" }, { "bank_name": "KADUPE MICROFINANCE BANK", "bank_code": "090669" }, { "bank_name": "KAYI MICROFINANCE BANK", "bank_code": "090667" }, { "bank_name": "Kayvee MICROFINANCE BANK", "bank_code": "090554" }, { "bank_name": "Kenechukwu microfinance bank", "bank_code": "090602" }, { "bank_name": "Keystone bank", "bank_code": "000002" }, { "bank_name": "KONTAGORA MICROFINANCE BANK", "bank_code": "090299" }, { "bank_name": "Kuda Microfinance Bank", "bank_code": "090267" }, { "bank_name": "LAGOS BUILDING AND INVESTMENT COMPANY", "bank_code": "070012" }, { "bank_name": "LAPO MICROFINANCE BANK", "bank_code": "090177" }, { "bank_name": "LAVENDER MICROFINANCE BANK", "bank_code": "090271" }, { "bank_name": "LEGEND MICROFINANCE BANK", "bank_code": "090372" }, { "bank_name": "Letshego MFB", "bank_code": "090420" }, { "bank_name": "Links Microfinance Bank", "bank_code": "090435" }, { "bank_name": "LOMA MICROFINANCE BANK", "bank_code": "090620" }, { "bank_name": "LOTUS Bank", "bank_code": "000029" }, { "bank_name": "LOVONUS MICROFINANCE BANK", "bank_code": "090265" }, { "bank_name": "M36", "bank_code": "100035" }, { "bank_name": "Madobi MFB", "bank_code": "090605" }, { "bank_name": "MAINSTREET MICROFINANCE BANK", "bank_code": "090171" }, { "bank_name": "MANNY MICROFINANCE BANK", "bank_code": "090383" }, { "bank_name": "MAYFAIR MICROFINANCE BANK", "bank_code": "090321" }, { "bank_name": "MAYFRESH MORTGAGE BANK", "bank_code": "070019" }, { "bank_name": "MEGAPRAISE MICROFINANCE BANK", "bank_code": "090280" }, { "bank_name": "MICROVIS MICROFINANCE BANK ", "bank_code": "090113" }, { "bank_name": "MINT-FINEX MFB", "bank_code": "090281" }, { "bank_name": "Mint Microfinance Bank", "bank_code": "090763" }, { "bank_name": "M&M MICROFINANCE BANK", "bank_code": "090685" }, { "bank_name": "MOLUSI MICROFINANCE BANK", "bank_code": "090362" }, { "bank_name": "MoMo PSB", "bank_code": "120003" }, { "bank_name": "MONEY BOX", "bank_code": "100020" }, { "bank_name": "MONEYFIELD MICROFINANCE BANK", "bank_code": "090144" }, { "bank_name": "Moneymaster PSB", "bank_code": "120005" }, { "bank_name": "MONEY TRUST MICROFINANCE BANK", "bank_code": "090129" }, { "bank_name": "Moniepoint Microfinance Bank", "bank_code": "090405" }, { "bank_name": "MOZFIN MICROFINANCE BANK", "bank_code": "090392" }, { "bank_name": "MUTUAL ALLIANCE MORTGAGE BANK", "bank_code": "070028" }, { "bank_name": "MUTUAL BENEFITS MFB", "bank_code": "090190" }, { "bank_name": "MUTUAL TRUST MICROFINANCE BANK", "bank_code": "090151" }, { "bank_name": "NDDC MICROFINANCE BANK", "bank_code": "90679" }, { "bank_name": "NDIORAH MICROFINANCE BANK", "bank_code": "090128" }, { "bank_name": "NEPTUNE MICROFINANCE BANK", "bank_code": "090329" }, { "bank_name": "NET MFB", "bank_code": "090675" }, { "bank_name": "NEW DAWN MICROFINANCE BANK", "bank_code": "090205" }, { "bank_name": "NEW GOLDEN PASTURES MICROFINANCE BANK", "bank_code": "090378" }, { "bank_name": "NIGERIAN NAVY MICROFINANCE BANK ", "bank_code": "090263" }, { "bank_name": "NIRSAL NATIONAL MICROFINANCE BANK", "bank_code": "090194" }, { "bank_name": "NNEW WOMEN MICROFINANCE BANK", "bank_code": "090283" }, { "bank_name": "NOVA MERCHANT BANK", "bank_code": "060003" }, { "bank_name": "NOVUS MFB", "bank_code": "090734" }, { "bank_name": "NPF MICROFINANCE BANK", "bank_code": "070001" }, { "bank_name": "NUGGETS MFB", "bank_code": "090676" }, { "bank_name": "NUTURE MICROFINANCE BANK", "bank_code": "090364" }, { "bank_name": "NWANNEGADI MICROFINANCE BANK", "bank_code": "090399" }, { "bank_name": "OCHE MICROFINANCE BANK", "bank_code": "090333" }, { "bank_name": "OCTOPUS MICROFINANCE BANK", "bank_code": "090576" }, { "bank_name": "OHAFIA MICROFINANCE BANK", "bank_code": "090119" }, { "bank_name": "OKENGWE MICROFINANCE BANK", "bank_code": "090646" }, { "bank_name": "OK MICROFINANCE BANK", "bank_code": "090567" }, { "bank_name": "OKPOGA MICROFINANCE BANK", "bank_code": "090161" }, { "bank_name": "OLABISI ONABANJO UNIVERSITY MICROFINANCE ", "bank_code": "090272" }, { "bank_name": "OLIVE MFB", "bank_code": "090696" }, { "bank_name": "OMIYE MICROFINANCE BANK", "bank_code": "090295" }, { "bank_name": "OMOLUABI", "bank_code": "070007" }, { "bank_name": "OPAY", "bank_code": "100004" }, { "bank_name": "OPTIMUS BANK", "bank_code": "000036" }, { "bank_name": "OSCOTECH MICROFINANCE BANK", "bank_code": "090396" }, { "bank_name": "OTUO MICROFINANCE BANK", "bank_code": "090542" }, { "bank_name": "PAGA", "bank_code": "100002" }, { "bank_name": "PAGE MFBank", "bank_code": "070008" }, { "bank_name": "PALMPAY", "bank_code": "100033" }, { "bank_name": "PARALLEX", "bank_code": "000030" }, { "bank_name": "Parkway Microfinance Bank", "bank_code": "090390" }, { "bank_name": "PARKWAY-READYCASH", "bank_code": "100003" }, { "bank_name": "PATHFINDER MICROFINANACE BANK LIMITED", "bank_code": "090680" }, { "bank_name": "PATRICKGOLD MICROFINANCE BANK", "bank_code": "090317" }, { "bank_name": "PAYATTITUDE ONLINE", "bank_code": "110001" }, { "bank_name": "PAYSTACK PAYMENTS LIMITED", "bank_code": "110006" }, { "bank_name": "PECANTRUST MICROFINANCE BANK", "bank_code": "090137" }, { "bank_name": "PENNYWISE MICROFINANCE BANK ", "bank_code": "090196" }, { "bank_name": "PERSONAL TRUST MICROFINANCE BANK", "bank_code": "090135" }, { "bank_name": "Petra Mircofinance Bank Plc", "bank_code": "090165" }, { "bank_name": "PFI FINANCE COMPANY LIMITED", "bank_code": "050021" }, { "bank_name": "PILLAR MICROFINANCE BANK", "bank_code": "090289" }, { "bank_name": "PLATINUM MORTGAGE BANK", "bank_code": "070013" }, { "bank_name": "Polaris Bank", "bank_code": "000008" }, { "bank_name": "POLYIBADAN MFB", "bank_code": "090534" }, { "bank_name": "POLYUNWANA MICROFINANCE BANK", "bank_code": "090296" }, { "bank_name": "Premier Microfinance Bank", "bank_code": "090779" }, { "bank_name": "Premium Trust Bank", "bank_code": "000031" }, { "bank_name": "PRESTIGE MICROFINANCE BANK", "bank_code": "090274" }, { "bank_name": "PROSPECTS MFB", "bank_code": "090689" }, { "bank_name": "PROSPERITY MFB", "bank_code": "090642" }, { "bank_name": "Providus Bank", "bank_code": "000023" }, { "bank_name": "PRUDENT MICROFINANCE BANK", "bank_code": "090690" }, { "bank_name": "PURPLEMONEY MICROFINANCE BANK", "bank_code": "090303" }, { "bank_name": "Qube Microfinance Bank", "bank_code": "090569" }, { "bank_name": "QUICKFUND MICROFINANCE BANK", "bank_code": "090261" }, { "bank_name": "Randalpha Microfinance Bank", "bank_code": "090496" }, { "bank_name": "RAND MERCHANT BANK", "bank_code": "000024" }, { "bank_name": "REFUGE MORTGAGE BANK", "bank_code": "070011" }, { "bank_name": "REGENT MICROFINANCE BANK", "bank_code": "090125" }, { "bank_name": "Rehoboth Microfinance bank", "bank_code": "090463" }, { "bank_name": "RENMONEY MICROFINANCE BANK ", "bank_code": "090198" }, { "bank_name": "REPHIDIM MICROFINANCE BANK", "bank_code": "090322" }, { "bank_name": "REX Microfinance Bank", "bank_code": "090449" }, { "bank_name": "RICHWAY MICROFINANCE BANK", "bank_code": "090132" }, { "bank_name": "ROCKSHIELD MICROFINANCE BANK", "bank_code": "090547" }, { "bank_name": "ROYAL EXCHANGE MICROFINANCE BANK", "bank_code": "090138" }, { "bank_name": "RSU MICROFINANCE BANK", "bank_code": "090535" }, { "bank_name": "RUBIES MICROFINANCE BANK", "bank_code": "090175" }, { "bank_name": "SAFE HAVEN MICROFINANCE BANK", "bank_code": "090286" }, { "bank_name": "SAFETRUST", "bank_code": "090006" }, { "bank_name": "SAGAMU MICROFINANCE BANK", "bank_code": "090140" }, { "bank_name": "SEAP Microfinance Bank", "bank_code": "090513" }, { "bank_name": "SEED CAPITAL MICROFINANCE BANK", "bank_code": "090112" }, { "bank_name": "SEEDVEST MICROFINANCE BANK", "bank_code": "090369" }, { "bank_name": "SHALOM MFB", "bank_code": "090502" }, { "bank_name": "Signature Bank", "bank_code": "000034" }, { "bank_name": "SmartCash", "bank_code": "120004" }, { "bank_name": "Sparkle Microfinance Bank", "bank_code": "090325" }, { "bank_name": "Stanbic IBTC Bank Ltd.", "bank_code": "000012" }, { "bank_name": "STANBIC IBTC @Ease WALLET", "bank_code": "100007" }, { "bank_name": "Standard Chartered Bank Nigeria Ltd.", "bank_code": "000021" }, { "bank_name": "STANFORD MICROFINANACE BANK", "bank_code": "090162" }, { "bank_name": "STELLAS MICROFINANCE BANK ", "bank_code": "090262" }, { "bank_name": "Sterling bank", "bank_code": "000001" }, { "bank_name": "STERLING MOBILE", "bank_code": "100022" }, { "bank_name": "SULSPAP MICROFINANCE BANK", "bank_code": "090305" }, { "bank_name": "Suntrust Bank Nigeria Limited", "bank_code": "000022" }, { "bank_name": "TAGPAY", "bank_code": "100023" }, { "bank_name": "Taj Bank", "bank_code": "000026" }, { "bank_name": "Taj_Pinspay", "bank_code": "080002" }, { "bank_name": "TCF MFB", "bank_code": "090115" }, { "bank_name": "TEASY INTERNATIONAL", "bank_code": "100010" }, { "bank_name": "THINK FINANCE MICROFINANCE BANK", "bank_code": "090373" }, { "bank_name": "Titan Bank", "bank_code": "000025" }, { "bank_name": "TITAN-PAYSTACK MICROFINANCE BANK", "bank_code": "100039" }, { "bank_name": "TREASURES MICROFINANCE BANK", "bank_code": "090663" }, { "bank_name": "TRIDENT MICROFINANCE BANK", "bank_code": "090146" }, { "bank_name": "TRIVES FINANCE COMPANY LTD", "bank_code": "050023" }, { "bank_name": "TRUSTBANC J6 MICROFINANCE BANK LIMITED", "bank_code": "090123" }, { "bank_name": "TRUSTFUND MICROFINANCE BANK ", "bank_code": "090276" }, { "bank_name": "TRUST MICROFINANCE BANK", "bank_code": "090327" }, { "bank_name": "TSANYAWA MICROFINANCE BANK", "bank_code": "090672" }, { "bank_name": "UCEE MFB", "bank_code": "090706" }, { "bank_name": "U & C MICROFINANCE BANK", "bank_code": "090315" }, { "bank_name": "UMUCHINEMERE PROCREDIT MICROFINANCE BANK", "bank_code": "090514" }, { "bank_name": "UNAAB MICROFINANCE BANK", "bank_code": "090331" }, { "bank_name": "Unical Microfinance Bank", "bank_code": "090193" }, { "bank_name": "Union bank", "bank_code": "000018" }, { "bank_name": "United Bank For Africa Plc", "bank_code": "000004" }, { "bank_name": "Unity Bank Plc", "bank_code": "000011" }, { "bank_name": "UNIUYO MICROFINANCE BANK", "bank_code": "090338" }, { "bank_name": "UNIVERSITY OF NIGERIA, NSUKKA MICROFINANCE BANK", "bank_code": "090251" }, { "bank_name": "URE MICROFINANCE BANK", "bank_code": "090619" }, { "bank_name": "VENTURE GARDEN NIGERIA LIMITED", "bank_code": "110009" }, { "bank_name": "VFD microfinance bank", "bank_code": "090110" }, { "bank_name": "VIRTUE MICROFINANCE BANK", "bank_code": "090150" }, { "bank_name": "VISA MICROFINANCE BANK", "bank_code": "090139" }, { "bank_name": "VT NETWORKS", "bank_code": "100012" }, { "bank_name": "Wema bank", "bank_code": "000017" }, { "bank_name": "WESLEY MFB", "bank_code": "090699" }, { "bank_name": "Wetland Microfinance Bank Limited", "bank_code": "090120" }, { "bank_name": "WRA MFB", "bank_code": "090631" }, { "bank_name": "WUDIL MICROFINANCE BANK", "bank_code": "090253" }, { "bank_name": "Xpress Wallet", "bank_code": "100040" }, { "bank_name": "XSLNCE MICROFINANCE BANK", "bank_code": "090124" }, { "bank_name": "YES MICROFINANCE BANK", "bank_code": "090142" }, { "bank_name": "YOBE MICROFINANCE BANK", "bank_code": "090252" }, { "bank_name": "Zenith bank", "bank_code": "000015" }, { "bank_name": "ZENITH MOBILE", "bank_code": "100018" }, { "bank_name": "ZINTERNET - KONGAPAY", "bank_code": "100025" }, { "bank_name": "Zitra MfB", "bank_code": "090718" } ], "country_code": "NGA", "country_name": "Nigeria", "total": 358 }, "timestamp": "2026-06-19T10:47:03.309040201Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List payouts", "description": "Payout history with filters.", "operationId": "get_api_payouts", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "example": "50" }, "description": "" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Payouts retrieved successfully", "data": { "items": [], "total_count": 0, "limit": 50, "offset": 0, "has_more": false }, "timestamp": "2026-06-19T10:47:04.431490635Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/payouts/{id}": { "get": { "tags": [ "Payouts" ], "summary": "Get payout", "description": "Single payout, including lifecycle events and rail-specific metadata.", "operationId": "get_api_payouts_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "id identifier" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "success": true, "message": "Payout retrieved successfully", "data": { "payout": { "id": "019edfb7-b435-7c95-a34c-226966aaed21", "quote_id": "QT_107371", "company_id": "7a3f909c-1208-42d5-927a-583c41281d8a", "customer_id": "019edc65-bc3f-7bc4-980b-e328a940ef5d", "status": "INITIATED", "source": "OFFCHAIN", "from_asset": "USDT", "chain": "CHAIN_TYPE_UNSPECIFIED", "to_currency": "NGN", "sat_amount": "5790", "btc_amount": "0.0000579", "cent_amount": "500000", "amount": "3.62902", "settlement_amount": "5000", "cent_fees": "0", "fees": "0", "exchange_rate": { "rate": "1380.5434", "btc_rate": "62678.85", "currency": "ngn", "effective_rate": "1377.7824316206579187" }, "beneficiary": { "account_name": "CHIAMAKA JENNIFER EZEOBI", "account_number": "1421795566", "bank_code": "000014", "country": "NG", "destination_type": "bank" }, "trip": { "quote_at": "2026-06-19T11:50:18.933821639Z", "initialized_at": "2026-06-19T11:50:19.531892243Z" }, "reference": "init-1781869819", "callback_url": "https://example.com/webhooks/payouts", "provider_settlement_id": "sandbox_txn_40ac2ffd-b9d6-4217-be7f-d16f5ea1420f", "country": "NG", "expires_at": "2026-06-19T12:06:18.933832Z", "created_at": "2026-06-19T11:50:18.933833Z", "updated_at": "2026-06-19T11:50:19.531892Z" } }, "timestamp": "2026-06-19T11:51:05.77225279Z" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (bad HMAC signature or client id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BitnobHmacAuth": { "type": "apiKey", "in": "header", "name": "X-Auth-Signature", "description": "HMAC-SHA256 authentication. All calls must include four headers:\n- `X-Auth-Client` — your workspace client id\n- `X-Auth-Timestamp` — Unix seconds\n- `X-Auth-Nonce` — 16-byte random hex\n- `X-Auth-Signature` — hex(HMAC-SHA256(\n `{client_id}:{timestamp}:{nonce}:{compact_json_body}`,\n client_secret))\n" } }, "schemas": { "Error": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "example": { "type": "https://api.bitnob.com/errors/UNAUTHORIZED", "title": "Unauthorized", "status": 401, "detail": "Invalid HMAC signature", "code": "UNAUTHORIZED", "correlation_id": "req_019d9b7e-9e76-711e-afbe-aba9b9455412", "timestamp": "2026-04-17T12:50:59.850532036Z" } }, "PayoutWebhookEvent": { "type": "object", "description": "Payload delivered to your callback_url when a payout changes state. Switch on `event`; `data.status` is the lower-case event outcome, not the payout record lifecycle status.", "required": [ "event", "event_id", "data" ], "properties": { "event": { "type": "string", "description": "Event name.", "enum": [ "payouts.initialized", "payouts.processing", "payouts.withdrawal.success", "payouts.withdrawal.expired" ] }, "event_id": { "type": "string", "description": "Unique id for this delivery. De-duplicate on it, since events may be retried.", "format": "uuid" }, "data": { "type": "object", "required": [ "id", "quote_id", "company_id", "reference", "status", "from_asset", "to_currency", "amount", "settlement_amount", "fees", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The payout's internal identifier.", "format": "uuid" }, "quote_id": { "type": "string", "description": "The quote this payout was created from." }, "company_id": { "type": "string", "description": "The company that owns the payout.", "format": "uuid" }, "reference": { "type": "string", "description": "Reference for the payout, echoed back for reconciliation." }, "status": { "type": "string", "description": "Event outcome, lower-case.", "enum": [ "initiated", "processing", "success", "expired" ] }, "from_asset": { "type": "string", "description": "Crypto asset debited, lower-case.", "example": "usdt" }, "to_currency": { "type": "string", "description": "Fiat currency paid out, lower-case.", "example": "ngn" }, "amount": { "type": "string", "description": "Amount debited in from_asset." }, "settlement_amount": { "type": "string", "description": "Amount credited to the beneficiary in to_currency." }, "fees": { "type": "string", "description": "Fee charged for processing the payout, in from_asset." }, "payment_reason": { "type": "string", "description": "The payment_reason supplied on initialize, when one was set." }, "beneficiary": { "type": "object", "description": "Destination the funds settled to. Absent on some events.", "properties": { "country": { "type": "string", "description": "Destination country, lower-case.", "example": "ng" }, "bank_code": { "type": "string", "description": "Destination bank or mobile-money provider code.", "example": "100004" }, "account_number": { "type": "string", "description": "Masked destination account number.", "example": "****3001" } } }, "created_at": { "type": "string", "description": "When the payout record was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "When the payout record was last updated.", "format": "date-time" }, "completed_at": { "type": "string", "description": "When the payout reached a terminal state. Absent while in flight.", "format": "date-time" } } } } } } } }