> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/models.md). # Models ## The SupportedAssetsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SupportedAssetsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Supported assets data"}},"required":["success","message"]}}}} ``` ## The PaginationMetaDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The PaginatedApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaginatedApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The ApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Response data"}},"required":["success","message"]}}}} ``` ## The BalanceDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceDto":{"type":"object","properties":{"currency":{"type":"string","description":"Balance currency","enum":["NGN","USDT","USDC"]},"available":{"type":"string","description":"Available balance that can be used for transactions"},"pending":{"type":"string","description":"Pending balance from transactions awaiting confirmation"},"total":{"type":"string","description":"Total balance (available + pending)"}},"required":["currency","available","pending","total"]}}}} ``` ## The BalanceListResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"The merchant balances, one entry per currency.","type":"array","items":{"$ref":"#/components/schemas/BalanceDto"}}},"required":["success","message","data"]},"BalanceDto":{"type":"object","properties":{"currency":{"type":"string","description":"Balance currency","enum":["NGN","USDT","USDC"]},"available":{"type":"string","description":"Available balance that can be used for transactions"},"pending":{"type":"string","description":"Pending balance from transactions awaiting confirmation"},"total":{"type":"string","description":"Total balance (available + pending)"}},"required":["currency","available","pending","total"]}}}} ``` ## The BalanceSnapshotDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]}}}} ``` ## The BalanceTransactionDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction."},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from."},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees."},"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."},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise."},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance."},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction."},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`."},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected."},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction."},"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)."}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]}}}} ``` ## The BalanceTransactionListResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceTransactionListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful."},"message":{"type":"string","description":"Response message."},"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"]},"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction."},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from."},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees."},"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."},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise."},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance."},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction."},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`."},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected."},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction."},"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)."}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The BalanceTransactionResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BalanceTransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful."},"message":{"type":"string","description":"Response message."},"data":{"description":"The balance transaction.","allOf":[{"$ref":"#/components/schemas/BalanceTransactionDto"}]}},"required":["success","message","data"]},"BalanceTransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the balance transaction."},"source":{"type":"string","nullable":true,"enum":["deposit","payment_session","invoice","payout","swap","refund","fee"],"description":"What this transaction originated from."},"sourceId":{"type":"string","nullable":true,"description":"Id of the object this transaction came from (session, invoice, payout, or swap). Null for deposits and fees."},"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."},"description":{"type":"string","nullable":true,"description":"What this transaction was for. Set for compliance screening fees and their refunds; null otherwise."},"direction":{"type":"string","enum":["credit","debit"],"description":"Whether funds were added to or removed from the balance."},"status":{"type":"string","enum":["pending","completed","failed","cancelled"],"description":"Current status of the transaction."},"amount":{"type":"string","description":"Amount added to or removed from the balance, in `currency`."},"currency":{"type":"string","enum":["USDT","NGN"],"description":"Currency of the balance this transaction affected."},"reference":{"type":"string","nullable":true,"description":"Reference for the transaction."},"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)."}},"required":["id","source","sourceId","sourceReference","description","direction","status","amount","currency","reference","balanceBefore","balanceAfter","createdAt"]},"BalanceSnapshotDto":{"type":"object","properties":{"available":{"type":"string","nullable":true,"description":"Available balance after this transaction."},"pending":{"type":"string","nullable":true,"description":"Pending balance after this transaction."},"total":{"type":"string","nullable":true,"description":"Total balance after this transaction."}},"required":["available","pending","total"]}}}} ``` ## The SwapRateResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]},"toCurrency":{"type":"string","description":"Settlement currency the rate is priced into.","enum":["NGN","USDT","USDC"]},"rate":{"type":"string","description":"Amount of toCurrency received per 1 fromCurrency."},"timestamp":{"type":"string","description":"When the rate was observed."}},"required":["fromCurrency","toCurrency","rate","timestamp"]}}}} ``` ## The SwapEstimationResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SwapEstimationResponseDto":{"type":"object","properties":{"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}}} ``` ## The SwapQuotationResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}}} ``` ## The SwapBalanceDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SwapBalanceDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Currency to swap from","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","description":"Currency to swap to","enum":["NGN","USDT","USDC"]},"amount":{"type":"string","description":"Amount to swap"}},"required":["fromCurrency","toCurrency","amount"]}}}} ``` ## The SwapResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SwapResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"status":{"type":"string"},"quotation":{"$ref":"#/components/schemas/SwapQuotationResponseDto"},"createdAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","status","createdAt"]},"SwapQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string"},"fromCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"toCurrency":{"type":"string","enum":["NGN","USDT","USDC"]},"sourceAmount":{"type":"string"},"targetAmount":{"type":"string"},"rate":{"type":"string"},"executed":{"type":"boolean"},"expiresAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","fromCurrency","toCurrency","sourceAmount","targetAmount","rate","executed","expiresAt","createdAt"]}}}} ``` ## The ExecuteSwapDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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."}}}}}} ``` ## The CryptoRecipientDetailsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CryptoRecipientDetailsResponseDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]}}}} ``` ## The BankRecipientDetailsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BankRecipientDetailsResponseDto":{"type":"object","properties":{"accountName":{"type":"string"},"accountNumber":{"type":"string","description":"Masked account number."},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountType":{"type":"string","enum":["savings","current"]},"currency":{"type":"string"}},"required":["accountName","accountNumber","bankName","bankCode","currency"]}}}} ``` ## The MobileMoneyRecipientDetailsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"MobileMoneyRecipientDetailsResponseDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient is paid in."},"countryIsoCode":{"type":"string","description":"Recipient country code."},"accountNumber":{"type":"string","description":"Masked phone number."},"accountName":{"type":"string"},"institutionCode":{"type":"string"},"institutionName":{"type":"string"},"accountType":{"type":"string","enum":["individual","corporate"]}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The RecipientDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RecipientDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"label":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isTrusted":{"type":"boolean","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"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","type","label","isDefault","isTrusted","details","createdAt","updatedAt"]},"CryptoRecipientDetailsResponseDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]},"BankRecipientDetailsResponseDto":{"type":"object","properties":{"accountName":{"type":"string"},"accountNumber":{"type":"string","description":"Masked account number."},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountType":{"type":"string","enum":["savings","current"]},"currency":{"type":"string"}},"required":["accountName","accountNumber","bankName","bankCode","currency"]},"MobileMoneyRecipientDetailsResponseDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient is paid in."},"countryIsoCode":{"type":"string","description":"Recipient country code."},"accountNumber":{"type":"string","description":"Masked phone number."},"accountName":{"type":"string"},"institutionCode":{"type":"string"},"institutionName":{"type":"string"},"accountType":{"type":"string","enum":["individual","corporate"]}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The RecipientResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RecipientResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/RecipientDto"}},"required":["success","message","data"]},"RecipientDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"label":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isTrusted":{"type":"boolean","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"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","type","label","isDefault","isTrusted","details","createdAt","updatedAt"]},"CryptoRecipientDetailsResponseDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]},"BankRecipientDetailsResponseDto":{"type":"object","properties":{"accountName":{"type":"string"},"accountNumber":{"type":"string","description":"Masked account number."},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountType":{"type":"string","enum":["savings","current"]},"currency":{"type":"string"}},"required":["accountName","accountNumber","bankName","bankCode","currency"]},"MobileMoneyRecipientDetailsResponseDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient is paid in."},"countryIsoCode":{"type":"string","description":"Recipient country code."},"accountNumber":{"type":"string","description":"Masked phone number."},"accountName":{"type":"string"},"institutionCode":{"type":"string"},"institutionName":{"type":"string"},"accountType":{"type":"string","enum":["individual","corporate"]}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The RecipientListResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RecipientListResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"RecipientDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"label":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"isTrusted":{"type":"boolean","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"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","type","label","isDefault","isTrusted","details","createdAt","updatedAt"]},"CryptoRecipientDetailsResponseDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]},"BankRecipientDetailsResponseDto":{"type":"object","properties":{"accountName":{"type":"string"},"accountNumber":{"type":"string","description":"Masked account number."},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountType":{"type":"string","enum":["savings","current"]},"currency":{"type":"string"}},"required":["accountName","accountNumber","bankName","bankCode","currency"]},"MobileMoneyRecipientDetailsResponseDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient is paid in."},"countryIsoCode":{"type":"string","description":"Recipient country code."},"accountNumber":{"type":"string","description":"Masked phone number."},"accountName":{"type":"string"},"institutionCode":{"type":"string"},"institutionName":{"type":"string"},"accountType":{"type":"string","enum":["individual","corporate"]}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The ValidateResolvedResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ValidateResolvedResponseDto":{"type":"object","properties":{"valid":{"type":"boolean"},"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]}}}} ``` ## The CryptoRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"],"description":"Blockchain the address belongs to. Every asset on this chain uses this address."},"address":{"type":"string","description":"Destination wallet address."}},"required":["chain","address"]}}}} ``` ## The NGNBankRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"NGNBankRecipientDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Bank account number."},"bankCode":{"type":"string","description":"Bank code from the supported bank list."},"accountType":{"type":"string","enum":["savings","current"],"description":"Account type."}},"required":["accountNumber","bankCode"]}}}} ``` ## The MobileMoneyRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"MobileMoneyRecipientDetailsDto":{"type":"object","properties":{"phoneNumber":{"type":"string","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","description":"Full name the mobile money account is registered under."},"institutionCode":{"type":"string","enum":["MPESA","MTN"],"description":"Mobile money provider. MPESA pays Kenyan recipients; MTN pays Ghanaian recipients."},"accountType":{"type":"string","enum":["individual","corporate"],"description":"Whether the recipient is a person or a business. Defaults to individual."}},"required":["phoneNumber","accountName","institutionCode"]}}}} ``` ## The CreateRecipientDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"],"description":"Recipient type. Determines the shape of details."},"label":{"type":"string","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"]},"CryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"],"description":"Blockchain the address belongs to. Every asset on this chain uses this address."},"address":{"type":"string","description":"Destination wallet address."}},"required":["chain","address"]},"NGNBankRecipientDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Bank account number."},"bankCode":{"type":"string","description":"Bank code from the supported bank list."},"accountType":{"type":"string","enum":["savings","current"],"description":"Account type."}},"required":["accountNumber","bankCode"]},"MobileMoneyRecipientDetailsDto":{"type":"object","properties":{"phoneNumber":{"type":"string","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","description":"Full name the mobile money account is registered under."},"institutionCode":{"type":"string","enum":["MPESA","MTN"],"description":"Mobile money provider. MPESA pays Kenyan recipients; MTN pays Ghanaian recipients."},"accountType":{"type":"string","enum":["individual","corporate"],"description":"Whether the recipient is a person or a business. Defaults to individual."}},"required":["phoneNumber","accountName","institutionCode"]}}}} ``` ## The ValidateCryptoDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ValidateCryptoDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]}}}} ``` ## The ValidateBankDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ValidateBankDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string"},"bankCode":{"type":"string"}},"required":["accountNumber","bankCode"]}}}} ``` ## The ValidateRecipientDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ValidateRecipientDto":{"type":"object","properties":{"type":{"type":"string","enum":["crypto_address","ngn_bank_account","kes_mobile_money","ghs_mobile_money"]},"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"]},"ValidateCryptoDetailsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["bsc","tron","solana","base","ethereum","polygon"]},"address":{"type":"string"}},"required":["chain","address"]},"ValidateBankDetailsDto":{"type":"object","properties":{"accountNumber":{"type":"string"},"bankCode":{"type":"string"}},"required":["accountNumber","bankCode"]},"MobileMoneyRecipientDetailsDto":{"type":"object","properties":{"phoneNumber":{"type":"string","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","description":"Full name the mobile money account is registered under."},"institutionCode":{"type":"string","enum":["MPESA","MTN"],"description":"Mobile money provider. MPESA pays Kenyan recipients; MTN pays Ghanaian recipients."},"accountType":{"type":"string","enum":["individual","corporate"],"description":"Whether the recipient is a person or a business. Defaults to individual."}},"required":["phoneNumber","accountName","institutionCode"]}}}} ``` ## The KoraPayBankDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"KoraPayBankDto":{"type":"object","properties":{"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug"},"code":{"type":"string","description":"Bank code"},"nibss_bank_code":{"type":"string","description":"NIBSS 6-digit institution code for the bank"},"country":{"type":"string","description":"Country code"}},"required":["name","slug","code","country"]}}}} ``` ## The KoraPayBankListResponse object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"KoraPayBankListResponse":{"type":"object","properties":{"status":{"type":"boolean","description":"Request status"},"message":{"type":"string","description":"Response message"},"data":{"description":"List of banks","type":"array","items":{"$ref":"#/components/schemas/KoraPayBankDto"}}},"required":["status","message","data"]},"KoraPayBankDto":{"type":"object","properties":{"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug"},"code":{"type":"string","description":"Bank code"},"nibss_bank_code":{"type":"string","description":"NIBSS 6-digit institution code for the bank"},"country":{"type":"string","description":"Country code"}},"required":["name","slug","code","country"]}}}} ``` ## The BankListResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BankListResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"description":"Provider bank list payload.","allOf":[{"$ref":"#/components/schemas/KoraPayBankListResponse"}]}},"required":["success","message","data"]},"KoraPayBankListResponse":{"type":"object","properties":{"status":{"type":"boolean","description":"Request status"},"message":{"type":"string","description":"Response message"},"data":{"description":"List of banks","type":"array","items":{"$ref":"#/components/schemas/KoraPayBankDto"}}},"required":["status","message","data"]},"KoraPayBankDto":{"type":"object","properties":{"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug"},"code":{"type":"string","description":"Bank code"},"nibss_bank_code":{"type":"string","description":"NIBSS 6-digit institution code for the bank"},"country":{"type":"string","description":"Country code"}},"required":["name","slug","code","country"]}}}} ``` ## The SupportedPayoutChainsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SupportedPayoutChainsResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"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"}}}},"required":["success","message","data"]},"AssetInfoDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"networkId":{"type":"string","description":"Network ID"},"metadata":{"description":"Asset metadata","allOf":[{"$ref":"#/components/schemas/AssetMetadataDto"}]},"contract":{"description":"Contract information (for tokens)","allOf":[{"$ref":"#/components/schemas/AssetContractDto"}]}},"required":["asset","networkId","metadata"]},"AssetMetadataDto":{"type":"object","properties":{"name":{"type":"string","description":"Asset name"},"symbol":{"type":"string","description":"Asset symbol"},"decimals":{"type":"number","description":"Asset decimals"}},"required":["name","symbol","decimals"]},"AssetContractDto":{"type":"object","properties":{"address":{"type":"string","description":"Contract address"},"decimals":{"type":"number","description":"Contract decimals"}},"required":["address","decimals"]}}}} ``` ## The AssetMetadataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"AssetMetadataDto":{"type":"object","properties":{"name":{"type":"string","description":"Asset name"},"symbol":{"type":"string","description":"Asset symbol"},"decimals":{"type":"number","description":"Asset decimals"}},"required":["name","symbol","decimals"]}}}} ``` ## The AssetContractDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"AssetContractDto":{"type":"object","properties":{"address":{"type":"string","description":"Contract address"},"decimals":{"type":"number","description":"Contract decimals"}},"required":["address","decimals"]}}}} ``` ## The AssetInfoDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"AssetInfoDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset symbol"},"networkId":{"type":"string","description":"Network ID"},"metadata":{"description":"Asset metadata","allOf":[{"$ref":"#/components/schemas/AssetMetadataDto"}]},"contract":{"description":"Contract information (for tokens)","allOf":[{"$ref":"#/components/schemas/AssetContractDto"}]}},"required":["asset","networkId","metadata"]},"AssetMetadataDto":{"type":"object","properties":{"name":{"type":"string","description":"Asset name"},"symbol":{"type":"string","description":"Asset symbol"},"decimals":{"type":"number","description":"Asset decimals"}},"required":["name","symbol","decimals"]},"AssetContractDto":{"type":"object","properties":{"address":{"type":"string","description":"Contract address"},"decimals":{"type":"number","description":"Contract decimals"}},"required":["address","decimals"]}}}} ``` ## The CreateRefundDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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."}},"required":["refundAddress"]}}}} ``` ## The RefundResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` ## The RefundApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["success","message"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` ## The CreateInvoiceRefundDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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."}},"required":["refundAddress"]}}}} ``` ## The RefundsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The ConversionDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}}} ``` ## The PayoutCryptoRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]}}}} ``` ## The PayoutBankRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]}}}} ``` ## The PayoutCrossBorderRecipientDetailsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutRecipientDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutV2Dto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutV2ResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["success","message"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The CreatePayoutDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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."},"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"]},"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."},"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."},"recipientId":{"type":"string","description":"Payout receipient Id"},"narration":{"type":"string","description":"Optional narration/description for the payout"},"reference":{"type":"string","description":"Optional idempotency reference for your request. If omitted, we generate a reference for you."},"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."}},"required":["currency","recipientId"]}}}} ``` ## The CrossBorderQuoteDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CrossBorderQuoteDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives.","enum":["KES","GHS"]},"sourceCurrency":{"type":"string","description":"Stablecoin balance the payout is funded from and debited in.","enum":["USDT","USDC"]},"sourceAmount":{"type":"string","description":"Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it."}},"required":["currency","sourceCurrency","sourceAmount"]}}}} ``` ## The CrossBorderQuoteResponseDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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."},"conversion":{"description":"The FX applied: the funding stablecoin converted to the amount the recipient receives. sourceAmount x rate = targetAmount.","allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"fee":{"type":"string","description":"Flat fee, in conversion.fromCurrency."},"total":{"type":"string","description":"Total debited from the balance: conversion.sourceAmount plus fee, in conversion.fromCurrency."},"expiresAt":{"type":"string","description":"When this quote expires. After this time, request a new quote."}},"required":["id","conversion","fee","total","expiresAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}}} ``` ## The PayoutsV2ResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutsV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The RequestedAmountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RequestedAmountDto":{"type":"object","properties":{"amount":{"type":"string","description":"Requested payout amount"},"currency":{"type":"string","description":"Currency the merchant balance will be debited from"}},"required":["amount","currency"]}}}} ``` ## The CalculatePayoutFeesResponseDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CalculatePayoutFeesResponseDataDto":{"type":"object","properties":{"fiat":{"type":"object","description":"Fiat payout fees grouped by currency, then method. Covers every supported fiat payout rail.","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.","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.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}},"required":["fiat","crossBorder","crypto"]}}}} ``` ## The CalculatePayoutFeesApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CalculatePayoutFeesApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/CalculatePayoutFeesResponseDataDto"}]}},"required":["success","message"]},"CalculatePayoutFeesResponseDataDto":{"type":"object","properties":{"fiat":{"type":"object","description":"Fiat payout fees grouped by currency, then method. Covers every supported fiat payout rail.","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.","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.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}},"required":["fiat","crossBorder","crypto"]}}}} ``` ## The CreateDepositAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateDepositAccountDto":{"type":"object","properties":{"customerId":{"type":"string","description":"Existing customer to scope the account to. Omit to create the merchant parent account."},"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"}}}}}} ``` ## The CustomerDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The DepositAccountAddressDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]}}}} ``` ## The DepositAccountNgnVirtualAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The DepositAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"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"]},"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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The CreateDepositAccountApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateDepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/DepositAccountDto"}},"required":["success","message","data"]},"DepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"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"]},"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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The UpdateDepositAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]}},"required":["settlementCurrency"]}}}} ``` ## The DepositAccountApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/DepositAccountDto"}},"required":["success","message","data"]},"DepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"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"]},"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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The IssueDepositIdentityDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"IssueDepositIdentityDto":{"type":"object","properties":{"type":{"type":"string","description":"Which identity to issue","enum":["static_deposit_address","ngn_virtual_account"]},"chain":{"type":"string","description":"Blockchain. Required when type is static_deposit_address.","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"bvn":{"type":"string","description":"BVN of the account holder (11 digits). Required when type is ngn_virtual_account."},"currency":{"type":"string","description":"Currency for a virtual account.","enum":["NGN"]}},"required":["type"]}}}} ``` ## The ParentDepositAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ParentDepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"settlementCurrency":{"type":"string","description":"Always `default` on the merchant parent account.","enum":["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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The ParentDepositAccountApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ParentDepositAccountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ParentDepositAccountDto"}},"required":["success","message","data"]},"ParentDepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"settlementCurrency":{"type":"string","description":"Always `default` on the merchant parent account.","enum":["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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The DepositAccountListApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositAccountListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DepositAccountDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"DepositAccountDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"isParent":{"type":"boolean"},"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"]},"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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The DepositCryptoDetailDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositCryptoDetailDto":{"type":"object","properties":{"txHash":{"type":"string","nullable":true},"chain":{"type":"string","nullable":true},"asset":{"type":"string","nullable":true},"amount":{"type":"string","description":"Deposited amount in the source asset"},"fromAddress":{"type":"string","nullable":true},"toAddress":{"type":"string","nullable":true},"amlCheck":{"type":"string","description":"Aml result.","enum":["passed","pending","failed","under_review"]},"staticDepositAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountAddressDto"}]}},"required":["txHash","chain","asset","amount","fromAddress","toAddress","amlCheck","staticDepositAddress"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]}}}} ``` ## The DepositFiatPartyDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"bankCode":{"type":"string","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]}}}} ``` ## The DepositFiatDetailDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositFiatDetailDto":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"method":{"type":"string"},"payer":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"payee":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"ngnVirtualAccount":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}]}},"required":["reference","method","payer","payee","ngnVirtualAccount"]},"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"bankCode":{"type":"string","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The DepositDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto","fiat"]},"status":{"type":"string","enum":["pending","completed","failed"]},"amount":{"type":"string"},"currency":{"type":"string"},"fee":{"type":"string"},"netAmount":{"type":"string"},"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.","nullable":true},"balanceReference":{"type":"string","description":"Reference of the balance history entry this deposit credited. Null until the deposit is credited.","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"},"completedAt":{"type":"string","nullable":true}},"required":["id","type","status","amount","currency","fee","netAmount","depositAccountId","customer","crypto","fiat","createdAt","completedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositCryptoDetailDto":{"type":"object","properties":{"txHash":{"type":"string","nullable":true},"chain":{"type":"string","nullable":true},"asset":{"type":"string","nullable":true},"amount":{"type":"string","description":"Deposited amount in the source asset"},"fromAddress":{"type":"string","nullable":true},"toAddress":{"type":"string","nullable":true},"amlCheck":{"type":"string","description":"Aml result.","enum":["passed","pending","failed","under_review"]},"staticDepositAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountAddressDto"}]}},"required":["txHash","chain","asset","amount","fromAddress","toAddress","amlCheck","staticDepositAddress"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositFiatDetailDto":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"method":{"type":"string"},"payer":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"payee":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"ngnVirtualAccount":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}]}},"required":["reference","method","payer","payee","ngnVirtualAccount"]},"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"bankCode":{"type":"string","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The DepositListApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DepositDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"DepositDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto","fiat"]},"status":{"type":"string","enum":["pending","completed","failed"]},"amount":{"type":"string"},"currency":{"type":"string"},"fee":{"type":"string"},"netAmount":{"type":"string"},"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.","nullable":true},"balanceReference":{"type":"string","description":"Reference of the balance history entry this deposit credited. Null until the deposit is credited.","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"},"completedAt":{"type":"string","nullable":true}},"required":["id","type","status","amount","currency","fee","netAmount","depositAccountId","customer","crypto","fiat","createdAt","completedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositCryptoDetailDto":{"type":"object","properties":{"txHash":{"type":"string","nullable":true},"chain":{"type":"string","nullable":true},"asset":{"type":"string","nullable":true},"amount":{"type":"string","description":"Deposited amount in the source asset"},"fromAddress":{"type":"string","nullable":true},"toAddress":{"type":"string","nullable":true},"amlCheck":{"type":"string","description":"Aml result.","enum":["passed","pending","failed","under_review"]},"staticDepositAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountAddressDto"}]}},"required":["txHash","chain","asset","amount","fromAddress","toAddress","amlCheck","staticDepositAddress"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositFiatDetailDto":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"method":{"type":"string"},"payer":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"payee":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"ngnVirtualAccount":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}]}},"required":["reference","method","payer","payee","ngnVirtualAccount"]},"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"bankCode":{"type":"string","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The DepositApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"DepositApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/DepositDto"}},"required":["success","message","data"]},"DepositDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["crypto","fiat"]},"status":{"type":"string","enum":["pending","completed","failed"]},"amount":{"type":"string"},"currency":{"type":"string"},"fee":{"type":"string"},"netAmount":{"type":"string"},"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.","nullable":true},"balanceReference":{"type":"string","description":"Reference of the balance history entry this deposit credited. Null until the deposit is credited.","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"},"completedAt":{"type":"string","nullable":true}},"required":["id","type","status","amount","currency","fee","netAmount","depositAccountId","customer","crypto","fiat","createdAt","completedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"DepositCryptoDetailDto":{"type":"object","properties":{"txHash":{"type":"string","nullable":true},"chain":{"type":"string","nullable":true},"asset":{"type":"string","nullable":true},"amount":{"type":"string","description":"Deposited amount in the source asset"},"fromAddress":{"type":"string","nullable":true},"toAddress":{"type":"string","nullable":true},"amlCheck":{"type":"string","description":"Aml result.","enum":["passed","pending","failed","under_review"]},"staticDepositAddress":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountAddressDto"}]}},"required":["txHash","chain","asset","amount","fromAddress","toAddress","amlCheck","staticDepositAddress"]},"DepositAccountAddressDto":{"type":"object","properties":{"chain":{"type":"string"},"address":{"type":"string"},"createdAt":{"type":"string"}},"required":["chain","address","createdAt"]},"DepositFiatDetailDto":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"method":{"type":"string"},"payer":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"payee":{"$ref":"#/components/schemas/DepositFiatPartyDto"},"ngnVirtualAccount":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/DepositAccountNgnVirtualAccountDto"}]}},"required":["reference","method","payer","payee","ngnVirtualAccount"]},"DepositFiatPartyDto":{"type":"object","properties":{"accountName":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"bankCode":{"type":"string","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode"]},"DepositAccountNgnVirtualAccountDto":{"type":"object","properties":{"currency":{"type":"string"},"accountNumber":{"type":"string"},"accountName":{"type":"string"},"bankName":{"type":"string"},"bankCode":{"type":"string"},"accountReference":{"type":"string"},"createdAt":{"type":"string"}},"required":["currency","accountNumber","accountName","bankName","bankCode","accountReference","createdAt"]}}}} ``` ## The CreateCustomerRequestDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateCustomerRequestDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"}}}}}} ``` ## The CustomerResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CustomerResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Customer data","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]}},"required":["success","message"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The UpdateCustomerDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"UpdateCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"}}}}}} ``` ## The CustomersResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CustomersResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The CreateInvoiceItemDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateInvoiceItemDto":{"type":"object","properties":{"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description"},"unit":{"type":"string","description":"Unit of measure label"},"quantity":{"type":"string","description":"Quantity, as a numeric string with up to 8 decimal places"},"unitPrice":{"type":"string","description":"Price per unit, as a numeric string with up to 12 decimal places"}},"required":["name","quantity","unitPrice"]}}}} ``` ## The CreateInvoiceCustomerDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateInvoiceCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email","firstName"]}}}} ``` ## The CreateInvoiceDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateInvoiceDto":{"type":"object","properties":{"reference":{"type":"string","description":"Custom invoice reference. If not provided, auto-generated."},"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"]},"description":{"type":"string","description":"Invoice description shown to the customer"},"expiresAt":{"type":"string","description":"Invoice expiry date in ISO 8601 format. Defaults to 1 day from creation, up to a maximum of 5 days."},"periodStart":{"type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"metadata":{"type":"object","description":"custom metadata"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice"},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice"},"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."},"asset":{"type":"string","description":"Cryptocurrency asset"},"chain":{"type":"string","description":"Blockchain network"},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CreateInvoiceCustomerDto"}]}},"required":["items","currency","description","expiresAt","customer"]},"CreateInvoiceItemDto":{"type":"object","properties":{"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description"},"unit":{"type":"string","description":"Unit of measure label"},"quantity":{"type":"string","description":"Quantity, as a numeric string with up to 8 decimal places"},"unitPrice":{"type":"string","description":"Price per unit, as a numeric string with up to 12 decimal places"}},"required":["name","quantity","unitPrice"]},"CreateInvoiceCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email","firstName"]}}}} ``` ## The InvoiceItemResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]}}}} ``` ## The MerchantInfoDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]}}}} ``` ## The InvoiceResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The InvoiceApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/InvoiceResponseDto"}]}},"required":["success","message"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The InvoicesResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoicesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The BuildX402RequirementsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"BuildX402RequirementsDto":{"type":"object","properties":{"chain":{"type":"string","enum":["base","arbitrum","bsc","solana"]},"asset":{"type":"string","enum":["USDC","USDT"],"description":"Friendly symbol; resolved to the contract/mint"},"amount":{"type":"string","description":"Human units; converted to atomic maxAmountRequired"},"payTo":{"type":"string","description":"Destination address. Defaults to your deposit address for the chain when omitted."},"resource":{"type":"string","description":"The protected resource URL","maxLength":500},"description":{"type":"string","maxLength":255},"mimeType":{"type":"string","maxLength":255},"maxTimeoutSeconds":{"type":"number"}},"required":["chain","asset","amount"]}}}} ``` ## The X402RequirementsAcceptDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402RequirementsAcceptDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string"},"extra":{"type":"object"}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","payTo","maxTimeoutSeconds","asset","extra"]}}}} ``` ## The X402RequirementsResult object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402RequirementsResult":{"type":"object","properties":{"x402Version":{"type":"number"},"chain":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402RequirementsAcceptDto"}}},"required":["x402Version","chain","asset","amount","accepts"]},"X402RequirementsAcceptDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string"},"extra":{"type":"object"}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","payTo","maxTimeoutSeconds","asset","extra"]}}}} ``` ## The X402RequirementsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402RequirementsResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402RequirementsResult"}},"required":["success","message","data"]},"X402RequirementsResult":{"type":"object","properties":{"x402Version":{"type":"number"},"chain":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402RequirementsAcceptDto"}}},"required":["x402Version","chain","asset","amount","accepts"]},"X402RequirementsAcceptDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string"},"extra":{"type":"object"}},"required":["scheme","network","maxAmountRequired","resource","description","mimeType","payTo","maxTimeoutSeconds","asset","extra"]}}}} ``` ## The X402AuthorizationDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"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"]}}}} ``` ## The X402PaymentPayloadInnerDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"}}},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"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"]}}}} ``` ## The X402PaymentPayloadDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402PaymentPayloadDto":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string","description":"CAIP-2 network id"},"payload":{"$ref":"#/components/schemas/X402PaymentPayloadInnerDto"}},"required":["x402Version","scheme","network","payload"]},"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"}}},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"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"]}}}} ``` ## The X402PaymentRequirementsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402PaymentRequirementsDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string","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","description":"Destination address"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string","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"]}}}} ``` ## The X402FacilitatorRequestDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402FacilitatorRequestDto":{"type":"object","properties":{"x402Version":{"type":"number"},"paymentPayload":{"$ref":"#/components/schemas/X402PaymentPayloadDto"},"paymentRequirements":{"$ref":"#/components/schemas/X402PaymentRequirementsDto"}},"required":["x402Version","paymentPayload","paymentRequirements"]},"X402PaymentPayloadDto":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string","description":"CAIP-2 network id"},"payload":{"$ref":"#/components/schemas/X402PaymentPayloadInnerDto"}},"required":["x402Version","scheme","network","payload"]},"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"}}},"X402AuthorizationDto":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string","description":"Atomic units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"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"]},"X402PaymentRequirementsDto":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"maxAmountRequired":{"type":"string","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","description":"Destination address"},"maxTimeoutSeconds":{"type":"number"},"asset":{"type":"string","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"]}}}} ``` ## The X402VerifyResult object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402VerifyResult":{"type":"object","properties":{"isValid":{"type":"boolean"},"invalidReason":{"type":"string","nullable":true},"payer":{"type":"string","nullable":true},"chain":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"amount":{"type":"string"},"checks":{"type":"object"}},"required":["isValid","invalidReason","payer","chain","asset","payTo","amount","checks"]}}}} ``` ## The X402VerifyResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402VerifyResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402VerifyResult"}},"required":["success","message","data"]},"X402VerifyResult":{"type":"object","properties":{"isValid":{"type":"boolean"},"invalidReason":{"type":"string","nullable":true},"payer":{"type":"string","nullable":true},"chain":{"type":"string"},"asset":{"type":"string"},"payTo":{"type":"string"},"amount":{"type":"string"},"checks":{"type":"object"}},"required":["isValid","invalidReason","payer","chain","asset","payTo","amount","checks"]}}}} ``` ## The X402TransactionDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]}}}} ``` ## The X402SettleResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402SettleResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]}}}} ``` ## The X402SupportedKind object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402SupportedKind":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string"},"chain":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"extra":{"type":"object"}},"required":["x402Version","scheme","network","chain","assets"]}}}} ``` ## The X402SupportedResult object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402SupportedResult":{"type":"object","properties":{"kinds":{"type":"array","items":{"$ref":"#/components/schemas/X402SupportedKind"}}},"required":["kinds"]},"X402SupportedKind":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string"},"chain":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"extra":{"type":"object"}},"required":["x402Version","scheme","network","chain","assets"]}}}} ``` ## The X402SupportedResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402SupportedResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402SupportedResult"}},"required":["success","message","data"]},"X402SupportedResult":{"type":"object","properties":{"kinds":{"type":"array","items":{"$ref":"#/components/schemas/X402SupportedKind"}}},"required":["kinds"]},"X402SupportedKind":{"type":"object","properties":{"x402Version":{"type":"number"},"scheme":{"type":"string"},"network":{"type":"string"},"chain":{"type":"string"},"assets":{"type":"array","items":{"type":"string"}},"extra":{"type":"object"}},"required":["x402Version","scheme","network","chain","assets"]}}}} ``` ## The X402TransactionsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402TransactionsResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/X402TransactionDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","message","data","meta"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The X402TransactionResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"X402TransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/X402TransactionDto"}},"required":["success","message","data"]},"X402TransactionDto":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"amlCheck":{"type":"string","enum":["passed","pending","failed"]},"errorReason":{"type":"string","nullable":true},"network":{"type":"string","description":"CAIP-2 network id"},"chain":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string","nullable":true,"description":"The protected resource the agent paid to access"},"description":{"type":"string","nullable":true,"description":"Human description of the paid resource"},"payer":{"type":"string","description":"Paying agent wallet"},"payTo":{"type":"string","description":"Destination address"},"amount":{"type":"string"},"fee":{"type":"string","description":"CoinCircuit facilitator fee charged for this settlement"},"blockNumber":{"type":"number","nullable":true},"explorerUrl":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","txHash","status","amlCheck","errorReason","network","chain","asset","resource","description","payer","payTo","amount","fee","blockNumber","explorerUrl","createdAt"]}}}} ``` ## The CreateCustomerNestedDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateCustomerNestedDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email (used if customer record is created)"},"firstName":{"type":"string","description":"Customer first name (used if customer record is created)"},"lastName":{"type":"string","description":"Customer last name (used if customer record is created)"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email"]}}}} ``` ## The CreateCheckoutSessionDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreateCheckoutSessionDto":{"type":"object","properties":{"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"amount":{"type":"string","description":"Amount in fiat currency (e.g. 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"},"customer":{"description":"Customer details","allOf":[{"$ref":"#/components/schemas/CreateCustomerNestedDto"}]},"cancelUrl":{"type":"string","description":"Redirect URL when the customer cancels the payment (must be HTTPS)"},"successUrl":{"type":"string","description":"Redirect URL on successful payment (must be HTTPS)"},"webhookUrl":{"type":"string","description":"URL to receive webhook notifications for this session (must be HTTPS)"},"feePaidBy":{"type":"string","enum":["customer","merchant"],"description":"Who pays gas/network fees for this session. If not specified, uses dashboard default settings"},"settlementCurrency":{"type":"string","enum":["NGN","USDT","USDC"],"description":"currency this payment settles into. Defaults to your account currency"}},"required":["title","description","amount","currency","customer"]},"CreateCustomerNestedDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email (used if customer record is created)"},"firstName":{"type":"string","description":"Customer first name (used if customer record is created)"},"lastName":{"type":"string","description":"Customer last name (used if customer record is created)"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email"]}}}} ``` ## The SettlementsCustomerPaidDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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.","nullable":true}},"required":["amount"]}}}} ``` ## The SettlementsGrossDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]}}}} ``` ## The SettlementsFeeDetailDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The SettlementsFeesDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The SettlementsNetDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]}}}} ``` ## The SettlementsDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]}}}} ``` ## The PaymentResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}}}}} ``` ## The CheckoutSessionV2Dto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CheckoutSessionV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true}},"required":["id","reference","state","type","amount","currency","settlements","createdAt","expiresAt"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The PaymentSessionV2ResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentSessionV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Payment session data (V2)","allOf":[{"$ref":"#/components/schemas/CheckoutSessionV2Dto"}]}},"required":["success","message"]},"CheckoutSessionV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true}},"required":["id","reference","state","type","amount","currency","settlements","createdAt","expiresAt"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}}} ``` ## The GenerateDepositAddressDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]},"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"]},"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"}]}}},"CreateCustomerNestedDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email (used if customer record is created)"},"firstName":{"type":"string","description":"Customer first name (used if customer record is created)"},"lastName":{"type":"string","description":"Customer last name (used if customer record is created)"},"phone":{"type":"string","description":"Customer phone number in international format (E.164)"},"telegramId":{"type":"string","description":"Customer Telegram ID"}},"required":["email"]}}}} ``` ## The PaymentSessionsV2ResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentSessionsV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"CheckoutSessionV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true}},"required":["id","reference","state","type","amount","currency","settlements","createdAt","expiresAt"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The GrossAmountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"GrossAmountDto":{"type":"object","properties":{"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"]},"amount":{"type":"string","description":"Fiat amount"},"conversionRate":{"type":"string","description":"Conversion rate used to convert from this requested currency to gross currency. Always present (1.0 when no conversion occurred)"}},"required":["currency","amount","conversionRate"]}}}} ``` ## The FiatAmountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"FiatAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]}}}} ``` ## The CryptoAmountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CryptoAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"chain":{"type":"string"}},"required":["amount","asset","chain"]}}}} ``` ## The FeeDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"FeeDto":{"type":"object","properties":{"networkFee":{"type":"string"},"paidBy":{"type":"string"}},"required":["networkFee","paidBy"]}}}} ``` ## The CalculateCheckoutAmountResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CalculateCheckoutAmountResponseDto":{"type":"object","properties":{"fiat":{"$ref":"#/components/schemas/FiatAmountDto"},"crypto":{"$ref":"#/components/schemas/CryptoAmountDto"},"fees":{"$ref":"#/components/schemas/FeeDto"},"conversionRate":{"type":"string"}},"required":["fiat","crypto","fees","conversionRate"]},"FiatAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]},"CryptoAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"chain":{"type":"string"}},"required":["amount","asset","chain"]},"FeeDto":{"type":"object","properties":{"networkFee":{"type":"string"},"paidBy":{"type":"string"}},"required":["networkFee","paidBy"]}}}} ``` ## The CalculateCheckoutAmountApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CalculateCheckoutAmountApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/CalculateCheckoutAmountResponseDto"}]}},"required":["success","message"]},"CalculateCheckoutAmountResponseDto":{"type":"object","properties":{"fiat":{"$ref":"#/components/schemas/FiatAmountDto"},"crypto":{"$ref":"#/components/schemas/CryptoAmountDto"},"fees":{"$ref":"#/components/schemas/FeeDto"},"conversionRate":{"type":"string"}},"required":["fiat","crypto","fees","conversionRate"]},"FiatAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string"}},"required":["amount","currency"]},"CryptoAmountDto":{"type":"object","properties":{"amount":{"type":"string"},"asset":{"type":"string"},"chain":{"type":"string"}},"required":["amount","asset","chain"]},"FeeDto":{"type":"object","properties":{"networkFee":{"type":"string"},"paidBy":{"type":"string"}},"required":["networkFee","paidBy"]}}}} ``` ## The CreatePaymentPageProductDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreatePaymentPageProductDto":{"type":"object","properties":{"title":{"type":"string","description":"Title of the product","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the product"},"price":{"type":"number","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active","default":true},"sortOrder":{"type":"number","description":"Sort order for display","default":0},"id":{"type":"string","description":"Optional ID for updates"}},"required":["title","price","isActive","sortOrder"]}}}} ``` ## The CreatePaymentPageDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"CreatePaymentPageDto":{"type":"object","properties":{"title":{"type":"string","description":"Title for the payment page","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the payment page"},"isActive":{"type":"boolean","description":"Whether the payment page is active","default":true},"minAmount":{"type":"number","description":"Minimum amount for payments"},"currency":{"type":"string","description":"Fiat currency for this payment page","enum":["NGN","USD"]},"bankAccountIds":{"description":"Array of bank account IDs to associate with this payment page","type":"array","items":{"type":"string"}},"products":{"description":"Products for this payment page","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"]},"CreatePaymentPageProductDto":{"type":"object","properties":{"title":{"type":"string","description":"Title of the product","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the product"},"price":{"type":"number","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active","default":true},"sortOrder":{"type":"number","description":"Sort order for display","default":0},"id":{"type":"string","description":"Optional ID for updates"}},"required":["title","price","isActive","sortOrder"]}}}} ``` ## The MerchantBankAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Account number (last 4 digits)"},"bankName":{"type":"string","description":"Bank name"},"bankCode":{"type":"string","description":"Bank code (CBN identifier)"},"accountType":{"type":"string","description":"Account type"},"currency":{"type":"string","description":"Currency"},"nickName":{"type":"string","description":"Account nickname"},"default":{"type":"boolean","description":"Is default account"},"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."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["isTemporary","id","accountName","accountNumber","bankName","bankCode","accountType","currency","nickName","default","isTrusted","createdAt","updatedAt"]}}}} ``` ## The PaymentPageProductDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the product"},"title":{"type":"string","description":"Title of the product"},"description":{"type":"string","description":"Description of the product"},"price":{"type":"string","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active"},"sortOrder":{"type":"number","description":"Sort order for display"},"imageUrl":{"type":"string","description":"Image for this product"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the product was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was last updated"}},"required":["id","title","price","isActive","sortOrder","createdAt","updatedAt"]}}}} ``` ## The PaymentPageDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentPageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the payment page"},"reference":{"type":"string","description":"Reference for the payment page"},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"title":{"type":"string","description":"Payment page title"},"description":{"type":"string","description":"Payment page description"},"isActive":{"type":"boolean","description":"Whether the payment page is active"},"currency":{"type":"string","description":"Currency for the payment page","enum":["NGN","USD"]},"minAmount":{"type":"string","description":"Minimum amount"},"enableQuantity":{"type":"boolean","description":"Whether quantity selector is enabled for this payment page"},"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"},"url":{"type":"string","description":"Public URL to access this payment page"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was last updated"}},"required":["id","reference","merchant","url","createdAt","updatedAt"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"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"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Account number (last 4 digits)"},"bankName":{"type":"string","description":"Bank name"},"bankCode":{"type":"string","description":"Bank code (CBN identifier)"},"accountType":{"type":"string","description":"Account type"},"currency":{"type":"string","description":"Currency"},"nickName":{"type":"string","description":"Account nickname"},"default":{"type":"boolean","description":"Is default account"},"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."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"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"},"title":{"type":"string","description":"Title of the product"},"description":{"type":"string","description":"Description of the product"},"price":{"type":"string","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active"},"sortOrder":{"type":"number","description":"Sort order for display"},"imageUrl":{"type":"string","description":"Image for this product"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the product was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was last updated"}},"required":["id","title","price","isActive","sortOrder","createdAt","updatedAt"]}}}} ``` ## The PaymentPageResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentPageResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Payment page data","allOf":[{"$ref":"#/components/schemas/PaymentPageDto"}]}},"required":["success","message"]},"PaymentPageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the payment page"},"reference":{"type":"string","description":"Reference for the payment page"},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"title":{"type":"string","description":"Payment page title"},"description":{"type":"string","description":"Payment page description"},"isActive":{"type":"boolean","description":"Whether the payment page is active"},"currency":{"type":"string","description":"Currency for the payment page","enum":["NGN","USD"]},"minAmount":{"type":"string","description":"Minimum amount"},"enableQuantity":{"type":"boolean","description":"Whether quantity selector is enabled for this payment page"},"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"},"url":{"type":"string","description":"Public URL to access this payment page"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was last updated"}},"required":["id","reference","merchant","url","createdAt","updatedAt"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"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"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Account number (last 4 digits)"},"bankName":{"type":"string","description":"Bank name"},"bankCode":{"type":"string","description":"Bank code (CBN identifier)"},"accountType":{"type":"string","description":"Account type"},"currency":{"type":"string","description":"Currency"},"nickName":{"type":"string","description":"Account nickname"},"default":{"type":"boolean","description":"Is default account"},"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."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"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"},"title":{"type":"string","description":"Title of the product"},"description":{"type":"string","description":"Description of the product"},"price":{"type":"string","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active"},"sortOrder":{"type":"number","description":"Sort order for display"},"imageUrl":{"type":"string","description":"Image for this product"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the product was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was last updated"}},"required":["id","title","price","isActive","sortOrder","createdAt","updatedAt"]}}}} ``` ## The PaymentPagesResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentPagesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"PaymentPageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the payment page"},"reference":{"type":"string","description":"Reference for the payment page"},"merchant":{"description":"Merchant information","allOf":[{"$ref":"#/components/schemas/MerchantInfoDto"}]},"title":{"type":"string","description":"Payment page title"},"description":{"type":"string","description":"Payment page description"},"isActive":{"type":"boolean","description":"Whether the payment page is active"},"currency":{"type":"string","description":"Currency for the payment page","enum":["NGN","USD"]},"minAmount":{"type":"string","description":"Minimum amount"},"enableQuantity":{"type":"boolean","description":"Whether quantity selector is enabled for this payment page"},"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"},"url":{"type":"string","description":"Public URL to access this payment page"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the static checkout was last updated"}},"required":["id","reference","merchant","url","createdAt","updatedAt"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"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"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Account number (last 4 digits)"},"bankName":{"type":"string","description":"Bank name"},"bankCode":{"type":"string","description":"Bank code (CBN identifier)"},"accountType":{"type":"string","description":"Account type"},"currency":{"type":"string","description":"Currency"},"nickName":{"type":"string","description":"Account nickname"},"default":{"type":"boolean","description":"Is default account"},"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."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"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"},"title":{"type":"string","description":"Title of the product"},"description":{"type":"string","description":"Description of the product"},"price":{"type":"string","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active"},"sortOrder":{"type":"number","description":"Sort order for display"},"imageUrl":{"type":"string","description":"Image for this product"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the product was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was last updated"}},"required":["id","title","price","isActive","sortOrder","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The PublicPaymentPageProductDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PublicPaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Product ID"},"title":{"type":"string","description":"Title of the product"},"price":{"type":"string","description":"Fixed price"},"description":{"type":"string","description":"Description of the product"},"sortOrder":{"type":"number","description":"Sort order for displaying products"},"imageUrl":{"type":"string","description":"Image for this product"}},"required":["id","title","price","sortOrder"]}}}} ``` ## The PublicBankAccountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PublicBankAccountDto":{"type":"object","properties":{"id":{"type":"string","description":"Bank account ID"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Masked account number, only last 4 digits shown"},"bankName":{"type":"string","description":"Bank name"}},"required":["id","accountName","accountNumber","bankName"]}}}} ``` ## The PublicPaymentPageDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"},"url":{"type":"string","description":"Public URL to access this payment page"}},"required":["merchant","url"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"PublicPaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Product ID"},"title":{"type":"string","description":"Title of the product"},"price":{"type":"string","description":"Fixed price"},"description":{"type":"string","description":"Description of the product"},"sortOrder":{"type":"number","description":"Sort order for displaying products"},"imageUrl":{"type":"string","description":"Image for this product"}},"required":["id","title","price","sortOrder"]},"PublicBankAccountDto":{"type":"object","properties":{"id":{"type":"string","description":"Bank account ID"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Masked account number, only last 4 digits shown"},"bankName":{"type":"string","description":"Bank name"}},"required":["id","accountName","accountNumber","bankName"]}}}} ``` ## The PublicPaymentPageResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PublicPaymentPageResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Payment page data","allOf":[{"$ref":"#/components/schemas/PublicPaymentPageDto"}]}},"required":["success","message"]},"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"},"url":{"type":"string","description":"Public URL to access this payment page"}},"required":["merchant","url"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"PublicPaymentPageProductDto":{"type":"object","properties":{"id":{"type":"string","description":"Product ID"},"title":{"type":"string","description":"Title of the product"},"price":{"type":"string","description":"Fixed price"},"description":{"type":"string","description":"Description of the product"},"sortOrder":{"type":"number","description":"Sort order for displaying products"},"imageUrl":{"type":"string","description":"Image for this product"}},"required":["id","title","price","sortOrder"]},"PublicBankAccountDto":{"type":"object","properties":{"id":{"type":"string","description":"Bank account ID"},"accountName":{"type":"string","description":"Account holder name"},"accountNumber":{"type":"string","description":"Masked account number, only last 4 digits shown"},"bankName":{"type":"string","description":"Bank name"}},"required":["id","accountName","accountNumber","bankName"]}}}} ``` ## The UpdatePaymentPageDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"UpdatePaymentPageDto":{"type":"object","properties":{"title":{"type":"string","description":"Title for the payment page","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the payment page"},"isActive":{"type":"boolean","description":"Whether the payment page is active","default":true},"minAmount":{"type":"number","description":"Minimum amount for payments"},"currency":{"type":"string","description":"Fiat currency for this payment page","enum":["NGN","USD"]},"bankAccountIds":{"description":"Array of bank account IDs to associate with this payment page","type":"array","items":{"type":"string"}},"products":{"description":"Products for this payment page","type":"array","items":{"$ref":"#/components/schemas/CreatePaymentPageProductDto"}},"enableQuantity":{"type":"boolean","description":"Enable quantity selector (e.g. nights, units). Only valid when products are defined."}}},"CreatePaymentPageProductDto":{"type":"object","properties":{"title":{"type":"string","description":"Title of the product","minLength":1,"maxLength":50},"description":{"type":"string","description":"Description of the product"},"price":{"type":"number","description":"Fixed price for this product"},"isActive":{"type":"boolean","description":"Whether this product is active","default":true},"sortOrder":{"type":"number","description":"Sort order for display","default":0},"id":{"type":"string","description":"Optional ID for updates"}},"required":["title","price","isActive","sortOrder"]}}}} ``` ## The TransactionDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The TransactionsResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"TransactionsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The TransactionResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"TransactionResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Transaction data","allOf":[{"$ref":"#/components/schemas/TransactionDto"}]}},"required":["success","message"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The SettlementAmountDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementAmountDto":{"type":"object","properties":{"amount":{"type":"string"}},"required":["amount"]}}}} ``` ## The FeeDetailDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string"},"paidBy":{"type":"string","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The FeesDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"FeesDto":{"type":"object","properties":{"processing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]},"gas":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]}}},"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string"},"paidBy":{"type":"string","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The SettlementResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementResponseDto":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed","cancelled"]},"entity":{"type":"string","enum":["session","invoice"]},"reference":{"type":"string"},"balanceReference":{"type":"string","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"]},"RequestedAmountDto":{"type":"object","properties":{"amount":{"type":"string","description":"Requested payout amount"},"currency":{"type":"string","description":"Currency the merchant balance will be debited from"}},"required":["amount","currency"]},"GrossAmountDto":{"type":"object","properties":{"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"]},"amount":{"type":"string","description":"Fiat amount"},"conversionRate":{"type":"string","description":"Conversion rate used to convert from this requested currency to gross currency. Always present (1.0 when no conversion occurred)"}},"required":["currency","amount","conversionRate"]},"SettlementAmountDto":{"type":"object","properties":{"amount":{"type":"string"}},"required":["amount"]},"FeesDto":{"type":"object","properties":{"processing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]},"gas":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]}}},"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string"},"paidBy":{"type":"string","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The SettlementListApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementListApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"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"]},"SettlementResponseDto":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed","cancelled"]},"entity":{"type":"string","enum":["session","invoice"]},"reference":{"type":"string"},"balanceReference":{"type":"string","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"]},"RequestedAmountDto":{"type":"object","properties":{"amount":{"type":"string","description":"Requested payout amount"},"currency":{"type":"string","description":"Currency the merchant balance will be debited from"}},"required":["amount","currency"]},"GrossAmountDto":{"type":"object","properties":{"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"]},"amount":{"type":"string","description":"Fiat amount"},"conversionRate":{"type":"string","description":"Conversion rate used to convert from this requested currency to gross currency. Always present (1.0 when no conversion occurred)"}},"required":["currency","amount","conversionRate"]},"SettlementAmountDto":{"type":"object","properties":{"amount":{"type":"string"}},"required":["amount"]},"FeesDto":{"type":"object","properties":{"processing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]},"gas":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]}}},"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string"},"paidBy":{"type":"string","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}}} ``` ## The SettlementApiResponseDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"SettlementApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Settlement data","allOf":[{"$ref":"#/components/schemas/SettlementResponseDto"}]}},"required":["success","message"]},"SettlementResponseDto":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed","cancelled"]},"entity":{"type":"string","enum":["session","invoice"]},"reference":{"type":"string"},"balanceReference":{"type":"string","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"]},"RequestedAmountDto":{"type":"object","properties":{"amount":{"type":"string","description":"Requested payout amount"},"currency":{"type":"string","description":"Currency the merchant balance will be debited from"}},"required":["amount","currency"]},"GrossAmountDto":{"type":"object","properties":{"currency":{"type":"string","description":"Fiat currency","enum":["NGN","USD"]},"amount":{"type":"string","description":"Fiat amount"},"conversionRate":{"type":"string","description":"Conversion rate used to convert from this requested currency to gross currency. Always present (1.0 when no conversion occurred)"}},"required":["currency","amount","conversionRate"]},"SettlementAmountDto":{"type":"object","properties":{"amount":{"type":"string"}},"required":["amount"]},"FeesDto":{"type":"object","properties":{"processing":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]},"gas":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/FeeDetailDto"}]}}},"FeeDetailDto":{"type":"object","properties":{"amount":{"type":"string"},"paidBy":{"type":"string","enum":["customer","merchant"]}},"required":["amount","paidBy"]}}}} ``` ## The PaymentWebhookDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The PaymentWebhookEnvelopeDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The PaymentCompletedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentCompletedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payment.completed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The PaymentPartialWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentPartialWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payment.partial"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The PaymentExpiredWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentExpiredWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payment.expired"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The PaymentUnderpaidWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PaymentUnderpaidWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payment.underpaid"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PaymentWebhookEnvelopeDto"}]}},"required":["event","data"]},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The TransactionWebhookDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The TransactionReceivedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"TransactionReceivedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["transaction.received"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/TransactionWebhookDataDto"}]}},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The TransactionConfirmedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"TransactionConfirmedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["transaction.confirmed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/TransactionWebhookDataDto"}]}},"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"]},"PaymentWebhookDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Payment session ID"},"reference":{"type":"string","description":"Unique reference for this session"},"title":{"type":"string","description":"Session title"},"description":{"type":"string","description":"Session description"},"state":{"type":"string","description":"Session state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"type":{"type":"string","description":"Session type","enum":["checkout","invoice"]},"amount":{"type":"string","description":"Requested amount (plain string in requested currency)"},"amountPaid":{"type":"string","description":"Actual fiat amount paid by the customer, excluding customer-paid gas fee where applicable","nullable":true},"currency":{"type":"string","description":"Requested currency","enum":["NGN","USD"]},"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"},"cancelUrl":{"type":"string","description":"Cancel URL"},"successUrl":{"type":"string","description":"Success URL"},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]},"metadata":{"type":"object","description":"Additional metadata object","nullable":true},"invoiceId":{"type":"string","description":"Associated invoice ID if this session was created from an invoice","nullable":true},"refundStatus":{"type":"string","description":"Refund status if a refund has been initiated","enum":["pending","processing","completed","failed"],"nullable":true},"isRefunded":{"type":"boolean","description":"Whether this session has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"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"]},"SettlementsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency this payment is settled into","enum":["NGN","USDT","USDC"]},"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"]},"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.","nullable":true}},"required":["amount"]},"SettlementsGrossDto":{"type":"object","properties":{"amount":{"type":"string","description":"Gross amount"},"conversionRate":{"type":"string","description":"Conversion rate from requested currency"}},"required":["amount","conversionRate"]},"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"}]}}},"SettlementsFeeDetailDto":{"type":"object","properties":{"amount":{"type":"string","description":"Fee amount","nullable":true},"paidBy":{"type":"string","description":"Who pays this fee","enum":["customer","merchant"]}},"required":["amount","paidBy"]},"SettlementsNetDto":{"type":"object","properties":{"amount":{"type":"string","description":"Net amount after all fees","nullable":true}},"required":["amount"]},"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","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","description":"Blockchain network","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo"]},"amount":{"type":"string","description":"Total amount required (including fees)"},"amountReceived":{"type":"string","description":"Amount received so far"},"address":{"type":"string","description":"Payment address where crypto should be sent"},"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.","nullable":true},"feePaidBy":{"type":"string","description":"Who pays the network/gas fee for this payment.","enum":["customer","merchant"]},"conversionRate":{"type":"string","description":"Conversion rate (fiat per crypto unit)"}}},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"TransactionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the transaction record"},"sessionId":{"type":"string","description":"Payment session ID this transaction belongs to"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","confirmed","failed"]},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Cryptocurrency asset symbol"},"fromAddress":{"type":"string","description":"Sender address"},"toAddress":{"type":"string","description":"Recipient wallet address (deposit address)"},"amount":{"type":"string","description":"Transaction amount"},"confirmations":{"type":"string","description":"Number of blockchain confirmations"},"amlCheck":{"type":"string","description":"AML check status","enum":["passed","pending","failed","under_review"]},"failureReason":{"type":"string","description":"Reason for transaction failure"},"explorerUrl":{"type":"string","description":"Blockchain explorer URL for this transaction"},"confirmedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction was confirmed"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the transaction record was last updated"}},"required":["id","sessionId","txHash","status","chain","asset","fromAddress","toAddress","amount","confirmations","createdAt","updatedAt"]}}}} ``` ## The InvoiceWebhookPaymentDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The InvoiceWebhookDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The InvoiceCreatedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["invoice.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The InvoiceUpdatedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceUpdatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["invoice.updated"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The InvoicePaidWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoicePaidWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["invoice.paid"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The InvoiceExpiredWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InvoiceExpiredWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["invoice.expired"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/InvoiceWebhookDataDto"}]}},"required":["event","data"]},"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"]},"InvoiceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invoice ID"},"reference":{"type":"string","description":"Invoice reference"},"description":{"type":"string","description":"Invoice description"},"status":{"type":"string","description":"Invoice payment status (pending, partial, paid)","enum":["pending","partial","paid","expired"]},"state":{"type":"string","description":"Invoice state: open (accepting payment) or closed (finalized)","enum":["open","closed"]},"isRefunded":{"type":"boolean","description":"Whether this invoice has been refunded"},"isUnderpaymentAccepted":{"type":"boolean","description":"Whether the merchant accepted this partial payment"},"amount":{"type":"string","description":"Invoice amount (computed as the sum of all item totals)"},"amountPaid":{"type":"string","description":"Amount paid so far"},"currency":{"type":"string","description":"Invoice currency","enum":["NGN","USD"]},"items":{"description":"Invoice items","type":"array","items":{"$ref":"#/components/schemas/InvoiceItemResponseDto"}},"asset":{"type":"string","description":"Cryptocurrency asset","nullable":true},"chain":{"type":"string","description":"Blockchain network","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"},"successUrl":{"type":"string","description":"Custom success redirect URL for invoice","nullable":true},"cancelUrl":{"type":"string","description":"Custom cancel redirect URL for invoice","nullable":true},"metadata":{"type":"object","description":"Invoice-level metadata","nullable":true},"periodStart":{"format":"date-time","type":"string","description":"Billing period start date (for subscription/recurring invoices)"},"periodEnd":{"format":"date-time","type":"string","description":"Billing period end date (for subscription/recurring invoices)"},"paidAt":{"format":"date-time","type":"string","description":"Invoice paid date (when status became paid)"},"expiresAt":{"format":"date-time","type":"string","description":"Invoice expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","reference","status","state","isRefunded","amount","amountPaid","currency","items","merchant","customer","url","createdAt"]},"InvoiceItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID"},"name":{"type":"string","description":"Item name"},"description":{"type":"string","description":"Item description","nullable":true},"unit":{"type":"string","description":"Unit of measure label","nullable":true},"quantity":{"type":"string","description":"Quantity"},"unitPrice":{"type":"string","description":"Price per unit"},"lineTotal":{"type":"string","description":"Line total (quantity x unit price)"}},"required":["id","name","quantity","unitPrice","lineTotal"]},"MerchantInfoDto":{"type":"object","properties":{"businessName":{"type":"string","description":"Merchant business name"},"logoUrl":{"type":"string","description":"Merchant logo URL"}},"required":["businessName"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"InvoiceWebhookPaymentDto":{"type":"object","properties":{"asset":{"type":"string","description":"Crypto asset used for payment","nullable":true},"chain":{"type":"string","description":"Blockchain network","nullable":true},"amount":{"type":"string","description":"Crypto amount paid for this payment session"},"address":{"type":"string","description":"Deposit address used","nullable":true},"txHash":{"type":"string","description":"Transaction hash","nullable":true},"explorerUrl":{"type":"string","description":"Block explorer URL","nullable":true},"status":{"type":"string","description":"Payment session status"}},"required":["amount","address","status"]}}}} ``` ## The PayoutWebhookDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutWebhookDataDto":{"type":"object","properties":{"payout":{"description":"Payout data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["payout"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutCreatedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payout.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"PayoutWebhookDataDto":{"type":"object","properties":{"payout":{"description":"Payout data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["payout"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutSuccessWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutSuccessWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payout.success"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"PayoutWebhookDataDto":{"type":"object","properties":{"payout":{"description":"Payout data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["payout"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The PayoutFailedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutFailedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["payout.failed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/PayoutWebhookDataDto"}]}},"required":["event","data"]},"PayoutWebhookDataDto":{"type":"object","properties":{"payout":{"description":"Payout data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["payout"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee charged"},"total":{"type":"string","description":"Total deducted from merchant balance (amount + fee)"},"currency":{"type":"string","description":"Balance currency"},"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.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"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"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}}} ``` ## The RefundWebhookDataDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundWebhookDataDto":{"type":"object","properties":{"refund":{"description":"Refund data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["refund"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` ## The RefundCreatedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundCreatedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["refund.created"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]},"RefundWebhookDataDto":{"type":"object","properties":{"refund":{"description":"Refund data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["refund"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` ## The RefundSuccessWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundSuccessWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["refund.success"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]},"RefundWebhookDataDto":{"type":"object","properties":{"refund":{"description":"Refund data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["refund"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` ## The RefundFailedWebhookDto object ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"RefundFailedWebhookDto":{"type":"object","properties":{"event":{"type":"string","description":"Webhook event type","enum":["refund.failed"]},"data":{"description":"Webhook event data","allOf":[{"$ref":"#/components/schemas/RefundWebhookDataDto"}]}},"required":["event","data"]},"RefundWebhookDataDto":{"type":"object","properties":{"refund":{"description":"Refund data","allOf":[{"$ref":"#/components/schemas/RefundResponseDto"}]}},"required":["refund"]},"RefundResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Refund ID"},"entity":{"type":"string","description":"Entity type - session or invoice","enum":["session","invoice"]},"reference":{"type":"string","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)"},"status":{"type":"string","description":"Refund status","enum":["pending","processing","completed","failed"]},"reason":{"type":"string","description":"Reason for refund"},"chain":{"type":"string","description":"Blockchain network"},"asset":{"type":"string","description":"Crypto asset"},"amount":{"type":"string","description":"Crypto amount customer receives"},"fee":{"type":"string","description":"Network fee (crypto)"},"feePaidBy":{"type":"string","description":"Who paid the fee","enum":["merchant","customer"]},"fiatAmount":{"type":"string","description":"Fiat value of the refund"},"fiatCurrency":{"type":"string","description":"Fiat currency"},"merchantDebitAmount":{"type":"string","description":"Fiat amount debited from merchant"},"balanceSource":{"type":"string","description":"Balance that funded this refund","enum":["settled","pending"]},"refundAddress":{"type":"string","description":"Customer wallet address receiving refund"},"txHash":{"type":"string","description":"Blockchain transaction hash"},"explorerUrl":{"type":"string","description":"Block explorer URL for the refund transaction"},"createdAt":{"format":"date-time","type":"string","description":"Refund creation timestamp"},"completedAt":{"format":"date-time","type":"string","description":"Refund completion timestamp"}},"required":["id","entity","reference","status","chain","asset","amount","fee","feePaidBy","fiatAmount","fiatCurrency","merchantDebitAmount","balanceSource","refundAddress","createdAt"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.coincircuit.io/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.