openapi: 3.0.3 info: title: Bitnob API v2 version: 2.0.0 description: >- # Bitnob API v2 A single, ready-to-use collection for the Bitnob Core API v2 — balances, payouts, cards, trading, lightning, bulk transfers and more. ## Quick start 1. Set the collection variables: - `base_url` — e.g. `https://api.bitnob.com` - `client_id` — your workspace client id - `client_secret` — your workspace client secret 2. Run any request. The **collection-level pre-request script** automatically: - generates a fresh `timestamp` + `nonce`, - canonicalises the JSON body (compact form), - computes `HmacSHA256(client_id:timestamp:nonce:body, client_secret)`, and - injects `X-Auth-Client`, `X-Auth-Timestamp`, `X-Auth-Nonce`, `X-Auth-Signature`. You never modify headers manually — just edit the body and hit send. ## Conventions - **Amounts** are in *base units* (whole integers, no decimals). For USDT that's `1 USDT = 1_000_000` units. For BTC that's sats. - **`memo`** is only meaningful for chains that require a destination tag (e.g. Stellar). Omit it for Tron/Ethereum. - **`reference`** is caller-supplied and should be unique per action for safe retries / idempotency. - Most error responses follow RFC 7807 (`type`, `title`, `status`, `detail`, `correlation_id`, `timestamp`). ## Folders Every 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: flow_type: deposit from_address: TQrY8tryqsYVCYS3MFbtffiPp2ccyn4rkr 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: flow_type: deposit from_address: TQrY8tryqsYVCYS3MFbtffiPp2ccyn4rkr 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: flow_type: deposit from_address: TQrY8tryqsYVCYS3MFbtffiPp2ccyn4rkr 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: flow_type: deposit from_address: TQrY8tryqsYVCYS3MFbtffiPp2ccyn4rkr 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': &id001 description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': &id002 description: Unauthorized (bad HMAC signature or client id) content: application/json: schema: $ref: '#/components/schemas/Error' '404': &id003 description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' '422': &id004 description: Semantic validation error content: application/json: schema: $ref: '#/components/schemas/Error' '500': &id005 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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 /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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 /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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 /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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 /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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 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': *id001 '401': *id002 '404': *id003 '422': *id004 '500': *id005 /api/cards: post: tags: - Cards summary: Create card description: Issues a new card for a customer who has already been verified through Card KYC. Pass the `customer_id` returned by `POST /api/cards/kyc` — identity details were captured and verified during KYC, so they are not sent again here. KYC is asynchronous, so wait until it is approved before issuing the card. 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_id: type: string format: uuid description: The customer returned by Card KYC. Identity details were captured and verified during KYC, so they are not sent again here. example: 01a015ec-dc11-76e9-9a5a-68bddb798c37 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 - customer_id 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_id: 01a015ec-dc11-76e9-9a5a-68bddb798c37 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/kyc: post: tags: - Cards summary: Card KYC description: Submits a customer for identity verification before their first card is issued. A successful submission creates the customer and returns the `customer_id` you pass to `POST /api/cards`. Verification is instant for `bvn` and `nin`; document id types may take up to 10 minutes and resolve asynchronously, so listen on `webhook_url` rather than polling when a submission comes back pending. operationId: post_api_cards_kyc responses: "200": description: Successful response content: application/json: example: success: true message: Card KYC initiated successfully data: customer_id: 01a01914-0000-7000-a000-000000000000 status: approved completion_link: "" email: ifeoma.okafor@example.com first_name: Ifeoma last_name: Okafor normalized_status: approved timestamp: 2026-04-18T13:01:06.145180019Z "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: type: object description: Complete identity details of the person being verified. `first_name` and `last_name` are checked against the identity document, so submit them exactly as they appear on it. 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: 1990-01-15 id_type: type: string description: The type of ID being submitted for this customer. enum: - bvn - nin - passport - drivers_license - national_id - vnin - voters_card - ghana_card example: bvn id_number: type: string description: The value matching `id_type` — the BVN, NIN, or document number. example: "12345678901" 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: "900001" 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 occupation: type: string description: The customer's occupation, in lowercase snake_case. example: business_consultant employment_status: type: string example: employed account_purpose: type: string description: The customer's intended use for the card. example: business expenses annual_salary: type: string description: Declared annual income, in whole major currency units and sent as a string. example: "9600000" expected_monthly_volume: type: string description: Anticipated monthly card spend, in whole major currency units and sent as a string. example: "850000" place_of_birth: type: string example: Enugu terms_of_service_accepted: type: boolean description: Confirms the customer accepted your terms of service. Must be `true`; sending `false` or omitting the field returns "Terms of service must be accepted". example: true webhook_url: type: string format: uri description: Endpoint notified when the verification result changes. Use it in place of polling when a submission returns pending. example: https://example.com/webhooks/card-kyc id_front_image: type: string description: The front of the customer's ID document, base64-encoded, up to 1MB. Required for document id types — passport, drivers_license, national_id, vnin, voters_card and ghana_card — and must never be sent for bvn or nin. example: /9j/4AAQSkZJRgABAQAAAQABAAD... required: - customer - occupation - employment_status - account_purpose - annual_salary - expected_monthly_volume - terms_of_service_accepted example: customer: customer_type: individual first_name: Ifeoma last_name: Okafor date_of_birth: 1990-01-15 id_type: bvn id_number: "12345678901" email: ifeoma.okafor@example.com phone_number: "8034567890" dial_code: "+234" line1: 18 Wuse Zone 4 city: Abuja state: FCT postal_code: "900001" country: NGA occupation: business_consultant employment_status: employed account_purpose: business expenses annual_salary: "9600000" expected_monthly_volume: "850000" place_of_birth: Enugu terms_of_service_accepted: true webhook_url: https://example.com/webhooks/card-kyc /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 enum: - individual - business description: "`individual` for a person, `business` for a company. A business also needs `company_name` and `registration_number`." example: individual company_name: type: string description: The company's registered name. Required when customer_type is business. example: Okonkwo Agro Foods Ltd registration_number: type: string description: The company's registration number. Required when customer_type is business. example: RC1487263 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: - `X-Auth-Client` — your workspace client id - `X-Auth-Timestamp` — Unix seconds - `X-Auth-Nonce` — 16-byte random hex - `X-Auth-Signature` — hex(HMAC-SHA256( `{client_id}:{timestamp}:{nonce}:{compact_json_body}`, client_secret)) 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