explain-status

Explain Straddle Status

Parse the user's arguments to identify the entity type and the status, transition, or error code they are asking about. If no arguments were provided, ask what entity and status they want explained.

Supported Entity Types

• customer -- statuses: pending, review, verified, inactive, rejected
• paykey -- statuses: active, review, rejected, blocked, inactive, expired
• charge -- statuses: created, scheduled, pending, paid, failed, reversed, cancelled, on_hold, validating
• payout -- statuses: created, scheduled, pending, paid, failed, reversed, cancelled, on_hold
• funding_event -- statuses tied to settlement lifecycle
• account (Embed) -- statuses tied to onboarding lifecycle (pending, active, suspended, etc.)

What to Explain

For each status, cover the following:

1. Meaning -- what this status indicates
2. Cause -- how the entity reached this status
3. Transitions -- what statuses come before and after this one
4. Terminal vs recoverable -- whether this is a final state or can change
5. Next action -- what the developer or user should do

Payment Status Machine

For charges and payouts, reference this state machine:

created -> scheduled -> pending -> paid
                                -> failed
                     -> on_hold -> released -> scheduled
                                -> cancelled
                        paid    -> reversed

Key rules:

• Once a payment reaches pending, it cannot be modified, held, released, or cancelled
• failed, reversed, and cancelled are terminal states
• paid can still transition to reversed (ACH return after settlement)
• on_hold can transition to released (back to scheduled) or cancelled

Status Details

When a payment fails or reverses, status_details explains why:

• reason -- human-readable category (e.g., insufficient_funds, account_closed, unauthorized)
• message -- detailed explanation of what happened
• code -- raw return code when applicable (e.g., R01)