# Introduction ## Introduction Welcome to **CoinCircuit**. CoinCircuit is a crypto payment gateway for: * Online payments * In-store payments * Payouts * Refunds {% hint style="info" %} **Need help?** Use the AI assistant in the bottom-right corner while you browse the docs. {% endhint %} ### Start here New to CoinCircuit? Begin with [Quick Start](/introduction/quick-start). ### Core guides * [Sandbox Environment](/introduction/official-sdks) * [Official SDKs](/introduction/webhooks) * [Authentication](/introduction/mcp-integration) * [Webhooks](/introduction/error-handling) ### API behavior * [Error Handling](/introduction/authentication) * [Rate Limiting](/introduction/rate-limiting) * [Pagination](/introduction/pagination) ### Developer tooling * [MCP Integration](/introduction/sandbox-environment) ### Testing resources * [Testnet Faucets](/introduction/testnet-faucets) # Quick Start ## Quick Start Use this guide to get your CoinCircuit integration running fast. ### What to do first 1. Create sandbox API keys. 2. Use the sandbox base URL. 3. Install an SDK or call the API directly. 4. Authenticate requests with `x-api-key`. 5. Configure webhooks. 6. Test with faucet funds. ### Start here * Use `https://sandbox-api.coincircuit.io` * Authenticate with the `x-api-key` header * Test before switching to production ### Next steps * Set up authentication * Install an SDK * Configure webhooks * Review error handling and rate limits # Sandbox Environment ## Sandbox Environment Use sandbox to test safely before you go live. ### Base URLs * **Production base URL:** `https://api.coincircuit.io` * **Sandbox base URL:** `https://sandbox-api.coincircuit.io` ### Key usage Use test keys with the sandbox base URL. Use live keys with the production base URL. # MCP Integration ## MCP Integration CoinCircuit provides a **Model Context Protocol (MCP)** server for AI-powered IDEs. Supported clients include: * Cursor * Windsurf * Claude Desktop ### Endpoint **MCP URL:** `https://mcp.coincircuit.io` ### Authentication Generate an MCP access key in **Developer → MCP Access Keys**. Then add it to your config: ```json { "mcpServers": { "coincircuit": { "url": "https://mcp.coincircuit.io", "headers": { "x-mcp-key": "YOUR_MCP_KEY" } } } } ``` The MCP server works without authentication for: * Documentation browsing * API schema discovery Authentication is only required when tools execute actions like creating payments or listing transactions. # Official SDKs ## Official SDKs Install the CoinCircuit SDK for your stack. ### Node.js / TypeScript ```bash npm install coincircuit ``` ### Python ```bash pip install coincircuit ``` ### Checkout SDK ```bash npm install @coincircuit/checkout ``` ### Package links * [npm](https://www.npmjs.com/package/coincircuit) * [PyPI](https://pypi.org/project/coincircuit/) * [Checkout SDK](https://www.npmjs.com/package/@coincircuit/checkout) # Authentication ## Authentication Authenticate every request with the `x-api-key` header. ```http x-api-key: your_api_key_here ``` # Webhooks ## Webhooks CoinCircuit sends webhook events as payments move through their lifecycle. Use the webhook reference for event payloads, delivery behavior, and integration details. # Error Handling ## Error Handling The API uses standard HTTP status codes. | HTTP status | Description | | ----------- | ---------------------------------- | | `400` | Invalid input or malformed request | | `401` | Invalid or missing authentication | | `404` | Resource not found | | `409` | Resource conflict | | `429` | Too many requests | | `503` | Service unavailable | ### Basic error example ```json { "success": false, "timestamp": "2026-01-23T23:33:55.685Z", "path": "/api/v1/payments", "method": "POST", "error": "Unauthorized", "message": "Unauthorized" } ``` # Rate Limiting ## Rate Limiting The API is limited to **20 requests per second**. Exceeding the limit returns `429 Too Many Requests`. # Pagination ## Pagination List endpoints support: * `page` — default `1` * `size` — default `10`, max `100` ### Response metadata example ```json "meta": { "page": 1, "size": 10, "total": 42, "totalPages": 5 } ``` # Testnet Faucets ## Testnet Faucets Use free testnet tokens to validate your sandbox integration. ### Tron Tron is the recommended network for testing. Install [TronLink](https://www.tronlink.org/), then request testnet `TRX` and `USDT` from the Nile faucet: * [Nile Testnet Faucet](https://nileex.io/join/getJoinPage) ### Ethereum Use Sepolia for Ethereum testing: * [Google Cloud Faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) ### Solana Use devnet for Solana testing: * [Solana Faucet](https://faucet.solana.com/) # Invoices Create and manage invoices ## List invoices > Returns all invoices. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/invoices":{"get":{"description":"Returns all invoices.","operationId":"InvoicesController_listInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by invoice reference","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by invoice status","schema":{"type":"string","enum":["pending","partial","paid","expired"]}},{"name":"state","required":false,"in":"query","description":"Filter by invoice state","schema":{"type":"string","enum":["open","closed"]}},{"name":"currency","required":false,"in":"query","description":"Filter by currency","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter invoices created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter invoices created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicesResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List invoices","tags":["Invoices"]}}}} ``` ## Create invoice > Creates an invoice for a product/service. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/invoices":{"post":{"description":"Creates an invoice for a product/service.","operationId":"InvoicesController_createInvoice","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"400":{"description":"Invalid input or expiration date exceeds 5 days"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"summary":"Create invoice","tags":["Invoices"]}}}} ``` ## Retrieve invoice by reference > Returns the invoice for the given reference. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Invoices","description":"Create and manage invoices"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/invoices/reference/{reference}":{"get":{"description":"Returns the invoice for the given reference.","operationId":"InvoicesController_getInvoice","parameters":[{"name":"reference","required":true,"in":"path","description":"Invoice reference","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceApiResponseDto"}}}},"404":{"description":"Invoice not found"}},"summary":"Retrieve invoice by reference","tags":["Invoices"]}}},"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"]}}}} ``` # Payments Create and manage payment sessions ## List payment sessions > Returns all Payment Sessions. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payments":{"get":{"description":"Returns all Payment Sessions.","operationId":"CheckoutSessionsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by session reference, payment/deposit address, or transaction hash.","schema":{"type":"string"}},{"name":"invoiceReference","required":false,"in":"query","description":"Filter by invoice reference","schema":{"type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by customer ID","schema":{"type":"string"}},{"name":"pageReference","required":false,"in":"query","description":"Filter by payment page reference","schema":{"type":"string"}},{"name":"state","required":false,"in":"query","description":"Filter by session state: open or closed","schema":{"type":"string","enum":["open","closed"]}},{"name":"paymentStatus","required":false,"in":"query","description":"Filter by payment status","schema":{"type":"string","enum":["pending","partial","expired","completed","failed","under_review"]}},{"name":"asset","required":false,"in":"query","description":"Filter by asset","schema":{"type":"string"}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain","schema":{"type":"string"}},{"name":"minAmount","required":false,"in":"query","description":"Minimum amount (in fiat)","schema":{"type":"number"}},{"name":"maxAmount","required":false,"in":"query","description":"Maximum amount (in fiat)","schema":{"type":"number"}},{"name":"includeTransactions","required":false,"in":"query","description":"Set to true to add transactions to each session.","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by session type","schema":{"type":"string","enum":["checkout","invoice"]}},{"name":"currency","required":false,"in":"query","description":"Filter by fiat currency","schema":{"type":"string","enum":["NGN","USD"]}},{"name":"isRefunded","required":false,"in":"query","description":"Filter by refund status. Pass true to return only refunded sessions.","schema":{"type":"boolean"}},{"name":"startDate","required":false,"in":"query","description":"Filter sessions created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter sessions created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionsV2ResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List payment sessions","tags":["Payments"]}}}} ``` ## Create payment session > Creates a new payment session (payment link) to receive payments. You can set the asset and chain together, set one now and the other later, or leave both unset. A deposit address is created immediately only when the session already has the asset, chain, and customer details. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payments":{"post":{"description":"Creates a new payment session (payment link) to receive payments. You can set the asset and chain together, set one now and the other later, or leave both unset. A deposit address is created immediately only when the session already has the asset, chain, and customer details.","operationId":"CheckoutSessionsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"400":{"description":"Invalid input or unsupported asset/blockchain combination"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"summary":"Create payment session","tags":["Payments"]}}}} ``` ## Generate deposit address > Generates a deposit address for the session. If the session already has an asset or chain assigned, those values cannot be overridden. Any missing asset or chain must be provided before the address can be created. If the session does not already have a customer, include customer details (email, and optionally firstName, lastName, phone). If the session already has a customer, the customer field is ignored. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/payments/{reference}/address":{"post":{"description":"Generates a deposit address for the session. If the session already has an asset or chain assigned, those values cannot be overridden. Any missing asset or chain must be provided before the address can be created. If the session does not already have a customer, include customer details (email, and optionally firstName, lastName, phone). If the session already has a customer, the customer field is ignored.","operationId":"CheckoutSessionsController_generateDepositAddress","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment session reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDepositAddressDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"400":{"description":"Invalid session state, missing required asset/chain context, or unsupported asset/blockchain"},"404":{"description":"Session not found"}},"summary":"Generate deposit address","tags":["Payments"]}}},"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"]},"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"]}}}} ``` ## Create exchange payment link > Returns a link to pay the session from an exchange wallet, e.g. Binance. Generate a deposit address first. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/payments/{reference}/pay-with-exchange":{"post":{"description":"Returns a link to pay the session from an exchange wallet, e.g. Binance. Generate a deposit address first.","operationId":"CheckoutSessionsController_initiateExchangePayment","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment session reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateExchangePaymentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangePaymentApiResponseDto"}}}},"400":{"description":"Session is not active or already paid, has no deposit address yet, or the amount is outside what the exchange accepts"},"403":{"description":"Exchange payments are turned off for this merchant"},"404":{"description":"Session not found"}},"summary":"Create exchange payment link","tags":["Payments"]}}},"components":{"schemas":{"InitiateExchangePaymentDto":{"type":"object","properties":{"paymentMethod":{"type":"string","enum":["binance_pay_onchain"],"description":"Exchange pay product to pay with"}},"required":["paymentMethod"]},"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"]}}}} ``` ## Retrieve payment session by reference > Returns the session for the given reference. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/payments/reference/{reference}":{"get":{"description":"Returns the session for the given reference.","operationId":"CheckoutSessionsController_findByReference","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment session reference","schema":{"type":"string"}},{"name":"includeTransactions","required":false,"in":"query","schema":{"type":"boolean"},"description":"When true, the response includes the transactions array."}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionV2ResponseDto"}}}},"404":{"description":"Session not found"}},"summary":"Retrieve payment session by reference","tags":["Payments"]}}},"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"]}}}} ``` ## Calculate crypto amount for session > Calculate the required crypto amount for a session based on selected asset and chain without locking the rate. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/payments/estimate":{"get":{"description":"Calculate the required crypto amount for a session based on selected asset and chain without locking the rate.","operationId":"CheckoutSessionsController_calculateAmount","parameters":[{"name":"amount","required":true,"in":"query","description":"Amount in fiat currency","schema":{"type":"string"}},{"name":"currency","required":true,"in":"query","description":"Fiat currency for the amount","schema":{"type":"string","enum":["NGN","USD"]}},{"name":"asset","required":true,"in":"query","description":"Crypto asset to pay with","schema":{"type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]}},{"name":"chain","required":true,"in":"query","description":"Blockchain network","schema":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]}},{"name":"feePaidBy","required":false,"in":"query","description":"Fee paid by: who pays the network fee (merchant or customer)","schema":{"type":"string","enum":["customer","merchant"]}},{"name":"settlementCurrency","required":false,"in":"query","description":"Settlement currency (optional)","schema":{"type":"string","enum":["NGN","USD","USDT","USDC"]}},{"name":"reference","required":false,"in":"query","description":"Session reference ","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateCheckoutAmountApiResponseDto"}}}},"400":{"description":"Invalid input or unsupported asset/blockchain"}},"summary":"Calculate crypto amount for session","tags":["Payments"]}}},"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"]}}}} ``` # X402 Accept x402 agent payments ## Build x402 payment requirements > Build the payment requirements to return to a paying agent. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/requirements":{"post":{"description":"Build the payment requirements to return to a paying agent.","operationId":"X402V2Controller_requirements","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildX402RequirementsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402RequirementsResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Build x402 payment requirements","tags":["x402"]}}},"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"]},"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"]}}}} ``` ## Verify an x402 payment > Validate a signed payment against its requirements without settling. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/verify":{"post":{"description":"Validate a signed payment against its requirements without settling.","operationId":"X402V2Controller_verify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402VerifyResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Verify an x402 payment","tags":["x402"]}}},"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"]},"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"]}}}} ``` ## Settle an x402 payment > Submit a signed payment on-chain and return the settlement receipt. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/settle":{"post":{"description":"Submit a signed payment on-chain and return the settlement receipt.","operationId":"X402V2Controller_settle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402FacilitatorRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SettleResponseDto"}}}},"400":{"description":"Invalid input"}},"summary":"Settle an x402 payment","tags":["x402"]}}},"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"]},"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"]}}}} ``` ## GET /api/v1/x402/supported > List supported x402 networks and assets ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/supported":{"get":{"operationId":"X402V2Controller_supported","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402SupportedResponseDto"}}}}},"summary":"List supported x402 networks and assets","tags":["x402"]}}},"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"]}}}} ``` ## List x402 transactions > List settled x402 payments for your account, newest first. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/transactions":{"get":{"description":"List settled x402 payments for your account, newest first.","operationId":"X402V2Controller_transactions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by transaction hash or address","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","confirmed"]}},{"name":"chain","required":false,"in":"query","schema":{"type":"string","enum":["base","arbitrum","bsc","arc","solana"]}},{"name":"asset","required":false,"in":"query","schema":{"type":"string","enum":["USDC","USDT"]}},{"name":"startDate","required":false,"in":"query","description":"Created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionsResponseDto"}}}}},"summary":"List x402 transactions","tags":["x402"]}}},"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"]}}}} ``` ## Get an x402 transaction > Fetch a settled x402 payment by transaction hash. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"x402","description":"Accept x402 agent payments"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/x402/transactions/{txHash}":{"get":{"description":"Fetch a settled x402 payment by transaction hash.","operationId":"X402V2Controller_transaction","parameters":[{"name":"txHash","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402TransactionResponseDto"}}}},"404":{"description":"Not found"}},"summary":"Get an x402 transaction","tags":["x402"]}}},"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"]}}}} ``` # Transactions View transaction history ## List transactions > Returns all Payment Sessions Blockchain transactions. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Transactions","description":"View transaction history"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/transactions":{"get":{"description":"Returns all Payment Sessions Blockchain transactions.","operationId":"TransactionsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by transaction hash or asset","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by transaction status","schema":{"type":"string","enum":["pending","confirmed","failed"]}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain","schema":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]}},{"name":"asset","required":false,"in":"query","description":"Filter by asset","schema":{"type":"string","enum":["BTC","ETH","USDT","USDC","SOL","BNB","TRX","POL","CELO","CNGN"]}},{"name":"sessionReference","required":false,"in":"query","description":"Filter by payment session reference","schema":{"type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by customer ID","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter transactions created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter transactions created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsResponseDto"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"summary":"List transactions","tags":["Transactions"]}}},"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"]}}}} ``` ## Retrieve transaction > Returns the transaction for the given hash. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Transactions","description":"View transaction history"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"paths":{"/api/v1/transactions/{txHash}":{"get":{"description":"Returns the transaction for the given hash.","operationId":"TransactionsController_findOne","parameters":[{"name":"txHash","required":true,"in":"path","description":"Transaction hash","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionResponseDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{}}}},"500":{"description":"Internal server error"}},"summary":"Retrieve transaction","tags":["Transactions"]}}},"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"]}}}} ``` # Deposits View inbound crypto and fiat deposits to deposit accounts ## List deposit accounts > Lists your deposit accounts. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits/accounts":{"get":{"description":"Lists your deposit accounts.","operationId":"DepositsController_listAccounts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by account status","schema":{"type":"string","enum":["active","inactive"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountListApiResponseDto"}}}}},"summary":"List deposit accounts","tags":["Deposits"]}}}} ``` ## Create a deposit account > Creates a deposit account. Omit customerId to create a parent account. A holder has one deposit account, so repeat calls return the existing account. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"}}},"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"]}}},"paths":{"/api/v1/deposits/accounts":{"post":{"description":"Creates a deposit account. Omit customerId to create a parent account. A holder has one deposit account, so repeat calls return the existing account.","operationId":"DepositsController_createAccount","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDepositAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDepositAccountApiResponseDto"}}}},"404":{"description":"Customer not found"}},"summary":"Create a deposit account","tags":["Deposits"]}}}} ``` ## Retrieve a deposit account > Retrieves a deposit account and its identities. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits/accounts/{id}":{"get":{"description":"Retrieves a deposit account and its identities.","operationId":"DepositsController_getAccountById","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"summary":"Retrieve a deposit account","tags":["Deposits"]}}}} ``` ## Update a deposit account > Changes the settlement currency of a customer-scoped deposit account. Deposits already in flight keep the currency they were credited in. The merchant parent account is always \`default\`. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/deposits/accounts/{id}":{"patch":{"description":"Changes the settlement currency of a customer-scoped deposit account. Deposits already in flight keep the currency they were credited in. The merchant parent account is always `default`.","operationId":"DepositsController_updateAccount","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDepositAccountDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"400":{"description":"The merchant parent account always settles as `default`"},"404":{"description":"Deposit account not found"}},"summary":"Update a deposit account","tags":["Deposits"]}}}} ``` ## Issue a deposit identity > Issues a pay-in identity into a deposit account: a static crypto deposit address or an NGN virtual account. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/deposits/accounts/{id}/identities":{"post":{"description":"Issues a pay-in identity into a deposit account: a static crypto deposit address or an NGN virtual account.","operationId":"DepositsController_issueIdentity","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueDepositIdentityDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"summary":"Issue a deposit identity","tags":["Deposits"]}}}} ``` ## Retrieve parent deposit account > Retrieves the merchant parent deposit account. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits/accounts/parent":{"get":{"description":"Retrieves the merchant parent deposit account.","operationId":"DepositsController_getParentAccount","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParentDepositAccountApiResponseDto"}}}}},"summary":"Retrieve parent deposit account","tags":["Deposits"]}}}} ``` ## Retrieve a customer's deposit account > Retrieves the deposit account for a customer. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits/accounts/customer/{customerId}":{"get":{"description":"Retrieves the deposit account for a customer.","operationId":"DepositsController_getAccountByCustomerId","parameters":[{"name":"customerId","required":true,"in":"path","description":"Customer ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositAccountApiResponseDto"}}}},"404":{"description":"Deposit account not found"}},"summary":"Retrieve a customer's deposit account","tags":["Deposits"]}}}} ``` ## List deposits > Lists your inbound deposits (crypto and fiat). ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits":{"get":{"description":"Lists your inbound deposits (crypto and fiat).","operationId":"DepositsController_listDeposits","parameters":[{"name":"customerId","required":false,"in":"query","description":"Filter by customer id","schema":{"type":"string"}},{"name":"depositAccountId","required":false,"in":"query","description":"Filter by deposit account id","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by type","schema":{"type":"string","enum":["crypto","fiat"]}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","completed","failed"]}},{"name":"chain","required":false,"in":"query","description":"Filter by crypto chain","schema":{"type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by currency","schema":{"type":"string"}},{"name":"txHash","required":false,"in":"query","description":"Filter by crypto deposit transaction hash (exact)","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string)","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositListApiResponseDto"}}}}},"summary":"List deposits","tags":["Deposits"]}}}} ``` ## Retrieve a deposit > Retrieves a single deposit. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Deposits","description":"View inbound crypto and fiat deposits to deposit accounts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/deposits/{id}":{"get":{"description":"Retrieves a single deposit.","operationId":"DepositsController_getDepositById","parameters":[{"name":"id","required":true,"in":"path","description":"Deposit ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositApiResponseDto"}}}},"404":{"description":"Deposit not found"}},"summary":"Retrieve a deposit","tags":["Deposits"]}}}} ``` # Payouts Manage payouts ## List payouts > Returns all payouts. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payouts":{"get":{"description":"Returns all payouts.","operationId":"PayoutV2Controller_getAllPayouts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by payout reference, transaction hash or destination address.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by payout status","schema":{"type":"string","enum":["pending","processing","success","failed"]}},{"name":"recipientId","required":false,"in":"query","description":"Filter by payout recipient.","schema":{"type":"string"}},{"name":"method","required":false,"in":"query","description":"Filter by payout method.","schema":{"type":"string","enum":["crypto","fiat"]}},{"name":"currency","required":false,"in":"query","description":"Filter by payout currency.","schema":{"type":"string","enum":["NGN","USDT","USDC","KES","ZAR","GHS"]}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain. Only crypto payouts move on a blockchain, so this excludes fiat payouts from the results.","schema":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutsV2ResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List payouts","tags":["Payouts"]}}}} ``` ## Initiate payout > Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payouts":{"post":{"description":"Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted.","operationId":"PayoutV2Controller_initializePayout","parameters":[],"requestBody":{"required":true,"description":"Payout initiation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutDto"}}}},"responses":{"201":{"description":"Payout initialized successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"}}}},"400":{"description":"Bad request - validation error, insufficient balance, daily limit exceeded, or missing one-time code (not required when the recipient is trusted)"},"404":{"description":"Recipient (bank account or wallet address) not found"},"500":{"description":"Internal server error - payout processing failed"}},"summary":"Initiate payout","tags":["Payouts"]}}}} ``` ## Quote a payout > Returns the fee and conversion for a payout the recipient receives in a different currency from the balance that pays for it, e.g. KES or ETH. Call it before creating the payout to show the cost. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payouts/quote":{"post":{"description":"Returns the fee and conversion for a payout the recipient receives in a different currency from the balance that pays for it, e.g. KES or ETH. Call it before creating the payout to show the cost.","operationId":"PayoutV2Controller_quotePayout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutQuoteDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutQuoteResponseDataDto"}}}}},"summary":"Quote a payout","tags":["Payouts"]}}}} ``` ## Quote a cross-border payout > Deprecated: use POST /payouts/quote. Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Cross-border payouts are available to verified businesses. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payouts/cross-border/quote":{"post":{"deprecated":true,"description":"Deprecated: use POST /payouts/quote. Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Cross-border payouts are available to verified businesses.","operationId":"PayoutV2Controller_quoteCrossBorderPayout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteResponseDataDto"}}}}},"summary":"Quote a cross-border payout","tags":["Payouts"]}}}} ``` ## Retrieve payout > Returns the payout for the given ID. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payouts/{id}":{"get":{"description":"Returns the payout for the given ID.","operationId":"PayoutV2Controller_findOnePayout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Payout retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Payout not found"}},"summary":"Retrieve payout","tags":["Payouts"]}}}} ``` ## Retrieve all payout fees > Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payouts/fees":{"get":{"description":"Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset.","operationId":"PayoutV2Controller_getPayoutFees","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatePayoutFeesApiResponseDto"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error - Unable to calculate fees"}},"summary":"Retrieve all payout fees","tags":["Payouts"]}}}} ``` # Payout Recipients Manage saved payout recipients for crypto and fiat in one place ## List payout recipients > Returns your saved payout recipients. Filter by type to return a single rail, or omit type to return all types. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/recipients":{"get":{"description":"Returns your saved payout recipients. Filter by type to return a single rail, or omit type to return all types.","operationId":"PayoutRecipientsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"isTemporary","required":false,"in":"query","description":"Omit for all recipients; true for temporary, false for address book.","schema":{"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"Filter by recipient type. Omit to list every type.","schema":{"enum":["crypto_address","ngn_bank_account","kes_mobile_money","ghs_mobile_money"],"type":"string"}},{"name":"customerId","required":false,"in":"query","description":"Filter by the customer the recipient is linked to.","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by account holder name, institution, or label.","schema":{"type":"string"}}],"responses":{"200":{"description":"Recipients retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientListResponseDto"}}}}},"summary":"List payout recipients","tags":["Payout Recipients"]}}}} ``` ## Create payout recipient > Adds a payout recipient. Set type to crypto\_address, ngn\_bank\_account, kes\_mobile\_money (Kenya) or ghs\_mobile\_money (Ghana) and supply the matching details. Bank accounts are verified and must match your name or business name. If a matching recipient already exists, the existing one is returned instead of creating a duplicate. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/recipients":{"post":{"description":"Adds a payout recipient. Set type to crypto_address, ngn_bank_account, kes_mobile_money (Kenya) or ghs_mobile_money (Ghana) and supply the matching details. Bank accounts are verified and must match your name or business name. If a matching recipient already exists, the existing one is returned instead of creating a duplicate.","operationId":"PayoutRecipientsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecipientDto"}}}},"responses":{"201":{"description":"Recipient created, or the existing recipient if it already existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientResponseDto"}}}},"400":{"description":"Invalid details or unsupported type."}},"summary":"Create payout recipient","tags":["Payout Recipients"]}}}} ``` ## Validate recipient details > Preflight check before creating a recipient. Crypto validates the address format. Bank resolves the account holder name through the provider. Mobile money resolves the corridor and provider for the details. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/recipients/validate":{"post":{"description":"Preflight check before creating a recipient. Crypto validates the address format. Bank resolves the account holder name through the provider. Mobile money resolves the corridor and provider for the details.","operationId":"PayoutRecipientsController_validate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRecipientDto"}}}},"responses":{"200":{"description":"Details are valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResolvedResponseDto"}}}},"400":{"description":"Invalid details."}},"summary":"Validate recipient details","tags":["Payout Recipients"]}}}} ``` ## List supported banks > Banks available for bank account recipients. Nigeria (ng) only for now. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/recipients/banks":{"get":{"description":"Banks available for bank account recipients. Nigeria (ng) only for now.","operationId":"PayoutRecipientsController_banks","parameters":[{"name":"country","required":false,"in":"query","description":"ISO 3166-1 alpha-2 country code. Optional, defaults to ng; only ng is supported for now.","schema":{"default":"ng","type":"string"}}],"responses":{"200":{"description":"Bank list retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankListResponseDto"}}}}},"summary":"List supported banks","tags":["Payout Recipients"]}}}} ``` ## List supported payout chains > Returns the chains and assets available for crypto\_address recipients, keyed by chain. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/recipients/chains":{"get":{"description":"Returns the chains and assets available for crypto_address recipients, keyed by chain.","operationId":"PayoutRecipientsController_chains","parameters":[],"responses":{"200":{"description":"Supported chains retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedPayoutChainsResponseDto"}}}}},"summary":"List supported payout chains","tags":["Payout Recipients"]}}}} ``` ## Retrieve payout recipient > Returns the payout recipient for the given ID. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/recipients/{id}":{"get":{"description":"Returns the payout recipient for the given ID.","operationId":"PayoutRecipientsController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Recipient ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Recipient retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientResponseDto"}}}},"404":{"description":"Recipient not found."}},"summary":"Retrieve payout recipient","tags":["Payout Recipients"]}}}} ``` ## Delete payout recipient > Deletes the payout recipient. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payout Recipients","description":"Manage saved payout recipients for crypto and fiat in one place"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}}},"paths":{"/api/v1/recipients/{id}":{"delete":{"description":"Deletes the payout recipient.","operationId":"PayoutRecipientsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"Recipient ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Recipient deleted.","content":{"application/json":{}}},"404":{"description":"Recipient not found."}},"summary":"Delete payout recipient","tags":["Payout Recipients"]}}}} ``` # Balance Check account balance ## Retrieve balances > Returns all balances ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/balance":{"get":{"description":"Returns all balances","operationId":"BalanceController_getBalances","parameters":[],"responses":{"200":{"description":"Balances retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceListResponseDto"}}}}},"summary":"Retrieve balances","tags":["Balance"]}}}} ``` ## List balance transactions > Returns your balance transactions. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/balance/transactions":{"get":{"description":"Returns your balance transactions.","operationId":"BalanceController_getBalanceTransactions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"source","required":false,"in":"query","description":"Filter by source type","schema":{"type":"string","enum":["payment_session","invoice","deposit","payout","swap","refund","fee"]}},{"name":"status","required":false,"in":"query","description":"Filter by status","schema":{"type":"string","enum":["pending","completed","failed","cancelled"]}},{"name":"direction","required":false,"in":"query","description":"Filter by direction (money in or out)","schema":{"type":"string","enum":["credit","debit"]}},{"name":"currency","required":false,"in":"query","description":"Filter by balance currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"txHash","required":false,"in":"query","description":"Filter by crypto deposit transaction hash (exact)","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date (ISO string)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date (ISO string)","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance transactions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionListResponseDto"}}}}},"summary":"List balance transactions","tags":["Balance"]}}}} ``` ## GET /api/v1/balance/transactions/{id} > Get a balance transaction by id ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Balance","description":"Check account balance"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/balance/transactions/{id}":{"get":{"operationId":"BalanceController_getBalanceTransactionById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Balance transaction retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceTransactionResponseDto"}}}},"404":{"description":"Balance transaction not found"}},"summary":"Get a balance transaction by id","tags":["Balance"]}}}} ``` # Swap Swap between balance currencies ## GET /api/v1/swap/rates > List swap rates ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/swap/rates":{"get":{"operationId":"SwapController_getAllRates","parameters":[],"responses":{"200":{"description":"Swap rates retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapRateResponseDto"}}}}]}}}}},"summary":"List swap rates","tags":["Swap"]}}}} ``` ## GET /api/v1/swap/estimate > Estimate swap amount ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/swap/estimate":{"get":{"operationId":"SwapController_estimateSwap","parameters":[{"name":"fromCurrency","required":true,"in":"query","description":"Currency to swap from","schema":{"type":"string","enum":["NGN","USDT","BTC","ETH","BNB","SOL","TRX","USDC","POL","CELO","CNGN"]}},{"name":"toCurrency","required":true,"in":"query","description":"Currency to swap to","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"amount","required":true,"in":"query","description":"Amount to swap","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap estimation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapEstimationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"summary":"Estimate swap amount","tags":["Swap"]}}}} ``` ## Create a swap quotation > Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]},"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"]}}},"paths":{"/api/v1/swap/quotation":{"post":{"description":"Creates a swap quotation that locks the rate for 30 seconds. Execute the quotation before it expires.","operationId":"SwapController_createQuotation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapBalanceDto"}}}},"responses":{"201":{"description":"Quotation created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"400":{"description":"Invalid currency pair or amount"}},"summary":"Create a swap quotation","tags":["Swap"]}}}} ``` ## GET /api/v1/swap/quotation/{quotationId} > Get swap quotation by ID ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/swap/quotation/{quotationId}":{"get":{"operationId":"SwapController_getQuotation","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Quotation retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapQuotationResponseDto"}}}]}}}},"404":{"description":"Quotation not found"}},"summary":"Get swap quotation by ID","tags":["Swap"]}}}} ``` ## POST /api/v1/swap/execute/{quotationId} > Execute swap quotation ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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."}}},"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"]},"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"]}}},"paths":{"/api/v1/swap/execute/{quotationId}":{"post":{"operationId":"SwapController_executeSwap","parameters":[{"name":"quotationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteSwapDto"}}}},"responses":{"200":{"description":"Swap completed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"400":{"description":"Quotation expired or already used"},"404":{"description":"Quotation not found"}},"summary":"Execute swap quotation","tags":["Swap"]}}}} ``` ## GET /api/v1/swaps > List swaps ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/swaps":{"get":{"operationId":"SwapController_getSwapHistory","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"fromCurrency","required":false,"in":"query","description":"Filter by source currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"toCurrency","required":false,"in":"query","description":"Filter by target currency","schema":{"type":"string","enum":["NGN","USDT","USDC"]}},{"name":"startDate","required":false,"in":"query","description":"Start date for filtering (ISO string)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for filtering (ISO string)","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap history retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedApiResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SwapResponseDto"}}}}]}}}}},"summary":"List swaps","tags":["Swap"]}}}} ``` ## GET /api/v1/swaps/{id} > Get swap details by ID ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Swap","description":"Swap between balance currencies"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/swaps/{id}":{"get":{"operationId":"SwapController_getSwapDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap details retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SwapResponseDto"}}}]}}}},"404":{"description":"Swap not found"}},"summary":"Get swap details by ID","tags":["Swap"]}}}} ``` # Settlements Track Settlement activity ## GET /api/v1/settlements > List settlements ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Settlements","description":"Track Settlement activity"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/settlements":{"get":{"operationId":"SettlementController_listSettlements","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"entity","required":false,"in":"query","description":"Filter by entity type","schema":{"enum":["session","invoice"],"type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by settlement currency","schema":{"enum":["USD","NGN"],"type":"string"}}],"responses":{"200":{"description":"Settlements retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementListApiResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List settlements","tags":["Settlements"]}}}} ``` ## GET /api/v1/settlements/{reference} > Retrieve settlement data ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Settlements","description":"Track Settlement activity"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/settlements/{reference}":{"get":{"operationId":"SettlementController_getSettlement","parameters":[{"name":"reference","required":true,"in":"path","description":"Session or invoice reference","schema":{"type":"string"}},{"name":"entity","required":true,"in":"query","description":"Entity type","schema":{"enum":["session","invoice"],"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementApiResponseDto"}}}},"400":{"description":"Missing or invalid \"entity\" query parameter"},"401":{"description":"Unauthorized"},"404":{"description":"Session or invoice not found"}},"summary":"Retrieve settlement data","tags":["Settlements"]}}}} ``` # Customers Manage customer information ## List customers > Returns all customers. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/customers":{"get":{"description":"Returns all customers.","operationId":"CustomersController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by customer name, email, or phone","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","description":"Filter by exact email address","schema":{"type":"string"}},{"name":"phone","required":false,"in":"query","description":"Filter by exact phone number","schema":{"type":"string"}},{"name":"telegramId","required":false,"in":"query","description":"Filter by exact Telegram ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersResponseDto"}}}}},"summary":"List customers","tags":["Customers"]}}}} ``` ## Create customer > Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"}}},"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"]}}},"paths":{"/api/v1/customers":{"post":{"description":"Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead.","operationId":"CustomersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data"}},"summary":"Create customer","tags":["Customers"]}}}} ``` ## Retrieve customer > Returns the customer for the given ID. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/customers/{id}":{"get":{"description":"Returns the customer for the given ID.","operationId":"CustomersController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{}}}}},"summary":"Retrieve customer","tags":["Customers"]}}}} ``` ## Update customer > Updates the customer. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"}}},"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"]}}},"paths":{"/api/v1/customers/{id}":{"patch":{"description":"Updates the customer.","operationId":"CustomersController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data or duplicate email/phone/telegram ID"},"404":{"description":"Customer not found"}},"summary":"Update customer","tags":["Customers"]}}}} ``` # Refunds Create and track refunds ## Process session refund > Refunds the money received in a payment session back to the customer. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Refunds","description":"Create and track refunds"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/refunds/session/{sessionReference}":{"post":{"description":"Refunds the money received in a payment session back to the customer.","operationId":"RefundsController_refundSession","parameters":[{"name":"sessionReference","required":true,"in":"path","description":"Session reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"summary":"Process session refund","tags":["Refunds"]}}}} ``` ## Process invoice refund > Refunds the money paid for an invoice back to the customer. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Refunds","description":"Create and track refunds"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/refunds/invoice/{invoiceReference}":{"post":{"description":"Refunds the money paid for an invoice back to the customer.","operationId":"RefundsController_refundInvoice","parameters":[{"name":"invoiceReference","required":true,"in":"path","description":"Invoice reference","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRefundDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"summary":"Process invoice refund","tags":["Refunds"]}}}} ``` ## List refunds > Returns all refunds. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Refunds","description":"Create and track refunds"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/refunds":{"get":{"description":"Returns all refunds.","operationId":"RefundsController_listRefunds","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by refund status","schema":{"type":"string","enum":["pending","processing","success","failed"]}},{"name":"sessionReference","required":false,"in":"query","description":"Filter by payment session reference","schema":{"type":"string"}},{"name":"invoiceReference","required":false,"in":"query","description":"Filter by invoice reference","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search term for session or invoice reference","schema":{"type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter refunds created from this date/time (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter refunds created up to this date/time (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundsResponseDto"}}}}},"summary":"List refunds","tags":["Refunds"]}}}} ``` ## Estimate refund > Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Refunds","description":"Create and track refunds"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}}},"paths":{"/api/v1/refunds/estimate/{reference}":{"get":{"description":"Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter.","operationId":"RefundsController_estimateRefund","parameters":[{"name":"reference","required":true,"in":"path","description":"Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)","schema":{"type":"string"}},{"name":"entity","required":true,"in":"query","description":"Entity type - whether the reference is for a session or invoice","schema":{"type":"string","enum":["session","invoice"]}},{"name":"feePaidBy","required":false,"in":"query","description":"Who will pay the network fee","schema":{"type":"string","enum":["merchant","customer"]}}],"responses":{"200":{"description":""}},"summary":"Estimate refund","tags":["Refunds"]}}}} ``` ## Retrieve refund > Returns the refund for the given ID. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Refunds","description":"Create and track refunds"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/refunds/{id}":{"get":{"description":"Returns the refund for the given ID.","operationId":"RefundsController_getRefund","parameters":[{"name":"id","required":true,"in":"path","description":"Refund ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApiResponseDto"}}}}},"summary":"Retrieve refund","tags":["Refunds"]}}}} ``` # Payment Pages Create and manage hosted payment pages ## List payment pages > Returns all payment pages. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payment Pages","description":"Create and manage hosted payment pages"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payments/pages":{"get":{"description":"Returns all payment pages.","operationId":"StaticCheckoutsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by payment page title","schema":{"type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPagesResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"summary":"List payment pages","tags":["Payment Pages"]}}}} ``` ## Create payment page > Creates a new payment page. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payment Pages","description":"Create and manage hosted payment pages"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payments/pages":{"post":{"description":"Creates a new payment page.","operationId":"StaticCheckoutsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentPageDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPageResponseDto"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict - Nickname already exists"}},"summary":"Create payment page","tags":["Payment Pages"]}}}} ``` ## Retrieve payment page by reference > Returns the payment page for the given reference. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payment Pages","description":"Create and manage hosted payment pages"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]}}},"paths":{"/api/v1/payments/pages/{reference}/sessions":{"get":{"description":"Returns the payment page for the given reference.","operationId":"StaticCheckoutsController_getStaticCheckout","parameters":[{"name":"reference","required":true,"in":"path","description":"Payment page reference","schema":{"type":"string"}},{"name":"x-api-key","in":"header","description":"API key for authentication","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentPageResponseDto"}}}},"404":{"description":"Payment page not found"},"500":{"description":"Internal server error"}},"summary":"Retrieve payment page by reference","tags":["Payment Pages"]}}}} ``` ## Delete payment page > Deletes the payment page. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payment Pages","description":"Create and manage hosted payment pages"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}}},"paths":{"/api/v1/payments/pages/{id}":{"delete":{"description":"Deletes the payment page.","operationId":"StaticCheckoutsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"Payment page ID","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Payment page not found"}},"summary":"Delete payment page","tags":["Payment Pages"]}}}} ``` ## Update payment page > Updates the payment page. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payment Pages","description":"Create and manage hosted payment pages"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"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"]},"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"]}}},"paths":{"/api/v1/payments/pages/{id}":{"patch":{"description":"Updates the payment page.","operationId":"StaticCheckoutsController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Payment page ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentPageDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPageResponseDto"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Payment page not found"},"409":{"description":"Conflict - Nickname already exists"}},"summary":"Update payment page","tags":["Payment Pages"]}}}} ``` # Miscellaneous Miscellaneous endpoints ## Retrieve supported blockchains and assets > Returns the full detailed list of supported blockchains and assets. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Miscellaneous","description":"Miscellaneous endpoints"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"SupportedAssetsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"type":"object","description":"Supported assets data"}},"required":["success","message"]}}},"paths":{"/api/v1/blockchain/assets":{"get":{"description":"Returns the full detailed list of supported blockchains and assets.","operationId":"BlockchainController_findSupportedAssetsFull","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedAssetsResponseDto"}}}}},"summary":"Retrieve supported blockchains and assets","tags":["Miscellaneous"]}}}} ``` ## Retrieve confirmation requirements > Returns the number of confirmations required for transactions to be considered final on different blockchains. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Miscellaneous","description":"Miscellaneous endpoints"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}}},"paths":{"/api/v1/blockchain/confirmations":{"get":{"description":"Returns the number of confirmations required for transactions to be considered final on different blockchains.","operationId":"BlockchainController_getConfirmationRequirements","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{}}}}},"summary":"Retrieve confirmation requirements","tags":["Miscellaneous"]}}}} ``` ## Retrieve gas fees > Returns gas fees for all supported blockchains. All fee values are returned in the native token/asset value. ```json {"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Miscellaneous","description":"Miscellaneous endpoints"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}}},"paths":{"/api/v1/blockchain/gas-fees":{"get":{"description":"Returns gas fees for all supported blockchains. All fee values are returned in the native token/asset value.","operationId":"BlockchainController_getGasFeesForBlockchain","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{}}}}},"summary":"Retrieve gas fees","tags":["Miscellaneous"]}}}} ``` # 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"]}}}} ``` # Webhooks Receive real-time event notifications for payments, invoices, transactions, payouts, refunds, swaps, and deposits. Receive real-time event notifications when payment, invoice, transaction, payout, refund, swap, and deposit states change. Use webhooks to keep your system in sync without polling. ### Webhook references Choose a page for the event family you need:
ReferenceDescriptionPage
PaymentsPayment session lifecycle events.
InvoicesInvoice payment, updates, and expiry.
TransactionsOn-chain transaction detection and confirmation.
PayoutsOutgoing payout events.
RefundsRefund creation, completion, and failure.
SwapsCurrency swaps between your balances.
DepositsCrypto and bank transfer deposits into your account.
### Before you go live * Verify the webhook signature on every request. * Return a `200` response as soon as you accept the event. * Use `X-CoinCircuit-Delivery-Id` to handle retries safely. {% hint style="info" %} Process webhook deliveries asynchronously when possible. Store the delivery ID and ignore duplicates. {% endhint %} ### Event flow Most payment flows follow this order: 1. `transaction.received` 2. `transaction.confirmed` 3. One of the payment events 4. Any follow-up invoice, payout, or refund events Use transaction events for blockchain state. Use payment and invoice events for business state. ### Delivery format All webhook deliveries are sent as `POST` requests to your webhook endpoint. #### Standard headers | Header | Description | | --------------------------- | ------------------------------------------------ | | `X-CoinCircuit-Event` | Event name, such as `transaction.confirmed`. | | `X-CoinCircuit-Delivery-Id` | Unique ID for this delivery. | | `X-CoinCircuit-Signature` | HMAC-SHA256 signature of the request body. | | `X-CoinCircuit-Timestamp` | Unix timestamp of the delivery, used in signing. | #### Retry behavior If your endpoint returns anything other than a `200`, the delivery is retried with exponential backoff, roughly at 0 minutes, 1 minute, 10 minutes, then 1 hour. Build handlers to be idempotent. Use the delivery ID to detect duplicates safely. ### Verify signatures Verify signatures against the raw request body. Reject invalid requests before you process the payload. {% tabs %} {% tab title="Verify signature" %} ```javascript const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret, timestamp) { try { const signedPayload = timestamp ? `${timestamp}.${payload}` : payload; const expectedSignature = crypto .createHmac('sha256', secret) .update(signedPayload, 'utf8') .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex') ); } catch (_) { return false; } } ``` {% endtab %} {% tab title="Use in an endpoint" %} ```javascript const payload = rawBody; const signature = req.headers['x-coincircuit-signature']; const timestamp = req.headers['x-coincircuit-timestamp']; const secret = process.env.COINCIRCUIT_WEBHOOK_SECRET; if (!verifyWebhookSignature(payload, signature, secret, timestamp)) { return res.status(401).json({ error: 'Invalid signature' }); } return res.status(200).json({ received: true }); ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Use the raw request body for signature verification. Do not reformat the JSON before calculating the HMAC. {% endhint %} ### Shared payload shape Every delivery includes: * `event`: the event name * `data`: the event payload The object inside `data` changes by event family: * payment events use `data.session` * invoice events use `data.invoice` and `data.payments` * transaction events use `data.transaction` and `data.session` * payout events use `data.payout` * refund events use `data.refund` * swap events use `data.swap` * deposit events put the deposit directly in `data` # Transactions Transaction webhook events and example payloads. Transaction webhooks track blockchain activity for incoming payments. Use these events to follow on-chain state before the payment is final. ### Field descriptions Transaction webhook events use `data.transaction`. They also include `data.session` for the related payment session. #### Transaction object | Field | Type | Description | | -------------------------------- | ---------------- | ---------------------------------------------------- | | `data.transaction.id` | `string` | Unique transaction identifier. | | `data.transaction.txHash` | `string` | Transaction hash on the blockchain. | | `data.transaction.status` | `string` | Transaction status. See each event below. | | `data.transaction.chain` | `string` | Blockchain network. | | `data.transaction.asset` | `string` | Crypto asset received. | | `data.transaction.fromAddress` | `string` | Sender's wallet address. | | `data.transaction.toAddress` | `string` | Destination wallet address. | | `data.transaction.amount` | `string` | Crypto amount received. | | `data.transaction.confirmations` | `number` | Number of blockchain confirmations. | | `data.transaction.failureReason` | `string \| null` | Failure reason when present. | | `data.transaction.confirmedAt` | `string \| null` | When the transaction was confirmed. Null until then. | | `data.transaction.createdAt` | `string` | When the transaction was detected (ISO 8601). | #### Related session object `data.session` has the same shape as in [payment events](/webhooks/readme/payments). `settlements` is always `null` here, because the session has not settled yet. ### Events * `transaction.received` * `transaction.confirmed` ### `transaction.received` Sent when an incoming transaction is first detected on the blockchain. `data.transaction.status` is `pending`. Use this event for early detection. Do not treat it as final confirmation. ```json { "event": "transaction.received", "data": { "transaction": { "id": "tx_123", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "status": "pending", "chain": "ethereum", "asset": "USDT", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234", "amount": "100.55", "confirmations": 1, "failureReason": null, "confirmedAt": null, "createdAt": "2024-01-15T10:30:00.000Z" }, "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "open", "type": "payment", "amount": "100.00", "amountPaid": null, "currency": "USD", "settlements": null, "payment": { "status": "pending", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "0", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null } } } ``` ### `transaction.confirmed` Sent when a transaction reaches the required number of confirmations. `data.transaction.status` is `confirmed`. Use this event when you need confirmed blockchain state. ```json { "event": "transaction.confirmed", "data": { "transaction": { "id": "tx_123", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "status": "confirmed", "chain": "ethereum", "asset": "USDT", "fromAddress": "0x1234567890abcdef1234567890abcdef12345678", "toAddress": "0xabcdef1234567890abcdef1234567890abcdef1234", "amount": "100.55", "confirmations": 12, "failureReason": null, "confirmedAt": "2024-01-15T10:35:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z" }, "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "open", "type": "payment", "amount": "100.00", "amountPaid": "100.00", "currency": "USD", "settlements": null, "payment": { "status": "pending", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "100.55", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null } } } ``` # Payments Payment session webhook events and example payloads. Payment webhooks track the lifecycle of a payment session. Use these events to update order state, trigger fulfillment, or handle failed payments. ### Field descriptions Payment webhook events use `data.session`. | Field | Type | Description | | ----------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `data.session.id` | `string` | Unique session identifier. | | `data.session.reference` | `string` | Your order or payment reference. | | `data.session.title` | `string` | Session title. | | `data.session.description` | `string \| null` | Optional session description. | | `data.session.state` | `'open' \| 'closed'` | `open` while the session can still take payment, `closed` once it is final. | | `data.session.type` | `string` | Session type. Always `payment`. | | `data.session.amount` | `string` | Requested amount, as a decimal string. | | `data.session.amountPaid` | `string \| null` | Fiat amount the customer paid in the requested currency, not counting any gas fee the customer paid. Null until a payment arrives. | | `data.session.currency` | `string` | Requested currency, such as `USD` or `NGN`. | | `data.session.settlements` | `object \| null` | Settlement breakdown. Null until the session settles. | | `data.session.settlements.currency` | `string` | Currency of every settlement amount. | | `data.session.settlements.gross.amount` | `string` | Amount received before fees. | | `data.session.settlements.gross.conversionRate` | `string` | Rate used to convert the crypto received. | | `data.session.settlements.fees` | `object \| null` | Fee breakdown. Null when no fees were charged. | | `data.session.settlements.fees.processing` | `object \| null` | Processing fee, with `amount` and `paidBy`. | | `data.session.settlements.fees.gas` | `object \| null` | Network fee, with `amount` and `paidBy`. | | `data.session.settlements.net.amount` | `string` | Amount credited to your balance. | | `data.session.payment` | `object \| null` | Crypto payment details. | | `data.session.payment.status` | `string` | Payment status. See each event below. | | `data.session.payment.asset` | `string` | Crypto asset, such as `USDT`. | | `data.session.payment.chain` | `string` | Blockchain network, such as `ethereum`. | | `data.session.payment.amount` | `string` | Crypto amount required. | | `data.session.payment.amountReceived` | `string` | Crypto amount received so far. | | `data.session.payment.conversionRate` | `string` | Rate used to convert the requested amount to crypto. | | `data.session.payment.gasFee` | `string` | Network fee for the payment. | | `data.session.payment.address` | `string` | Deposit address the customer pays to. | | `data.session.payment.feePaidBy` | `'merchant' \| 'customer'` | Who pays the network fee. | | `data.session.customer` | `object` | Customer details: `id`, `email`, `phone`, `firstName`, `lastName`, and `metadata`. | | `data.session.metadata` | `object \| null` | Your custom key-value data. | | `data.session.successUrl` | `string` | Where the customer is sent after paying. | | `data.session.cancelUrl` | `string` | Where the customer is sent after cancelling. | | `data.session.createdAt` | `string` | When the session was created (ISO 8601). | | `data.session.expiresAt` | `string` | When the session expires (ISO 8601). | | `data.session.completedAt` | `string \| null` | When the session completed. Null until then. | | `data.failureReason` | `string` | Why the session was rejected. Sent only with `payment.failed`. | ### Events * `payment.completed` * `payment.partial` * `payment.expired` * `payment.underpaid` * `payment.failed` ### `payment.completed` Sent when a payment session receives the full amount. Use this event to mark the order as paid. {% hint style="success" %} This event is sent only when the full required amount is received. `data.session.payment.status` is `completed`. {% endhint %} ```json { "event": "payment.completed", "data": { "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "closed", "type": "payment", "amount": "100.00", "amountPaid": "100.00", "currency": "USD", "settlements": { "currency": "NGN", "gross": { "amount": "150000.00", "conversionRate": "1500.00" }, "fees": { "processing": { "amount": "1500.00", "paidBy": "merchant" }, "gas": { "amount": "75.00", "paidBy": "customer" } }, "net": { "amount": "148425.00" } }, "payment": { "status": "completed", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "100.55", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": "2024-01-15T10:35:00.000Z" } } } ``` ### `payment.partial` Sent when a payment session receives less than the required amount and is still open, so it can take more payments. Use this event to tell the customer what is left to pay, or to keep the order on hold. {% hint style="warning" %} Compare `data.session.payment.amountReceived` with `data.session.payment.amount` to work out the remaining amount due. `data.session.payment.status` is `partial`. {% endhint %} ```json { "event": "payment.partial", "data": { "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "open", "type": "payment", "amount": "100.00", "amountPaid": "49.98", "currency": "USD", "settlements": null, "payment": { "status": "partial", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "50.25", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null } } } ``` ### `payment.expired` Sent when a payment session closes with no payment received. Use this event to expire checkout state. `data.session.payment.status` is `expired`. ```json { "event": "payment.expired", "data": { "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "closed", "type": "payment", "amount": "100.00", "amountPaid": null, "currency": "USD", "settlements": null, "payment": { "status": "expired", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "0", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null } } } ``` ### `payment.underpaid` Sent when a payment session closes with less than the required amount. Use this event when the session is final but still short. `data.session.payment.status` is `partial`. {% hint style="warning" %} Check `data.session.payment.amountReceived` for the crypto amount received before the session closed. {% endhint %} ```json { "event": "payment.underpaid", "data": { "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "closed", "type": "payment", "amount": "100.00", "amountPaid": "39.78", "currency": "USD", "settlements": null, "payment": { "status": "partial", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "40.00", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null } } } ``` ### `payment.failed` Sent when a payment session is rejected by a compliance check. Use this event to stop fulfillment and surface the failure. `data.session.payment.status` is `failed`. {% hint style="danger" %} Check `data.failureReason` for why the session was rejected. {% endhint %} ```json { "event": "payment.failed", "data": { "session": { "id": "cs_123456789_abcdef", "reference": "ORDER-2024-001", "title": "Order #2024-001", "description": "Payment for premium subscription", "state": "closed", "type": "payment", "amount": "100.00", "amountPaid": "100.00", "currency": "USD", "settlements": null, "payment": { "status": "failed", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "amountReceived": "100.55", "conversionRate": "1.0055", "gasFee": "0.05", "address": "0x1234567890abcdef1234567890abcdef12345678", "feePaidBy": "customer" }, "cancelUrl": "https://example.com/cancel", "successUrl": "https://example.com/success", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "metadata": { "userId": "usr_8f21c3" } }, "metadata": { "orderId": "ORDER-2024-001", "userId": "user_123" }, "createdAt": "2024-01-15T10:30:00.000Z", "expiresAt": "2024-01-15T11:30:00.000Z", "completedAt": null }, "failureReason": "Session contained flagged transactions" } } ``` # Invoices Invoice webhook events and example payloads. Invoice webhooks track invoice payments, updates, and expiry. Use these events to keep invoice state in sync with your system. ### Field descriptions Invoice webhook events use `data.invoice` and `data.payments`. | Field | Type | Description | | ---------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------ | | `data.invoice.id` | `string` | Unique invoice identifier. | | `data.invoice.reference` | `string` | Your invoice reference. | | `data.invoice.description` | `string \| null` | Optional description or notes for the invoice. | | `data.invoice.status` | `string` | Payment status of the invoice. See each event below. | | `data.invoice.state` | `'open' \| 'closed'` | `open` while the invoice accepts payment, `closed` once it is final. | | `data.invoice.isRefunded` | `boolean` | Whether the invoice has been refunded. When `true`, `status` keeps the original payment status. | | `data.invoice.amount` | `string` | Total invoice amount, as a decimal string. Equals the sum of all line totals. | | `data.invoice.amountPaid` | `string` | Amount paid so far, as a decimal string. | | `data.invoice.currency` | `string` | Invoice currency, such as `NGN` or `USD`. | | `data.invoice.items` | `array` | Invoice line items. | | `data.invoice.items[].id` | `string` | Line item identifier. | | `data.invoice.items[].name` | `string` | Line item name. | | `data.invoice.items[].description` | `string \| null` | Line item description. | | `data.invoice.items[].unit` | `string \| null` | Unit label, such as `seats`. | | `data.invoice.items[].quantity` | `string` | Quantity, as a decimal string. | | `data.invoice.items[].unitPrice` | `string` | Price per unit, as a decimal string. | | `data.invoice.items[].lineTotal` | `string` | Quantity times unit price, as a decimal string. | | `data.invoice.customer` | `object` | Customer details: `id`, `email`, `phone`, `firstName`, `lastName`, `telegramId`, and `metadata`. | | `data.invoice.successUrl` | `string` | Where the customer is sent after paying. | | `data.invoice.cancelUrl` | `string` | Where the customer is sent after cancelling. | | `data.invoice.metadata` | `object \| null` | Your custom key-value data. | | `data.invoice.periodStart` | `string \| null` | Start of the billing period, when set. | | `data.invoice.periodEnd` | `string \| null` | End of the billing period, when set. | | `data.invoice.paidAt` | `string \| null` | When the invoice was fully paid. Null until then. | | `data.invoice.expiresAt` | `string \| null` | When the invoice expires. | | `data.invoice.createdAt` | `string` | When the invoice was created (ISO 8601). | | `data.invoice.updatedAt` | `string` | When the invoice was last updated (ISO 8601). | | `data.payments` | `array \| null` | Payments made toward the invoice. Null when there are none. | | `data.payments[].sessionId` | `string` | Payment session the payment came through. | | `data.payments[].sessionReference` | `string` | Reference of that payment session. | | `data.payments[].status` | `string` | Payment status, such as `confirmed`. | | `data.payments[].asset` | `string` | Crypto asset paid. | | `data.payments[].chain` | `string` | Blockchain network. | | `data.payments[].amount` | `string` | Crypto amount paid. | | `data.payments[].txHash` | `string` | Transaction hash on the blockchain. | | `data.payments[].createdAt` | `string` | When the payment was detected. | | `data.payments[].confirmedAt` | `string \| null` | When the payment was confirmed. | ### Events * `invoice.updated` * `invoice.paid` * `invoice.expired` ### `invoice.updated` Sent when an invoice receives a payment or its status changes. `data.invoice.status` is `pending` or `partial`. Use this event to refresh totals and partial payment state. ```json { "event": "invoice.updated", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "partial", "state": "open", "isRefunded": false, "amount": "1000.00", "amountPaid": "500.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": null, "expiresAt": "2024-02-15T10:30:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }, "payments": [ { "sessionId": "cs_123456789_abcdef", "sessionReference": "ORDER-2024-001", "status": "confirmed", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "createdAt": "2024-01-15T10:30:00.000Z", "confirmedAt": "2024-01-15T10:35:00.000Z" } ] } } ``` ### `invoice.paid` Sent when an invoice is fully paid. `data.invoice.status` is `paid`. Use this event to fulfill the order. ```json { "event": "invoice.paid", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "paid", "state": "open", "isRefunded": false, "amount": "1000.00", "amountPaid": "1000.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": "2024-01-15T10:35:00.000Z", "expiresAt": "2024-02-15T10:30:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }, "payments": [ { "sessionId": "cs_123456789_abcdef", "sessionReference": "ORDER-2024-001", "status": "confirmed", "asset": "USDT", "chain": "ethereum", "amount": "100.55", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "createdAt": "2024-01-15T10:30:00.000Z", "confirmedAt": "2024-01-15T10:35:00.000Z" } ] } } ``` ### `invoice.expired` Sent when an invoice expires. `data.invoice.status` is the payment status at expiry, `pending` or `partial`. Use this event to close unpaid invoices. ```json { "event": "invoice.expired", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "pending", "state": "closed", "isRefunded": false, "amount": "1000.00", "amountPaid": "0.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": null, "expiresAt": "2024-01-15T10:30:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }, "payments": null } } ``` # Payouts Payout webhook events and example payloads. Payout webhooks track outgoing transfers to recipients. The examples on this page show crypto payouts. Bank payouts use the same events and shape, with `method` set to `fiat` and a bank account recipient. ### Field descriptions Payout webhook events use `data.payout`. | Field | Type | Description | | --------------------------------------------- | ---------------- | ----------------------------------------------------------------- | | `data.payout.id` | `string` | Unique payout identifier. | | `data.payout.reference` | `string \| null` | Payout reference. | | `data.payout.method` | `string` | `crypto` or `fiat`. | | `data.payout.type` | `string` | `instant`, `withdrawal`, or `refund`. | | `data.payout.status` | `string` | Payout status. See each event below. | | `data.payout.amount` | `string` | Amount the recipient receives. | | `data.payout.fee` | `string` | Fee charged for the payout. | | `data.payout.total` | `string` | Total taken from your balance (amount plus fee). | | `data.payout.currency` | `string` | Payout currency, such as `NGN` or `USDT`. | | `data.payout.conversion` | `object \| null` | Conversion details, when the payout converted between currencies. | | `data.payout.narration` | `string \| null` | Payout narration. | | `data.payout.recipient` | `object` | Recipient details. The shape of `details` depends on `type`. | | `data.payout.recipient.id` | `string \| null` | ID of the saved recipient (crypto address or bank account). | | `data.payout.recipient.type` | `string` | `crypto_address` or `ngn_bank_account`. | | `data.payout.recipient.details.chain` | `string \| null` | Blockchain network. `crypto_address` only. | | `data.payout.recipient.details.address` | `string \| null` | Destination wallet address. `crypto_address` only. | | `data.payout.recipient.details.accountName` | `string \| null` | Account holder name. `ngn_bank_account` only. | | `data.payout.recipient.details.accountNumber` | `string \| null` | Masked account number. `ngn_bank_account` only. | | `data.payout.recipient.details.bankName` | `string \| null` | Bank name. `ngn_bank_account` only. | | `data.payout.recipient.details.bankCode` | `string \| null` | Bank code. `ngn_bank_account` only. | | `data.payout.recipient.details.accountType` | `string \| null` | Account type. `ngn_bank_account` only. | | `data.payout.recipient.details.currency` | `string \| null` | Account currency. `ngn_bank_account` only. | | `data.payout.channel` | `string` | Where the payout was requested: `API` or `dashboard`. | | `data.payout.txHash` | `string \| null` | Transaction hash on the blockchain, for crypto payouts. | | `data.payout.completedAt` | `string` | When the payout completed. Sent only with `payout.success`. | | `data.payout.failureReason` | `string` | Why the payout failed. Sent only with `payout.failed`. | | `data.payout.createdAt` | `string` | When the payout was created (ISO 8601). | | `data.payout.updatedAt` | `string` | When the payout was last updated (ISO 8601). | ### Events * `payout.created` * `payout.success` * `payout.failed` ### `payout.created` Sent when a payout is created. `data.payout.status` is `pending`. Use this event to track payout initiation. ```json { "event": "payout.created", "data": { "payout": { "id": "po_123", "reference": "PAY-ABC123DEF456", "method": "crypto", "type": "withdrawal", "status": "pending", "amount": "99.50", "fee": "0.50", "total": "100.00", "currency": "USDT", "narration": "Withdrawal payout", "recipient": { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "crypto_address", "details": { "chain": "ethereum", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "channel": "API", "txHash": null, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } } } ``` ### `payout.success` Sent when a payout reaches the recipient. `data.payout.status` is `success`. Use this event to close the payout in your ledger. ```json { "event": "payout.success", "data": { "payout": { "id": "po_123", "reference": "PAY-ABC123DEF456", "method": "crypto", "type": "withdrawal", "status": "success", "amount": "99.50", "fee": "0.50", "total": "100.00", "currency": "USDT", "narration": "Withdrawal payout", "recipient": { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "crypto_address", "details": { "chain": "ethereum", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "channel": "API", "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "completedAt": "2024-01-15T10:40:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:40:00.000Z" } } } ``` ### `payout.failed` Sent when a payout fails. `data.payout.status` is `failed`. Use this event to stop reconciliation and surface the error. {% hint style="danger" %} Check `data.payout.failureReason` for why the payout failed. {% endhint %} ```json { "event": "payout.failed", "data": { "payout": { "id": "po_123", "reference": "PAY-ABC123DEF456", "method": "crypto", "type": "withdrawal", "status": "failed", "amount": "99.50", "fee": "0.50", "total": "100.00", "currency": "USDT", "narration": "Withdrawal payout", "recipient": { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "crypto_address", "details": { "chain": "ethereum", "address": "0x1234567890abcdef1234567890abcdef12345678" } }, "channel": "API", "txHash": null, "failureReason": "Invalid address", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } } } ``` # Refunds Refund webhook events and example payloads. Refund webhooks track refund creation, completion, and failure. Use these events to keep refund state in sync with your support and ledger systems. ### Field descriptions Refund webhook events use `data.refund`. | Field | Type | Description | | --------------------------- | -------------------------- | ---------------------------------------------------------- | | `data.refund.id` | `string` | Unique refund identifier. | | `data.refund.entity` | `string` | What was refunded: `session` or `invoice`. | | `data.refund.reference` | `string` | Reference of the refunded session or invoice. | | `data.refund.status` | `string` | Refund status. See each event below. | | `data.refund.reason` | `string \| null` | Optional reason for the refund. | | `data.refund.chain` | `string` | Blockchain network, such as `tron` or `ethereum`. | | `data.refund.asset` | `string` | Crypto asset, such as `USDT`. | | `data.refund.amount` | `string` | Crypto amount refunded to the customer. | | `data.refund.fee` | `string` | Network fee for the refund. | | `data.refund.feePaidBy` | `'merchant' \| 'customer'` | Who paid the refund network fee. | | `data.refund.fiatAmount` | `string` | Fiat value of the refund amount. | | `data.refund.fiatCurrency` | `string` | Fiat currency. | | `data.refund.balanceSource` | `string` | Which balance paid for the refund: `settled` or `pending`. | | `data.refund.refundAddress` | `string` | Customer wallet address that receives the refund. | | `data.refund.txHash` | `string \| null` | Transaction hash on the blockchain, once sent. | | `data.refund.explorerUrl` | `string \| null` | Block explorer link for the refund transaction. | | `data.refund.createdAt` | `string` | When the refund was created (ISO 8601). | | `data.refund.completedAt` | `string \| null` | When the refund completed. Null until then. | | `data.refund.failureReason` | `string \| null` | Why the refund failed. Null unless it failed. | ### Events * `refund.created` * `refund.success` * `refund.failed` ### `refund.created` Sent when a refund is created. `data.refund.status` is `pending` or `processing`. Use this event to start refund tracking. ```json { "event": "refund.created", "data": { "refund": { "id": "ref_12345678-1234-1234-1234-123456789abc", "entity": "session", "reference": "cs_1234567890", "status": "pending", "reason": "Customer requested refund", "chain": "tron", "asset": "USDT", "amount": "49.50000000", "fee": "0.50000000", "feePaidBy": "customer", "fiatAmount": "10000.00", "fiatCurrency": "NGN", "balanceSource": "settled", "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1", "txHash": null, "explorerUrl": null, "createdAt": "2024-01-15T10:30:00.000Z", "completedAt": null, "failureReason": null } } } ``` ### `refund.success` Sent when a refund completes. `data.refund.status` is `success`. Use this event to mark the refund as settled. ```json { "event": "refund.success", "data": { "refund": { "id": "ref_12345678-1234-1234-1234-123456789abc", "entity": "session", "reference": "cs_1234567890", "status": "success", "reason": "Customer requested refund", "chain": "tron", "asset": "USDT", "amount": "49.50000000", "fee": "0.50000000", "feePaidBy": "customer", "fiatAmount": "10000.00", "fiatCurrency": "NGN", "balanceSource": "settled", "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1", "txHash": "7c2d4f9e1b3a5c8d0e6f2a4b9c1d3e5f7a8b0c2d4e6f8a1b3c5d7e9f0a2b4c6d", "explorerUrl": "https://tronscan.org/#/transaction/7c2d4f9e1b3a5c8d0e6f2a4b9c1d3e5f7a8b0c2d4e6f8a1b3c5d7e9f0a2b4c6d", "createdAt": "2024-01-15T10:30:00.000Z", "completedAt": "2024-01-15T10:45:00.000Z", "failureReason": null } } } ``` ### `refund.failed` Sent when a refund fails. `data.refund.status` is `failed`. Use this event to notify support or retry with a corrected address. {% hint style="danger" %} Check `data.refund.failureReason` for why the refund failed. {% endhint %} ```json { "event": "refund.failed", "data": { "refund": { "id": "ref_12345678-1234-1234-1234-123456789abc", "entity": "session", "reference": "cs_1234567890", "status": "failed", "reason": "Customer requested refund", "chain": "tron", "asset": "USDT", "amount": "49.50000000", "fee": "0.50000000", "feePaidBy": "customer", "fiatAmount": "10000.00", "fiatCurrency": "NGN", "balanceSource": "settled", "refundAddress": "TQ5Nf9vK3pXw7RcL2mYhD8sJ4uGb6EaZt1", "txHash": null, "explorerUrl": null, "createdAt": "2024-01-15T10:30:00.000Z", "completedAt": null, "failureReason": "Invalid address" } } } ``` # Swaps Swap webhook events and example payloads. Swap webhooks tell you when a swap between two of your balances completes or fails. ### Field descriptions Swap webhook events use `data.swap`. It has the same shape as the swap returned by the API. | Field | Type | Description | | ---------------------------------- | ---------------- | -------------------------------------------------- | | `data.swap.id` | `string` | Unique swap identifier. | | `data.swap.fromCurrency` | `string` | Currency taken from your balance, such as `USDT`. | | `data.swap.toCurrency` | `string` | Currency added to your balance, such as `NGN`. | | `data.swap.sourceAmount` | `string` | Amount taken, as a decimal string. | | `data.swap.targetAmount` | `string` | Amount added, as a decimal string. | | `data.swap.rate` | `string` | Exchange rate used, as a decimal string. | | `data.swap.status` | `string` | Swap status. See each event below. | | `data.swap.completedAt` | `string \| null` | When the swap completed. Null for failed swaps. | | `data.swap.createdAt` | `string` | When the swap was created (ISO 8601). | | `data.swap.quotation` | `object` | The quote the swap was made from. | | `data.swap.quotation.id` | `string` | Unique quotation identifier. | | `data.swap.quotation.fromCurrency` | `string` | Quoted source currency. | | `data.swap.quotation.toCurrency` | `string` | Quoted target currency. | | `data.swap.quotation.sourceAmount` | `string` | Quoted source amount. | | `data.swap.quotation.targetAmount` | `string` | Quoted target amount. | | `data.swap.quotation.rate` | `string` | Quoted rate. | | `data.swap.quotation.executed` | `boolean` | Whether the quote was used for a swap. | | `data.swap.quotation.expiresAt` | `string` | When the quote expires (ISO 8601). | | `data.swap.quotation.createdAt` | `string` | When the quote was created (ISO 8601). | | `data.failureReason` | `string` | Why the swap failed. Sent only with `swap.failed`. | ### Events * `swap.completed` * `swap.failed` ### `swap.completed` Sent when a swap completes and both balances are updated. `data.swap.status` is `completed`. ```json { "event": "swap.completed", "data": { "swap": { "id": "f2908051-6326-4708-bc73-1153209e7689", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.48767500", "status": "completed", "completedAt": "2026-05-29T20:25:23.680Z", "createdAt": "2026-05-29T20:25:23.640Z", "quotation": { "id": "99f41fc8-47e2-4f34-a1dd-64f52ee4ff0c", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.487675", "executed": true, "expiresAt": "2026-05-29T20:25:38.553Z", "createdAt": "2026-05-29T20:25:23.556Z" } } } } ``` ### `swap.failed` Sent when a swap fails after it has started. `data.swap.status` is `failed`. Requests that are rejected before the swap starts, such as invalid input, do not send this event. {% hint style="danger" %} Check `data.failureReason` for why the swap failed. {% endhint %} ```json { "event": "swap.failed", "data": { "swap": { "id": "f2908051-6326-4708-bc73-1153209e7689", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.48767500", "status": "failed", "completedAt": null, "createdAt": "2026-05-29T20:25:23.640Z", "quotation": { "id": "99f41fc8-47e2-4f34-a1dd-64f52ee4ff0c", "fromCurrency": "USDT", "toCurrency": "NGN", "sourceAmount": "4.00", "targetAmount": "5493.95", "rate": "1373.487675", "executed": true, "expiresAt": "2026-05-29T20:25:38.553Z", "createdAt": "2026-05-29T20:25:23.556Z" } }, "failureReason": "Swap could not be completed" } } ``` # Deposits Deposit webhook events and example payloads. Deposit webhooks track money sent to your deposit accounts, either crypto to a deposit address or a bank transfer to a virtual account. ### Field descriptions Deposit webhook events put the deposit directly in `data`. It has the same shape as a deposit returned by the API. Exactly one of `data.crypto` and `data.fiat` is set. The other is `null`. | Field | Type | Description | | ---------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data.id` | `string` | Unique deposit identifier. | | `data.type` | `'crypto' \| 'fiat'` | `crypto` for a blockchain transfer, `fiat` for a bank transfer. | | `data.status` | `string` | `pending`, `completed`, or `failed`. See each event below. | | `data.amount` | `string` | Amount received, as a decimal string. | | `data.currency` | `string` | Deposit currency, such as `USDT` or `NGN`. | | `data.fee` | `string` | Fee charged on the deposit, as a decimal string. | | `data.netAmount` | `string` | Amount credited to your balance (amount minus fee), as a decimal string. | | `data.conversion` | `object \| null` | Set when a crypto deposit was converted to USDT on arrival: `fromCurrency`, `toCurrency`, `sourceAmount`, `targetAmount`, and `rate`. | | `data.depositAccountId` | `string \| null` | The deposit account the deposit went into. | | `data.balanceReference` | `string \| null` | Reference of the balance entry this deposit credited. Null until it is credited. | | `data.customer` | `object \| null` | The customer the deposit belongs to: `id`, `firstName`, `lastName`, `email`, and `metadata`. Null for a deposit to your own account. | | `data.crypto.txHash` | `string \| null` | Transaction hash on the blockchain. | | `data.crypto.chain` | `string \| null` | Blockchain network, such as `ethereum` or `tron`. | | `data.crypto.asset` | `string \| null` | Crypto asset received, such as `USDT`. | | `data.crypto.amount` | `string` | Amount received in the asset that was sent. | | `data.crypto.fromAddress` | `string \| null` | Wallet address the funds came from. | | `data.crypto.toAddress` | `string \| null` | Deposit address the funds were sent to. | | `data.crypto.amlCheck` | `string` | Result of the compliance check: `pending`, `passed`, `failed`, or `under_review`. | | `data.crypto.staticDepositAddress` | `object \| null` | The deposit address that received the funds: `chain`, `address`, and `createdAt`. | | `data.fiat.reference` | `string \| null` | Reference for the bank transfer. | | `data.fiat.method` | `string` | Always `bank_transfer`. | | `data.fiat.payer` | `object` | Account that sent the money: `accountName`, `accountNumber`, `bankName`, `bankCode`. | | `data.fiat.payee` | `object` | Account that received the money, with the same fields as `payer`. | | `data.fiat.ngnVirtualAccount` | `object \| null` | The NGN virtual account that received the money: `currency`, `accountNumber`, `accountName`, `bankName`, `bankCode`, `accountReference`, and `createdAt`. | | `data.createdAt` | `string` | When the deposit was detected (ISO 8601). | | `data.completedAt` | `string \| null` | When the deposit was credited. Null while pending or if it failed. | ### Events * `deposit.processing` * `deposit.completed` * `deposit.failed` ### `deposit.processing` Sent when a deposit is detected and is being processed. `data.status` is `pending`. ```json { "event": "deposit.processing", "data": { "id": "dep_123456789_abcdef", "type": "crypto", "status": "pending", "amount": "100.00", "currency": "USDT", "fee": "0.50", "netAmount": "99.50", "conversion": null, "depositAccountId": "da_123456789_abcdef", "balanceReference": null, "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "customer@example.com", "metadata": { "userId": "usr_8f21c3" } }, "crypto": { "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "chain": "ethereum", "asset": "USDT", "amount": "100.00", "fromAddress": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432", "toAddress": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "amlCheck": "pending", "staticDepositAddress": { "chain": "ethereum", "address": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "createdAt": "2026-01-10T08:00:00.000Z" } }, "fiat": null, "createdAt": "2026-01-15T10:30:00.000Z", "completedAt": null } } ``` ### `deposit.completed` Sent when a deposit is credited to your balance. `data.status` is `completed`. {% tabs %} {% tab title="Crypto deposit" %} ```json { "event": "deposit.completed", "data": { "id": "dep_123456789_abcdef", "type": "crypto", "status": "completed", "amount": "100.00", "currency": "USDT", "fee": "0.50", "netAmount": "99.50", "conversion": null, "depositAccountId": "da_123456789_abcdef", "balanceReference": "BAL-9f1c4a2b7de3", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "customer@example.com", "metadata": { "userId": "usr_8f21c3" } }, "crypto": { "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "chain": "ethereum", "asset": "USDT", "amount": "100.00", "fromAddress": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432", "toAddress": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "amlCheck": "passed", "staticDepositAddress": { "chain": "ethereum", "address": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "createdAt": "2026-01-10T08:00:00.000Z" } }, "fiat": null, "createdAt": "2026-01-15T10:30:00.000Z", "completedAt": "2026-01-15T10:35:00.000Z" } } ``` {% endtab %} {% tab title="Bank transfer deposit" %} ```json { "event": "deposit.completed", "data": { "id": "dep_987654321_fedcba", "type": "fiat", "status": "completed", "amount": "150000.00", "currency": "NGN", "fee": "100.00", "netAmount": "149900.00", "conversion": null, "depositAccountId": "da_123456789_abcdef", "balanceReference": "BAL-3e7a1c9d5b20", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "customer@example.com", "metadata": { "userId": "usr_8f21c3" } }, "crypto": null, "fiat": { "reference": "NMB-12345", "method": "bank_transfer", "payer": { "accountName": "John Doe", "accountNumber": "0123456789", "bankName": "Wema Bank", "bankCode": "035" }, "payee": { "accountName": "COINCIRCUIT/John Doe", "accountNumber": "9876543210", "bankName": "Nomba Bank", "bankCode": "090645" }, "ngnVirtualAccount": { "currency": "NGN", "accountNumber": "9876543210", "accountName": "COINCIRCUIT/John Doe", "bankName": "Nomba Bank", "bankCode": "090645", "accountReference": "CCVBA-7f3a9c12", "createdAt": "2026-01-10T08:00:00.000Z" } }, "createdAt": "2026-01-15T10:30:00.000Z", "completedAt": "2026-01-15T10:31:00.000Z" } } ``` {% endtab %} {% endtabs %} ### `deposit.failed` Sent when a deposit fails a compliance check and is rejected. `data.status` is `failed`. ```json { "event": "deposit.failed", "data": { "id": "dep_123456789_abcdef", "type": "crypto", "status": "failed", "amount": "100.00", "currency": "USDT", "fee": "0.50", "netAmount": "99.50", "conversion": null, "depositAccountId": "da_123456789_abcdef", "balanceReference": null, "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "customer@example.com", "metadata": { "userId": "usr_8f21c3" } }, "crypto": { "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "chain": "ethereum", "asset": "USDT", "amount": "100.00", "fromAddress": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a098765432", "toAddress": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "amlCheck": "failed", "staticDepositAddress": { "chain": "ethereum", "address": "0x2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c", "createdAt": "2026-01-10T08:00:00.000Z" } }, "fiat": null, "createdAt": "2026-01-15T10:30:00.000Z", "completedAt": null } } ``` # Welcome Ready-to-use CoinCircuit integration prompts. Ready-to-use prompts for the most common CoinCircuit integration flows. Use these prompts with your AI coding assistant or MCP-enabled workflow. {% hint style="info" %} Each prompt is written for production-style implementation work. Pick a use case, copy the prompt, and replace the example values with your own. {% endhint %} ### Browse by category {% columns %} {% column %} #### Commerce * [E-Commerce crypto checkout](/promp-library/e-commerce-crypto-checkout) * [Donation and tip page](/promp-library/donation-and-tip-page) * [Marketplace vendor payouts](/promp-library/marketplace-vendor-payouts) {% endcolumn %} {% column %} #### Operations * [SaaS invoice billing](/promp-library/saas-invoice-billing) * [Crypto payouts](/promp-library/crypto-payouts) * [Refund and dispute handling](/promp-library/refund-and-dispute-handling) {% endcolumn %} {% endcolumns %} ### Automation and agent flows * [x402 API monetization](/promp-library/x402-api-monetization) * [Telegram bot crypto payments](/promp-library/telegram-bot-crypto-payments) ### Featured prompts
IconTitleDescriptionOpen
:cart-shopping:E-Commerce crypto checkoutEmbedded checkout, payment sessions, and webhook-driven fulfillment.E-Commerce crypto checkout
:gear:x402 API monetizationCharge AI agents per request with x402 and CoinCircuit settlement.x402 API monetization
:file-invoice:SaaS invoice billingGenerate expiring invoices with partial payment tracking and webhooks.SaaS invoice billing
:wallet:Crypto payoutsSend payouts with balance checks, fee estimation, and async status tracking.Crypto payouts
:heart:Donation and tip pageLaunch hosted or custom donation flows with flexible amount handling.Donation and tip page
:store:Marketplace vendor payoutsCollect buyer payments and pay vendors from merchant balance.Marketplace vendor payouts
:rotate-left:Refund and dispute handlingEstimate, create, and track refunds for sessions and invoices.Refund and dispute handling
:paper-plane:Telegram bot crypto paymentsCreate payment links and trigger bot actions from payment webhooks.Telegram bot crypto payments
### How to use these prompts {% stepper %} {% step %} #### Pick a use case Open the prompt that matches your integration. {% endstep %} {% step %} #### Copy the prompt Paste it into your AI assistant with the CoinCircuit MCP connected. {% endstep %} {% endstepper %} # E-Commerce crypto checkout Embedded checkout, session creation, and webhook-driven fulfillment. Use this prompt to add CoinCircuit checkout to an existing e-commerce flow. `Checkout SDK` `Webhooks` `Node.js` ### What this prompt covers * Create a payment session on your server * Launch embedded checkout or redirect to hosted checkout * Fulfill orders from verified webhook events {% code title="ecommerce-checkout.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me integrate CoinCircuit crypto payments into my existing e-commerce website. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/payments` to get the full request/response schema for creating payment sessions. - Call `search_api` with query `webhook` and type `schemas` to get all webhook payload schemas. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the exact payment.completed webhook payload. - Call `get_schema` with name `TransactionReceivedWebhookDto` for the transaction.received webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an e-commerce site and I'm adding crypto payments at checkout using CoinCircuit. The flow: 1. Customer clicks "Pay with Crypto" on my checkout page 2. My server creates a CoinCircuit payment session via `POST /api/v1/payments` 3. The embedded checkout modal opens on the frontend using the session `reference` 4. Customer pays, my server gets a webhook, and the order is fulfilled ## What I Need You to Implement ### 1. Server-side: Create a payment session **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a ready-to-use sample request.)* **Required fields:** - `title` (string) - e.g. "Order #1234" - `description` (string) - e.g. "Payment for order #1234" - `amount` (string) - fiat amount as a string, e.g. `"150.00"` (NOT a number) - `currency` (string) - `"NGN"` or `"USD"` - `customer` (object) - must include `email` (required). Optional: `firstName`, `lastName`, `phone` (E.164 format), `telegramId` **Optional fields:** - `asset` (string) - lock to a specific crypto: `"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"`. If omitted, the customer chooses on the checkout page. - `chain` (string) - lock to a specific blockchain: `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"`. If omitted, the customer chooses. - `metadata` (object) - store your internal `orderId` here for webhook reconciliation - `successUrl` (string) - redirect after successful payment (must be HTTPS) - `cancelUrl` (string) - redirect if customer cancels - `webhookUrl` (string) - per-session webhook URL override (must be HTTPS) - `feePaidBy` (string) - `"customer"` or `"merchant"`, controls who pays network gas fees. If omitted, uses your dashboard default. **Example request body:** ```json { "title": "Order #1234", "description": "2x Widget Pro", "amount": "150.00", "currency": "USD", "customer": { "email": "buyer@example.com", "firstName": "Jane", "lastName": "Smith" }, "metadata": { "orderId": "ORD-1234", "items": "2x Widget Pro" }, "successUrl": "https://mystore.com/order/1234/success", "cancelUrl": "https://mystore.com/cart" } ``` **Response (201):** Returns a session object. The key fields you need: - `data.reference` - pass this to the frontend checkout SDK - `data.url` - hosted checkout page URL (e.g. `https://checkout.coincircuit.io/pay/cs_ref_abc123`) - `data.payment.status` - starts as `"pending"` - `data.payment.address` - the deposit address (if asset/chain were specified) - `data.expiresAt` - ISO 8601 expiration timestamp *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `success` in the CoinCircuit MCP for the full response schema.)* **Error responses:** 400 (invalid input or unsupported asset/chain combo), 401 (bad API key) ### 2. Client-side: Embedded checkout Install the checkout SDK: ```bash npm install @coincircuit/checkout ``` Use `CoinCircuitCheckout` to open a modal with the session `reference` from the server response. Handle these callbacks: - `onPaymentComplete` - show success state, redirect to order confirmation - `onPaymentFailed` - show error, offer retry - `onClose` - user dismissed the modal without paying **Alternative:** Skip the SDK entirely and redirect the customer to `data.url` from the session response. This is the hosted checkout page and requires zero frontend code. ### 3. Webhook handler: Order fulfillment Set up an endpoint to receive CoinCircuit webhooks. *(Call `search_api` with query `payment webhook` and type `schemas` in the CoinCircuit MCP to list all payment and transaction webhook schemas. Then call `get_schema` on any specific one for full field details.)* **Payment events** (envelope: `{ event: string, data: { session: PaymentSession, failureReason?: string } }`): - `payment.completed` - full payment confirmed. The `data.session` object contains the full session with `payment.status: "completed"`, `payment.amountReceived`, and a `transaction` object with `txHash`, `chain`, `asset`, `fromAddress`, `toAddress`, `amount`, `explorerUrl`, `confirmations`. **This is your trigger to fulfill the order.** - `payment.partial` - customer sent crypto but not enough. `data.session.payment.amountReceived` shows what you got. The session stays open for more payments. - `payment.expired` - session expired before full payment. Cancel or hold the order. - `payment.underpaid` - session closed with less than the required amount. Check `data.session.payment.amountReceived` vs `data.session.payment.amount`. *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for every field in the payment.completed payload.)* **Transaction events** (envelope: `{ event: string, data: { session: PaymentSession } }`, the session includes a `transaction` field): - `transaction.received` - payment detected on-chain but unconfirmed. Good for showing "payment detected" UI. The `transaction` object has `status: "pending"`, `txHash`, `chain`, `asset`, `amount`, `fromAddress`, `toAddress`. - `transaction.confirmed` - payment confirmed on the blockchain. The `transaction` object has `status: "confirmed"`, `confirmations`, `confirmedAt`. *(Call `get_schema` with name `TransactionReceivedWebhookDto` or `TransactionConfirmedWebhookDto` in the CoinCircuit MCP for exact field details.)* **Webhook security:** - Verify the HMAC-SHA256 signature in the `x-webhook-signature` header using your webhook secret - Use the `x-delivery-id` header for idempotency (store processed delivery IDs and skip duplicates) **Key webhook fields for reconciliation:** - `data.session.reference` - matches the session you created - `data.session.metadata` - your `orderId` is here - `data.session.settlements.net.amount` - the amount you actually receive after all fees ## Constraints - `amount` is a **string** in fiat, not a number - Always verify webhook signatures before processing - Store the session `reference` alongside the order for reconciliation - Handle partial payments gracefully. If the session state is `"open"`, the customer can still make additional payments. If `"closed"`, no further payments are accepted. - `successUrl` and `cancelUrl` must be HTTPS - Supported currencies: NGN, USD. Supported assets: BTC, ETH, USDT, USDC, SOL, BNB, TRX. Supported chains: bitcoin, ethereum, solana, bsc, tron, base, arbitrum. ```` {% endcode %} # SaaS invoice billing Generate invoices with expiration, tracking, and webhook handling. Use this prompt to add CoinCircuit invoices to subscription billing and renewal flows. `Invoices` `Webhooks` ### What this prompt covers * Create invoices on subscription renewal * Send hosted payment links to customers * Track full and partial payments from webhooks {% code title="saas-invoice-billing.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me integrate CoinCircuit crypto invoicing into my existing SaaS billing system. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/invoices` in the CoinCircuit MCP for the full invoice creation schema. - Call `search_api` with query `invoice webhook` and type `schemas` to list all invoice webhook payload schemas. - Call `get_schema` with name `InvoicePaidWebhookDto` for the exact invoice.paid webhook payload. - Call `get_schema` with name `InvoiceExpiredWebhookDto` for the invoice.expired webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a SaaS app that bills customers monthly. I'm adding crypto invoice payments via CoinCircuit so customers can pay in any supported crypto (USDT, BTC, ETH, etc.). ## What I Need You to Implement ### 1. Invoice creation on subscription renewal **Endpoint:** `POST /api/v1/invoices` *(Call `get_endpoint` with method `post`, path `/api/v1/invoices`, section `request` in the CoinCircuit MCP for the exact request body schema with all field types and validations.)* **Required fields:** - `amount` (string) - the subscription price as a string with up to 2 decimal places, e.g. `"29.99"` - `currency` (string) - `"NGN"` or `"USD"` - `description` (string) - e.g. "Pro Plan - May 2026" - `expiresAt` (string, ISO 8601) - when the invoice expires. Max 2 days from creation. Defaults to 12 hours if omitted. - `customer` (object) - must include `email` (required). Optional: `firstName`, `lastName`, `phone` (E.164), `telegramId` **Optional fields:** - `reference` (string) - custom invoice reference, e.g. `"INV-2026-005"`. Auto-generated if omitted. - `periodStart` / `periodEnd` (string, ISO 8601) - billing period dates for subscription context - `nextPaymentDate` (string, ISO 8601) - next billing date, shown on the invoice - `metadata` (object) - store `subscriptionId`, `plan`, etc. for webhook reconciliation - `successUrl` / `cancelUrl` (string) - redirect URLs after payment - `asset` (string) - lock to a specific crypto (`"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"`) - `chain` (string) - lock to a specific blockchain (`"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"`) **Example request body:** ```json { "amount": "29.99", "currency": "USD", "description": "Pro Plan - May 2026", "expiresAt": "2026-05-03T00:00:00.000Z", "customer": { "email": "subscriber@example.com", "firstName": "John", "lastName": "Doe" }, "periodStart": "2026-05-01T00:00:00.000Z", "periodEnd": "2026-05-31T23:59:59.000Z", "nextPaymentDate": "2026-06-01T00:00:00.000Z", "metadata": { "subscriptionId": "sub_abc123", "plan": "pro" }, "successUrl": "https://myapp.com/billing/success" } ``` **Response (201):** Returns the invoice object. Key fields: - `data.id` - invoice UUID - `data.reference` - invoice reference (e.g. `"inv_ref_abc123xyz789"`) - `data.url` - payment URL (e.g. `https://checkout.coincircuit.io/invoice/inv-abc123`) - `data.status` - starts as `"pending"`, transitions to `"partial"`, `"paid"`, or `"expired"` - `data.state` - `"open"` (accepting payments) or `"closed"` (finalized) - `data.amount` / `data.amountPaid` - track payment progress - `data.isRefunded` - boolean *(Call `get_endpoint` with method `post`, path `/api/v1/invoices`, section `success` in the CoinCircuit MCP for the full response schema.)* **Error responses:** 400 (invalid input or expiresAt exceeds 2 days), 401 (bad API key) ### 2. Send the payment link The response includes `data.url`. Email this to the customer or display it in your app's billing dashboard. The hosted page handles crypto selection, address display, and payment detection automatically. ### 3. Webhook event handling *(Call `get_schema` with name `InvoicePaidWebhookDto` in the CoinCircuit MCP for the full invoice.paid webhook payload with all nested fields including the payments array.)* **Invoice events** (envelope: `{ event: string, data: { invoice: InvoiceObject, payments?: PaymentArray } }`): - `invoice.created` - confirmation the invoice was created. Good for logging. *(Call `get_schema` with name `InvoiceCreatedWebhookDto` for details.)* - `invoice.paid` - full payment received. **Activate or extend the subscription.** The `data.payments` array contains details on each payment session: `asset`, `chain`, `amount`, `address`, `txHash`, `explorerUrl`, `status`. - `invoice.updated` - partial payment received. Check `data.invoice.amountPaid` vs `data.invoice.amount` to track progress. `data.invoice.status` will be `"partial"`. *(Call `get_schema` with name `InvoiceUpdatedWebhookDto` for details.)* - `invoice.expired` - invoice expired unpaid. Suspend access or create a new invoice with a reminder email. *(Call `get_schema` with name `InvoiceExpiredWebhookDto` for details.)* **Invoice webhook data fields:** - `data.invoice.reference` - matches your invoice - `data.invoice.metadata` - your `subscriptionId` and `plan` are here - `data.invoice.amount` / `data.invoice.amountPaid` - track cumulative payments - `data.invoice.status` - `"pending"`, `"partial"`, `"paid"`, `"expired"` - `data.invoice.paidAt` - ISO 8601 timestamp when fully paid - `data.invoice.periodStart` / `data.invoice.periodEnd` - billing period - `data.invoice.customer.email` - for confirmation emails **Webhook security:** Same as checkout: verify HMAC-SHA256 via `x-webhook-signature`, deduplicate via `x-delivery-id`. ## Constraints - Invoice `amount` is a **string** with up to 2 decimal places (e.g. `"29.99"`), same as checkout sessions - `expiresAt` max is 2 days from creation. Defaults to 12 hours. - Invoices support partial payments. Track `amountPaid` before activating the subscription. - The invoice stays `"open"` until fully paid or expired - Supported currencies: NGN, USD ```` {% endcode %} # x402 API monetization Charge agents per request with x402 and CoinCircuit settlement. Use this prompt to gate API access behind x402 payments and settle agent-signed authorizations through CoinCircuit. `x402` `Agent Payments` `Payments` `Node.js` ### What this prompt covers * Create per-request payment sessions * Return `402` responses with payment details * Verify and settle signed agent payments on-chain {% code title="x402-api-monetization.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me add per-request crypto payments to my existing API using the x402 protocol and CoinCircuit for settlement. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/payments` for the checkout session creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/payments/agent/settle` for the agent settlement schema. - Call `get_endpoint` with method `post` and path `/api/v1/payments/agent/verify` for the pre-validation schema. - Call `search_api` with query `agent settle` and type `endpoints` to find all agent payment endpoints. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an API backend and I'm adding x402 payment gating so AI agents pay per-request. The flow: 1. Agent hits a paid endpoint on my API 2. My server creates a CoinCircuit payment session for the resource price 3. Returns a 402 response with the payment details (deposit address, amount, chain) 4. Agent signs the payment and sends it back 5. My server submits the signed payload to CoinCircuit for on-chain settlement 6. Delivers the resource once settlement confirms The agent only needs a wallet and signing key. No CoinCircuit API key, no gas tokens. ## What I Need You to Implement ### 1. Middleware: check for payment Create middleware that intercepts requests to paid endpoints. If the request has no payment proof, proceed to step 2 (create session + return 402). If it includes a signed payload, proceed to step 5 (settle). ### 2. Create a payment session When an agent hits a paid endpoint without payment: **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `request` in the CoinCircuit MCP for the full request body.)* ```json { "amount": "1.00", "currency": "USD", "title": "API call - /api/premium-data", "description": "Single API request", "asset": "USDC", "chain": "base", "customer": { "email": "agent@example.com" }, "metadata": { "endpoint": "/api/premium-data", "agentWallet": "0xAgentAddress..." } } ``` **Response (201):** Returns a session object with: - `data.reference` - session reference (keep this server-side for settlement) - `data.payment.address` - the deposit address - `data.payment.amount` - the required crypto amount - `data.expiresAt` - session expiration *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `success` in the CoinCircuit MCP for the full response.)* ### 3. Return the 402 response Send the payment details back to the agent. Your server stores the session reference internally, keyed by the deposit address or a short-lived token, so you can match the agent's payment to the session. ### 4. Agent signs the payment (client-side reference) The agent picks a signing scheme and produces a flat payload. Each scheme produces a payload with `from`, `to`, `value`, and scheme-specific fields: - **EIP-3009:** `validAfter`, `validBefore`, `nonce` (random 32-byte hex), `signature` - **Permit2:** `deadline`, `nonce` (numeric), `signature` - **Solana:** `transaction` (base64 partially signed tx) The agent sends this back to your server. ### 5. Pre-validate the payment (optional but recommended) Before settling, dry-run the payment: **Endpoint:** `POST /api/v1/payments/agent/verify` *(Call `get_endpoint` with method `post`, path `/api/v1/payments/agent/verify` in the CoinCircuit MCP for the full schema.)* Returns 200 if the payment will succeed, or 400 with per-check pass/fail results. Catches issues like insufficient balance, expired nonces, and invalid signatures before touching the blockchain. ### 6. Settle the payment on-chain **Endpoint:** `POST /api/v1/payments/agent/settle` *(Call `get_endpoint` with method `post`, path `/api/v1/payments/agent/settle` in the CoinCircuit MCP for the full request/response schema.)* **Always include `sessionReference` from step 2 in the settle request.** CoinCircuit uses it to verify the signed payment against the original session's required amount, deposit address, chain, and asset. Without it, these checks are skipped and the payment is not validated against the session. Also include the scheme, chain, asset, and the signed payload. CoinCircuit submits the transaction on-chain, covers gas, and returns the transaction hash and block confirmation. ### 7. Deliver the resource Once the settle response confirms success, return the requested data to the agent along with the transaction hash as a receipt. ### Integration Flow Summary ``` Agent -> GET /api/premium-data Server -> CoinCircuit: POST /payments (creates session) Server -> Agent: 402 (deposit address, amount, schemes) Agent -> Signs payment (eip3009 / permit2 / solana) Agent -> Server: POST /api/premium-data/pay (signed payload) Server -> CoinCircuit: POST /payments/agent/verify (optional) Server -> CoinCircuit: POST /payments/agent/settle Server -> Agent: 200 (resource + tx receipt) ``` ### Supported Chains and Assets | Scheme | Asset | Chains | |--------|-------|--------| | eip3009 | USDC | Base, Arbitrum | | permit2 | USDC, USDT | Base, Arbitrum, BSC | | solana | SOL, USDC, USDT | Solana | ## Constraints - **Always pass `sessionReference` in the settle call.** This is how CoinCircuit verifies the payment matches the session's required amount, deposit address, chain, and asset. Without it, those checks are skipped. - The agent signs the authorization, but your server submits it. This lets you control the session lifecycle and validate amounts before settlement. - The agent needs no CoinCircuit API key and no gas tokens. It only needs a wallet and signing capability. - Session `amount` is a **string** in fiat (e.g. `"1.00"`) - Always use the verify endpoint first in production to catch bad signatures before spending gas - Solana transactions expire in ~60 seconds based on the blockhash. Generate the session close to when the agent will sign. - EIP-3009 nonces are random 32-byte hex values. Permit2 nonces are numeric. - For Permit2, the agent must have done a one-time on-chain approval of the Permit2 contract (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) for the token - All EVM networks offer sub-second block times and gas costs under a cent. Solana settles in under a second with fees below $0.001. ```` {% endcode %} # Crypto payouts Send crypto payouts with balance checks, fees, and status tracking. Use this prompt to build merchant-balance payout flows for creators, vendors, rewards, or other external disbursements. `Payouts` `Balance` `Webhooks` ### What this prompt covers * Check available balance before payouts * Save recipient wallet addresses * Estimate fees and track payout status from webhooks {% code title="crypto-payouts.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me add crypto payouts to my existing application using CoinCircuit. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `get` and path `/api/v1/balance` in the CoinCircuit MCP for the balance response schema. - Call `get_endpoint` with method `post` and path `/api/v1/crypto-addresses` for the address creation schema. - Call `get_endpoint` with method `get` and path `/api/v1/payouts/fees` for the fee estimation schema. - Call `get_endpoint` with method `post` and path `/api/v1/payouts` for the payout creation schema. - Call `get_schema` with name `PayoutSuccessWebhookDto` for the payout.success webhook payload. - Call `get_schema` with name `PayoutFailedWebhookDto` for the payout.failed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have an application that needs to pay users in crypto (USDT) from my CoinCircuit merchant balance to their wallet addresses. Use cases: vendor payments, creator payouts, rewards, or any disbursement to external wallets. ## What I Need You to Implement ### 1. Check merchant balance **Endpoint:** `GET /api/v1/balance` *(Call `get_endpoint` with method `get`, path `/api/v1/balance` in the CoinCircuit MCP for the full response schema.)* **Query params:** - `currency` (optional) - `"NGN"` or `"USDT"`. If omitted, returns your default currency balance. **Response (200):** ```json { "success": true, "data": { "currency": "USDT", "totalBalance": "1750.50", "availableBalance": "1500.50", "pendingBalance": "250.00", "merchant": { "id": "uuid", "businessName": "My Company", "email": "me@company.com", "status": "active" } } } ``` - `availableBalance` - funds you can use right now for payouts - `pendingBalance` - funds awaiting blockchain confirmation - `totalBalance` - available + pending Always check `availableBalance >= payoutAmount + estimatedFee` before creating a payout. ### 2. Save recipient crypto addresses Before you can send a payout, the recipient wallet address must be saved. **Endpoint:** `POST /api/v1/crypto-addresses` *(Call `get_endpoint` with method `post`, path `/api/v1/crypto-addresses` in the CoinCircuit MCP for the full request/response schema.)* **Required fields:** - `chain` (string) - `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, or `"arbitrum"` - `address` (string) - the wallet address **Optional fields:** - `label` (string) - friendly name, e.g. "Alice's BSC wallet" - `isDefault` (boolean) - set as default for this chain **Response (201):** Returns the saved address with an `id` (UUID). You'll use this `id` as the `recipientId` when creating payouts. **Errors:** 400 if the address format is invalid or the address already exists for that chain. ### 3. Estimate payout fees **Endpoint:** `GET /api/v1/payouts/fees` *(Call `get_endpoint` with method `get`, path `/api/v1/payouts/fees` in the CoinCircuit MCP for the full response schema with all fee breakdowns.)* **Query params:** - `currency` (required) - `"USDT"` or `"NGN"` **Response (200):** ```json { "success": true, "data": { "currency": "USDT", "fiat": { "BankTransfer": "50.00" }, "crypto": { "USDT": { "tron": "1.00", "bsc": "0.50" }, "USDC": { "base": "0.30" } } } } ``` Display the relevant chain fee before the user confirms. For example, a USDT payout on Tron costs 1.00 USDT in fees. ### 4. Create crypto payout **Endpoint:** `POST /api/v1/payouts` *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `request` in the CoinCircuit MCP for the exact request body with all field validations.)* **Required fields:** - `method` (string) - `"crypto"` (or `"fiat"` for bank transfers) - `currency` (string) - `"USDT"` or `"NGN"` - `amount` (string) - amount to send as a string, e.g. `"100.00"` - `recipientId` (string, UUID) - the saved crypto address ID from step 2 **Optional fields:** - `narration` (string) - description, e.g. "Creator payout - March" - `reference` (string) - your unique idempotency reference. **Duplicate references are rejected.** If omitted, CoinCircuit generates one. **Example request body:** ```json { "method": "crypto", "currency": "USDT", "amount": "100.00", "recipientId": "addr_123456789_abcdef", "narration": "Creator payout - March 2026", "reference": "PAYOUT-MARCH-ALICE-001" } ``` **Response (201):** Returns the payout object: - `data.id` - payout UUID - `data.status` - starts as `"pending"`, transitions to `"processing"`, `"success"`, or `"failed"` - `data.amount` - amount the recipient gets - `data.fee` - fee charged - `data.total` - total debited from your balance (amount + fee) - `data.currency` - `"USDT"` - `data.reference` - your reference or auto-generated - `data.txHash` - blockchain transaction hash (populated after success) - `data.recipient` - object with `type: "cryptoAddress"`, `address`, `chain`, `asset` - `data.conversion` - if cross-currency, includes `from`, `to`, `rate`, `convertedAmount`. Null if same currency. - `data.failureReason` - populated if failed *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `success` in the CoinCircuit MCP for the complete response schema.)* **Errors:** 400 (validation error, insufficient balance, daily limit exceeded), 404 (recipient address not found) ### 5. Track payout status via webhooks Payouts are async. The API returns immediately with `"pending"` status. Wait for webhooks: *(Call `get_schema` with name `PayoutSuccessWebhookDto` in the CoinCircuit MCP for the full payout.success webhook payload. Call `get_schema` with name `PayoutFailedWebhookDto` for the failure payload.)* **Payout events** (envelope: `{ event: string, data: { payout: PayoutObject } }`): - `payout.created` - payout submitted and processing - `payout.success` - funds delivered on-chain. `data.payout.txHash` has the transaction hash, `data.payout.completedAt` has the timestamp. - `payout.failed` - payout failed. `data.payout.failureReason` explains why. Funds are returned to your balance. ## Constraints - Always check balance before initiating payouts - `amount` is a string (e.g. `"100.00"`) - Duplicate `reference` values are rejected. Use unique references for idempotency. - Crypto payouts support USDT (on Tron, BSC) and USDC (on Base). - Payouts are async. Never assume success from the API response. Always wait for webhooks. - Fiat payouts go only to the merchant's own bank account. Use crypto payouts for third-party disbursements. ```` {% endcode %} # Telegram bot crypto payments Create payment links and webhook-driven bot actions. Use this prompt to add CoinCircuit payments to Telegram bot commands, access gating, and renewals. `Telegram` `Payments` `Webhooks` `Node.js` ### What this prompt covers * Create payment sessions from bot actions * Send hosted checkout links in chat * Trigger bot behavior from payment webhooks {% code title="telegram-bot-crypto-payments.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me integrate CoinCircuit crypto payments into my existing Telegram bot. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_api_overview` in the CoinCircuit MCP for base URLs, auth method, and available features. - Call `get_endpoint` with method `post` and path `/api/v1/payments` for the full payment session creation schema. - Call `search_api` with query `webhook` and type `schemas` to list all webhook payload schemas. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the exact payment.completed webhook payload. - Call `get_schema` with name `TransactionReceivedWebhookDto` for the transaction.received webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL (production):** `https://api.coincircuit.io` - **Base URL (sandbox):** `https://sandbox-api.coincircuit.io` - **Auth:** Pass your API key in the `x-api-key` header on every request. ## Project Context I have an existing Telegram bot and I want to add crypto payment support using CoinCircuit. The integration should: 1. Create a CoinCircuit payment session when a user wants to pay 2. Send the hosted checkout URL to the user in chat 3. Listen for payment confirmation via webhook 4. Trigger the appropriate action in my bot (grant access, deliver content, activate subscription, etc.) This pattern works for any Telegram bot use case: subscription access, one-time purchases, premium features, tip jars, or pay-per-use commands. ## What I Need You to Implement ### 1. Create a payment session from a bot command When a user triggers a payment (e.g. via a command or button callback), create a CoinCircuit payment session from your bot's backend: **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `request` in the CoinCircuit MCP for the exact request body schema.)* **Required fields:** - `title` (string) - e.g. "Premium Channel - 30 Days" - `description` (string) - e.g. "Subscription payment for premium access" - `amount` (string) - subscription price as a string, e.g. `"9.99"` - `currency` (string) - `"USD"` or `"NGN"` - `customer` (object) - must include `email` (required). Include `telegramId` for linking. **Optional fields:** - `metadata` (object) - store `telegramUserId`, `telegramUsername`, `plan`, `channelId`, `subscriptionPeriodEnd` for webhook reconciliation - `successUrl` (string) - redirect after payment (HTTPS) - `cancelUrl` (string) - redirect if cancelled - `webhookUrl` (string) - per-session webhook URL override (HTTPS) - `asset` (string) - lock to a specific crypto: `"BTC"`, `"ETH"`, `"USDT"`, `"USDC"`, `"SOL"`, `"BNB"`, `"TRX"` - `chain` (string) - lock to a specific blockchain: `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"` **Example request body:** ```json { "title": "Premium Channel - 30 Days", "description": "Subscription payment for premium Telegram access", "amount": "9.99", "currency": "USD", "customer": { "email": "user@example.com", "telegramId": "123456789" }, "metadata": { "telegramUserId": "123456789", "telegramUsername": "johndoe", "plan": "premium-monthly", "channelId": "-1001234567890", "subscriptionPeriodEnd": "2026-04-30T23:59:59.000Z" }, "successUrl": "https://mybot.com/subscription/success" } ``` **Response (201):** Returns a session object. Key fields: - `data.reference` - session reference (store this alongside the subscription) - `data.url` - hosted checkout page URL. **Send this to the user via Telegram.** - `data.payment.status` - starts as `"pending"` - `data.expiresAt` - session expiration timestamp *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `success` in the CoinCircuit MCP for the full response schema.)* ### 2. Send checkout link to the user After creating the session, send the `data.url` to the user in chat. The hosted checkout page handles crypto selection, address display, and payment detection automatically. No additional frontend work needed. ### 3. Webhook handler: process payment confirmation Set up an endpoint to receive CoinCircuit webhooks. This is where your bot takes action after payment. *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for the full payload.)* **Payment events** (envelope: `{ event: string, data: { session: PaymentSession } }`): - `payment.completed` - full payment confirmed. **This is your trigger to take action in your bot.** - Read `data.session.metadata.telegramUserId` to identify the user - Read `data.session.metadata` for any custom data you stored (plan, product, channel ID, etc.) - Execute your bot's logic: grant access, send a file, activate a feature, update a subscription, etc. - `payment.expired` - session expired before payment. Optionally notify the user and offer a new session. - `payment.partial` - customer sent crypto but not enough. The session stays open for more payments. - `payment.underpaid` - session closed with less than the required amount. Check `data.session.payment.amountReceived` vs `data.session.payment.amount`. Handle accordingly (refund, manual review, etc.). **Transaction events:** - `transaction.received` - payment detected on-chain but unconfirmed. Optionally notify the user that payment was detected. - `transaction.confirmed` - payment confirmed on the blockchain. **Webhook security:** - Verify the HMAC-SHA256 signature in the `x-webhook-signature` header using your webhook secret - Use the `x-delivery-id` header for idempotency (store processed delivery IDs and skip duplicates) ### 4. Track payment state Store a record linking the CoinCircuit session to your bot's user: - `telegramUserId` - `sessionReference` - the CoinCircuit payment session reference - `status` (`"pending"`, `"completed"`, `"expired"`) - Any use-case-specific fields (subscription expiry, product ID, etc.) This lets you look up payment status when a user asks, and lets your webhook handler find the right user to notify. ### 5. Recurring payments (if applicable) For subscription-based flows, create a new payment session each billing cycle: 1. **Before expiry:** Send the user a renewal payment link 2. **On expiry:** If not renewed, revoke access or downgrade 3. **On renewal payment:** Update the subscription period Store the `subscriptionPeriodEnd` in session metadata so your webhook handler knows the new expiry. ## Constraints - Session `amount` is a **string** in fiat, not a number (e.g. `"9.99"`) - Store the `telegramUserId` in both the session `metadata` and `customer.telegramId` for reconciliation - Always verify webhook signatures before taking action - Only act on `payment.completed`, not on partial or pending events - `successUrl` and `cancelUrl` must be HTTPS - Supported currencies: NGN, USD. Supported assets: BTC, ETH, USDT, USDC, SOL, BNB, TRX. Supported chains: bitcoin, ethereum, solana, bsc, tron, base, arbitrum. ```` {% endcode %} # Marketplace vendor payouts Collect buyer payments and route vendor payouts from merchant balance. Use this prompt to model a marketplace flow where buyers pay once and vendors get paid out later from merchant balance. `Payments` `Payouts` `Balance` ### What this prompt covers * Create checkout sessions for marketplace orders * Queue vendor payouts after payment completion * Manage rates, balances, and payout tracking {% code title="marketplace-vendor-payouts.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me integrate CoinCircuit into my existing marketplace for buyer payments and vendor payouts. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/payments` in the CoinCircuit MCP for the checkout session creation schema. - Call `get_endpoint` with method `get` and path `/api/v1/balance` for the balance response schema. - Call `get_endpoint` with method `post` and path `/api/v1/payouts` for the payout creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/crypto-addresses` for the address creation schema. - Call `get_endpoint` with method `get` and path `/api/v1/rates/convert` for the exchange rate schema. - Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload. - Call `get_schema` with name `PayoutSuccessWebhookDto` for the payout.success webhook payload. - Call `get_schema` with name `PayoutFailedWebhookDto` for the payout.failed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a marketplace that collects payment from buyers, takes a platform fee, and distributes the rest to vendors. I'm integrating CoinCircuit for crypto payments. CoinCircuit does not natively split payments, so the architecture is: ``` Buyer pays crypto -> CoinCircuit collects -> Merchant balance grows -> I pay out to vendors ``` **Important:** Vendor distribution uses crypto payouts (USDT to wallet addresses). Fiat payouts go only to the merchant's own bank account, not to third-party vendors. ## What I Need You to Implement ### 1. Collect payment from buyer **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a ready-to-use sample request.)* Create a checkout session for the full order amount. Store the vendor split in `metadata`: ```json { "title": "Order #ORD-123", "description": "Marketplace order with 2 vendors", "amount": "150.00", "currency": "USD", "customer": { "email": "buyer@example.com" }, "metadata": { "orderId": "ORD-123", "platformFee": "15.00", "vendors": [ { "vendorId": "v1", "amount": "90.00", "cryptoAddressId": "addr_v1_uuid" }, { "vendorId": "v2", "amount": "45.00", "cryptoAddressId": "addr_v2_uuid" } ] }, "successUrl": "https://marketplace.com/order/ORD-123/success", "cancelUrl": "https://marketplace.com/cart" } ``` Response gives you `data.reference` for the checkout SDK and `data.url` for the hosted page. ### 2. On payment.completed, queue vendor payouts When the `payment.completed` webhook fires: *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP to see every field in the webhook payload, including settlements and transaction details.)* 1. Verify the signature (`x-webhook-signature`, HMAC-SHA256) 2. Check idempotency (`x-delivery-id`) 3. Parse vendor split from `data.session.metadata.vendors` 4. Lock the conversion rate from `data.session.payment.conversionRate` and `data.session.settlements` 5. Deduct your platform fee 6. Queue crypto payouts for each vendor ### 3. Check balance before paying vendors **Endpoint:** `GET /api/v1/balance?currency=USDT` *(Call `get_endpoint` with method `get`, path `/api/v1/balance` in the CoinCircuit MCP for the full response schema.)* Verify `availableBalance` covers all vendor payouts plus fees. The response includes `totalBalance`, `availableBalance`, and `pendingBalance`. ### 4. Pay vendors via crypto payouts **Endpoint:** `POST /api/v1/payouts` *(Call `get_endpoint` with method `post`, path `/api/v1/payouts`, section `request` in the CoinCircuit MCP for the exact request body with all field validations.)* For each vendor: ```json { "method": "crypto", "currency": "USDT", "amount": "90.00", "recipientId": "addr_v1_uuid", "narration": "Vendor payout - Order ORD-123", "reference": "PAYOUT-ORD123-V1" } ``` Each payout returns with `status: "pending"`. The response includes `fee`, `total` (amount + fee), and `conversion` details if cross-currency. ### 5. Track vendor payout status *(Call `get_schema` with name `PayoutSuccessWebhookDto` and `PayoutFailedWebhookDto` in the CoinCircuit MCP for the full webhook payloads.)* **Webhook events:** - `payout.success` - funds delivered. `data.payout.txHash` and `data.payout.completedAt` confirm delivery. - `payout.failed` - payout failed. `data.payout.failureReason` explains why. Funds return to your balance. Retry or escalate. ### 6. Vendor onboarding Each vendor saves their crypto wallet address: **Endpoint:** `POST /api/v1/crypto-addresses` *(Call `get_endpoint` with method `post`, path `/api/v1/crypto-addresses` in the CoinCircuit MCP for the full request/response schema.)* ```json { "chain": "tron", "address": "TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT", "label": "Vendor Alice - Tron wallet", "isDefault": true } ``` Supported chains: `"bitcoin"`, `"ethereum"`, `"solana"`, `"bsc"`, `"tron"`, `"base"`, `"arbitrum"`. The response `data.id` is the UUID you use as `recipientId` in payouts. ### 7. Exchange rates for display **Endpoint:** `GET /api/v1/rates/convert?from=USDT&to=NGN` *(Call `get_endpoint` with method `get`, path `/api/v1/rates/convert` in the CoinCircuit MCP for the full response schema. You can also call `get_all_conversion_rates` in the CoinCircuit MCP to see all live rates.)* Returns: ```json { "success": true, "data": { "rate": 1462.1, "from": "USDT", "to": "NGN", "timestamp": "2025-01-15T10:30:00.000Z" } } ``` Both `from` and `to` must be uppercase. Supports fiat (NGN, USD, EUR, GBP) and crypto (BTC, ETH, USDT, USDC, BNB, SOL, XRP). Use this to show vendors their expected payout in local currency. ## Constraints - Store vendor split data in payment `metadata` so your webhook handler can process it - Check `availableBalance` before creating vendor payouts - Use unique `reference` values per payout. Duplicates are rejected. - Exchange rates fluctuate. Lock amounts at payment time using the session's conversion rate from `data.session.settlements.gross.conversionRate`. - Fiat payouts go only to the merchant's own bank account. Use crypto payouts for vendor distribution. - Payout `amount` is a string. Balance values are also strings. ```` {% endcode %} # Donation and tip page Launch hosted or custom donation flows with CoinCircuit. Use this prompt to create a hosted payment page or a fully custom donation flow. `Payment Pages` `Payments` `Frontend` ### What this prompt covers * Create hosted payment pages with open amounts * Build a custom branded donation experience * Track donation completion from webhooks {% code title="donation-tip-page.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me add a crypto donation/tip page to my existing site using CoinCircuit. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `get_endpoint` with method `post` and path `/api/v1/payments/pages` in the CoinCircuit MCP for the full payment page creation schema. - Call `get_endpoint` with method `post` and path `/api/v1/payments` for the checkout session creation schema (needed for Option B). - Call `search_api` with feature `Payment Pages` to see all available payment page endpoints (create, update, delete, list). - Call `get_schema` with name `PaymentCompletedWebhookDto` for the payment.completed webhook payload. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have a site and I'm adding a public page where supporters can donate any amount in crypto. ## What I Need You to Implement ### Option A: Payment Page (zero backend, simplest approach) CoinCircuit has hosted payment pages with open-amount input. One API call and you get a shareable URL. **Endpoint:** `POST /api/v1/payments/pages` *(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `request` in the CoinCircuit MCP for the exact request body with all field types and validations.)* **Required fields:** - `title` (string, 1-100 chars) - e.g. "Support My Project" - `isActive` (boolean) - set to `true` - `currency` (string) - `"NGN"` or `"USD"` **Optional fields:** - `description` (string) - displayed on the page - `minAmount` (number) - minimum donation amount - `bankAccountIds` (array of strings) - associate bank accounts for fiat settlement **Example request:** ```json { "title": "Support My Project", "description": "Help me keep building open source tools", "isActive": true, "currency": "USD", "minAmount": 1 } ``` **Response (201):** Returns the payment page object: - `data.reference` - page reference - `data.url` - the hosted page URL (e.g. `https://checkout.coincircuit.io/static/1234567890`). Share this anywhere. *(Call `get_endpoint` with method `post`, path `/api/v1/payments/pages`, section `success` in the CoinCircuit MCP for the full response schema.)* No backend required. Share the URL on social media, your website, or anywhere. Donors enter any amount they choose. ### Option B: Custom branded donation page (full UI control) For full control over the design: 1. Build a frontend with an open amount input field 2. On "Donate" click, your backend creates a checkout session: **Endpoint:** `POST /api/v1/payments` *(Call `get_endpoint` with method `post`, path `/api/v1/payments`, section `example` in the CoinCircuit MCP for a sample request.)* Required fields: `title`, `description`, `amount` (string), `currency`, `customer` (with at least `email`). Store donor info in `metadata`: ```json { "title": "Donation", "description": "Donation from Jane", "amount": "25.00", "currency": "USD", "customer": { "email": "jane@example.com" }, "metadata": { "donorName": "Jane", "message": "Keep up the great work!" }, "successUrl": "https://mysite.com/thanks" } ``` 3. Open the checkout SDK modal with the session `reference`, or redirect to `data.url` ### Webhook handler Listen for `payment.completed` to: - Display the donor on a public wall (read `data.session.metadata.donorName` and `data.session.metadata.message`) - Update a running donation total (read `data.session.amount` and `data.session.currency`) - Send a thank-you email (read `data.session.customer.email`) *(Call `get_schema` with name `PaymentCompletedWebhookDto` in the CoinCircuit MCP for every field available in the webhook payload.)* ### Updating or deleting a payment page *(Call `search_api` with feature `Payment Pages` in the CoinCircuit MCP to see all available endpoints: create, update, delete, list, and get by reference.)* - `PUT /api/v1/payments/pages/{reference}` - update title, description, or deactivate the page - `DELETE /api/v1/payments/pages/{reference}` - delete the page *(Call `get_endpoint` with method `put`, path `/api/v1/payments/pages/{reference}` in the CoinCircuit MCP for the update request schema.)* ## Constraints - Payment pages are the zero-code option for basic donation pages - For custom amounts, validate minimum amount server-side - Session `amount` is a string in fiat (e.g. `"25.00"`) - Use `metadata` to store donor info without needing CoinCircuit customer records - Supported currencies: NGN, USD ```` {% endcode %} # Refund and dispute handling Estimate, create, and track refunds for sessions and invoices. Use this prompt to add refund estimation, refund creation, and refund status tracking to your support workflow. `Refunds` `Webhooks` `Support` ### What this prompt covers * Estimate refund outcomes before sending funds * Create refunds for sessions and invoices * Track refund progress with webhook events {% code title="refund-dispute-handling.prompt.md" expandable="true" collapsedlinecount="20" %} ````markdown You are helping me add refund handling to my existing CoinCircuit payment integration. I have the CoinCircuit MCP server connected. **If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:** - Call `search_api` with feature `Refunds` in the CoinCircuit MCP to see all available refund endpoints (estimate, create session refund, create invoice refund, list, get by ID). - Call `get_endpoint` with method `post` and path `/api/v1/refunds/session/{sessionReference}` for the session refund request/response schema. - Call `get_endpoint` with method `post` and path `/api/v1/refunds/invoice/{invoiceReference}` for the invoice refund schema. - Call `get_endpoint` with method `get` and path `/api/v1/refunds/estimate/{reference}` for the refund estimation schema. - Call `get_schema` with name `RefundCreatedWebhookDto` for the refund.created webhook payload. - Call `get_schema` with name `RefundSuccessWebhookDto` for the refund.success webhook payload. - Call `get_schema` with name `RefundFailedWebhookDto` for the refund.failed webhook payload. - Call `get_schema` with name `RefundResponseDto` for the full refund object shape used in both API responses and webhooks. Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP. ## API Basics - **Base URL:** `https://api.coincircuit.io` - **Auth:** `x-api-key` header on every request. ## Project Context I have an application using CoinCircuit for payments and I need to handle customer refund requests for both checkout session payments and invoice payments. CoinCircuit sends crypto refunds to a wallet address you specify. ## What I Need You to Implement ### 1. Estimate refund before processing Before issuing a refund, show the customer what they'll receive after fees. **Endpoint:** `GET /api/v1/refunds/estimate/{reference}?entity={type}` *(Call `get_endpoint` with method `get`, path `/api/v1/refunds/estimate/{reference}` in the CoinCircuit MCP for the full parameter and response details.)* **Path params:** - `reference` (string) - the session reference (e.g. `CS_1234567890`) or invoice reference (e.g. `INV_1234567890`) **Query params:** - `entity` (required) - `"session"` or `"invoice"` - `feePaidBy` (optional) - `"merchant"` or `"customer"` Use this to display a confirmation screen: "Refund amount: X USDT, Network fee: Y USDT, Customer receives: Z USDT". ### 2. Refund a checkout session **Endpoint:** `POST /api/v1/refunds/session/{sessionReference}` *(Call `get_endpoint` with method `post`, path `/api/v1/refunds/session/{sessionReference}`, section `request` in the CoinCircuit MCP for the exact request body.)* **Path params:** - `sessionReference` (string) - the session reference from the original payment **Request body:** - `refundAddress` (string, **required**) - the customer's wallet address to receive the refund - `reason` (string, optional) - e.g. "Customer requested refund", "Product not delivered" - `feePaidBy` (string, optional) - `"merchant"` or `"customer"`. Defaults to your dashboard settings. Controls who absorbs the blockchain gas fee. **Example:** ```json { "refundAddress": "TF6yMCJqFcT6wFFutxVmRocKgJFD5imKUT", "reason": "Customer requested refund - product not as described", "feePaidBy": "merchant" } ``` **Response (201):** Returns the refund object: - `data.id` - refund UUID - `data.entity` - `"session"` - `data.reference` - the session reference - `data.status` - `"pending"`, `"processing"`, `"completed"`, or `"failed"` - `data.chain` - blockchain used for the refund (matches original payment) - `data.asset` - crypto asset (e.g. `"USDT"`) - `data.amount` - crypto amount the customer receives (e.g. `"49.50000000"`) - `data.fee` - network fee in crypto (e.g. `"0.50000000"`) - `data.feePaidBy` - `"merchant"` or `"customer"` - `data.balanceSource` - `"merchantBalance"` or `"pendingBalance"` - `data.merchantDebitAmount` - fiat amount debited from your balance - `data.fiatAmount` / `data.fiatCurrency` - fiat value of the refund - `data.refundAddress` - customer's wallet - `data.txHash` - blockchain tx hash (populated on completion) - `data.explorerUrl` - block explorer link (populated on completion) *(Call `get_schema` with name `RefundResponseDto` in the CoinCircuit MCP for every field in the refund object, including which are required vs optional.)* ### 3. Refund an invoice **Endpoint:** `POST /api/v1/refunds/invoice/{invoiceReference}` *(Call `get_endpoint` with method `post`, path `/api/v1/refunds/invoice/{invoiceReference}` in the CoinCircuit MCP for the full schema.)* Same request body as session refunds: `refundAddress` (required), `reason` (optional), `feePaidBy` (optional). Same response shape. ### 4. Track refund status via webhooks *(Call `get_schema` with name `RefundSuccessWebhookDto` in the CoinCircuit MCP for the full refund.success webhook payload. Call `get_schema` with name `RefundFailedWebhookDto` for the failure payload.)* **Refund events** (envelope: `{ event: string, data: { refund: RefundObject } }`): - `refund.created` - refund initiated, blockchain transaction pending. `data.refund.status` is `"pending"`. *(Call `get_schema` with name `RefundCreatedWebhookDto` for the full payload.)* - `refund.success` - crypto sent to customer's wallet. `data.refund.txHash` and `data.refund.explorerUrl` are populated. `data.refund.completedAt` has the timestamp. - `refund.failed` - refund failed (insufficient hot wallet balance, invalid address, etc.). `data.refund.status` is `"failed"`. **Refund object fields in webhook:** - `data.refund.id` - refund UUID - `data.refund.entity` - `"session"` or `"invoice"` - `data.refund.reference` - original session/invoice reference - `data.refund.status` - `"pending"`, `"processing"`, `"completed"`, `"failed"` - `data.refund.amount` - crypto amount customer receives - `data.refund.fee` - network fee - `data.refund.feePaidBy` - who paid the fee - `data.refund.refundAddress` - customer's wallet - `data.refund.txHash` - blockchain tx hash (on success) - `data.refund.explorerUrl` - block explorer URL (on success) - `data.refund.merchantDebitAmount` - fiat amount debited from merchant - `data.refund.fiatAmount` / `data.refund.fiatCurrency` - fiat value ### 5. Query refund history *(Call `search_api` with feature `Refunds` in the CoinCircuit MCP to see all listing and detail endpoints.)* **List all refunds:** `GET /api/v1/refunds` (returns paginated list) *(Call `get_endpoint` with method `get`, path `/api/v1/refunds` in the CoinCircuit MCP for pagination params and response schema.)* **Get single refund:** `GET /api/v1/refunds/{id}` *(Call `get_endpoint` with method `get`, path `/api/v1/refunds/{id}` in the CoinCircuit MCP for the full response.)* Use these to build a support dashboard showing all refunds with their status, amounts, and transaction details. ### 6. Customer communication flow Build email/notification triggers based on webhook events: - On `refund.created`: "Your refund has been initiated. We're sending {amount} {asset} to your wallet." - On `refund.success`: "Your refund of {amount} {asset} has been sent to {refundAddress}. Track it here: {explorerUrl}" - On `refund.failed`: "We encountered an issue processing your refund. Our team is looking into it. Reference: {reference}" ## Constraints - `refundAddress` is **required**. CoinCircuit needs to know where to send the crypto. - Refunds are async. The API returns immediately with `"pending"` status. Use webhooks for final status. - A session or invoice can only be refunded **once**. - You cannot refund more than the original payment amount. - The refund is sent in crypto (on the same chain/asset as the original payment) regardless of the original fiat denomination. - Network fees (gas) may be deducted from the refund amount (if `feePaidBy: "customer"`) or from your merchant balance (if `feePaidBy: "merchant"`). - Use the estimate endpoint first to show the customer what they'll receive. - Refund statuses: `"pending"` -> `"processing"` -> `"completed"` or `"failed"`. ```` {% endcode %} # Changelog New updates and improvements Track API changes, new features, migration guides, and deprecation notices. {% hint style="info" %} Each release starts with the headline changes first. Expand the examples when you need implementation detail. {% endhint %} {% updates format="full" %} {% update date="2026-03-01" %} ## v2.1.0 — x402 Agent Payments, Base, and Arbitrum New endpoints now support AI agent payments with gasless stablecoin transfers. Base and Arbitrum are also now supported across payment sessions and agent payments. ### Highlights * Added `POST /payments/agent/settle` * Added `POST /payments/agent/verify` * Added x402 payment session support * Added Base and Arbitrum support ### Agent payments #### `POST /payments/agent/settle` Settle gasless stablecoin payments from AI agents. This endpoint accepts signed payloads from: * `eip3009` for USDC on Base and Arbitrum * `permit2` for USDC and USDT on Base, Arbitrum, and BSC * `solana` for SOL, USDC, and USDT on Solana CoinCircuit submits the transaction on-chain and covers gas.
Example request ```json POST /api/v1/payments/agent/settle { "sessionReference": "cs_ref_abc123", "scheme": "eip3009", "chain": "base", "asset": "USDC", "payload": { "from": "0xAgentWallet...", "to": "0xDepositAddress...", "value": "1000000", "validAfter": "0", "validBefore": "1774055094", "nonce": "0xrandom32bytes...", "signature": "0xabcd...1234" } } ```
#### `POST /payments/agent/verify` Pre-validate a signed agent payment before touching the blockchain. This runs scheme-specific checks and returns `200` for a valid payment, or `400` with per-check results.
Example request and response ```json POST /api/v1/payments/agent/verify { "scheme": "eip3009", "chain": "base", "asset": "USDC", "payload": { ... } } ``` ```json { "valid": true, "checks": { "balance": "pass", "nonce": "pass", "authorization": "pass" } } ```
#### x402 HTTP 402 payment flow Payment sessions now work in the x402 flow. {% stepper %} {% step %} ### Create a payment session Create a session with `POST /payments`. {% endstep %} {% step %} ### Return `402 Payment Required` Return deposit details to the agent in the `402` response. {% endstep %} {% step %} ### Receive the signed payload The agent signs the payment with `eip3009`, `permit2`, or `solana`. {% endstep %} {% step %} ### Settle the payment Call `POST /payments/agent/settle` and deliver the resource. {% endstep %} {% endstepper %}
View end-to-end flow ``` Agent -> GET /api/premium-data Server -> CoinCircuit: POST /payments Server -> Agent: 402 (deposit address, amount) Agent -> Signs payment (eip3009 / permit2 / solana) Agent -> Server: POST /pay (signed payload) Server -> CoinCircuit: POST /payments/agent/settle Server -> Agent: 200 (resource delivered) ```
### Supported schemes and chains * `eip3009` — USDC on Base and Arbitrum * `permit2` — USDC and USDT on Base, Arbitrum, and BSC * `solana` — SOL, USDC, and USDT on Solana ### New supported blockchains #### Base Base is now supported for all payment sessions. USDC on Base settles in under 2 seconds. Base is also the default chain for EIP-3009 agent payments. #### Arbitrum Arbitrum One is now supported for all payment sessions. It supports USDC and USDT with both EIP-3009 and Permit2. {% endupdate %} {% update date="2026-02-01" %} ## v2.0.0 — Payment API Transition and Payouts Unified This release updates payment session payloads, renames webhook event types, and introduces a unified payouts API. Existing API keys keep their current behavior. New API keys use the updated format automatically. ### Highlights * Renamed webhook event types from `session.*` to `payment.*` * Redesigned payment session response shape * Added inline `settlements` * Unified payouts under `POST /payouts` * Deprecated legacy payout endpoints ### Payment API changes #### Webhook event types renamed Payment session event names now use `payment.*` instead of `session.*`. The payload shape stays the same. Only the event type string changes. {% tabs %} {% tab title="Previous" %} ```javascript "session.completed" "session.expired" "session.partial" "session.failed" ``` {% endtab %} {% tab title="New" %} ```javascript "payment.completed" "payment.expired" "payment.partial" "payment.underpaid" "payment.failed" ``` {% endtab %} {% endtabs %} #### New API keys use the updated format automatically Versioning is tied to your API key: * Existing API keys keep the current response shape and event types * New API keys use the updated response shape and webhook names * No extra config is required {% hint style="success" %} No change is required to keep your current integration working. Create a new API key only when you are ready to adopt the new format. {% endhint %} #### Session response shape redesigned The session response is now flatter: * `status` is replaced by `state` * `amount` and `currency` are now top-level strings * `gross`, `fees`, and `net` move to `settlements`
View full session response example ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "reference": "cs_ref_abc123xyz789", "state": "closed", "type": "payment", "amount": "10000.00", "currency": "NGN", "payment": { "status": "completed", "asset": "USDT", "chain": "tron", "amount": "6.84", "amountReceived": "6.84", "address": "T...", "txHash": "0x..." }, "settlements": { "currency": "NGN", "gross": { "amount": "10000.00", "conversionRate": "1.0" }, "fees": { "processing": { "amount": "100.00", "paidBy": "merchant" }, "gas": { "amount": "50.00", "paidBy": "merchant" } }, "net": { "amount": "9850.00" } }, "customer": { ... }, "createdAt": "...", "expiresAt": "...", "completedAt": "..." } ```
#### `state` replaces `status` The top-level session status is now binary: * `open` while the session is active * `closed` once the session is finalized The payment outcome now lives in `payment.status`. {% tabs %} {% tab title="Previous" %} ```javascript { "status": "completed" } // "pending" | "completed" | "expired" | "failed" ``` {% endtab %} {% tab title="New" %} ```javascript { "state": "closed" } // "open" | "closed" // payment outcome lives in payment.status ``` {% endtab %} {% endtabs %} #### `settlements` is now included in the payment response Payment session responses now include settlement details inline. You no longer need a separate settlements lookup for the same breakdown.
View `settlements` example ```json { "settlements": { "currency": "NGN", "gross": { "amount": "10000.00", "conversionRate": "1.0" }, "fees": { "processing": { "amount": "100.00", "paidBy": "merchant" }, "gas": { "amount": "50.00", "paidBy": "merchant" } }, "net": { "amount": "9850.00" } } } ```
### Payouts API changes {% hint style="warning" %} `/payout/fiat` and `/payout/crypto` are deprecated. They will be removed on March 30, 2026. {% endhint %} #### Legacy payout endpoints replaced by `/payouts` Use the unified payouts API for both fiat and crypto payouts. Fee lookup is also now unified. {% tabs %} {% tab title="Previous" %} ``` POST /payout/fiat POST /payout/crypto GET /payout/fiat/fee GET /payout/crypto/fee ``` {% endtab %} {% tab title="New" %} ``` POST /payouts GET /payouts/fees ``` {% endtab %} {% endtabs %} #### Unified payout request body Use `method` to choose fiat or crypto. Use `recipientId` instead of `bankAccountId` or `addressId`.
View example request ```json { "method": "fiat", "currency": "NGN", "amount": "10000.00", "recipientId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "narration": "Payout", "reference": "CLIENT-REF-123" } ```
#### Amount now means what the recipient receives The old API treated `amount` as the total deducted from your balance. The new API treats `amount` as the amount delivered to the recipient. Fees are charged separately. {% tabs %} {% tab title="Previous" %} ```javascript { "amount": "10050.00" } // fee: 50.00 // recipient gets: 10000.00 ``` {% endtab %} {% tab title="New" %} ```javascript { "amount": "10000.00" } // fee: 50.00 // total deducted: 10050.00 ``` {% endtab %} {% endtabs %} #### Payout response redesigned The response now uses flat amount fields, a unified `recipient` object, and a `conversion` object when payout currency differs from the balance currency.
View full payout response example ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "method": "crypto", "type": "manual", "status": "success", "amount": "100.00", "fee": "1.50", "total": "101.50", "currency": "USDC", "conversion": { "from": "USDT", "to": "USDC", "rate": "0.9998", "convertedAmount": "100.00" }, "recipient": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "type": "cryptoAddress", "address": "T...", "chain": "tron", "asset": "USDC" }, "txHash": "0x...", "reference": "CLIENT-REF-123", "narration": "Payout", "createdAt": "...", "completedAt": "..." } ```
### Migration guide Follow these steps to move to the new format. You can adopt them incrementally. {% stepper %} {% step %} ### 1. Generate a new API key New API keys automatically use the updated format. Keep your existing key for the current integration. Test the new key before switching production traffic. {% endstep %} {% step %} ### 2. Update webhook event handlers Replace `session.*` event strings with `payment.*` equivalents in your webhook handler. ```javascript "session.completed" -> "payment.completed" "session.expired" -> "payment.expired" "session.partial" -> "payment.partial" "session.failed" -> "payment.failed" ``` {% endstep %} {% step %} ### 3. Update `payment.partial` handling `payment.partial` is now strictly mid-flow. It only fires when the session is still open and waiting for more funds. Terminal underpayment now emits `payment.underpaid`. ```javascript if (event === "payment.partial") { // data.session.state === "open" notifyCustomerOfPartialPayment(data.session.payment.amountReceived); } if (event === "payment.underpaid") { // data.session.state === "closed" initiateRefundFlow(data.session.payment.amountReceived); } ``` {% endstep %} {% step %} ### 4. Update session response parsing Move parsing logic from nested `amount` fields to top-level `amount`, `currency`, and `settlements`. ```javascript // Previous session.status session.amount.requested.amount session.amount.requested.currency session.amount.gross session.amount.fees session.amount.net // New session.state session.amount session.currency session.settlements.gross session.settlements.fees session.settlements.net ``` {% endstep %} {% step %} ### 5. Migrate payout endpoints Replace legacy payout endpoints with `POST /payouts`. Add `method` to the request body. Replace `bankAccountId` or `addressId` with `recipientId`. Replace fee lookups with `GET /payouts/fees`. ```javascript // Old POST /payout/fiat { balanceCurrency, amount, bankAccountId, narration } POST /payout/crypto { balanceCurrency, amount, addressId } // New POST /payouts { method: "fiat" | "crypto", currency: "NGN", amount: "10000.00", recipientId: "...", narration: "...", reference: "..." } ``` {% endstep %} {% step %} ### 6. Update payout amount handling Remove any logic that adds fees into the request amount. In the new API, `amount` is the amount the recipient receives. ```javascript // Old const amount = recipientAmount + fee; POST /payout/fiat { amount: "10050.00" } // New POST /payouts { amount: "10000.00" } ``` {% endstep %} {% step %} ### 7. Update payout response parsing Move response parsing from nested amount and endpoint-specific recipient objects to flat fields and the unified `recipient` object. ```javascript // Old response fields payout.amount.gross payout.amount.fee payout.amount.net payout.amount.currency payout.bankAccount payout.crypto.amount payout.crypto.chain payout.crypto.address // New response fields payout.amount payout.fee payout.total payout.currency payout.recipient.type payout.recipient.address payout.recipient.chain payout.recipient.bankName payout.conversion ``` {% endstep %} {% endstepper %} {% endupdate %} {% endupdates %}