{"openapi":"3.0.0","paths":{"/api/v1/blockchain/assets":{"get":{"description":"Returns the full detailed list of supported blockchains and assets.","operationId":"BlockchainController_findSupportedAssetsFull","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedAssetsResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Retrieve supported blockchains and assets","tags":["Miscellaneous"]}},"/api/v1/blockchain/confirmations":{"get":{"description":"Returns the number of confirmations required for transactions to be considered final on different blockchains.","operationId":"BlockchainController_getConfirmationRequirements","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"example":{"success":true,"message":"Confirmation requirements retrieved successfully","data":{"ethereum":2,"bsc":6,"solana":1,"bitcoin":1,"tron":6,"dogecoin":5}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"example":{"success":false,"message":"Failed to fetch confirmation requirements"}}}}}},"security":[{"api-key":[]}],"summary":"Retrieve confirmation requirements","tags":["Miscellaneous"]}},"/api/v1/blockchain/gas-fees":{"get":{"description":"Returns gas fees for all supported blockchains. All fee values are returned in the native token/asset value.","operationId":"BlockchainController_getGasFeesForBlockchain","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"example":{"success":true,"message":"Gas fees retrieved","data":{"tron":{"usdt":"0.15","usdc":"0.15","trx":"1.2"},"ethereum":{"usdt":"0.4","usdc":"0.4","eth":"0.001"},"bsc":{"usdt":"0.2","usdc":"0.2","bnb":"0.05"},"solana":{"usdt":"0.1","usdc":"0.1","sol":"0.0001"},"bitcoin":{"btc":"0.00005"},"dogecoin":{"doge":"1.0"}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"example":{"success":false,"message":"Failed to fetch gas fees"}}}}}},"security":[{"api-key":[]}],"summary":"Retrieve gas fees","tags":["Miscellaneous"]}},"/api/v1/balance":{"get":{"description":"Returns all balances","operationId":"BalanceController_getBalances","parameters":[],"responses":{"200":{"description":"Balances retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceListResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Retrieve balances","tags":["Balance"]}},"/api/v1/balance/transactions":{"get":{"description":"Returns your balance transactions.","operationId":"BalanceController_getBalanceTransactions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"source","required":false,"in":"query","description":"Filter by source type","schema":{"example":"deposit","type":"string","enum":["payment_session","invoice","deposit","payout","swap","refund","fee"]}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"example":"completed","type":"string","enum":["pending","completed","failed","cancelled"]}},{"name":"direction","required":false,"in":"query","description":"Filter by direction (money in or out)","schema":{"example":"credit","type":"string","enum":["credit","debit"]}},{"name":"currency","required":false,"in":"query","description":"Filter by balance currency","schema":{"example":"USDT","type":"string","enum":["NGN","USDT","USDC"]}},{"name":"txHash","required":false,"in":"query","description":"Filter by crypto deposit transaction hash (exact)","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string)","schema":{"example":"2026-01-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string)","schema":{"example":"2026-12-31T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"Balance transactions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionListResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List balance transactions","tags":["Balance"]}},"/api/v1/balance/transactions/{id}":{"get":{"operationId":"BalanceController_getBalanceTransactionById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance transaction retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionResponseDto"}}}},"404":{"description":"Balance transaction not found"}},"security":[{"api-key":[]}],"summary":"Get a balance transaction by id","tags":["Balance"]}},"/api/v1/swap/rates":{"get":{"operationId":"SwapController_getAllRates","parameters":[],"responses":{"200":{"description":"Swap rates retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapRateResponseDto"}}}}]}}}}},"security":[{"api-key":[]}],"summary":"List swap rates","tags":["Swap"]}},"/api/v1/swap/estimate":{"get":{"operationId":"SwapController_estimateSwap","parameters":[{"name":"fromCurrency","required":true,"in":"query","description":"Currency to swap from","schema":{"example":"USDT","type":"string","enum":["NGN","USDT","ETH","BNB","SOL","TRX","USDC","POL","CELO","CNGN"]}},{"name":"toCurrency","required":true,"in":"query","description":"Currency to swap to","schema":{"example":"NGN","type":"string","enum":["NGN","USDT","USDC"]}},{"name":"amount","required":true,"in":"query","description":"Amount to swap","schema":{"example":"100.00","type":"string"}}],"responses":{"200":{"description":"Swap estimation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapEstimationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"security":[{"api-key":[]}],"summary":"Estimate swap amount","tags":["Swap"]}},"/api/v1/swap/quotation":{"post":{"description":"Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires.","operationId":"SwapController_createQuotation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapBalanceDto"}}}},"responses":{"201":{"description":"Quotation created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"security":[{"api-key":[]}],"summary":"Create a swap quotation","tags":["Swap"]}},"/api/v1/swap/quotation/{quotationId}":{"get":{"operationId":"SwapController_getQuotation","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Quotation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"404":{"description":"Quotation not found"}},"security":[{"api-key":[]}],"summary":"Get swap quotation by ID","tags":["Swap"]}},"/api/v1/swap/execute/{quotationId}":{"post":{"operationId":"SwapController_executeSwap","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteSwapDto"}}}},"responses":{"200":{"description":"Swap completed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"400":{"description":"Quotation expired or already used"},"404":{"description":"Quotation not found"}},"security":[{"api-key":[]}],"summary":"Execute swap quotation","tags":["Swap"]}},"/api/v1/swaps":{"get":{"operationId":"SwapController_getSwapHistory","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"fromCurrency","required":false,"in":"query","description":"Filter by source currency","schema":{"example":"USDT","type":"string","enum":["NGN","USDT","USDC"]}},{"name":"toCurrency","required":false,"in":"query","description":"Filter by target currency","schema":{"example":"NGN","type":"string","enum":["NGN","USDT","USDC"]}},{"name":"startDate","required":false,"in":"query","description":"Start date for filtering (ISO string)","schema":{"example":"2024-01-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for filtering (ISO string)","schema":{"example":"2024-12-31T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"Swap history retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapResponseDto"}}}}]}}}}},"security":[{"api-key":[]}],"summary":"List swaps","tags":["Swap"]}},"/api/v1/swaps/{id}":{"get":{"operationId":"SwapController_getSwapDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap details retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"404":{"description":"Swap not found"}},"security":[{"api-key":[]}],"summary":"Get swap details by ID","tags":["Swap"]}},"/api/v1/recipients":{"post":{"description":"Adds a payout recipient. Set type to crypto_address, ngn_bank_account, kes_mobile_money (Kenya) or ghs_mobile_money (Ghana) and supply the matching details. Bank accounts are verified and must match your name or business name. If a matching recipient already exists, the existing one is returned instead of creating a duplicate.","operationId":"PayoutRecipientsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecipientDto"}}}},"responses":{"201":{"description":"Recipient created, or the existing recipient if it already existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientResponseDto"},"examples":{"bankAccount":{"summary":"Bank account","value":{"success":true,"message":"Recipient created successfully","data":{"id":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"ngn_bank_account","label":"Payroll GTBank","isDefault":true,"isTrusted":false,"details":{"accountName":"JOHN ADEYEMI DOE","accountNumber":"******6789","bankName":"Guaranty Trust Bank","bankCode":"058","accountType":"savings","currency":"NGN"},"createdAt":"2026-06-27T10:20:05.000Z","updatedAt":"2026-06-27T10:20:05.000Z"}}},"cryptoAddress":{"summary":"Crypto address","value":{"success":true,"message":"Recipient created successfully","data":{"id":"f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","type":"crypto_address","label":"Treasury TRON wallet","isDefault":true,"isTrusted":false,"details":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"},"createdAt":"2026-06-27T10:14:32.000Z","updatedAt":"2026-06-27T10:14:32.000Z"}}},"mobileMoney":{"summary":"Mobile money","value":{"success":true,"message":"Recipient created successfully","data":{"id":"3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31","type":"kes_mobile_money","label":"Nairobi supplier","isDefault":false,"isTrusted":false,"details":{"currency":"KES","countryIsoCode":"KE","accountNumber":"******5678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"},"createdAt":"2026-06-27T10:26:48.000Z","updatedAt":"2026-06-27T10:26:48.000Z"}}}}}}},"400":{"description":"Invalid details or unsupported type."}},"security":[{"api-key":[]}],"summary":"Create payout recipient","tags":["Payout Recipients"]},"get":{"description":"Returns your saved payout recipients. Filter by type to return a single rail, or omit type to return all types.","operationId":"PayoutRecipientsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"isTemporary","required":false,"in":"query","description":"Omit for all recipients; true for temporary, false for address book.","schema":{"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"Filter by recipient type. Omit to list every type.","schema":{"enum":["crypto_address","ngn_bank_account","kes_mobile_money","ghs_mobile_money"],"type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by the customer the recipient is linked to.","schema":{"example":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by account holder name, institution, or label.","schema":{"example":"payroll","type":"string"}}],"responses":{"200":{"description":"Recipients retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientListResponseDto"},"examples":{"recipients":{"summary":"Mixed recipients","value":{"success":true,"message":"Recipients retrieved successfully","data":[{"id":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"ngn_bank_account","label":"Payroll GTBank","isDefault":true,"isTrusted":false,"details":{"accountName":"JOHN ADEYEMI DOE","accountNumber":"******6789","bankName":"Guaranty Trust Bank","bankCode":"058","accountType":"savings","currency":"NGN"},"createdAt":"2026-06-27T10:20:05.000Z","updatedAt":"2026-06-27T10:20:05.000Z"},{"id":"f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","type":"crypto_address","label":"Treasury TRON wallet","isDefault":true,"isTrusted":false,"details":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"},"createdAt":"2026-06-27T10:14:32.000Z","updatedAt":"2026-06-27T10:14:32.000Z"},{"id":"3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31","type":"kes_mobile_money","label":"Nairobi supplier","isDefault":false,"isTrusted":false,"details":{"currency":"KES","countryIsoCode":"KE","accountNumber":"******5678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"},"createdAt":"2026-06-27T10:26:48.000Z","updatedAt":"2026-06-27T10:26:48.000Z"}],"meta":{"page":1,"size":10,"total":3,"totalPages":1}}}}}}}},"security":[{"api-key":[]}],"summary":"List payout recipients","tags":["Payout Recipients"]}},"/api/v1/recipients/validate":{"post":{"description":"Preflight check before creating a recipient. Crypto validates the address format. Bank resolves the account holder name through the provider. Mobile money resolves the corridor and provider for the details.","operationId":"PayoutRecipientsController_validate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRecipientDto"}}}},"responses":{"200":{"description":"Details are valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResolvedResponseDto"},"examples":{"bankAccount":{"summary":"Bank account","value":{"success":true,"message":"Recipient details are valid","data":{"valid":true,"type":"ngn_bank_account","resolved":{"accountName":"JOHN ADEYEMI DOE","bankName":"Guaranty Trust Bank","bankCode":"058","accountNumber":"0123456789"}}}},"cryptoAddress":{"summary":"Crypto address","value":{"success":true,"message":"Recipient details are valid","data":{"valid":true,"type":"crypto_address","resolved":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"}}}},"mobileMoney":{"summary":"Mobile money","value":{"success":true,"message":"Recipient details are valid","data":{"valid":true,"type":"kes_mobile_money","resolved":{"currency":"KES","countryIsoCode":"KE","accountNumber":"0712345678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"}}}}}}}},"400":{"description":"Invalid details."}},"security":[{"api-key":[]}],"summary":"Validate recipient details","tags":["Payout Recipients"]}},"/api/v1/recipients/banks":{"get":{"description":"Banks available for bank account recipients. Nigeria (ng) only for now.","operationId":"PayoutRecipientsController_banks","parameters":[{"name":"country","required":false,"in":"query","description":"ISO 3166-1 alpha-2 country code. Optional, defaults to ng; only ng is supported for now.","schema":{"default":"ng","example":"ng","type":"string"}}],"responses":{"200":{"description":"Bank list retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankListResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List supported banks","tags":["Payout Recipients"]}},"/api/v1/recipients/chains":{"get":{"description":"Returns the chains and assets available for crypto_address recipients, keyed by chain.","operationId":"PayoutRecipientsController_chains","parameters":[],"responses":{"200":{"description":"Supported chains retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedPayoutChainsResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List supported payout chains","tags":["Payout Recipients"]}},"/api/v1/recipients/{id}":{"get":{"description":"Returns the payout recipient for the given ID.","operationId":"PayoutRecipientsController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Recipient ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Recipient retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientResponseDto"},"examples":{"bankAccount":{"summary":"Bank account","value":{"success":true,"message":"Recipient retrieved successfully","data":{"id":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"ngn_bank_account","label":"Payroll GTBank","isDefault":true,"isTrusted":false,"details":{"accountName":"JOHN ADEYEMI DOE","accountNumber":"******6789","bankName":"Guaranty Trust Bank","bankCode":"058","accountType":"savings","currency":"NGN"},"createdAt":"2026-06-27T10:20:05.000Z","updatedAt":"2026-06-27T10:20:05.000Z"}}},"cryptoAddress":{"summary":"Crypto address","value":{"success":true,"message":"Recipient retrieved successfully","data":{"id":"f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","type":"crypto_address","label":"Treasury TRON wallet","isDefault":true,"isTrusted":false,"details":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"},"createdAt":"2026-06-27T10:14:32.000Z","updatedAt":"2026-06-27T10:14:32.000Z"}}},"mobileMoney":{"summary":"Mobile money","value":{"success":true,"message":"Recipient retrieved successfully","data":{"id":"3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31","type":"kes_mobile_money","label":"Nairobi supplier","isDefault":false,"isTrusted":false,"details":{"currency":"KES","countryIsoCode":"KE","accountNumber":"******5678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"},"createdAt":"2026-06-27T10:26:48.000Z","updatedAt":"2026-06-27T10:26:48.000Z"}}}}}}},"404":{"description":"Recipient not found."}},"security":[{"api-key":[]}],"summary":"Retrieve payout recipient","tags":["Payout Recipients"]},"delete":{"description":"Deletes the payout recipient.","operationId":"PayoutRecipientsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"Recipient ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Recipient deleted.","content":{"application/json":{"examples":{"deleted":{"summary":"Deleted","value":{"success":true,"message":"Recipient deleted successfully","data":{"success":true}}}}}}},"404":{"description":"Recipient not found."}},"security":[{"api-key":[]}],"summary":"Delete payout recipient","tags":["Payout Recipients"]}},"/api/v1/refunds/session/{sessionReference}":{"post":{"description":"Refunds the money received in a payment session back to the customer.","operationId":"RefundsController_refundSession","parameters":[{"name":"sessionReference","required":true,"in":"path","description":"Session reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Process session refund","tags":["Refunds"]}},"/api/v1/refunds/invoice/{invoiceReference}":{"post":{"description":"Refunds the money paid for an invoice back to the customer.","operationId":"RefundsController_refundInvoice","parameters":[{"name":"invoiceReference","required":true,"in":"path","description":"Invoice reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRefundDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Process invoice refund","tags":["Refunds"]}},"/api/v1/refunds":{"get":{"description":"Returns all refunds.","operationId":"RefundsController_listRefunds","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by refund status","schema":{"type":"string","enum":["pending","processing","success","failed"]}},{"name":"sessionReference","required":false,"in":"query","description":"Filter by payment session reference","schema":{"type":"string"}},{"name":"invoiceReference","required":false,"in":"query","description":"Filter by invoice reference","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search term for session or invoice reference","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter refunds created from this date/time (ISO 8601)","schema":{"example":"2026-03-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter refunds created up to this date/time (ISO 8601)","schema":{"example":"2026-03-11T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundsResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List refunds","tags":["Refunds"]}},"/api/v1/refunds/estimate/{reference}":{"get":{"description":"Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter.","operationId":"RefundsController_estimateRefund","parameters":[{"name":"reference","required":true,"in":"path","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)","schema":{"example":"CS_1234567890","type":"string"}},{"name":"entity","required":true,"in":"query","description":"Entity type - whether the reference is for a session or invoice","schema":{"example":"session","type":"string","enum":["session","invoice"]}},{"name":"feePaidBy","required":false,"in":"query","description":"Who will pay the network fee","schema":{"example":"customer","type":"string","enum":["merchant","customer"]}}],"responses":{"200":{"description":""}},"security":[{"api-key":[]}],"summary":"Estimate refund","tags":["Refunds"]}},"/api/v1/refunds/{id}":{"get":{"description":"Returns the refund for the given ID.","operationId":"RefundsController_getRefund","parameters":[{"name":"id","required":true,"in":"path","description":"Refund ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Retrieve refund","tags":["Refunds"]}},"/api/v1/payouts":{"post":{"description":"Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted.","operationId":"PayoutV2Controller_initializePayout","parameters":[],"requestBody":{"required":true,"description":"Payout initiation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutDto"}}}},"responses":{"201":{"description":"Payout initialized successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"},"examples":{"cryptoPayout":{"summary":"Crypto payout (USDT)","value":{"success":true,"message":"Crypto payout initialized successfully","data":{"id":"123e4567-e89b-12d3-a456-426614174000","reference":"PAY-ABC123DEF456","method":"crypto","status":"processing","amount":"100.00","fee":"1.00","total":"101.00","currency":"USDT","conversion":null,"narration":"Manual merchant payout","recipient":{"id":"f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","type":"crypto_address","details":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"}},"channel":"API","txHash":null,"failureReason":null,"completedAt":null,"createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:00:00.000Z"}}},"crossBorderPayout":{"summary":"Cross-border payout (KES)","value":{"success":true,"message":"Cross-border payout initialized successfully","data":{"id":"9c1b8a70-3d2e-4f6a-a5b9-1e0d7c4f2a88","reference":"PAY-KE9X2M4Q7R1T","method":"fiat","status":"processing","amount":"10000.00","fee":"193.31","total":"10193.31","currency":"KES","conversion":{"fromCurrency":"USDT","toCurrency":"KES","sourceAmount":"77.60","targetAmount":"10000.00","rate":"128.87"},"narration":"Supplier payment","recipient":{"id":"3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31","type":"kes_mobile_money","details":{"currency":"KES","countryIsoCode":"KE","accountNumber":"******5678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"}},"channel":"API","txHash":null,"failureReason":null,"completedAt":null,"createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:00:00.000Z"}}},"ngnBankPayout":{"summary":"NGN bank payout","value":{"success":true,"message":"Fiat payout initialized successfully","data":{"id":"5e8d4c2a-9b1f-4a3e-8c6d-7f0b2e4a9c15","reference":"PAY-NG7T4W2E9Y1U","method":"fiat","status":"processing","amount":"50000.00","fee":"50.00","total":"50050.00","currency":"NGN","conversion":null,"narration":"Vendor settlement","recipient":{"id":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"ngn_bank_account","details":{"accountName":"JOHN ADEYEMI DOE","accountNumber":"******6789","bankName":"Guaranty Trust Bank","bankCode":"058","accountType":"savings","currency":"NGN"}},"channel":"API","txHash":null,"failureReason":null,"completedAt":null,"createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:00:00.000Z"}}}}}}},"400":{"description":"Bad request - validation error, insufficient balance, daily limit exceeded, or missing one-time code (not required when the recipient is trusted)"},"404":{"description":"Recipient (bank account or wallet address) not found"},"500":{"description":"Internal server error - payout processing failed"}},"security":[{"api-key":[]}],"summary":"Initiate payout","tags":["Payouts"]},"get":{"description":"Returns all payouts.","operationId":"PayoutV2Controller_getAllPayouts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by payout reference, transaction hash or destination address.","schema":{"example":"PAY-123456","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by payout status","schema":{"example":"success","type":"string","enum":["pending","processing","success","failed"]}},{"name":"recipientId","required":false,"in":"query","description":"Filter by payout recipient.","schema":{"example":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"string"}},{"name":"method","required":false,"in":"query","description":"Filter by payout method.","schema":{"example":"crypto","type":"string","enum":["crypto","fiat"]}},{"name":"currency","required":false,"in":"query","description":"Filter by payout currency.","schema":{"example":"NGN","type":"string","enum":["NGN","USDT","USDC","KES","ZAR","GHS"]}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain. Only crypto payouts move on a blockchain, so this excludes fiat payouts from the results.","schema":{"example":"tron","type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutsV2ResponseDto"}}}},"401":{"description":"Unauthorized"}},"security":[{"api-key":[]}],"summary":"List payouts","tags":["Payouts"]}},"/api/v1/payouts/cross-border/quote":{"post":{"description":"Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Call this before creating the payout to show the cost. Cross-border payouts are available to verified businesses.","operationId":"PayoutV2Controller_quoteCrossBorderPayout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteResponseDataDto"}}}}},"security":[{"api-key":[]}],"summary":"Quote a cross-border payout","tags":["Payouts"]}},"/api/v1/payouts/{id}":{"get":{"description":"Returns the payout for the given ID.","operationId":"PayoutV2Controller_findOnePayout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Payout retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"},"examples":{"cryptoPayout":{"summary":"Crypto payout (USDT)","value":{"success":true,"message":"Payout retrieved successfully","data":{"id":"123e4567-e89b-12d3-a456-426614174000","reference":"PAY-ABC123DEF456","method":"crypto","status":"success","amount":"100.00","fee":"1.00","total":"101.00","currency":"USDT","conversion":null,"narration":"Manual merchant payout","recipient":{"id":"f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","type":"crypto_address","details":{"chain":"tron","address":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"}},"channel":"API","txHash":"b9f4a2d6e8c1073a5f4e2b8d9c0a1f3e6d5b4a2c8e7f9d0b1a3c5e7f9b2d4a6c","failureReason":null,"completedAt":"2026-07-01T12:05:00.000Z","createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:05:00.000Z"}}},"crossBorderPayout":{"summary":"Cross-border payout (KES)","value":{"success":true,"message":"Payout retrieved successfully","data":{"id":"9c1b8a70-3d2e-4f6a-a5b9-1e0d7c4f2a88","reference":"PAY-KE9X2M4Q7R1T","method":"fiat","status":"success","amount":"10000.00","fee":"193.31","total":"10193.31","currency":"KES","conversion":{"fromCurrency":"USDT","toCurrency":"KES","sourceAmount":"77.60","targetAmount":"10000.00","rate":"128.87"},"narration":"Supplier payment","recipient":{"id":"3a7f2b90-5c1d-4e8a-b6f4-9d0c2e5a7b31","type":"kes_mobile_money","details":{"currency":"KES","countryIsoCode":"KE","accountNumber":"******5678","accountName":"Jane Wanjiku","institutionCode":"MPESA","institutionName":"M-Pesa","accountType":"individual"}},"channel":"API","txHash":null,"failureReason":null,"completedAt":"2026-07-01T12:03:12.000Z","createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:03:12.000Z"}}},"ngnBankPayout":{"summary":"NGN bank payout","value":{"success":true,"message":"Payout retrieved successfully","data":{"id":"5e8d4c2a-9b1f-4a3e-8c6d-7f0b2e4a9c15","reference":"PAY-NG7T4W2E9Y1U","method":"fiat","status":"success","amount":"50000.00","fee":"50.00","total":"50050.00","currency":"NGN","conversion":null,"narration":"Vendor settlement","recipient":{"id":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11","type":"ngn_bank_account","details":{"accountName":"JOHN ADEYEMI DOE","accountNumber":"******6789","bankName":"Guaranty Trust Bank","bankCode":"058","accountType":"savings","currency":"NGN"}},"channel":"API","txHash":null,"failureReason":null,"completedAt":"2026-07-01T12:01:44.000Z","createdAt":"2026-07-01T12:00:00.000Z","updatedAt":"2026-07-01T12:01:44.000Z"}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Payout not found"}},"security":[{"api-key":[]}],"summary":"Retrieve payout","tags":["Payouts"]}},"/api/v1/payouts/fees":{"get":{"description":"Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset.","operationId":"PayoutV2Controller_getPayoutFees","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatePayoutFeesApiResponseDto"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error - Unable to calculate fees"}},"security":[{"api-key":[]}],"summary":"Retrieve all payout fees","tags":["Payouts"]}},"/api/v1/deposits/accounts":{"post":{"description":"Creates a deposit account. Omit customerId to create a parent account. A holder has one deposit account, so repeat calls return the existing account.","operationId":"DepositsController_createAccount","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDepositAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDepositAccountApiResponseDto"}}}},"404":{"description":"Customer not found"}},"security":[{"api-key":[]}],"summary":"Create a deposit account","tags":["Deposits"]},"get":{"description":"Lists your deposit accounts.","operationId":"DepositsController_listAccounts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by account status","schema":{"example":"active","type":"string","enum":["active","inactive"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountListApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List deposit accounts","tags":["Deposits"]}},"/api/v1/deposits/accounts/{id}":{"patch":{"description":"Changes the settlement currency of a customer-scoped deposit account. Deposits already in flight keep the currency they were credited in. The merchant parent account is always `default`.","operationId":"DepositsController_updateAccount","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDepositAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"400":{"description":"The merchant parent account always settles as `default`"},"404":{"description":"Deposit account not found"}},"security":[{"api-key":[]}],"summary":"Update a deposit account","tags":["Deposits"]},"get":{"description":"Retrieves a deposit account and its identities.","operationId":"DepositsController_getAccountById","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"security":[{"api-key":[]}],"summary":"Retrieve a deposit account","tags":["Deposits"]}},"/api/v1/deposits/accounts/{id}/identities":{"post":{"description":"Issues a pay-in identity into a deposit account: a static crypto deposit address or an NGN virtual account.","operationId":"DepositsController_issueIdentity","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueDepositIdentityDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"security":[{"api-key":[]}],"summary":"Issue a deposit identity","tags":["Deposits"]}},"/api/v1/deposits/accounts/parent":{"get":{"description":"Retrieves the merchant parent deposit account.","operationId":"DepositsController_getParentAccount","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParentDepositAccountApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"Retrieve parent deposit account","tags":["Deposits"]}},"/api/v1/deposits/accounts/customer/{customerId}":{"get":{"description":"Retrieves the deposit account for a customer.","operationId":"DepositsController_getAccountByCustomerId","parameters":[{"name":"customerId","required":true,"in":"path","description":"Customer ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"security":[{"api-key":[]}],"summary":"Retrieve a customer's deposit account","tags":["Deposits"]}},"/api/v1/deposits":{"get":{"description":"Lists your inbound deposits (crypto and fiat).","operationId":"DepositsController_listDeposits","parameters":[{"name":"customerId","required":false,"in":"query","description":"Filter by customer id","schema":{"type":"string"}},{"name":"depositAccountId","required":false,"in":"query","description":"Filter by deposit account id","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by type","schema":{"type":"string","enum":["crypto","fiat"]}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","completed","failed"]}},{"name":"chain","required":false,"in":"query","description":"Filter by crypto chain","schema":{"example":"ethereum","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by currency","schema":{"example":"USDT","type":"string"}},{"name":"txHash","required":false,"in":"query","description":"Filter by crypto deposit transaction hash (exact)","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string)","schema":{"example":"2026-01-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string)","schema":{"example":"2026-12-31T23:59:59Z","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositListApiResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List deposits","tags":["Deposits"]}},"/api/v1/deposits/{id}":{"get":{"description":"Retrieves a single deposit.","operationId":"DepositsController_getDepositById","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositApiResponseDto"}}}},"404":{"description":"Deposit not found"}},"security":[{"api-key":[]}],"summary":"Retrieve a deposit","tags":["Deposits"]}},"/api/v1/customers":{"post":{"description":"Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead.","operationId":"CustomersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data"}},"security":[{"api-key":[]}],"summary":"Create customer","tags":["Customers"]},"get":{"description":"Returns all customers.","operationId":"CustomersController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by customer name, email, or phone","schema":{"example":"john@example.com","type":"string"}},{"name":"email","required":false,"in":"query","description":"Filter by exact email address","schema":{"example":"john@example.com","type":"string"}},{"name":"phone","required":false,"in":"query","description":"Filter by exact phone number","schema":{"example":"+2348012345678","type":"string"}},{"name":"telegramId","required":false,"in":"query","description":"Filter by exact Telegram ID","schema":{"example":"123456789","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersResponseDto"}}}}},"security":[{"api-key":[]}],"summary":"List customers","tags":["Customers"]}},"/api/v1/customers/{id}":{"patch":{"description":"Updates the customer.","operationId":"CustomersController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data or duplicate email/phone/telegram ID"},"404":{"description":"Customer not found"}},"security":[{"api-key":[]}],"summary":"Update customer","tags":["Customers"]},"get":{"description":"Returns the customer for the given ID.","operationId":"CustomersController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"example":{"success":false,"message":"Customer not found"}}}}}},"security":[{"api-key":[]}],"summary":"Retrieve customer","tags":["Customers"]}},"/api/v1/invoices":{"post":{"description":"Creates an invoice for a product/service.","operationId":"InvoicesController_createInvoice","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"400":{"description":"Invalid input or expiration date exceeds 5 days"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"api-key":[]}],"summary":"Create invoice","tags":["Invoices"]},"get":{"description":"Returns all invoices.","operationId":"InvoicesController_listInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by invoice reference","schema":{"example":"INV-123","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by invoice status","schema":{"example":"pending","type":"string","enum":["pending","partial","paid","expired"]}},{"name":"state","required":false,"in":"query","description":"Filter by invoice state","schema":{"example":"open","type":"string","enum":["open","closed"]}},{"name":"currency","required":false,"in":"query","description":"Filter by currency","schema":{"example":"NGN","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter invoices created from this date/time (ISO 8601)","schema":{"example":"2026-03-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter invoices created up to this date/time (ISO 8601)","schema":{"example":"2026-03-11T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesResponseDto"}}}},"401":{"description":"Unauthorized"}},"security":[{"api-key":[]}],"summary":"List invoices","tags":["Invoices"]}},"/api/v1/invoices/reference/{reference}":{"get":{"description":"Returns the invoice for the given reference.","operationId":"InvoicesController_getInvoice","parameters":[{"name":"reference","required":true,"in":"path","description":"Invoice reference","schema":{"example":"inv-lx123abc-xyz789def0123456789","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"404":{"description":"Invoice not found"}},"summary":"Retrieve invoice by reference","tags":["Invoices"]}},"/api/v1/x402/requirements":{"post":{"description":"Build the payment requirements to return to a paying agent.","operationId":"X402V2Controller_requirements","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildX402RequirementsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402RequirementsResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Build x402 payment requirements","tags":["x402"]}},"/api/v1/x402/verify":{"post":{"description":"Validate a signed payment against its requirements without settling.","operationId":"X402V2Controller_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402VerifyResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Verify an x402 payment","tags":["x402"]}},"/api/v1/x402/settle":{"post":{"description":"Submit a signed payment on-chain and return the settlement receipt.","operationId":"X402V2Controller_settle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Settle an x402 payment","tags":["x402"]}},"/api/v1/x402/supported":{"get":{"operationId":"X402V2Controller_supported","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SupportedResponseDto"}}}}},"summary":"List supported x402 networks and assets","tags":["x402"]}},"/api/v1/x402/transactions":{"get":{"description":"List settled x402 payments for your account, newest first.","operationId":"X402V2Controller_transactions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by transaction hash or address","schema":{"example":"0x4b7a1f0c9d2e","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"example":"confirmed","type":"string","enum":["pending","confirmed"]}},{"name":"chain","required":false,"in":"query","schema":{"example":"base","type":"string","enum":["base","arbitrum","bsc","solana"]}},{"name":"asset","required":false,"in":"query","schema":{"example":"USDC","type":"string","enum":["USDC","USDT"]}},{"name":"startDate","required":false,"in":"query","description":"Created from this date/time (ISO 8601)","schema":{"example":"2026-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Created up to this date/time (ISO 8601)","schema":{"example":"2026-06-30T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionsResponseDto"}}}}},"summary":"List x402 transactions","tags":["x402"]}},"/api/v1/x402/transactions/{txHash}":{"get":{"description":"Fetch a settled x402 payment by transaction hash.","operationId":"X402V2Controller_transaction","parameters":[{"name":"txHash","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionResponseDto"}}}},"404":{"description":"Not found"}},"summary":"Get an x402 transaction","tags":["x402"]}},"/api/v1/payments":{"post":{"description":"Creates a new payment session (payment link) to receive payments. You can set the asset and chain together, set one now and the other later, or leave both unset. A deposit address is created immediately only when the session already has the asset, chain, and customer details.","operationId":"CheckoutSessionsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionDto"},"examples":{"immediate-setup":{"summary":"Immediate setup","description":"Resource initialized with predefined settings","value":{"title":"Payment for invoice 112","description":"Payment for invoice 112","amount":"1000.00","currency":"NGN","asset":"USDT","chain":"bsc","customer":{"email":"customer@example.com","firstName":"John","lastName":"Doe"},"metadata":{"orderId":"ORD-123","purpose":"Payment for invoice"},"webhookUrl":"https://example.com/webhook","cancelUrl":"https://example.com/cancel","successUrl":"https://example.com/success"}},"deferred-selection":{"summary":"Deferred selection","description":"Resource initialized without locked parameters","value":{"title":"Payment for invoice 112","description":"Payment for invoice 112","amount":"50000.00","currency":"NGN","customer":{"email":"customer@example.com","firstName":"Jane","lastName":"Smith"}}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"400":{"description":"Invalid input or unsupported asset/blockchain combination"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"api-key":[]}],"summary":"Create payment session","tags":["Payments"]},"get":{"description":"Returns all Payment Sessions.","operationId":"CheckoutSessionsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by session reference, payment/deposit address, or transaction hash.","schema":{"example":"ORDER-123","type":"string"}},{"name":"invoiceReference","required":false,"in":"query","description":"Filter by invoice reference","schema":{"example":"inv_abc123xyz789","type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by customer ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"pageReference","required":false,"in":"query","description":"Filter by payment page reference","schema":{"example":"page_abc123def456","type":"string"}},{"name":"state","required":false,"in":"query","description":"Filter by session state: open or closed","schema":{"example":"open","type":"string","enum":["open","closed"]}},{"name":"paymentStatus","required":false,"in":"query","description":"Filter by payment status","schema":{"example":"completed","type":"string","enum":["pending","partial","expired","completed","failed","under_review"]}},{"name":"asset","required":false,"in":"query","description":"Filter by asset","schema":{"example":"USDT","type":"string"}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain","schema":{"example":"ethereum","type":"string"}},{"name":"minAmount","required":false,"in":"query","description":"Minimum amount (in fiat)","schema":{"example":10,"type":"number"}},{"name":"maxAmount","required":false,"in":"query","description":"Maximum amount (in fiat)","schema":{"example":1000,"type":"number"}},{"name":"includeTransactions","required":false,"in":"query","description":"Set to true to add transactions to each session.","schema":{"example":"true","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by session type","schema":{"example":"checkout","type":"string","enum":["checkout","invoice"]}},{"name":"currency","required":false,"in":"query","description":"Filter by fiat currency","schema":{"example":"NGN","type":"string","enum":["NGN","USD"]}},{"name":"isRefunded","required":false,"in":"query","description":"Filter by refund status. Pass true to return only refunded sessions.","schema":{"example":"true","type":"boolean"}},{"name":"startDate","required":false,"in":"query","description":"Filter sessions created from this date/time (ISO 8601)","schema":{"example":"2026-03-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter sessions created up to this date/time (ISO 8601)","schema":{"example":"2026-03-11T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionsV2ResponseDto"}}}},"401":{"description":"Unauthorized"}},"security":[{"api-key":[]}],"summary":"List payment sessions","tags":["Payments"]}},"/api/v1/payments/{reference}/address":{"post":{"description":"Generates a deposit address for the session. If the session already has an asset or chain assigned, those values cannot be overridden. Any missing asset or chain must be provided before the address can be created. If the session does not already have a customer, include customer details (email, and optionally firstName, lastName, phone). If the session already has a customer, the customer field is ignored.","operationId":"CheckoutSessionsController_generateDepositAddress","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment session reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDepositAddressDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"400":{"description":"Invalid session state, missing required asset/chain context, or unsupported asset/blockchain"},"404":{"description":"Session not found"}},"summary":"Generate deposit address","tags":["Payments"]}},"/api/v1/payments/reference/{reference}":{"get":{"description":"Returns the session for the given reference.","operationId":"CheckoutSessionsController_findByReference","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment session reference","schema":{"type":"string"}},{"name":"includeTransactions","required":false,"in":"query","schema":{"type":"boolean"},"description":"When true, the response includes the transactions array."}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"404":{"description":"Session not found"}},"summary":"Retrieve payment session by reference","tags":["Payments"]}},"/api/v1/payments/estimate":{"get":{"description":"Calculate the required crypto amount for a session based on selected asset and chain without locking the rate.","operationId":"CheckoutSessionsController_calculateAmount","parameters":[{"name":"amount","required":true,"in":"query","description":"Amount in fiat currency","schema":{"example":"100.00","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Fiat currency for the amount","schema":{"example":"USD","type":"string","enum":["NGN","USD"]}},{"name":"asset","required":true,"in":"query","description":"Crypto asset to pay with","schema":{"example":"USDT","type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]}},{"name":"chain","required":true,"in":"query","description":"Blockchain network","schema":{"example":"TRON","type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]}},{"name":"feePaidBy","required":false,"in":"query","description":"Fee paid by: who pays the network fee (merchant or customer)","schema":{"type":"string","enum":["customer","merchant"]}},{"name":"settlementCurrency","required":false,"in":"query","description":"Settlement currency (optional)","schema":{"type":"string","enum":["NGN","USD","USDT","USDC"]}},{"name":"reference","required":false,"in":"query","description":"Session reference ","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateCheckoutAmountApiResponseDto"}}}},"400":{"description":"Invalid input or unsupported asset/blockchain"}},"summary":"Calculate crypto amount for session","tags":["Payments"]}},"/api/v1/payments/pages":{"post":{"description":"Creates a new payment page.","operationId":"StaticCheckoutsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentPageDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPageResponseDto"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict - Nickname already exists"}},"security":[{"api-key":[]}],"summary":"Create payment page","tags":["Payment Pages"]},"get":{"description":"Returns all payment pages.","operationId":"StaticCheckoutsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by payment page title","schema":{"example":"Monthly Subscription","type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"example":true,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPagesResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"security":[{"api-key":[]}],"summary":"List payment pages","tags":["Payment Pages"]}},"/api/v1/payments/pages/{reference}/sessions":{"get":{"description":"Returns the payment page for the given reference.","operationId":"StaticCheckoutsController_getStaticCheckout","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment page reference","schema":{"example":"abc123def456","type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":false,"schema":{"type":"string","example":"pk_live_1234567890abcdef"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentPageResponseDto"}}}},"404":{"description":"Payment page not found"},"500":{"description":"Internal server error"}},"security":[{"api-key":[]}],"summary":"Retrieve payment page by reference","tags":["Payment Pages"]}},"/api/v1/payments/pages/{id}":{"patch":{"description":"Updates the payment page.","operationId":"StaticCheckoutsController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Payment page ID","schema":{"example":"uuid-string","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentPageDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPageResponseDto"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Payment page not found"},"409":{"description":"Conflict - Nickname already exists"}},"security":[{"api-key":[]}],"summary":"Update payment page","tags":["Payment Pages"]},"delete":{"description":"Deletes the payment page.","operationId":"StaticCheckoutsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"Payment page ID","schema":{"example":"uuid-string","type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Payment page not found"}},"security":[{"api-key":[]}],"summary":"Delete payment page","tags":["Payment Pages"]}},"/api/v1/transactions":{"get":{"description":"Returns all Payment Sessions Blockchain transactions.","operationId":"TransactionsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by transaction hash or asset","schema":{"example":"0x1234567890abcdef","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by transaction status","schema":{"example":"confirmed","type":"string","enum":["pending","confirmed","failed"]}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain","schema":{"example":"ethereum","type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]}},{"name":"asset","required":false,"in":"query","description":"Filter by asset","schema":{"example":"USDT","type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]}},{"name":"sessionReference","required":false,"in":"query","description":"Filter by payment session reference","schema":{"example":"sess_1234567890","type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by customer ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter transactions created from this date/time (ISO 8601)","schema":{"example":"2026-03-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter transactions created up to this date/time (ISO 8601)","schema":{"example":"2026-03-11T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsResponseDto"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"summary":"List transactions","tags":["Transactions"]}},"/api/v1/transactions/{txHash}":{"get":{"description":"Returns the transaction for the given hash.","operationId":"TransactionsController_findOne","parameters":[{"name":"txHash","required":true,"in":"path","description":"Transaction hash","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResponseDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"example":{"success":false,"message":"Transaction with hash 0x1234567890abcdef1234567890abcdef12345678 not found"}}}}},"500":{"description":"Internal server error"}},"summary":"Retrieve transaction","tags":["Transactions"]}},"/api/v1/settlements":{"get":{"operationId":"SettlementController_listSettlements","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}},{"name":"entity","required":false,"in":"query","description":"Filter by entity type","schema":{"enum":["session","invoice"],"type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by settlement currency","schema":{"enum":["USD","NGN"],"type":"string"}}],"responses":{"200":{"description":"Settlements retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementListApiResponseDto"}}}},"401":{"description":"Unauthorized"}},"security":[{"api-key":[]}],"summary":"List settlements","tags":["Settlements"]}},"/api/v1/settlements/{reference}":{"get":{"operationId":"SettlementController_getSettlement","parameters":[{"name":"reference","required":true,"in":"path","description":"Session or invoice reference","schema":{"example":"cs_ref_abc123xyz789","type":"string"}},{"name":"entity","required":true,"in":"query","description":"Entity type","schema":{"enum":["session","invoice"],"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementApiResponseDto"}}}},"400":{"description":"Missing or invalid \"entity\" query parameter"},"401":{"description":"Unauthorized"},"404":{"description":"Session or invoice not found"}},"security":[{"api-key":[]}],"summary":"Retrieve settlement data","tags":["Settlements"]}}},"info":{"title":"CoinCircuit API","description":"","version":"1.0","contact":{}},"tags":[{"name":"Invoices","description":"Create and manage invoices"},{"name":"Payments","description":"Create and manage payment sessions"},{"name":"x402","description":"Accept x402 agent payments"},{"name":"Transactions","description":"View transaction history"},{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"},{"name":"Payouts","description":"Manage payouts"},{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"},{"name":"Balance","description":"Check account balance"},{"name":"Swap","description":"Swap between balance currencies"},{"name":"Settlements","description":"Track Settlement activity"},{"name":"Customers","description":"Manage customer information"},{"name":"Refunds","description":"Create and track refunds"},{"name":"Payment Pages","description":"Create and manage hosted payment pages"},{"name":"Miscellaneous","description":"Miscellaneous endpoints"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"SupportedAssetsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"type":"object","description":"Supported assets data","example":{"ethereum":[{"asset":"ETH","networkId":"eip155:1","metadata":{"name":"Ethereum","symbol":"ETH","decimals":18}},{"asset":"USDT","networkId":"eip155:1","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"0xdAC17F958D2ee523a2206206994597C13D831ec7","decimals":6}},{"asset":"USDC","networkId":"eip155:1","metadata":{"name":"USD Coin","symbol":"USDC","decimals":6},"contract":{"address":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","decimals":6}}],"solana":[{"asset":"SOL","networkId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","metadata":{"name":"Solana","symbol":"SOL","decimals":9}},{"asset":"USDT","networkId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","decimals":6}},{"asset":"USDC","networkId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","metadata":{"name":"USD Coin","symbol":"USDC","decimals":6},"contract":{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6}}],"bsc":[{"asset":"BNB","networkId":"eip155:56","metadata":{"name":"BNB","symbol":"BNB","decimals":18}},{"asset":"USDT","networkId":"eip155:56","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"0x55d398326f99059ff775485246999027b3197955","decimals":18}},{"asset":"USDC","networkId":"eip155:56","metadata":{"name":"USD Coin","symbol":"USDC","decimals":6},"contract":{"address":"0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d","decimals":18}}],"tron":[{"asset":"USDT","networkId":"tron:0000000000000000000000000000000000000000","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","decimals":6}},{"asset":"TRX","networkId":"tron:0000000000000000000000000000000000000000","metadata":{"name":"TRON","symbol":"TRX","decimals":6}}]}}},"required":["success","message"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)","example":1},"size":{"type":"number","description":"Number of items per page","example":10},"total":{"type":"number","description":"Total number of items available for this query","example":42},"totalPages":{"type":"number","description":"Total number of pages for this query","example":5}},"required":["page","size","total","totalPages"]},"PaginatedApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"type":"object","description":"Response data"},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]},"BalanceDto":{"type":"object","properties":{"currency":{"type":"string","description":"Balance currency","enum":["NGN","USDT","USDC"],"example":"USDT"},"available":{"type":"string","description":"Available balance that can be used for transactions","example":"1500.50"},"pending":{"type":"string","description":"Pending balance from transactions awaiting confirmation","example":"250.00"},"total":{"type":"string","description":"Total balance (available + pending)","example":"1750.50"}},"required":["currency","available","pending","total"]},"BalanceListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Balances retrieved successfully"},"data":{"description":"The merchant balances, one entry per currency.","type":"array","items":{"$ref":"#/components/schemas/BalanceDto"}}},"required":["success","message","data"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction.","example":"1100.00"},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction.","example":"0.00"},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction.","example":"1100.00"}},"required":["available","pending","total"]},"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction.","example":"bt_123456789_abcdef"},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from.","example":"deposit"},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees.","example":"123e4567-e89b-12d3-a456-426614174000"},"sourceReference":{"type":"string","nullable":true,"description":"Reference of the object this transaction came from. Set for sessions, invoices, and payouts; null for swaps, deposits, and fees.","example":"CC-1G3fDjgD93md"},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise.","example":"Compliance screening fee - address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance.","example":"credit"},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction.","example":"completed"},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`.","example":"100.00"},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected.","example":"USDT"},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction.","example":"DEP-123456789"},"balanceBefore":{"description":"The balance immediately before this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"balanceAfter":{"description":"The resulting balance after this transaction was applied.","allOf":[{"$ref":"#/components/schemas/BalanceSnapshotDto"}]},"createdAt":{"type":"string","description":"When the transaction was created (ISO 8601).","example":"2026-05-31T10:00:00.000Z"}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceTransactionListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful.","example":true},"message":{"type":"string","description":"Response message.","example":"Balance transactions retrieved successfully"},"data":{"description":"The balance transactions for this page.","type":"array","items":{"$ref":"#/components/schemas/BalanceTransactionDto"}},"meta":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","data","meta"]},"BalanceTransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful.","example":true},"message":{"type":"string","description":"Response message.","example":"Balance transaction retrieved successfully"},"data":{"description":"The balance transaction.","allOf":[{"$ref":"#/components/schemas/BalanceTransactionDto"}]}},"required":["success","message","data"]},"SwapRateResponseDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Asset the rate is priced from.","enum":["NGN","USDT","USDC","BTC","ETH","SOL","BNB","TRX","POL","CELO","CNGN"],"example":"USDT"},"toCurrency":{"type":"string","description":"Settlement currency the rate is priced into.","enum":["NGN","USDT","USDC"],"example":"NGN"},"rate":{"type":"string","description":"Amount of toCurrency received per 1 fromCurrency.","example":"1490.00000000"},"timestamp":{"type":"string","description":"When the rate was observed.","example":"2026-07-27T10:30:00.000Z"}},"required":["fromCurrency","toCurrency","rate","timestamp"]},"SwapEstimationResponseDto":{"type":"object","properties":{"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string","example":"100.00"},"targetAmount":{"type":"string","example":"149000.00"},"rate":{"type":"string","example":"1490.00000000"}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b1a2c3d4-e5f6-7890-1234-56789abcdef0"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string","example":"100.00"},"targetAmount":{"type":"string","example":"149000.00"},"rate":{"type":"string","example":"1490.00000000"},"executed":{"type":"boolean","example":true},"expiresAt":{"type":"string","example":"2024-05-12T10:00:15.000Z"},"createdAt":{"type":"string","example":"2024-05-12T10:00:00.000Z"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]},"SwapBalanceDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Currency to swap from","enum":["NGN","USDT","USDC"],"example":"USDT"},"toCurrency":{"type":"string","description":"Currency to swap to","enum":["NGN","USDT","USDC"],"example":"NGN"},"amount":{"type":"string","description":"Amount to swap","example":"100.00"}},"required":["fromCurrency","toCurrency","amount"]},"SwapResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b1a2c3d4-e5f6-7890-1234-56789abcdef0"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string","example":"100.00"},"targetAmount":{"type":"string","example":"149000.00"},"rate":{"type":"string","example":"1490.00000000"},"status":{"type":"string","example":"completed"},"quotation":{"$ref":"#/components/schemas/SwapQuotationResponseDto"},"createdAt":{"type":"string","example":"2024-05-12T10:00:00.000Z"},"completedAt":{"type":"string","example":"2024-05-12T10:00:15.000Z"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","status","createdAt"]},"ExecuteSwapDto":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this swap (must be HTTPS). Overrides your dashboard webhook URL for this swap only.","example":"https://example.com/webhooks"}}},"CryptoRecipientDetailsResponseDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"],"example":"tron"},"address":{"type":"string","example":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"}},"required":["chain","address"]},"BankRecipientDetailsResponseDto":{"type":"object","properties":{"accountName":{"type":"string","example":"JOHN ADEYEMI DOE"},"accountNumber":{"type":"string","example":"******6789","description":"Masked account number."},"bankName":{"type":"string","example":"Guaranty Trust Bank"},"bankCode":{"type":"string","example":"058"},"accountType":{"type":"string","enum":["savings","current"],"example":"savings"},"currency":{"type":"string","example":"NGN"}},"required":["accountName","accountNumber","bankName","bankCode","currency"]},"MobileMoneyRecipientDetailsResponseDto":{"type":"object","properties":{"currency":{"type":"string","example":"KES","description":"Currency the recipient is paid in."},"countryIsoCode":{"type":"string","example":"KE","description":"Recipient country code."},"accountNumber":{"type":"string","example":"******5678","description":"Masked phone number."},"accountName":{"type":"string","example":"Jane Wanjiku"},"institutionCode":{"type":"string","example":"MPESA"},"institutionName":{"type":"string","example":"M-Pesa"},"accountType":{"type":"string","enum":["individual","corporate"],"example":"individual"}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]},"RecipientDto":{"type":"object","properties":{"id":{"type":"string","example":"b1d9a0e2-7c44-4f1a-9b3e-2d5a8c6f0e11"},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"],"example":"ngn_bank_account"},"label":{"type":"string","example":"Payroll GTBank","nullable":true},"isDefault":{"type":"boolean","example":true},"isTrusted":{"type":"boolean","example":false,"description":"Whether the account owner has marked this recipient as trusted. Payouts to a trusted recipient do not require a one-time code."},"details":{"description":"Type-specific details, matching `type`. crypto_address resolves to { chain, address }; ngn_bank_account resolves to { accountName, accountNumber, bankName, bankCode, accountType, currency }; kes_mobile_money and ghs_mobile_money resolve to { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.","oneOf":[{"$ref":"#/components/schemas/CryptoRecipientDetailsResponseDto"},{"$ref":"#/components/schemas/BankRecipientDetailsResponseDto"},{"$ref":"#/components/schemas/MobileMoneyRecipientDetailsResponseDto"}]},"createdAt":{"format":"date-time","type":"string","example":"2026-06-27T10:20:05.000Z"},"updatedAt":{"format":"date-time","type":"string","example":"2026-06-27T10:20:05.000Z"}},"required":["id","type","label","isDefault","isTrusted","details","createdAt","updatedAt"]},"RecipientResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Recipient created successfully"},"data":{"$ref":"#/components/schemas/RecipientDto"}},"required":["success","message","data"]},"RecipientListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","type":"array","items":{"$ref":"#/components/schemas/RecipientDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"ValidateResolvedResponseDto":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"],"example":"ngn_bank_account"},"resolved":{"type":"object","description":"Resolved details, matching `type`. crypto_address: { chain, address }. ngn_bank_account: { accountName, bankName, bankCode, accountNumber }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }."}},"required":["valid","type","resolved"]},"CryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"],"example":"tron","description":"Blockchain the address belongs to. Every asset on this chain uses this address."},"address":{"type":"string","example":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC","description":"Destination wallet address."}},"required":["chain","address"]},"NGNBankRecipientDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string","example":"0123456789","description":"Bank account number."},"bankCode":{"type":"string","example":"058","description":"Bank code from the supported bank list."},"accountType":{"type":"string","enum":["savings","current"],"example":"savings","description":"Account type."}},"required":["accountNumber","bankCode"]},"MobileMoneyRecipientDetailsDto":{"type":"object","properties":{"phoneNumber":{"type":"string","example":"0712345678","description":"Mobile money phone number that receives the payout. Kenya (MPESA) and Ghana (MTN) local or international formats are accepted (e.g. 0712345678, 254712345678, or +254712345678) and must match the provider country."},"accountName":{"type":"string","example":"Jane Wanjiku","description":"Full name the mobile money account is registered under."},"institutionCode":{"type":"string","enum":["MPESA","MTN"],"example":"MPESA","description":"Mobile money provider. MPESA pays Kenyan recipients; MTN pays Ghanaian recipients."},"accountType":{"type":"string","enum":["individual","corporate"],"example":"individual","description":"Whether the recipient is a person or a business. Defaults to individual."}},"required":["phoneNumber","accountName","institutionCode"]},"CreateRecipientDto":{"type":"object","properties":{"isTemporary":{"type":"boolean","description":"True for a one-time recipient that is not saved to the address book. Defaults to false."},"notes":{"type":"string","description":"Merchant notes about this recipient. Use an empty string to clear.","maxLength":500},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","ghs_mobile_money"],"example":"ngn_bank_account","description":"Recipient type. Determines the shape of details."},"label":{"type":"string","example":"Payroll GTBank","description":"Friendly label for the recipient."},"details":{"description":"Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountNumber, bankCode, accountType? }. kes_mobile_money and ghs_mobile_money: { phoneNumber, accountName, institutionCode, accountType? }.","oneOf":[{"$ref":"#/components/schemas/CryptoRecipientDetailsDto"},{"$ref":"#/components/schemas/NGNBankRecipientDetailsDto"},{"$ref":"#/components/schemas/MobileMoneyRecipientDetailsDto"}]}},"required":["type","details"]},"ValidateCryptoDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"],"example":"tron"},"address":{"type":"string","example":"TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC"}},"required":["chain","address"]},"ValidateBankDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string","example":"0123456789"},"bankCode":{"type":"string","example":"058"}},"required":["accountNumber","bankCode"]},"ValidateRecipientDto":{"type":"object","properties":{"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","ghs_mobile_money"],"example":"ngn_bank_account"},"details":{"description":"Type-specific details to validate. crypto_address: { chain, address }. ngn_bank_account: { accountNumber, bankCode }. kes_mobile_money and ghs_mobile_money take the same details as create.","oneOf":[{"$ref":"#/components/schemas/ValidateCryptoDetailsDto"},{"$ref":"#/components/schemas/ValidateBankDetailsDto"},{"$ref":"#/components/schemas/MobileMoneyRecipientDetailsDto"}]}},"required":["type","details"]},"KoraPayBankDto":{"type":"object","properties":{"name":{"type":"string","description":"Bank name","example":"Access Bank Nigeria"},"slug":{"type":"string","description":"Bank slug","example":"access"},"code":{"type":"string","description":"Bank code","example":"044"},"nibss_bank_code":{"type":"string","description":"NIBSS 6-digit institution code for the bank","example":"000014"},"country":{"type":"string","description":"Country code","example":"NG"}},"required":["name","slug","code","country"]},"KoraPayBankListResponse":{"type":"object","properties":{"status":{"type":"boolean","description":"Request status","example":true},"message":{"type":"string","description":"Response message","example":"success"},"data":{"description":"List of banks","type":"array","items":{"$ref":"#/components/schemas/KoraPayBankDto"}}},"required":["status","message","data"]},"BankListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bank list retrieved successfully"},"data":{"description":"Provider bank list payload.","allOf":[{"$ref":"#/components/schemas/KoraPayBankListResponse"}]}},"required":["success","message","data"]},"SupportedPayoutChainsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Supported payout chains retrieved successfully"},"data":{"type":"object","description":"Map keyed by chain, each value a list of the assets you can pay out on that chain. Only chains and assets supported for payouts appear.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/AssetInfoDto"}},"example":{"tron":[{"asset":"USDT","networkId":"tron:0000000000000000000000000000000000000000","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","decimals":6}}],"base":[{"asset":"USDC","networkId":"eip155:8453","metadata":{"name":"USD Coin","symbol":"USDC","decimals":6},"contract":{"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6}}],"bsc":[{"asset":"USDT","networkId":"eip155:56","metadata":{"name":"Tether USD","symbol":"USDT","decimals":6},"contract":{"address":"0x55d398326f99059ff775485246999027b3197955","decimals":18}}]}}},"required":["success","message","data"]},"AssetMetadataDto":{"type":"object","properties":{"name":{"type":"string","description":"Asset name","example":"Ethereum"},"symbol":{"type":"string","description":"Asset symbol","example":"ETH"},"decimals":{"type":"number","description":"Asset decimals","example":18}},"required":["name","symbol","decimals"]},"AssetContractDto":{"type":"object","properties":{"address":{"type":"string","description":"Contract address","example":"0xdAC17F958D2ee523a2206206994597C13D831ec7"},"decimals":{"type":"number","description":"Contract decimals","example":6}},"required":["address","decimals"]},"AssetInfoDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol","example":"ETH"},"networkId":{"type":"string","description":"Network ID","example":"eip155:1"},"metadata":{"description":"Asset metadata","allOf":[{"$ref":"#/components/schemas/AssetMetadataDto"}]},"contract":{"description":"Contract information (for tokens)","allOf":[{"$ref":"#/components/schemas/AssetContractDto"}]}},"required":["asset","networkId","metadata"]},"CreateRefundDto":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for refund"},"refundAddress":{"type":"string","description":"Customer wallet address to receive the refund"},"feePaidBy":{"type":"string","description":"Who pays the blockchain fee. Defaults to merchant settings.","enum":["merchant","customer"]},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.","example":"https://example.com/webhooks"}},"required":["refundAddress"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID","example":"123e4567-e89b-12d3-a456-426614174000"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"],"example":"session"},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)","example":"cs_1234567890"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"],"example":"pending"},"reason":{"type":"string","description":"Reason for refund","example":"Customer requested refund"},"chain":{"type":"string","description":"Blockchain network","example":"tron"},"asset":{"type":"string","description":"Crypto asset","example":"USDT"},"amount":{"type":"string","description":"Crypto amount customer receives","example":"49.50000000"},"fee":{"type":"string","description":"Network fee (crypto)","example":"0.50000000"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"],"example":"customer"},"fiatAmount":{"type":"string","description":"Fiat value of the refund","example":"10000.00"},"fiatCurrency":{"type":"string","description":"Fiat currency","example":"NGN"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant","example":"10000.00"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"],"example":"settled"},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund","example":"TXyz1234567890abcdef"},"txHash":{"type":"string","description":"Blockchain transaction hash","example":"0x1234567890abcdef1234567890abcdef12345678"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction","example":"https://tronscan.org/#/transaction/abc123"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp","example":"2024-01-15T10:30:00.000Z"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp","example":"2024-01-15T10:35:00.000Z"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]},"RefundApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["success","message"]},"CreateInvoiceRefundDto":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for refund"},"refundAddress":{"type":"string","description":"Customer wallet address to receive the refund"},"feePaidBy":{"type":"string","description":"Who pays the blockchain fee. Defaults to merchant settings.","enum":["merchant","customer"]},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.","example":"https://example.com/webhooks"}},"required":["refundAddress"]},"RefundsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of refunds","type":"array","items":{"$ref":"#/components/schemas/RefundResponseDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset.","example":"USDT"},"toCurrency":{"type":"string","description":"Target currency or asset.","example":"NGN"},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency.","example":"100.00"},"targetAmount":{"type":"string","description":"Amount produced, in the target currency.","example":"149000.00"},"rate":{"type":"string","description":"Conversion rate applied.","example":"1490.00"}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","example":"tron","nullable":true},"address":{"type":"string","description":"Destination wallet address","example":"TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","example":"JOHN ADEYEMI DOE","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","example":"******6789","nullable":true},"bankName":{"type":"string","description":"Bank name","example":"Guaranty Trust Bank","nullable":true},"bankCode":{"type":"string","description":"Bank code","example":"058","nullable":true},"accountType":{"type":"string","description":"Account type","example":"savings","nullable":true},"currency":{"type":"string","description":"Account currency","example":"NGN","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","example":"KES","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","example":"KE","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","example":"******5678","nullable":true},"accountName":{"type":"string","description":"Recipient name","example":"Jane Wanjiku","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","example":"MPESA","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","example":"M-Pesa","nullable":true},"accountType":{"type":"string","description":"Recipient account type","example":"individual","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"],"example":"crypto_address"},"details":{"description":"Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountName, accountNumber, bankName, bankCode, accountType, currency }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.","oneOf":[{"$ref":"#/components/schemas/PayoutCryptoRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutBankRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutCrossBorderRecipientDetailsDto"}]}},"required":["id","type","details"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID","example":"123e4567-e89b-12d3-a456-426614174000"},"reference":{"type":"string","description":"Payout reference","example":"PAY-ABC123DEF456","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"],"example":"crypto"},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"],"example":"success"},"amount":{"type":"string","description":"Amount the recipient receives","example":"100.00"},"fee":{"type":"string","description":"Fee charged","example":"1.50"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)","example":"101.50"},"currency":{"type":"string","description":"Balance currency","example":"USDT"},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. The fee is carried by the top-level fee field, not here.","example":{"fromCurrency":"USDT","toCurrency":"KES","sourceAmount":"77.60","targetAmount":"10000.00","rate":"128.87"},"nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration","example":"Manual merchant payout"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"],"example":"API"},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","example":"0x1234567890abcdef1234567890abcdef12345678","nullable":true},"failureReason":{"type":"string","description":"Failure reason","example":null,"nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","example":"2024-01-01T12:05:00.000Z","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp","example":"2024-01-01T12:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp","example":"2024-01-01T12:05:00.000Z"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"PayoutV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["success","message"]},"CreatePayoutDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives. Local fiat: NGN. Crypto: the asset (USDT/USDC). Cross-border: KES/GHS, funded from the stablecoin balance in sourceCurrency.","example":"NGN"},"sourceCurrency":{"type":"string","description":"Stablecoin balance to debit (USDT or USDC), for a cross-border payout where the recipient is paid in a different currency. Omit for local fiat and crypto payouts, which debit the balance in `currency`.","enum":["USDT","USDC"],"example":"USDT"},"quoteId":{"type":"string","description":"For a cross-border payout, the `quoteId` from POST /payouts/cross-border/quote. Pass it to pay exactly the quoted price. Quotes expire after two minutes; omit it to price at the current rate.","example":"cbq_123e4567-e89b-12d3-a456-426614174000"},"amount":{"type":"string","description":"Amount to pay out, in `currency`. For a cross-border payout this is the amount the recipient receives, and it is not needed when `quoteId` is given: the quote already fixes it.","example":"5000.00"},"recipientId":{"type":"string","description":"Payout receipient Id","example":"123e4567-e89b-12d3-a456-426614174000"},"narration":{"type":"string","description":"Optional narration/description for the payout","example":"Manual withdrawal - Week 45"},"reference":{"type":"string","description":"Optional idempotency reference for your request. If omitted, we generate a reference for you.","example":"CLIENT-REF-12345"},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this payout (must be HTTPS). Overrides your dashboard webhook URL for this payout only.","example":"https://example.com/webhooks"}},"required":["currency","recipientId"]},"CrossBorderQuoteDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives.","enum":["KES","GHS"],"example":"KES"},"sourceCurrency":{"type":"string","description":"Stablecoin balance the payout is funded from and debited in.","enum":["USDT","USDC"],"example":"USDT"},"sourceAmount":{"type":"string","description":"Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it.","example":"78.00"}},"required":["currency","sourceCurrency","sourceAmount"]},"CrossBorderQuoteResponseDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Quote id. Pass it as quoteId to POST /payouts to pay exactly this price before it expires.","example":"cbq_123e4567-e89b-12d3-a456-426614174000"},"conversion":{"description":"The FX applied: the funding stablecoin converted to the amount the recipient receives. sourceAmount x rate = targetAmount.","example":{"fromCurrency":"USDT","toCurrency":"KES","sourceAmount":"77.60","targetAmount":"10000.00","rate":"128.87"},"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"fee":{"type":"string","description":"Flat fee, in conversion.fromCurrency.","example":"1.50"},"total":{"type":"string","description":"Total debited from the balance: conversion.sourceAmount plus fee, in conversion.fromCurrency.","example":"79.10"},"expiresAt":{"type":"string","description":"When this quote expires. After this time, request a new quote.","example":"2026-07-22T12:02:00.000Z"}},"required":["id","conversion","fee","total","expiresAt"]},"PayoutsV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","type":"array","items":{"$ref":"#/components/schemas/PayoutV2Dto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"RequestedAmountDto":{"type":"object","properties":{"amount":{"type":"string","example":"5000.00","description":"Requested payout amount"},"currency":{"type":"string","example":"NGN","description":"Currency the merchant balance will be debited from"}},"required":["amount","currency"]},"CalculatePayoutFeesResponseDataDto":{"type":"object","properties":{"fiat":{"type":"object","description":"Fiat payout fees grouped by currency, then method. Covers every supported fiat payout rail.","example":{"NGN":{"BankTransfer":"50.00"}},"additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"crossBorder":{"type":"object","description":"Cross-border payout fees grouped by destination currency, then method. The fee is a flat charge in USD, debited from the funding stablecoin (USDT/USDC), not in the destination currency.","example":{"KES":{"MobileMoney":"2.00"},"GHS":{"MobileMoney":"2.00"}},"additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"crypto":{"type":"object","description":"Crypto payout fees (USDT) grouped by asset, then chain. Covers every supported payout chain and asset.","example":{"USDT":{"bsc":"0.50","tron":"1.00","solana":"0.50"},"USDC":{"solana":"0.50"}},"additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}},"required":["fiat","crossBorder","crypto"]},"CalculatePayoutFeesApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Payout fees retrieved successfully"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/CalculatePayoutFeesResponseDataDto"}]}},"required":["success","message"]},"CreateDepositAccountDto":{"type":"object","properties":{"customerId":{"type":"string","description":"Existing customer to scope the account to. Omit to create the merchant parent account.","example":"123e4567-e89b-12d3-a456-426614174000"},"settlementCurrency":{"type":"string","description":"Currency deposits into this account settle into. On `default`, a USDT, USDC or NGN deposit credits that balance directly and every other asset converts to USDT. Any other value converts every deposit into that currency. The merchant parent account is always `default`.","enum":["default","NGN","USDT","USDC"],"default":"default","example":"USDT"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer","example":"123e4567-e89b-12d3-a456-426614174000"},"firstName":{"type":"string","description":"First name of the customer","example":"John"},"lastName":{"type":"string","description":"Last name of the customer","example":"Doe"},"email":{"type":"string","description":"Email address of the customer","example":"customer@example.com"},"phone":{"type":"string","description":"Phone number of the customer","example":"+1234567890"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram","example":"123456789"},"metadata":{"type":"object","description":"Additional metadata for the customer","example":{"source":"website","referrer":"google"}},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created","example":"2024-01-15T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated","example":"2024-01-15T10:30:00.000Z"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string","example":"ethereum"},"address":{"type":"string","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"},"createdAt":{"type":"string","example":"2026-01-01T00:00:00.000Z"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string","example":"NGN"},"accountNumber":{"type":"string","example":"0123456789"},"accountName":{"type":"string","example":"COINCIRCUIT/JANE DOE"},"bankName":{"type":"string","example":"Nomba Bank"},"bankCode":{"type":"string","example":"090645"},"accountReference":{"type":"string","example":"CCVBA-7f3a9c12"},"createdAt":{"type":"string","example":"2026-01-01T00:00:00.000Z"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]},"DepositAccountDto":{"type":"object","properties":{"id":{"type":"string","example":"da_123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","enum":["active","inactive"],"example":"active"},"isParent":{"type":"boolean","example":false},"settlementCurrency":{"type":"string","description":"Currency deposits into this account settle into. On `default`, a USDT, USDC or NGN deposit credits that balance directly and every other asset converts to USDT.","enum":["default","NGN","USDT","USDC"],"example":"USDT"},"customer":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"staticDepositAddresses":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountAddressDto"}},"ngnVirtualAccounts":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}}},"required":["id","status","isParent","settlementCurrency","customer","staticDepositAddresses","ngnVirtualAccounts"]},"CreateDepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Deposit account ready"},"data":{"$ref":"#/components/schemas/DepositAccountDto"}},"required":["success","message","data"]},"UpdateDepositAccountDto":{"type":"object","properties":{"settlementCurrency":{"type":"string","description":"Currency deposits into this account settle into. On `default`, a USDT, USDC or NGN deposit credits that balance directly and every other asset converts to USDT. Any other value converts every deposit into that currency.","enum":["default","NGN","USDT","USDC"],"example":"USDC"}},"required":["settlementCurrency"]},"DepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Deposit account retrieved successfully"},"data":{"$ref":"#/components/schemas/DepositAccountDto"}},"required":["success","message","data"]},"IssueDepositIdentityDto":{"type":"object","properties":{"type":{"type":"string","description":"Which identity to issue","enum":["static_deposit_address","ngn_virtual_account"],"example":"static_deposit_address"},"chain":{"type":"string","description":"Blockchain. Required when type is static_deposit_address.","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"],"example":"ethereum"},"bvn":{"type":"string","description":"BVN of the account holder (11 digits). Required when type is ngn_virtual_account.","example":"12345678901"},"currency":{"type":"string","description":"Currency for a virtual account.","enum":["NGN"],"example":"NGN"}},"required":["type"]},"ParentDepositAccountDto":{"type":"object","properties":{"id":{"type":"string","example":"da_123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","enum":["active","inactive"],"example":"active"},"isParent":{"type":"boolean","example":true},"settlementCurrency":{"type":"string","description":"Always `default` on the merchant parent account.","enum":["default"],"example":"default"},"customer":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"staticDepositAddresses":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountAddressDto"}},"ngnVirtualAccounts":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}}},"required":["id","status","isParent","settlementCurrency","customer","staticDepositAddresses","ngnVirtualAccounts"]},"ParentDepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Deposit account retrieved successfully"},"data":{"$ref":"#/components/schemas/ParentDepositAccountDto"}},"required":["success","message","data"]},"DepositAccountListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Deposit accounts retrieved successfully"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"DepositCryptoDetailDto":{"type":"object","properties":{"txHash":{"type":"string","example":"0xabc...","nullable":true},"chain":{"type":"string","example":"ethereum","nullable":true},"asset":{"type":"string","example":"USDT","nullable":true},"amount":{"type":"string","description":"Deposited amount in the source asset","example":"12.5"},"fromAddress":{"type":"string","example":"0xfrom...","nullable":true},"toAddress":{"type":"string","example":"0xto...","nullable":true},"amlCheck":{"type":"string","description":"Aml result.","enum":["passed","pending","failed","under_review"],"example":"passed"},"staticDepositAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountAddressDto"}]}},"required":["txHash","chain","asset","amount","fromAddress","toAddress","amlCheck","staticDepositAddress"]},"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","example":"Jane Doe","nullable":true},"accountNumber":{"type":"string","example":"0123456789","nullable":true},"bankName":{"type":"string","example":"Nomba Bank","nullable":true},"bankCode":{"type":"string","example":"090645","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]},"DepositFiatDetailDto":{"type":"object","properties":{"reference":{"type":"string","example":"NMB-12345","nullable":true},"method":{"type":"string","example":"bank_transfer"},"payer":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"payee":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"ngnVirtualAccount":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}]}},"required":["reference","method","payer","payee","ngnVirtualAccount"]},"DepositDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","enum":["crypto","fiat"],"example":"crypto"},"status":{"type":"string","enum":["pending","completed","failed"],"example":"completed"},"amount":{"type":"string","example":"100.00"},"currency":{"type":"string","example":"USDT"},"fee":{"type":"string","example":"0.50"},"netAmount":{"type":"string","example":"99.50"},"conversion":{"description":"Set when the deposit was auto-converted to USDT. The source asset and amount are in `crypto`; this is the bridge to the credited USDT (rate and target).","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"depositAccountId":{"type":"string","description":"The deposit account this deposit settled into.","example":"da_123e4567-e89b-12d3-a456-426614174000","nullable":true},"balanceReference":{"type":"string","description":"Reference of the balance history entry this deposit credited. Null until the deposit is credited.","example":"BAL-9f1c4a2b7de3","nullable":true},"customer":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"crypto":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositCryptoDetailDto"}]},"fiat":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositFiatDetailDto"}]},"createdAt":{"type":"string","example":"2026-01-01T00:00:00.000Z"},"completedAt":{"type":"string","example":"2026-01-01T00:05:00.000Z","nullable":true}},"required":["id","type","status","amount","currency","fee","netAmount","depositAccountId","customer","crypto","fiat","createdAt","completedAt"]},"DepositListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Direct deposits retrieved successfully"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DepositDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"DepositApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Direct deposit retrieved successfully"},"data":{"$ref":"#/components/schemas/DepositDto"}},"required":["success","message","data"]},"CreateCustomerRequestDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer","example":"John"},"lastName":{"type":"string","description":"Last name of the customer","example":"Doe"},"email":{"type":"string","description":"Email address of the customer","example":"customer@example.com"},"phone":{"type":"string","description":"Phone number of the customer","example":"+1234567890"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram","example":123456789},"metadata":{"type":"object","description":"Additional metadata for the customer","example":{"source":"website","referrer":"google"}}}},"CustomerResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Customer data","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]}},"required":["success","message"]},"UpdateCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer","example":"John"},"lastName":{"type":"string","description":"Last name of the customer","example":"Doe"},"email":{"type":"string","description":"Email address of the customer","example":"customer@example.com"},"phone":{"type":"string","description":"Phone number of the customer","example":"+1234567890"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram","example":123456789}}},"CustomersResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of customers","type":"array","items":{"$ref":"#/components/schemas/CustomerDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"CreateInvoiceItemDto":{"type":"object","properties":{"name":{"type":"string","description":"Item name","example":"Pro Plan subscription"},"description":{"type":"string","description":"Item description","example":"January 2025 billing period"},"unit":{"type":"string","description":"Unit of measure label","example":"seats"},"quantity":{"type":"string","description":"Quantity, as a numeric string with up to 8 decimal places","example":"3"},"unitPrice":{"type":"string","description":"Price per unit, as a numeric string with up to 12 decimal places","example":"5000.00"}},"required":["name","quantity","unitPrice"]},"CreateInvoiceCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email","example":"customer@example.com"},"firstName":{"type":"string","description":"Customer name","example":"Jane Doe"},"lastName":{"type":"string","description":"Customer last name","example":"Doe"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)","example":"+2348012345678"},"telegramId":{"type":"string","description":"Customer Telegram ID","example":"1283761283"}},"required":["email","firstName"]},"CreateInvoiceDto":{"type":"object","properties":{"reference":{"type":"string","description":"Custom invoice reference. If not provided, auto-generated.","example":"INV-2024-001"},"items":{"description":"Invoice items. The invoice amount is computed as the sum of (quantity x unit price) across all items.","type":"array","items":{"$ref":"#/components/schemas/CreateInvoiceItemDto"}},"currency":{"type":"string","description":"Fiat currency for the invoice","enum":["NGN","USD"],"example":"NGN"},"description":{"type":"string","description":"Invoice description shown to the customer","example":"Payment for Pro Plan - January 2025"},"expiresAt":{"type":"string","description":"Invoice expiry date in ISO 8601 format. Defaults to 1 day from creation, up to a maximum of 5 days.","example":"2025-01-16T22:30:00.000Z"},"periodStart":{"type":"string","description":"Billing period start date (for subscription/recurring invoices)","example":"2024-12-01T00:00:00.000Z"},"periodEnd":{"type":"string","description":"Billing period end date (for subscription/recurring invoices)","example":"2024-12-31T23:59:59.000Z"},"metadata":{"type":"object","description":"custom metadata","example":{"orderId":"12345","customField":"value"}},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","example":"https://example.com/success"},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","example":"https://example.com/cancel"},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this invoice (must be HTTPS). Overrides your dashboard webhook URL for this invoice only.","example":"https://example.com/webhooks"},"asset":{"type":"string","description":"Cryptocurrency asset","example":"USDT"},"chain":{"type":"string","description":"Blockchain network","example":"ethereum"},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CreateInvoiceCustomerDto"}]}},"required":["items","currency","description","expiresAt","customer"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Item name","example":"Pro Plan subscription"},"description":{"type":"string","description":"Item description","example":"January 2025 billing period","nullable":true},"unit":{"type":"string","description":"Unit of measure label","example":"seats","nullable":true},"quantity":{"type":"string","description":"Quantity","example":"3"},"unitPrice":{"type":"string","description":"Price per unit","example":"5000.00"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)","example":"15000.00"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name","example":"Acme Corporation"},"logoUrl":{"type":"string","description":"Merchant logo URL","example":"https://example.com/logo.png"}},"required":["businessName"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID","example":"123e4567-e89b-12d3-a456-426614174000"},"reference":{"type":"string","description":"Invoice reference","example":"inv_ref_abc123xyz789"},"description":{"type":"string","description":"Invoice description","example":"Payment for subscription service"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","example":"pending","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","example":"open","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded","example":false},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment","example":false},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)","example":"100000"},"amountPaid":{"type":"string","description":"Amount paid so far","example":"50000"},"currency":{"type":"string","description":"Invoice currency","example":"NGN","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","example":"USDT","nullable":true},"chain":{"type":"string","description":"Blockchain network","example":"ethereum","nullable":true},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"url":{"type":"string","description":"Public URL to access this invoice","example":"https://checkout.coincircuit.io/invoice/inv-abc123"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","example":"https://example.com/success","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","example":"https://example.com/cancel","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","example":{"orderId":"ORD-12345","customerId":"CUST-67890"},"nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)","example":"2024-01-01T00:00:00.000Z"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)","example":"2024-01-31T23:59:59.999Z"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)","example":"2024-01-20T10:30:00.000Z"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date","example":"2024-02-15T10:30:00.000Z"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date","example":"2024-01-15T10:30:00.000Z"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/InvoiceResponseDto"}]}},"required":["success","message"]},"InvoicesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of invoices","type":"array","items":{"$ref":"#/components/schemas/InvoiceResponseDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"BuildX402RequirementsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["base","arbitrum","bsc","solana"],"example":"base"},"asset":{"type":"string","enum":["USDC","USDT"],"example":"USDC","description":"Friendly symbol; resolved to the contract/mint"},"amount":{"type":"string","example":"0.10","description":"Human units; converted to atomic maxAmountRequired"},"payTo":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b","description":"Destination address. Defaults to your deposit address for the chain when omitted."},"resource":{"type":"string","example":"https://api.example.com/premium","description":"The protected resource URL","maxLength":500},"description":{"type":"string","example":"Premium API call","maxLength":255},"mimeType":{"type":"string","example":"application/json","maxLength":255},"maxTimeoutSeconds":{"type":"number","example":60}},"required":["chain","asset","amount"]},"X402RequirementsAcceptDto":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"maxAmountRequired":{"type":"string","example":"100000"},"resource":{"type":"string","example":"https://api.example.com/premium"},"description":{"type":"string","example":"Premium API call"},"mimeType":{"type":"string","example":"application/json"},"payTo":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b"},"maxTimeoutSeconds":{"type":"number","example":60},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"extra":{"type":"object","example":{"name":"USD Coin","version":"2"}}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","payTo","maxTimeoutSeconds","asset","extra"]},"X402RequirementsResult":{"type":"object","properties":{"x402Version":{"type":"number","example":1},"chain":{"type":"string","example":"base"},"asset":{"type":"string","example":"USDC"},"amount":{"type":"string","example":"0.10"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402RequirementsAcceptDto"}}},"required":["x402Version","chain","asset","amount","accepts"]},"X402RequirementsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment requirements generated"},"data":{"$ref":"#/components/schemas/X402RequirementsResult"}},"required":["success","message","data"]},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string","example":"0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b"},"to":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b"},"value":{"type":"string","example":"100000","description":"Atomic units"},"validAfter":{"type":"string","example":"0"},"validBefore":{"type":"string","example":"1710003600"},"nonce":{"type":"string","description":"EIP-3009 32-byte hex nonce or Permit2 numeric nonce"},"deadline":{"type":"string","description":"Permit2 deadline (unix seconds)"}},"required":["from","to","value"]},"X402PaymentPayloadInnerDto":{"type":"object","properties":{"signature":{"type":"string","description":"[evm] EIP-712 signature"},"authorization":{"description":"[evm] signed authorization","allOf":[{"$ref":"#/components/schemas/X402AuthorizationDto"}]},"transaction":{"type":"string","description":"[solana] base64 partially-signed transaction"},"payer":{"type":"string","description":"[solana] payer public key"}}},"X402PaymentPayloadDto":{"type":"object","properties":{"x402Version":{"type":"number","example":1},"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453","description":"CAIP-2 network id"},"payload":{"$ref":"#/components/schemas/X402PaymentPayloadInnerDto"}},"required":["x402Version","scheme","network","payload"]},"X402PaymentRequirementsDto":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"maxAmountRequired":{"type":"string","example":"100000","description":"Atomic units; exact amount for the exact scheme"},"resource":{"type":"string","maxLength":500},"description":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"payTo":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b","description":"Destination address"},"maxTimeoutSeconds":{"type":"number","example":60},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Token contract (EVM) / mint (Solana)"},"extra":{"type":"object","description":"EVM EIP-712 domain { name, version } or Solana { feePayer }"}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"X402FacilitatorRequestDto":{"type":"object","properties":{"x402Version":{"type":"number","example":1},"paymentPayload":{"$ref":"#/components/schemas/X402PaymentPayloadDto"},"paymentRequirements":{"$ref":"#/components/schemas/X402PaymentRequirementsDto"}},"required":["x402Version","paymentPayload","paymentRequirements"]},"X402VerifyResult":{"type":"object","properties":{"isValid":{"type":"boolean","example":true},"invalidReason":{"type":"string","nullable":true,"example":null},"payer":{"type":"string","nullable":true,"example":"0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b"},"chain":{"type":"string","example":"base"},"asset":{"type":"string","example":"USDC"},"payTo":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b"},"amount":{"type":"string","example":"0.10"},"checks":{"type":"object","example":{"timestamp":"pass","nonce":"pass","balance":"pass"}}},"required":["isValid","invalidReason","payer","chain","asset","payTo","amount","checks"]},"X402VerifyResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Verification complete"},"data":{"$ref":"#/components/schemas/X402VerifyResult"}},"required":["success","message","data"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7"},"txHash":{"type":"string","example":"0x4b7a1f0c9d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"},"status":{"type":"string","enum":["pending","confirmed"],"example":"confirmed"},"amlCheck":{"type":"string","enum":["passed","pending","failed"],"example":"passed"},"errorReason":{"type":"string","nullable":true,"example":null},"network":{"type":"string","example":"eip155:8453","description":"CAIP-2 network id"},"chain":{"type":"string","example":"base"},"asset":{"type":"string","example":"USDC"},"resource":{"type":"string","nullable":true,"example":"https://api.example.com/premium","description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"example":"Premium API call","description":"Human description of the paid resource"},"payer":{"type":"string","example":"0x1A2b3C4d5E6f7A8b9C0d1E2f3A4b5C6d7E8f9A0b","description":"Paying agent wallet"},"payTo":{"type":"string","example":"0x9f1c4a2b7De3a01F5b8c2D4e6A7b9C0d1E2f3A4b","description":"Destination address"},"amount":{"type":"string","example":"0.10"},"fee":{"type":"string","example":"0","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true,"example":12345678},"explorerUrl":{"type":"string","nullable":true,"example":"https://basescan.org/tx/0x4b7a1f0c9d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"},"createdAt":{"format":"date-time","type":"string","example":"2026-06-25T21:09:02.000Z"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]},"X402SettleResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Payment settled"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"X402SupportedKind":{"type":"object","properties":{"x402Version":{"type":"number","example":1},"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"chain":{"type":"string","example":"base"},"assets":{"example":["USDC","USDT"],"type":"array","items":{"type":"string"}},"extra":{"type":"object","example":{"feePayer":"FeePayerExamp1e1111111111111111111111111111"}}},"required":["x402Version","scheme","network","chain","assets"]},"X402SupportedResult":{"type":"object","properties":{"kinds":{"type":"array","items":{"$ref":"#/components/schemas/X402SupportedKind"}}},"required":["kinds"]},"X402SupportedResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Supported networks retrieved"},"data":{"$ref":"#/components/schemas/X402SupportedResult"}},"required":["success","message","data"]},"X402TransactionsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"x402 transactions retrieved"},"data":{"type":"array","items":{"$ref":"#/components/schemas/X402TransactionDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"X402TransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"x402 transaction retrieved"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"CreateCustomerNestedDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email (used if customer record is created)","example":"customer@example.com"},"firstName":{"type":"string","description":"Customer first name (used if customer record is created)","example":"John"},"lastName":{"type":"string","description":"Customer last name (used if customer record is created)","example":"Doe"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)","example":"+2348012345678"},"telegramId":{"type":"string","description":"Customer Telegram ID","example":"1283761283"}},"required":["email"]},"CreateCheckoutSessionDto":{"type":"object","properties":{"title":{"type":"string","description":"Session title","example":"Payment for invoice 112"},"description":{"type":"string","description":"Session description","example":"Payment for invoice 112"},"amount":{"type":"string","description":"Amount in fiat currency (e.g. 100000.00)","example":"100000.00"},"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"],"default":"NGN"},"asset":{"type":"string","description":"Cryptocurrency to accept (optional - can be set later)","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network to accept the crypto on (optional - can be set later)","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"metadata":{"type":"object","description":"Additional metadata object","example":{"orderId":"ORD-9981","purpose":"Payment for invoice 112"}},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CreateCustomerNestedDto"}]},"cancelUrl":{"type":"string","description":"Redirect URL when the customer cancels the payment (must be HTTPS)","example":"https://example.com/cancel"},"successUrl":{"type":"string","description":"Redirect URL on successful payment (must be HTTPS)","example":"https://example.com/success"},"webhookUrl":{"type":"string","description":"URL to receive webhook notifications for this session (must be HTTPS)","example":"https://example.com/webhook"},"feePaidBy":{"type":"string","enum":["customer","merchant"],"description":"Who pays gas/network fees for this session. If not specified, uses dashboard default settings","example":"customer"},"settlementCurrency":{"type":"string","enum":["NGN","USDT","USDC"],"description":"currency this payment settles into. Defaults to your account currency","example":"USDT"}},"required":["title","description","amount","currency","customer"]},"SettlementsCustomerPaidDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fiat equivalent of what the customer actually paid, in gross (settlement) currency. Null if no crypto received yet.","example":"29850.00","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount","example":"5.00"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency","example":"1.00000000"}},"required":["amount","conversionRate"]},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","example":"0.05","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"],"example":"merchant"}},"required":["amount","paidBy"]},"SettlementsFeesDto":{"type":"object","properties":{"processing":{"description":"Processing fee","nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementsFeeDetailDto"}]},"gas":{"description":"Gas/network fee","nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementsFeeDetailDto"}]}}},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","example":"3.85","nullable":true}},"required":["amount"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"],"example":"USDT"},"customerPaid":{"description":"Fiat equivalent of what the customer actually paid in gross currency, after gas deduction if customer-paid","nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementsCustomerPaidDto"}]},"gross":{"description":"Gross amount after currency conversion, before fees","allOf":[{"$ref":"#/components/schemas/SettlementsGrossDto"}]},"fees":{"description":"Fee breakdown","nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementsFeesDto"}]},"net":{"description":"Net amount after all fees","nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementsNetDto"}]}},"required":["currency","gross","fees","net"]},"PaymentResponseDto":{"type":"object","properties":{"status":{"type":"string","description":"Payment status (tracks payment progress separately from session status)","enum":["pending","partial","expired","completed","failed","under_review"]},"asset":{"type":"string","description":"Cryptocurrency","example":"USDT","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","example":"ethereum","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)","example":"10.00"},"amountReceived":{"type":"string","description":"Amount received so far","example":"0.00"},"address":{"type":"string","description":"Payment address where crypto should be sent","example":"0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25"},"gasFee":{"type":"string","description":"Raw network/gas fee in the payment asset units (e.g. USDT, ETH). This is the on-chain fee in crypto, separate from fiat settlement fees. The fiat value of this fee is shown in amount.fees.gas.amount.","example":"0.50","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"],"example":"customer"},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)","example":"1.00"}}},"CheckoutSessionV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID","example":"123e4567-e89b-12d3-a456-426614174000"},"reference":{"type":"string","description":"Unique reference for this session","example":"cs_ref_abc123xyz789"},"title":{"type":"string","description":"Session title","example":"Payment for invoice 112"},"description":{"type":"string","description":"Session description","example":"Payment for invoice 112"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"],"example":"open"},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"],"example":"checkout"},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)","example":"100.00"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true,"example":"100.00"},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"],"example":"NGN"},"settlements":{"description":"Full settlement breakdown (gross, fees, net)","allOf":[{"$ref":"#/components/schemas/SettlementsDto"}]},"payment":{"description":"Payment details (cryptocurrency, amounts, and address)","allOf":[{"$ref":"#/components/schemas/PaymentResponseDto"}]},"url":{"type":"string","description":"Public URL to access this payment session","example":"https://checkout.coincircuit.io/pay/session-ref-123"},"cancelUrl":{"type":"string","description":"Cancel URL","example":"https://example.com/cancel"},"successUrl":{"type":"string","description":"Success URL","example":"https://example.com/success"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true,"example":{"orderId":"ORD-9981"}},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true,"example":null},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true,"example":null},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded","example":false},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment","example":false},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp","example":"2024-01-15T10:30:00.000Z"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp","example":"2024-01-15T11:30:00.000Z"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true,"example":null}},"required":["id","reference","state","type","amount","currency","settlements","createdAt","expiresAt"]},"PaymentSessionV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Payment session data (V2)","allOf":[{"$ref":"#/components/schemas/CheckoutSessionV2Dto"}]}},"required":["success","message"]},"GenerateDepositAddressDto":{"type":"object","properties":{"asset":{"type":"string","description":"Cryptocurrency to accept. Optional when the session already has a fixed asset.","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"],"example":"USDT"},"chain":{"type":"string","description":"Blockchain network. Optional when the session already has a fixed chain.","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"],"example":"ethereum"},"customer":{"description":"Customer details. Required if the session was created without a customer. If the session already has a customer attached, this field is ignored.","allOf":[{"$ref":"#/components/schemas/CreateCustomerNestedDto"}]}}},"PaymentSessionsV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Payment sessions data (V2)","type":"array","items":{"$ref":"#/components/schemas/CheckoutSessionV2Dto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"GrossAmountDto":{"type":"object","properties":{"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"],"example":"NGN"},"amount":{"type":"string","description":"Fiat amount","example":"10000"},"conversionRate":{"type":"string","description":"Conversion rate used to convert from this requested currency to gross currency. Always present (1.0 when no conversion occurred)","example":"1464.96"}},"required":["currency","amount","conversionRate"]},"FiatAmountDto":{"type":"object","properties":{"amount":{"type":"string","example":"100.00"},"currency":{"type":"string","example":"USD"}},"required":["amount","currency"]},"CryptoAmountDto":{"type":"object","properties":{"amount":{"type":"string","example":"50.234567"},"asset":{"type":"string","example":"USDT"},"chain":{"type":"string","example":"TRON"}},"required":["amount","asset","chain"]},"FeeDto":{"type":"object","properties":{"networkFee":{"type":"string","example":"1.200000"},"paidBy":{"type":"string","example":"merchant"}},"required":["networkFee","paidBy"]},"CalculateCheckoutAmountResponseDto":{"type":"object","properties":{"fiat":{"$ref":"#/components/schemas/FiatAmountDto"},"crypto":{"$ref":"#/components/schemas/CryptoAmountDto"},"fees":{"$ref":"#/components/schemas/FeeDto"},"conversionRate":{"type":"string","example":"0.00234"}},"required":["fiat","crypto","fees","conversionRate"]},"CalculateCheckoutAmountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/CalculateCheckoutAmountResponseDto"}]}},"required":["success","message"]},"CreatePaymentPageProductDto":{"type":"object","properties":{"title":{"type":"string","description":"Title of the product","example":"Standard Room","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the product","example":"Single bed, breakfast included"},"price":{"type":"number","description":"Fixed price for this product","example":50000},"isActive":{"type":"boolean","description":"Whether this product is active","example":true,"default":true},"sortOrder":{"type":"number","description":"Sort order for display","example":0,"default":0},"id":{"type":"string","description":"Optional ID for updates"}},"required":["title","price","isActive","sortOrder"]},"CreatePaymentPageDto":{"type":"object","properties":{"title":{"type":"string","description":"Title for the payment page","example":"My Store Checkout","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the payment page","example":"Payment page for my online store"},"isActive":{"type":"boolean","description":"Whether the payment page is active","example":true,"default":true},"minAmount":{"type":"number","description":"Minimum amount for payments","example":100},"currency":{"type":"string","description":"Fiat currency for this payment page","enum":["NGN","USD"],"example":"USD"},"bankAccountIds":{"description":"Array of bank account IDs to associate with this payment page","example":["uuid-1","uuid-2"],"type":"array","items":{"type":"string"}},"products":{"description":"Products for this payment page","example":[{"title":"Standard Room","description":"Single bed, breakfast included","price":50000,"isActive":true,"sortOrder":0},{"title":"Deluxe Room","description":"King bed, breakfast & dinner","price":80000,"isActive":true,"sortOrder":1}],"type":"array","items":{"$ref":"#/components/schemas/CreatePaymentPageProductDto"}},"enableQuantity":{"type":"boolean","description":"Enable quantity selector (e.g. nights, units). Only valid when products are defined."}},"required":["title","isActive","currency"]},"MerchantBankAccountDto":{"type":"object","properties":{"isTemporary":{"type":"boolean","description":"Whether this is a temporary payout recipient."},"notes":{"type":"string","description":"Merchant notes about this recipient.","nullable":true},"id":{"type":"string","description":"Bank account ID","example":"123e4567-e89b-12d3-a456-426614174000"},"accountName":{"type":"string","description":"Account holder name","example":"John Doe Business Ltd"},"accountNumber":{"type":"string","description":"Account number (last 4 digits)","example":"****4852"},"bankName":{"type":"string","description":"Bank name","example":"Access Bank"},"bankCode":{"type":"string","description":"Bank code (CBN identifier)","example":"044"},"accountType":{"type":"string","description":"Account type","example":"savings"},"currency":{"type":"string","description":"Currency","example":"NGN"},"nickName":{"type":"string","description":"Account nickname","example":"Main Account"},"default":{"type":"boolean","description":"Is default account","example":true},"isTrusted":{"type":"boolean","description":"Whether the account owner has marked this bank account as trusted. Payouts to a trusted recipient do not require a one-time code.","example":false},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp","example":"2024-01-01T00:00:00.000Z"}},"required":["isTemporary","id","accountName","accountNumber","bankName","bankCode","accountType","currency","nickName","default","isTrusted","createdAt","updatedAt"]},"PaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the product","example":"uuid-string"},"title":{"type":"string","description":"Title of the product","example":"Standard Room"},"description":{"type":"string","description":"Description of the product","example":"Single bed, breakfast included"},"price":{"type":"string","description":"Fixed price for this product","example":"50000.00"},"isActive":{"type":"boolean","description":"Whether this product is active","example":true},"sortOrder":{"type":"number","description":"Sort order for display","example":0},"imageUrl":{"type":"string","description":"Image for this product","example":"https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the product was created","example":"2024-01-15T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was last updated","example":"2024-01-15T10:30:00.000Z"}},"required":["id","title","price","isActive","sortOrder","createdAt","updatedAt"]},"PaymentPageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the payment page","example":"123e4567-e89b-12d3-a456-426614174000"},"reference":{"type":"string","description":"Reference for the payment page","example":"1234567890"},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"title":{"type":"string","description":"Payment page title","example":"Donation Page"},"description":{"type":"string","description":"Payment page description","example":"Support our cause with a donation"},"isActive":{"type":"boolean","description":"Whether the payment page is active","example":true},"currency":{"type":"string","description":"Currency for the payment page","example":"NGN","enum":["NGN","USD"]},"minAmount":{"type":"string","description":"Minimum amount","example":"1000"},"enableQuantity":{"type":"boolean","description":"Whether quantity selector is enabled for this payment page","example":false},"bankAccounts":{"description":"Bank accounts","type":"array","items":{"$ref":"#/components/schemas/MerchantBankAccountDto"}},"products":{"description":"Products","type":"array","items":{"$ref":"#/components/schemas/PaymentPageProductDto"}},"imageUrl":{"type":"string","description":"Image for the payment page","example":"https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg"},"url":{"type":"string","description":"Public URL to access this payment page","example":"https://checkout.coincircuit.io/static/1234567890"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was created","example":"2024-01-15T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was last updated","example":"2024-01-15T10:30:00.000Z"}},"required":["id","reference","merchant","url","createdAt","updatedAt"]},"PaymentPageResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Payment page data","allOf":[{"$ref":"#/components/schemas/PaymentPageDto"}]}},"required":["success","message"]},"PaymentPagesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of payment pages","type":"array","items":{"$ref":"#/components/schemas/PaymentPageDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"PublicPaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Product ID","example":"123e4567-e89b-12d3-a456-426614174000"},"title":{"type":"string","description":"Title of the product","example":"Basic Plan"},"price":{"type":"string","description":"Fixed price","example":"100000"},"description":{"type":"string","description":"Description of the product","example":"Basic subscription plan with essential features"},"sortOrder":{"type":"number","description":"Sort order for displaying products","example":1},"imageUrl":{"type":"string","description":"Image for this product","example":"https://cdn.coincircuit.io/products/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg"}},"required":["id","title","price","sortOrder"]},"PublicBankAccountDto":{"type":"object","properties":{"id":{"type":"string","description":"Bank account ID","example":"bacc-123e4567-e89b-12d3-a456-426614174000"},"accountName":{"type":"string","description":"Account holder name","example":"John Smith"},"accountNumber":{"type":"string","description":"Masked account number, only last 4 digits shown","example":"******4321"},"bankName":{"type":"string","description":"Bank name","example":"GT Bank"}},"required":["id","accountName","accountNumber","bankName"]},"PublicPaymentPageDto":{"type":"object","properties":{"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"title":{"type":"string","description":"Static checkout title"},"description":{"type":"string","description":"Static checkout description"},"currency":{"type":"string","description":"Currency"},"minAmount":{"type":"string","description":"Minimum amount"},"enableQuantity":{"type":"boolean","description":"Whether quantity selector is enabled for this payment page"},"products":{"description":"Products","type":"array","items":{"$ref":"#/components/schemas/PublicPaymentPageProductDto"}},"bankAccounts":{"description":"Bank accounts","type":"array","items":{"$ref":"#/components/schemas/PublicBankAccountDto"}},"imageUrl":{"type":"string","description":"Image for the payment page","example":"https://cdn.coincircuit.io/payment-pages/8b1c2d3e-4f5a-6789-abcd-ef0123456789.jpeg"},"url":{"type":"string","description":"Public URL to access this payment page","example":"https://checkout.coincircuit.io/static/1234567890"}},"required":["merchant","url"]},"PublicPaymentPageResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Payment page data","allOf":[{"$ref":"#/components/schemas/PublicPaymentPageDto"}]}},"required":["success","message"]},"UpdatePaymentPageDto":{"type":"object","properties":{"title":{"type":"string","description":"Title for the payment page","example":"My Store Checkout","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the payment page","example":"Payment page for my online store"},"isActive":{"type":"boolean","description":"Whether the payment page is active","example":true,"default":true},"minAmount":{"type":"number","description":"Minimum amount for payments","example":100},"currency":{"type":"string","description":"Fiat currency for this payment page","enum":["NGN","USD"],"example":"USD"},"bankAccountIds":{"description":"Array of bank account IDs to associate with this payment page","example":["uuid-1","uuid-2"],"type":"array","items":{"type":"string"}},"products":{"description":"Products for this payment page","example":[{"title":"Standard Room","description":"Single bed, breakfast included","price":50000,"isActive":true,"sortOrder":0},{"title":"Deluxe Room","description":"King bed, breakfast & dinner","price":80000,"isActive":true,"sortOrder":1}],"type":"array","items":{"$ref":"#/components/schemas/CreatePaymentPageProductDto"}},"enableQuantity":{"type":"boolean","description":"Enable quantity selector (e.g. nights, units). Only valid when products are defined."}}},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record","example":"123e4567-e89b-12d3-a456-426614174000"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to","example":"123e4567-e89b-12d3-a456-426614174000"},"txHash":{"type":"string","description":"Blockchain transaction hash","example":"0x1234567890abcdef1234567890abcdef12345678"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"],"example":"confirmed"},"chain":{"type":"string","description":"Blockchain network","example":"bsc"},"asset":{"type":"string","description":"Cryptocurrency asset symbol","example":"USDT"},"fromAddress":{"type":"string","description":"Sender address","example":"0x1234567890abcdef1234567890abcdef12345678"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)","example":"0x742d35Cc6639C0532fF8037C7D6B8b123b2F4a25"},"amount":{"type":"string","description":"Transaction amount","example":"100.50"},"confirmations":{"type":"string","description":"Number of blockchain confirmations","example":"12"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"],"example":"pending"},"failureReason":{"type":"string","description":"Reason for transaction failure","example":"Insufficient confirmations"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction","example":"https://bscscan.com/tx/0x1234567890abcdef1234567890abcdef12345678"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed","example":"2024-01-15T10:30:00.000Z"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created","example":"2024-01-15T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated","example":"2024-01-15T10:30:00.000Z"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]},"TransactionsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of transactions","type":"array","items":{"$ref":"#/components/schemas/TransactionDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"TransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Transaction data","allOf":[{"$ref":"#/components/schemas/TransactionDto"}]}},"required":["success","message"]},"SettlementAmountDto":{"type":"object","properties":{"amount":{"type":"string","example":"222.000"}},"required":["amount"]},"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","example":"17.760"},"paidBy":{"type":"string","enum":["customer","merchant"],"example":"merchant"}},"required":["amount","paidBy"]},"FeesDto":{"type":"object","properties":{"processing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]},"gas":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]}}},"SettlementResponseDto":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"example":"completed"},"entity":{"type":"string","enum":["session","invoice"],"example":"session"},"reference":{"type":"string","example":"cs-mp9rm032-flh1obsqjpv"},"balanceReference":{"type":"string","example":"DEP-MP9RZA2D-9AEBQ1","nullable":true},"requested":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RequestedAmountDto"}]},"gross":{"$ref":"#/components/schemas/GrossAmountDto"},"customerPaid":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementAmountDto"}]},"fees":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeesDto"}]},"net":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SettlementAmountDto"}]}},"required":["status","entity","reference","balanceReference","gross"]},"SettlementListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"List of settlements","type":"array","items":{"$ref":"#/components/schemas/SettlementResponseDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"SettlementApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful","example":true},"message":{"type":"string","description":"Response message","example":"Success"},"data":{"description":"Settlement data","allOf":[{"$ref":"#/components/schemas/SettlementResponseDto"}]}},"required":["success","message"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID","example":"123e4567-e89b-12d3-a456-426614174000"},"reference":{"type":"string","description":"Unique reference for this session","example":"cs_ref_abc123xyz789"},"title":{"type":"string","description":"Session title","example":"Payment for invoice 112"},"description":{"type":"string","description":"Session description","example":"Payment for invoice 112"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"],"example":"open"},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"],"example":"checkout"},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)","example":"100.00"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true,"example":"100.00"},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"],"example":"NGN"},"settlements":{"description":"Full settlement breakdown (gross, fees, net)","allOf":[{"$ref":"#/components/schemas/SettlementsDto"}]},"payment":{"description":"Payment details (cryptocurrency, amounts, and address)","allOf":[{"$ref":"#/components/schemas/PaymentResponseDto"}]},"url":{"type":"string","description":"Public URL to access this payment session","example":"https://checkout.coincircuit.io/pay/session-ref-123"},"cancelUrl":{"type":"string","description":"Cancel URL","example":"https://example.com/cancel"},"successUrl":{"type":"string","description":"Success URL","example":"https://example.com/success"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true,"example":{"orderId":"ORD-9981"}},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true,"example":null},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true,"example":null},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded","example":false},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment","example":false},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp","example":"2024-01-15T10:30:00.000Z"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp","example":"2024-01-15T11:30:00.000Z"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true,"example":null},"transaction":{"description":"Transaction that triggered this event. Present on transaction.* events and payment.completed.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TransactionDto"}]}},"required":["id","reference","state","type","amount","currency","settlements","createdAt","expiresAt"]},"PaymentWebhookEnvelopeDto":{"type":"object","properties":{"session":{"description":"Payment session","allOf":[{"$ref":"#/components/schemas/PaymentWebhookDataDto"}]},"failureReason":{"type":"string","description":"Optional failure reason for failed payments","nullable":true}},"required":["session"]},"PaymentCompletedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payment.completed","enum":["payment.completed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"PaymentPartialWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payment.partial","enum":["payment.partial"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"PaymentExpiredWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payment.expired","enum":["payment.expired"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"PaymentUnderpaidWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payment.underpaid","enum":["payment.underpaid"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"TransactionWebhookDataDto":{"type":"object","properties":{"session":{"description":"The payment session this transaction belongs to","allOf":[{"$ref":"#/components/schemas/PaymentWebhookDataDto"}]},"transaction":{"description":"The transaction record","allOf":[{"$ref":"#/components/schemas/TransactionDto"}]}},"required":["session","transaction"]},"TransactionReceivedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"transaction.received","enum":["transaction.received"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/TransactionWebhookDataDto"}]}},"required":["event","data"]},"TransactionConfirmedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"transaction.confirmed","enum":["transaction.confirmed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/TransactionWebhookDataDto"}]}},"required":["event","data"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","example":"USDT","nullable":true},"chain":{"type":"string","description":"Blockchain network","example":"bsc","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session","example":"100.00"},"address":{"type":"string","description":"Deposit address used","example":"0x742d35...","nullable":true},"txHash":{"type":"string","description":"Transaction hash","example":"0xabc123...","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status","example":"completed"}},"required":["amount","address","status"]},"InvoiceWebhookDataDto":{"type":"object","properties":{"invoice":{"description":"Invoice data","allOf":[{"$ref":"#/components/schemas/InvoiceResponseDto"}]},"payments":{"description":"Payment sessions associated with this invoice","nullable":true,"type":"array","items":{"$ref":"#/components/schemas/InvoiceWebhookPaymentDto"}}},"required":["invoice"]},"InvoiceCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"invoice.created","enum":["invoice.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"InvoiceUpdatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"invoice.updated","enum":["invoice.updated"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"InvoicePaidWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"invoice.paid","enum":["invoice.paid"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"InvoiceExpiredWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"invoice.expired","enum":["invoice.expired"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"PayoutWebhookDataDto":{"type":"object","properties":{"payout":{"description":"Payout data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["payout"]},"PayoutCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payout.created","enum":["payout.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"PayoutSuccessWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payout.success","enum":["payout.success"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"PayoutFailedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"payout.failed","enum":["payout.failed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"RefundWebhookDataDto":{"type":"object","properties":{"refund":{"description":"Refund data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["refund"]},"RefundCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"refund.created","enum":["refund.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]},"RefundSuccessWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"refund.success","enum":["refund.success"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]},"RefundFailedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","example":"refund.failed","enum":["refund.failed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]}}}}