> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/payments.md).

# 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"]},"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"]},"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"]},"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"]},"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"]},"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"]}}}}
```

## 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"]},"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"]}},{"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"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/payments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.