Status reference

Hosted Checkout and the PaymentIntent API use different state models. Do not mix their state names.

Hosted Checkout

kyc_pending
  ├─ rejected → kyc_declined
  └─ approved → checkout_opened
                   ↓
              asset_selected
                   ↓
              awaiting_deposit
                ├─ timed out → expired
                └─ detected → deposit_detected
                                 ↓
                            deposit_confirmed
                                 ↓
                     bridging (applicable rails only)
                                 ↓
                   converting → transferring
                                 ↓
                             completed

Downstream failure or cancellation → failed

confirmed is a compatibility boolean meaning "the full amount was received"; it is false for an underpaid deposit (underpaid: true). Use state.state as the canonical state. Deposit amount matching is represented separately by state.matchStatus.

• exact: the deposit matches the expected amount
• underpaid: the deposit is short and proceeds to an automatic refund or operational handling
• overpaid: the deposit exceeds the expected amount and the difference proceeds to refund

PaymentIntent

create
  ↓
requires_payment_method
  ↓ confirm
requires_action
  ├─ cancel → canceled
  └─ record deposit → succeeded
                         ↓ request refund
                     remains succeeded

processing and failed are part of the public type, but the current simulation path moves directly from requires_action to succeeded. A refund does not change the PaymentIntent status from succeeded; it updates amountRefunded and refunds.data.

Implementation guidance

• Do not mark an order paid based only on the customer redirect
• For Gateway, verify confirmed or an explicit canonical state
• For PaymentIntents, choose the UI using both status and nextAction
• Treat refunds and settlement as asynchronous processes separate from payment completion