> 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","arbitrum","arc"]},"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","arbitrum","arc"]},"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","arbitrum","arc"]},"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","arbitrum","arc"]},"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","arbitrum","arc"],"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","arbitrum","arc"],"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","arbitrum","arc"]},"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","arbitrum","arc"]},"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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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. Stablecoin: USDT or USDC. Cross-border (KES, GHS) and native coins (ETH, BNB, POL, SOL) are funded from the stablecoin balance in sourceCurrency."},"sourceCurrency":{"type":"string","description":"Stablecoin balance to debit (USDT or USDC), for a cross-border or native coin payout, where the recipient is paid in a different currency. Omit for local fiat and stablecoin payouts, which debit the balance in `currency`.","enum":["USDT","USDC"]},"quoteId":{"type":"string","description":"The `id` of a quote from POST /payouts/quote, for a cross-border or native coin payout. 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 or native coin payout this is the amount the recipient receives, and it is not needed when `quoteId` is given: the quote already fixes it. A native coin amount takes up to 8 decimal places."},"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 PayoutQuoteDto object

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutQuoteDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives, e.g. KES or ETH.","enum":["KES","GHS","ETH","BNB","POL","SOL"]},"sourceCurrency":{"type":"string","description":"Stablecoin balance the payout is funded from and debited in.","enum":["USDT","USDC"]},"chain":{"type":"string","description":"Blockchain the recipient is paid on. Required when currency is a coin such as ETH.","enum":["bsc","tron","solana","base","ethereum","polygon","arbitrum","arc"]},"sourceAmount":{"type":"string","description":"Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it. Provide either sourceAmount or targetAmount, not both."},"targetAmount":{"type":"string","description":"Amount the recipient receives, in currency. Supported when currency is a coin such as ETH. Provide either sourceAmount or targetAmount, not both."}},"required":["currency","sourceCurrency"]}}}}
```

## The PayoutQuoteResponseDataDto object

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"PayoutQuoteResponseDataDto":{"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 exchange applied: the funding stablecoin converted to the amount the recipient receives. sourceAmount x rate = targetAmount. sourceAmount plus sourceFee is what the payout costs, in fromCurrency.","allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"fee":{"type":"string","description":"Fee, in conversion.toCurrency."},"total":{"type":"string","description":"conversion.targetAmount plus fee, in conversion.toCurrency."},"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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}}}
```

## 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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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","arc"]},"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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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","arc","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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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 InitiateExchangePaymentDto object

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"InitiateExchangePaymentDto":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["binance_pay_onchain"],"description":"Exchange pay product to pay with"}},"required":["paymentMethod"]}}}}
```

## The ExchangePaymentResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ExchangePaymentResponseDto":{"type":"object","properties":{"sessionReference":{"type":"string","description":"Reference of the session the link pays"},"paymentMethod":{"type":"string","enum":["binance_pay_onchain"]},"amount":{"type":"string","description":"Amount the link asks for. On a session this is what is still owed."},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]},"link":{"type":"string","description":"Link that opens the exchange app or website with the payment ready to confirm"},"expiresAt":{"type":"string","description":"When the link stops working"}},"required":["paymentMethod","amount","asset","chain","link","expiresAt"]}}}}
```

## The ExchangePaymentApiResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"components":{"schemas":{"ExchangePaymentApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/ExchangePaymentResponseDto"}},"required":["success","message","data"]},"ExchangePaymentResponseDto":{"type":"object","properties":{"sessionReference":{"type":"string","description":"Reference of the session the link pays"},"paymentMethod":{"type":"string","enum":["binance_pay_onchain"]},"amount":{"type":"string","description":"Amount the link asks for. On a session this is what is still owed."},"asset":{"type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]},"chain":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]},"link":{"type":"string","description":"Link that opens the exchange app or website with the payment ready to confirm"},"expiresAt":{"type":"string","description":"When the link stops working"}},"required":["paymentMethod","amount","asset","chain","link","expiresAt"]}}}}
```

## 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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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","arc"]},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","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."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"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"]}}}}
```
