Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Refunds

Create and track refunds

Process session refund

post
/api/v1/refunds/session/{sessionReference}

Refunds the money received in a payment session back to the customer.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
sessionReferencestringRequired

Session reference

Body
reasonstringOptional

Reason for refund

refundAddressstringRequired

Customer wallet address to receive the refund

feePaidBystring · enumOptional

Who pays the blockchain fee. Defaults to merchant settings.

Possible values:
webhookUrlstringOptional

Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.

Example: https://example.com/webhooks
Responses
201Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
post/api/v1/refunds/session/{sessionReference}
POST /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"
}
201Success
{
  "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"
  }
}

Process invoice refund

post
/api/v1/refunds/invoice/{invoiceReference}

Refunds the money paid for an invoice back to the customer.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
invoiceReferencestringRequired

Invoice reference

Body
reasonstringOptional

Reason for refund

refundAddressstringRequired

Customer wallet address to receive the refund

feePaidBystring · enumOptional

Who pays the blockchain fee. Defaults to merchant settings.

Possible values:
webhookUrlstringOptional

Optional URL to receive webhook notifications for this refund (must be HTTPS). Overrides your dashboard webhook URL for this refund only.

Example: https://example.com/webhooks
Responses
201Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
post/api/v1/refunds/invoice/{invoiceReference}
POST /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"
}
201Success
{
  "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"
  }
}

List refunds

get
/api/v1/refunds

Returns all refunds.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Query parameters
pagenumber · min: 1Optional

Page number (1-based)

Default: 1Example: 1
sizenumber · min: 1 · max: 100Optional

Number of items per page

Default: 10Example: 10
statusstring · enumOptional

Filter by refund status

Possible values:
sessionReferencestringOptional

Filter by payment session reference

invoiceReferencestringOptional

Filter by invoice reference

searchstringOptional

Search term for session or invoice reference

startDatestringOptional

Filter refunds created from this date/time (ISO 8601)

Example: 2026-03-01T00:00:00Z
endDatestringOptional

Filter refunds created up to this date/time (ISO 8601)

Example: 2026-03-11T23:59:59Z
Responses
200Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
get/api/v1/refunds
GET /api/v1/refunds HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200Success
{
  "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
  }
}

Estimate refund

get
/api/v1/refunds/estimate/{reference}

Get refund estimation including fees and amounts. Specify entity type (session/invoice) via query parameter.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
referencestringRequired

Session reference (CS_xxxxx) or invoice reference (INV_xxxxx)

Example: CS_1234567890
Query parameters
entitystring · enumRequired

Entity type - whether the reference is for a session or invoice

Example: sessionPossible values:
feePaidBystring · enumOptional

Who will pay the network fee

Example: customerPossible values:
Responses
200Success
No content
get/api/v1/refunds/estimate/{reference}
GET /api/v1/refunds/estimate/{reference}?entity=session HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200Success
No content

Retrieve refund

get
/api/v1/refunds/{id}

Returns the refund for the given ID.

Authorizations
x-api-keystringRequired

Your API key (obtain from dashboard)

Path parameters
idstringRequired

Refund ID

Responses
200Success
application/json
successbooleanRequired

Indicates if the request was successful

Example: true
messagestringRequired

Response message

Example: Success
get/api/v1/refunds/{id}
GET /api/v1/refunds/{id} HTTP/1.1
Host: api.coincircuit.io
x-api-key: YOUR_API_KEY
Accept: */*
200Success
{
  "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"
  }
}
PreviousCustomers
NextPayment Pages

Last updated

Was this helpful?