支払いを返金する

PaymentIntentの返金

succeeded のPaymentIntentは、secret keyで全額または一部を返金できます。

// 全額: amountを省略
const fullRefund = await paymentIntentClient.paymentIntents.refund(
  paymentIntentId,
);

// 一部: 法定通貨の主単位
const partialRefund = await paymentIntentClient.paymentIntents.refund(
  paymentIntentId,
  { amount: 500, reason: "customer_request" },
);

amount はPaymentIntentと同じ法定通貨の主単位です。JPYなら500円、USDなら500ドルを意味します。

返り値には更新後の paymentIntent と、新規返金の { id, status } が含まれます。

制約

• succeeded だけが返金可能
• secret keyとPaymentIntentのマーチャントが一致すること
• 一部返金額は0より大きく、未返金残高以下であること（残高超過は payment_intent_unexpected_state（409）、0以下・非数値は parameter_invalid（400））
• 同時リクエストはサーバ側のrow lockで残高超過を防止
• 全額返金は未返金残高の全額を起票

返金後もPaymentIntentの status は succeeded のままです。amountRefunded、refunds.data、payment_intent.refunded イベントで確認します。

REST endpointは POST /api/v1/payment_intents/{id}/refund です。旧来のtop-level /api/v1/refunds はありません。

EC Gatewayの不足／超過

EC Gatewayは実際の入金額を想定額と照合します。

• 不足: 受領資金の自動返金または運用対応
• 超過: 支払いを進め、差額返金を起票

進捗は checkoutStatus の state.matchStatus、underpaymentRefundStatus、overpaymentRefundStatus で確認します。これはPaymentIntentの手動返金APIとは別のフローです。