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);

Refund Failure Codes

When a refund fails, the failure_code attribute indicates the reason:

Code	Message	Description
failed_refund	"refund failed"	Refund processing error
not_refundable	"charge cannot be refunded"	Charge status doesn't allow refund
insufficient_refundable_amount	"amount exceeds refundable balance"	Amount greater than available
invalid_amount	"invalid amount"	Amount is zero or negative
refund_limit_exceeded	"refund limit exceeded"	Maximum number of refunds reached
charge_not_found	"charge not found"	Charge ID doesn't exist
charge_expired	"charge expired"	Cannot refund expired charge

Refund Limits

Refund Restrictions

• Time limit: Refunds must be made within 365 days of the original charge
• Partial refunds: Maximum of 15 partial refunds per charge
• Amount: Cannot exceed original charge amount minus previous refunds

Error Handling

Common refund errors:

Error Code	HTTP Status	Description	Solution
not_refundable	400	Charge cannot be refunded	Check charge status (must be successful)
insufficient_refundable_amount	400	Amount exceeds refundable balance	Check refunded_amount on charge
invalid_amount	400	Amount is invalid	Verify amount > 0 and is integer
refund_limit_exceeded	400	Too many partial refunds	Maximum 15 partial refunds per charge

API Reference

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

Related Resources

• Retrieve Charge
• Webhooks Guide
• Disputes API

---

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