Refunds
Create and track refunds
Refunds the money received in a payment session back to the customer.
Your API key (obtain from dashboard)
Session reference
Reason for refund
Customer wallet address to receive the refund
Who pays the blockchain fee. Defaults to merchant settings.
Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.
https://example.com/webhooksIndicates if the request was successful
trueResponse message
SuccessPOST /api/v1/refunds/session/{sessionReference} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"reason": "text",
"refundAddress": "text",
"feePaidBy": "merchant",
"webhookUrl": "https://example.com/webhooks"
}{
"success": true,
"message": "Success",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"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",
"merchantDebitAmount": "10000.00",
"balanceSource": "settled",
"refundAddress": "TXyz1234567890abcdef",
"txHash": "0x1234567890abcdef1234567890abcdef12345678",
"explorerUrl": "https://tronscan.org/#/transaction/abc123",
"createdAt": "2024-01-15T10:30:00.000Z",
"completedAt": "2024-01-15T10:35:00.000Z"
}
}Refunds the money paid for an invoice back to the customer.
Your API key (obtain from dashboard)
Invoice reference
Reason for refund
Customer wallet address to receive the refund
Who pays the blockchain fee. Defaults to merchant settings.
Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.
https://example.com/webhooksIndicates if the request was successful
trueResponse message
SuccessPOST /api/v1/refunds/invoice/{invoiceReference} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 107
{
"reason": "text",
"refundAddress": "text",
"feePaidBy": "merchant",
"webhookUrl": "https://example.com/webhooks"
}{
"success": true,
"message": "Success",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"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",
"merchantDebitAmount": "10000.00",
"balanceSource": "settled",
"refundAddress": "TXyz1234567890abcdef",
"txHash": "0x1234567890abcdef1234567890abcdef12345678",
"explorerUrl": "https://tronscan.org/#/transaction/abc123",
"createdAt": "2024-01-15T10:30:00.000Z",
"completedAt": "2024-01-15T10:35:00.000Z"
}
}Returns all refunds.
Your API key (obtain from dashboard)
Page number (1-based)
1Example: 1Number of items per page
10Example: 10Filter by refund status
Filter by payment session reference
Filter by invoice reference
Search term for session or invoice reference
Filter refunds created from this date/time (ISO 8601)
2026-03-01T00:00:00ZFilter refunds created up to this date/time (ISO 8601)
2026-03-11T23:59:59ZIndicates if the request was successful
trueResponse message
SuccessGET /api/v1/refunds HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"success": true,
"message": "Success",
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"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",
"merchantDebitAmount": "10000.00",
"balanceSource": "settled",
"refundAddress": "TXyz1234567890abcdef",
"txHash": "0x1234567890abcdef1234567890abcdef12345678",
"explorerUrl": "https://tronscan.org/#/transaction/abc123",
"createdAt": "2024-01-15T10:30:00.000Z",
"completedAt": "2024-01-15T10:35:00.000Z"
}
],
"meta": {
"page": 1,
"size": 10,
"total": 42,
"totalPages": 5
}
}Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter.
Your API key (obtain from dashboard)
Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)
CS_1234567890Entity type - whether the reference is for a session or invoice
sessionPossible values: Who will pay the network fee
customerPossible values: No content
GET /api/v1/refunds/estimate/{reference}?entity=session HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
No content
Returns the refund for the given ID.
Your API key (obtain from dashboard)
Refund ID
Indicates if the request was successful
trueResponse message
SuccessGET /api/v1/refunds/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"success": true,
"message": "Success",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"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",
"merchantDebitAmount": "10000.00",
"balanceSource": "settled",
"refundAddress": "TXyz1234567890abcdef",
"txHash": "0x1234567890abcdef1234567890abcdef12345678",
"explorerUrl": "https://tronscan.org/#/transaction/abc123",
"createdAt": "2024-01-15T10:30:00.000Z",
"completedAt": "2024-01-15T10:35:00.000Z"
}
}Last updated
Was this helpful?