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

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