Refunds

Request and manage refunds for completed checkout payments.

Overview

Refunds allow you to return funds to customers after a successful payment. The refund process involves:

1. Merchant requests a refund
2. Refund is approved (manual or automatic based on settings)
3. Funds are returned to the customer's wallet

Request Refund

Create a refund request for a completed checkout.

POST /v1/checkouts/:id/refunds

Headers

Header	Required	Description
x-api-key	Yes	Server Key (volr_server_...)

Request Body

{
  "amount": "5000000",
  "reason": "Customer requested cancellation",
  "recipientAddress": "0xcustomer..."
}

Parameter	Type	Required	Description
amount	string	Yes	Refund amount in token's smallest unit
reason	string	No	Reason for the refund
recipientAddress	string	No	Override recipient (defaults to original payer)

Response

{
  "ok": true,
  "data": {
    "id": "refund_xyz123",
    "checkoutId": "cm5xyz123...",
    "amount": "5000000",
    "status": "PENDING",
    "reason": "Customer requested cancellation",
    "recipientAddress": "0xcustomer...",
    "createdAt": "2026-01-30T12:00:00.000Z"
  }
}

---

List Refunds

Get all refunds for a checkout.

GET /v1/checkouts/:id/refunds

Headers

Header	Required	Description
x-api-key	Yes	Server Key (volr_server_...)

Response

{
  "ok": true,
  "data": [
    {
      "id": "refund_xyz123",
      "checkoutId": "cm5xyz123...",
      "amount": "5000000",
      "status": "EXECUTED",
      "txHash": "0xabc...",
      "executedAt": "2026-01-30T12:05:00.000Z"
    }
  ]
}

---

Refund Status

Status	Description
PENDING	Refund requested, awaiting approval
APPROVED	Approved, awaiting execution
EXECUTED	Refund completed on-chain
FAILED	Refund execution failed

---

Refund Limits

• Partial refunds: Supported. You can refund any amount up to the original payment.
• Multiple refunds: Supported. Total refunds cannot exceed the original payment amount.
• Full refund: Refund the entire paidAmount to fully refund the customer.

---

Example: Full Refund

const fullRefund = async (checkoutId) => {
  // Get checkout details
  const { data: checkout } = await fetch(
    `https://api.volr.io/v1/checkouts/${checkoutId}`,
    { headers: { 'x-api-key': SERVER_KEY } }
  ).then(r => r.json());

  // Request full refund
  const response = await fetch(
    `https://api.volr.io/v1/checkouts/${checkoutId}/refunds`,
    {
      method: 'POST',
      headers: {
        'x-api-key': SERVER_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount: checkout.amount,
        reason: 'Full refund requested',
      }),
    }
  );

  return response.json();
};