返金API

概要

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

返金とは？

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

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

主な機能

柔軟な返金オプション

• 全額または一部 - 元の課金額まで任意の金額を返金
• 複数回返金 - 複数のトランザクションに分割して返金
• メタデータサポート - 追跡用のカスタムデータを追加
• 即時処理 - 返金は即座に処理

簡単な管理

• 返金一覧 - 課金のすべての返金を表示
• ステータス追跡 - 返金処理を監視
• 返金検索 - 特定の返金トランザクションを検索
• 監査証跡 - 完全な返金履歴

自動処理

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

返金の仕組み

標準フロー

┌─────────┐         ┌─────────┐         ┌─────────┐
│ あなたの │         │ Omise   │         │ 顧客の  │
│ サーバー │         │ API     │         │ 銀行    │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. 返金を作成     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. 返金を返却     │                   │
     │<──────────────────┤                   │
     │                   │                   │
     │                   │ 3. 返金を処理     │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 4. 資金が返金     │
     │                   │<──────────────────┤
     │                   │                   │
     │ 5. Webhook通知    │                   │
     │<──────────────────┤                   │
     │                   │                   │

返金タイムライン

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

APIエンドポイント

メソッド	エンドポイント	説明
POST	/charges/:id/refunds	課金に対して返金を作成
GET	/refunds/:id	返金の詳細を取得
GET	/charges/:id/refunds	課金のすべての返金を一覧表示

クイックスタート

全額返金

// 課金の全額を返金
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t');

console.log('返金作成:', refund.id);
console.log('金額:', refund.amount);
console.log('ステータス:', refund.status);

一部返金

// 課金の一部を返金
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t', {
  amount: 50000  // ฿1000の課金から฿500を返金
});

console.log('返金額:', refund.amount);
console.log('元の金額:', refund.charge.amount);

複数回の一部返金

// 同じ課金に対して複数回返金を発行
const refund1 = await omise.charges.refund(chargeId, { amount: 30000 });
const refund2 = await omise.charges.refund(chargeId, { amount: 20000 });

// 返金合計を確認
const charge = await omise.charges.retrieve(chargeId);
console.log('返金合計:', charge.refunded_amount);
console.log('残高:', charge.amount - charge.refunded_amount);

一般的なユースケース

商品の返品

// 顧客が商品を返品
const refund = await omise.charges.refund(chargeId, {
  amount: productPrice,
  metadata: {
    reason: 'product_return',
    order_id: 'ORDER-123',
    return_tracking: 'TRACK-456'
  }
});

注文のキャンセル

// 注文をキャンセル、全額返金
const refund = await omise.charges.refund(chargeId, {
  metadata: {
    reason: 'order_cancelled',
    cancelled_by: 'customer'
  }
});

一部返金（破損商品）

// 破損商品の一部を返金
const refund = await omise.charges.refund(chargeId, {
  amount: damageCompensation,  // 例: 元の30%
  metadata: {
    reason: 'partial_damage',
    compensation_rate: 0.3
  }
});

返金ルール

タイミング

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

金額

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

適格性

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

取引手数料

手数料の処理

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

ベストプラクティス

✅ 推奨

• 返金理由のメタデータを追加
• 返金前に課金ステータスを確認（successfulである必要があります）
• 返金可能額を確認（元の金額 - 返金済み金額）
• 返金発行時に顧客に通知
• システムで返金IDを追跡
• 返金通知用のWebhookを設定
• エラーを適切に処理（残高不足など）

❌ 非推奨

• 保留中の課金を返金しない（失敗します）
• 元の金額を超えない（失敗します）
• 即時反映を想定しない（5〜10日かかります）
• 確認なしで返金しない（正当性を確認）
• 理由の追跡をスキップしない（メタデータを使用）

テスト

テストモードの返金

// テスト返金は本番と同じように動作
const refund = await omise.charges.refund('chrg_test_xxx', {
  amount: 50000
});

// テストダッシュボードで返金を確認
console.log('テスト返金:', refund.id);

返金失敗コード

返金が失敗した場合、failure_code属性が理由を示します：

コード	メッセージ	説明
failed_refund	"refund failed"	返金処理エラー
not_refundable	"charge cannot be refunded"	課金ステータスが返金を許可しない
insufficient_refundable_amount	"amount exceeds refundable balance"	金額が利用可能額を超過
invalid_amount	"invalid amount"	金額がゼロまたは負数
refund_limit_exceeded	"refund limit exceeded"	返金の最大回数に到達
charge_not_found	"charge not found"	課金IDが存在しない
charge_expired	"charge expired"	期限切れの課金は返金不可

返金の制限

返金の制約

• 期限: 返金は元の課金から365日以内に行う必要があります
• 一部返金: 1つの課金につき最大15回の一部返金
• 金額: 元の課金額から以前の返金を差し引いた額を超えることはできません

エラー処理

一般的な返金エラー：

エラーコード	HTTPステータス	説明	解決策
not_refundable	400	課金を返金できない	課金ステータスを確認（successfulである必要があります）
insufficient_refundable_amount	400	金額が返金可能残高を超過	課金のrefunded_amountを確認
invalid_amount	400	金額が無効	金額が0より大きく整数であることを確認
refund_limit_exceeded	400	一部返金が多すぎる	1つの課金につき最大15回の一部返金

APIリファレンス

• 返金の作成 - POST /charges/:id/refunds
• 返金の取得 - GET /refunds/:id

関連リソース

• 課金の取得
• Webhookガイド
• 紛争API

---

お困りですか？ 返金ガイドをご確認いただくか、support@omise.coまでお問い合わせください