メインコンテンツへスキップ
バージョン: 最新版

Refunds API

概要​

Refunds APIを使用すると、クレジットカードのChargeに対して顧客に資金を返金できます。全額または一部の返金を発行し、返金履歴を追跡し、返品をシームレスに処理します。

Refundとは​

Refundは、顧客に返金される金額を表すオブジェクトです：

  • 全額返金 - Charge全体の金額を返金
  • 一部返金 - Chargeの一部の金額を返金
  • 複数の返金 - 元の金額まで複数の一部返金を発行
  • 自動処理 - 顧客のカードに自動的に資金を返金

主要な機能​

柔軟な返金オプション​

  • 全額または一部 - 元のChargeまでの任意の金額を返金
  • 複数の返金 - 複数の取引に返金を分割
  • Metadataサポート - 追跡用のカスタムデータを追加
  • 即時処理 - Refundは即座に処理

簡単な管理​

  • Refundの一覧表示 - Chargeのすべての返金を表示
  • ステータスの追跡 - 返金処理を監視
  • Refundの検索 - 特定の返金取引を検索
  • 監査証跡 - 完全な返金履歴

自動処理​

  • カードに直接 - 顧客の元のカードに資金を返金
  • 顧客の操作不要 - 自動処理
  • 手数料の処理 - ポリシーに従って取引手数料を処理
  • 通貨の一致 - 元のChargeと同じ通貨

Refundの仕組み​

標準フロー​

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

Refundのタイムライン​

  1. 即時: OmiseシステムでRefundが作成
  2. 処理中: カードネットワークに送信（即時）
  3. 顧客が確認: 通常5〜10営業日
  4. Webhookが送信: Refund完了時

APIエンドポイント​

MethodEndpointDescription
POST/charges/:id/refundsChargeのRefundを作成
GET/refunds/:idRefundの詳細を取得
GET/charges/:id/refundsChargeのすべての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);

一部返金​

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

複数の一部返金​

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

一般的な使用例​

商品の返品​

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

注文のキャンセル​

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

一部返金（破損商品）​

// 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のルール​

タイミング​

  • 返金可能: 成功したCharge後いつでも
  • 返金不可: 失敗または保留中のCharge
  • 期限: 制限なし（数年後でも返金可能）

金額​

  • 最小: 通貨の1単位（THBの場合1サタン）
  • 最大: 元のCharge金額から以前の返金を差し引いた額
  • 複数: 複数の一部返金を発行可能
  • 合計: 元のCharge金額を超えることはできない

資格​

  • ✅ 成功したCharge - 返金可能
  • ❌ 保留中のCharge - 返金不可
  • ❌ 失敗したCharge - 返金不可
  • ✅ 一部返金済み - 残りの金額を返金可能

取引手数料​

手数料の処理​

  • 全額返金: 取引手数料が返金される場合があります（ポリシーによる）
  • 一部返金: 手数料は通常返金されません
  • ポリシーを確認: アカウントの返金手数料ポリシーについてはサポートにお問い合わせください

ベストプラクティス​

✅ 推奨事項​

  • Metadataを追加して返金理由を記録
  • Chargeステータスを確認してから返金（成功している必要があります）
  • 返金可能額を確認（元の金額 - すでに返金された金額）
  • 顧客に通知Refundが発行されたとき
  • Refund IDを追跡システムで記録
  • Webhookを設定して返金通知を受信
  • エラーを適切に処理（資金不足など）

❌ 非推奨事項​

  • 保留中のChargeを返金しない（失敗します）
  • 元の金額を超えない（失敗します）
  • 即時入金を想定しない（5〜10日かかります）
  • 確認なしに返金しない（正当性を確保）
  • 理由の追跡をスキップしない（Metadataを使用）

テスト​

テストモードのRefund​

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

エラー処理​

一般的な返金エラー：

エラーコード説明解決方法
not_refundableChargeは返金できませんChargeステータスを確認
insufficient_refundable_amount金額が返金可能残高を超えていますrefunded_amountを確認
invalid_amount金額が無効です金額 > 0を確認

APIリファレンス​

関連リソース​

サポートが必要ですか？ 返金ガイドを確認するか、support@omise.coまでお問い合わせください。