状態リファレンス
Hosted CheckoutとPaymentIntentの状態遷移
Hosted CheckoutとPaymentIntent APIは別の状態modelを持ちます。両方の状態名を混在させないでください。
Hosted Checkout
kyc_pending
├─ 審査NG → kyc_declined
└─ 審査OK → checkout_opened
↓
asset_selected
↓
awaiting_deposit
├─ 期限切れ → expired
└─ 入金検知 → deposit_detected
↓
deposit_confirmed
↓
bridging（該当レールのみ）
↓
converting → transferring
↓
completed
後続処理が失敗／キャンセル → failedconfirmed は「全額の入金を確認した」互換booleanで、不足入金では false になります（underpaid: true）。canonicalな状態は state.state を使います。入金額の一致状況は状態とは別の state.matchStatus で表されます。
exact: 想定額と一致underpaid: 不足。自動返金または運用対応へ進むoverpaid: 超過。差額返金へ進む
PaymentIntent
create
↓
requires_payment_method
↓ confirm
requires_action
├─ cancel → canceled
└─ deposit記録 → succeeded
↓ refundを起票
succeededのままprocessing と failed は公開型に含まれますが、現行のsimulate経路は requires_action から直接 succeeded へ進みます。返金してもPaymentIntentの status は succeeded のままで、amountRefunded と refunds.data が更新されます。
PaymentIntentのsimulate着金は、指定した正の amount が請求額と異なっていても現行実装では succeeded になります。EC Gatewayの不足／超過ロジックとは別物です。
実装上の判断
- 買い手のredirectだけで支払い済みにしない
- EC Gatewayは
confirmedまたは明示的なcanonical stateで照合する - PaymentIntentは
statusとnextActionを組み合わせて画面を決める - 返金・精算は支払い完了とは別の非同期処理として扱う