Firmware State Machines for Payment-Enabled Machines: Handling Every Transaction State

The customer pays, a command reaches the machine, and the product is delivered. That is the happy path. The firmware also needs a defensible answer when confirmation arrives late, a message arrives twice, power fails during delivery, or the machine reports an outcome the backend has not seen yet. A state machine makes those distinctions explicit instead of asking a few booleans to remember the transaction history.

This guide focuses on firmware and transaction state across the complete system. Payment integration for physical machines covers the broader architecture, and general machine state design covers physical sequencing. Here, the essential task is to prevent a digital message from being mistaken for evidence of a physical result.

1. Separate order, payment, and machine-operation state

A business order identifies the requested product or service, price, and context. Payment state describes evidence from the provider according to the integration policy. Machine state describes whether the local action was accepted, started, completed, failed, or remains uncertain. These can progress at different times. Represent them separately and define how they relate.

Do not use one flag called paid to mean that a provider event was received, authorization was checked, a motor command was sent, and delivery occurred. Those are different assertions with different evidence. A customer-facing success message should reflect the outcome it claims, not the fact that the application reached the last line of its request handler.

2. Give each operation an identity and binding

Distinguish the order identifier, provider transaction or attempt, provider event, machine identity, and local operation identifier. Define how they are associated and which fields are immutable for a particular action. A payment event identifier can help handle a repeated event, but it is not automatically the correct identifier for the physical dispense across several message types.

Bind the authorized operation to the intended device, product or service, amount and currency checks where applicable, and validity policy. The trusted backend should establish the required payment state using the selected provider integration. A screen displaying a QR code or a client reporting success is not equivalent to verified authorization for a physical action.

Razorpay's webhook validation guidance addresses signature verification, duplicate events, and event order. Apply the current provider-specific process at the trusted integration boundary. The local firmware still needs its own operation identity and recovery policy; validating a webhook does not supply those automatically.

3. Define the permitted transitions and their conditions

Write states with explicit entry conditions, actions, expected events, timeouts, and retained records. The exact names are less important than the meaning. Separate waiting for payment from a verified payment waiting for a machine action, and separate a completed action from an outcome that cannot yet be established. Include unavailable, cancelled, expired, and service-required conditions where the product policy needs them.

ORDER_CREATED -> PAYMENT_PENDING
PAYMENT_PENDING -> PAYMENT_VERIFIED | EXPIRED | CANCELLED
PAYMENT_VERIFIED -> ACTION_REQUESTED | RESOLUTION_REQUIRED
ACTION_REQUESTED -> ACCEPTED | REJECTED | STATUS_UNKNOWN
ACCEPTED -> EXECUTING
EXECUTING -> PHYSICAL_OUTCOME_CONFIRMED | FAILED | OUTCOME_UNKNOWN
PHYSICAL_OUTCOME_CONFIRMED -> ORDER_COMPLETED
FAILED / OUTCOME_UNKNOWN -> RECONCILIATION
RECONCILIATION -> RESOLVED | AUTHORIZED_SERVICE_REQUIRED

This is a discussion model, not executable control logic or a universal provider mapping. Define the required authorization, local operating conditions, and application-specific safety responsibilities through the appropriate design. A trusted request should not bypass the machine's own conditions for permitting an action.

4. Make repeated and late messages non-destructive

A repeated request for the same operation should consult the operation record and return the relevant state rather than blindly repeat a physical action. Define behavior for an operation in progress, already completed, rejected, or uncertain. Different operations still need normal authorization. Idempotency is a property of the defined action and record handling, not simply a check that two payload strings look similar.

Handle delayed and out-of-order events using the authoritative records and transition rules. Do not let an older message move a completed order backward or a late payment start an expired machine action without an explicit policy. Stripe's webhook documentation also discusses duplicate and ordering considerations. Provider event delivery and physical-action confirmation remain separate engineering boundaries.

Include acknowledgments that distinguish receipt, acceptance, progress, and result where needed. Network delivery guarantees cannot by themselves prove exactly-once physical delivery. A message can be acknowledged before or after a physical event, and an interruption can leave the other side uncertain. Preserve that uncertainty rather than inventing a successful outcome.

5. Persist enough state to interpret an interruption

Identify the irreversible actions and the information needed before and after them. Record the operation identity, intended action, relevant version and configuration, accepted state, progress or outcome evidence, and reconciliation status as appropriate. The storage design must account for interrupted updates and the target hardware; the article cannot supply one universal commit strategy.

Consider a constructed scenario: the controller starts delivery, power fails, and the completion record has not been committed. On restart, a stored accepted state does not prove that nothing happened. An automatic repeat can deliver twice; automatic completion can claim a delivery that never occurred. Use available physical and retained evidence to resolve the state, or keep it explicitly unresolved and follow the authorized support policy.

Watchdog and recovery design covers restart behavior, while the PCB requirements guide helps identify power and storage requirements early enough to influence hardware.

6. Design reconciliation as part of the product

Specify how the backend compares provider, order, and device records after a delay or outage. Define which evidence can resolve an order automatically and which needs authorized intervention. Keep financial actions such as refund decisions within the agreed business and provider policy rather than embedding an undocumented rule in the motor-control task.

Record reason codes and what was observed, not just a generic failure. Support needs to distinguish unpaid, paid but not attempted, attempted and failed, confirmed delivered, and uncertain outcome. Include time information and its limitations, machine configuration, and operation identity. Minimize sensitive data in device logs and preserve authorized access to the evidence actually needed.

7. Align the display and local machine behavior

The interface should explain whether the system is waiting, processing, unavailable, completed, or asking for assistance. Distinguish a timed-out screen from an authoritative payment or machine result. If the user walks away, the transaction still needs a policy. A display returning to the home screen must not erase the operation record.

Industrial HMI design and custom vending requirements connect the user journey to machine state. Connected-machine architecture explains the local and backend split. Keep the physical sequence independent of an assumption that a network response always arrives promptly.

8. Test every boundary where state can disagree

Build cases for duplicate provider events, duplicate commands, delayed acknowledgment, expired orders, restart before action, interruption during action, confirmed outcome with delayed reporting, and incompatible configuration. Define expected device and backend states, physical behavior, customer message, and retained evidence. Use appropriate provider test environments and reviewed machine test arrangements.

Simulation is useful for interface cases, but identify what needs representative hardware. Factory acceptance planning helps agree the machine-level evidence, and bring-up establishes the electronics baseline.

9. Release the state model with the implementation

Keep the transition definitions, identifiers, protocol, storage assumptions, tests, versions, and known limitations in the release package. Review changes across firmware, backend, display, provider integration, and service. A change to one layer can alter the meaning of an operation for another. Treat the complete transaction as a product interface, not a set of independent endpoints.

SolveMpire can discuss payment-enabled machine architecture, firmware, and connected services. Bring the provider flow, order model, physical action, confirmation method, outage behavior, and support policy. The useful result is a system that can explain what happened—even when the happy path declined to attend.

For the repeat-delivery boundary, duplicate dispensing prevention examines atomic authorization, durable device acceptance, result replay, retention, and interrupted physical actions.