Refunds API

Overview

The Refunds API enables you to return funds to customers for credit card charges. Issue full or partial refunds, track refund history, and handle returns seamlessly.

What are Refunds?

Refunds are objects that represent money returned to customers:

• Full refunds - Return entire charge amount
• Partial refunds - Return portion of charge amount
• Multiple refunds - Issue several partial refunds up to original amount
• Automatic processing - Funds returned to customer's card automatically

Key Features

Flexible Refund Options

• Full or partial - Refund any amount up to original charge
• Multiple refunds - Split refund across multiple transactions
• Metadata support - Add custom data for tracking
• Instant processing - Refunds processed immediately

Easy Management

• List refunds - View all refunds for a charge
• Track status - Monitor refund processing
• Search refunds - Find specific refund transactions
• Audit trail - Complete refund history

Automatic Handling

• Direct to card - Funds returned to customer's original card
• No customer action - Automatic processing
• Fee handling - Transaction fees handled per policy
• Currency matching - Same currency as original charge

How Refunds Work

Standard Flow

┌─────────┐         ┌─────────┐         ┌─────────┐
│ Your    │         │ Omise   │         │ Customer│
│ Server  │         │ API     │         │ Bank    │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. Create refund  │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. Return refund  │                   │
     │<──────────────────┤                   │
     │                   │                   │
     │                   │ 3. Process refund │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 4. Funds returned │
     │                   │<──────────────────┤
     │                   │                   │
     │ 5. Webhook notify │                   │
     │<──────────────────┤                   │
     │                   │                   │

Refund Timeline

1. Immediate: Refund created in Omise system
2. Processing: Sent to card network (instant)
3. Customer sees: Typically 5-10 business days
4. Webhook sent: When refund completes

API Endpoints

Method	Endpoint	Description
POST	/charges/:id/refunds	Create a refund for charge
GET	/refunds/:id	Retrieve refund details
GET	/charges/:id/refunds	List all refunds for charge

Quick Start

Full Refund

// Refund entire charge
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t');

console.log('Refund created:', refund.id);
console.log('Amount:', refund.amount);
console.log('Status:', refund.status);

Partial Refund

// Refund portion of charge
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t', {
  amount: 50000  // Refund ฿500 of ฿1000 charge
});

console.log('Refunded:', refund.amount);
console.log('Original:', refund.charge.amount);

Multiple Partial Refunds

// Issue multiple refunds for same charge
const refund1 = await omise.charges.refund(chargeId, { amount: 30000 });
const refund2 = await omise.charges.refund(chargeId, { amount: 20000 });

// Check total refunded
const charge = await omise.charges.retrieve(chargeId);
console.log('Total refunded:', charge.refunded_amount);
console.log('Remaining:', charge.amount - charge.refunded_amount);

Common Use Cases

Product Return

// Customer returns product
const refund = await omise.charges.refund(chargeId, {
  amount: productPrice,
  metadata: {
    reason: 'product_return',
    order_id: 'ORDER-123',
    return_tracking: 'TRACK-456'
  }
});

Order Cancellation

// Cancel order, full refund
const refund = await omise.charges.refund(chargeId, {
  metadata: {
    reason: 'order_cancelled',
    cancelled_by: 'customer'
  }
});

Partial Refund (Damaged Item)

// Refund portion for damaged item
const refund = await omise.charges.refund(chargeId, {
  amount: damageCompensation,  // e.g., 30% of original
  metadata: {
    reason: 'partial_damage',
    compensation_rate: 0.3
  }
});

Refund Rules

Timing

• Can refund: Any time after successful charge
• Cannot refund: Failed or pending charges
• Time limit: No limit (can refund years later)

Amounts

• Minimum: 1 unit in currency (1 satang for THB)
• Maximum: Original charge amount minus previous refunds
• Multiple: Can issue multiple partial refunds
• Total: Cannot exceed original charge amount

Eligibility

• ✅ Successful charges - Can be refunded
• ❌ Pending charges - Cannot be refunded
• ❌ Failed charges - Cannot be refunded
• ✅ Partially refunded - Can refund remaining amount

Transaction Fees

Fee Handling

• Full refund: Transaction fee may be returned (policy dependent)
• Partial refund: Fee typically not returned
• Check policy: Contact support for your account's refund fee policy

Best Practices

✅ Do This

• Add metadata for refund reasons
• Verify charge status before refunding (must be successful)
• Check refundable amount (original - already refunded)
• Notify customer when refund is issued
• Track refund IDs in your system
• Set up webhooks for refund notifications
• Handle errors gracefully (insufficient funds, etc.)

❌ Don't Do This

• Don't refund pending charges (will fail)
• Don't exceed original amount (will fail)
• Don't assume instant credit (takes 5-10 days)
• Don't refund without verification (ensure legitimate)
• Don't skip reason tracking (use metadata)

Testing

Test Mode Refunds

// Test refunds work same as live
const refund = await omise.charges.refund('chrg_test_xxx', {
  amount: 50000
});

// Check refund in test dashboard
console.log('Test refund:', refund.id);

Error Handling

Common refund errors:

Error Code	Description	Solution
not_refundable	Charge cannot be refunded	Check charge status
insufficient_refundable_amount	Amount exceeds refundable balance	Check refunded_amount
invalid_amount	Amount is invalid	Verify amount > 0

API Reference

• Create Refund - POST /charges/:id/refunds
• Retrieve Refund - GET /refunds/:id
• List Refunds - GET /charges/:id/refunds

Related Resources

• Retrieve Charge
• Webhooks Guide
• Disputes API

---

Need help? Check our Refunds Guide or contact support@omise.co