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


---

# 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/refunds.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.