Refunds

When an order fails to deliver, Bitrefill issues a refund. This guide explains how refunds work.

When Refunds Occur

Refunds happen when:

Order delivery fails
Product is out of stock after payment
Technical error prevents fulfillment
Invoice is cancelled before delivery

Refund Methods

Refunds go back to the payment method used:

Payment Method	Refund Destination
Balance	Account balance
Bitcoin	`refund_address`
Lightning	Cannot refund (instant)
Ethereum/ERC-20	`refund_address`
Other crypto	`refund_address`

Providing a Refund Address

When paying with crypto, always include refund_address:

{
  products: [...],
  payment_method: 'bitcoin',
  refund_address: 'bc1q...'  // Required for refunds
}

If you don't provide a refund address and the order fails, the refund may be delayed or require manual intervention.

Checking for Refunds

Check the order status:

const response = await fetch(`${BASE_URL}/orders/${orderId}`, { headers });
const { data: order } = await response.json();

if (order.status === 'refunded') {
  console.log(`Refund: ${order.refund.amount} ${order.refund.currency}`);
}

Handling Refunds in Code

async function processInvoice(invoice) {
  const results = { successful: [], refunded: [] };
  
  for (const orderSummary of invoice.orders) {
    const response = await fetch(`${BASE_URL}/orders/${orderSummary.id}`, { headers });
    const { data: order } = await response.json();
    
    if (order.status === 'delivered') {
      results.successful.push({
        orderId: order.id,
        product: order.product.name,
        code: order.redemption_info?.code
      });
    } else if (order.status === 'refunded') {
      results.refunded.push({
        orderId: order.id,
        product: order.product.name,
        refundAmount: order.refund?.amount
      });
    }
  }
  
  return results;
}

Refund Timeline

Scenario	Timeline
Balance refund	Immediate
Crypto refund	10 mins - 1 hour
Manual intervention	1-3 business days

Best Practices

Always provide refund address — For crypto payments
Use valid addresses — Ensure you control the refund address
Monitor order status — Check for failed/refunded orders
Handle partial failures — Some orders may succeed while others fail
Contact support if delayed — For refunds taking longer than expected

Contact Support

If a refund is delayed or missing:

Email: [email protected]
Include: Invoice ID, order ID, expected refund amount