> 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/settlements.md).

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