Payment state machines: the states you will forget

The first version of every payments integration has two states: paid and not paid. It works until the first bank payment sits in processing overnight, the first 3D Secure challenge leaves a payment in requires_action, or the first payout marked paid bounces three days later.

This is a reference to every status the Paydude API can report, taken from its specification, with the transitions we observed in the sandbox on 28 September 2026 marked as such.

Payment intent

The payment intent is the object your code creates and the one your order should follow.

Paths observed in the sandbox:

• Card, approved: requires_payment_method → succeeded on confirm, with charge.succeeded and payment_intent.succeeded events.
• Card, declined: requires_payment_method → confirm → requires_payment_method again, with the reason in last_payment_error. The status does not change; only the error does.
• ACH debit: requires_payment_method → processing → succeeded about fourteen and a half hours later, delivered as an event.

Charge

A charge is one attempt at moving money. A payment intent can own several — every declined attempt leaves a failed charge behind, and a retry adds a new one to the same intent's charges list.

Track the payment intent, not the charges. The charges are the history; the intent is the answer.

Refund

The one to handle is failed. A customer whose card was closed after they paid cannot be refunded to that card, and an integration that marks the order refunded when it requests the refund will tell them the money is coming when it is not. Mark it refunded on success, and route failures to a person who can pay the customer another way.

Subscription

past_due is the one that costs money. It is not retried automatically: the subscription sits there until you act, and your app keeps granting access unless you decide otherwise. Handling failed payments in code covers the dunning loop it needs. And do not call /confirm on a pending subscription — pending is the healthy state, and confirm only applies to requires_confirmation.

Payout

Two more things the sandbox showed. A payout can carry a negative amount — a debit from the bank rather than a deposit. And one payout.created event arrived already reporting status: "paid", because the payout was created and paid in the same instant; the event name tells you what happened first, not the current state. Reconciling payouts with your database goes through a payout line by line.

Dispute

Disputes have the richest state machine, because an inquiry can precede a formal chargeback.

Evidence can only be submitted before closing_at; after it, the dispute closes with no response, which usually means losing it. That date is the one to alert on. The sandbox's testing guide shows inquiries moving from warning_needs_response to warning_under_review, and an inquiry that escalates continuing on to needs_response — so one dispute can pass through both halves of the table. What is a chargeback covers the process from the cardholder's side.

Modelling it in your own database

Two columns do most of the work. Keep the processor's status exactly as the API reports it, and keep your own business state — what the order means to you — separately, derived from it by an explicit table.

// Processor status -> what the order means to us. Every status the API can
// report appears here, so a new one fails loudly instead of falling through.
const ORDER_STATE = {
  requires_payment_method: "awaiting_payment",   // new, or declined — check last_payment_error
  requires_confirmation:   "awaiting_payment",
  requires_action:         "awaiting_customer",  // 3D Secure: prompt, do not time out silently
  processing:              "pending",            // ACH: do not fulfil yet
  requires_capture:        "authorised",         // capture within 7 days
  succeeded:               "paid",
  canceled:                "canceled",
};

const TERMINAL = new Set(["paid", "canceled"]);

function nextOrderState(order, intent) {
  const next = ORDER_STATE[intent.status];
  if (next === undefined) throw new Error(`Unmapped intent status: ${intent.status}`);
  if (TERMINAL.has(order.state)) return order.state;   // never reopen a closed order
  return next;
}

Throwing on an unmapped status is deliberate. The day the API adds a status, you want an alert, not an order that silently falls into the wrong branch.

• Store the processor's status verbatim, as processor_status, next to your own state. When they disagree, you can see why.
• Keep a history table of every transition with its timestamp and the event that caused it. Disputes and support tickets arrive weeks later, and "what did we know when" is the question they ask.
• Terminal for the order is not terminal for the money. An order can be paid and later partially refunded, disputed, or included in a payout that fails. Model those as separate records against the order, not as more order states.

The states you will forget, in one list