Payment State

Overview

Payment State represents the current business interpretation of a payment record. It can combine invoice activity, detected blockchain transfers, confirmation policy, manual decisions, and refund processing. The state is application-level data even when it is driven by blockchain events.

A state should answer what the system currently believes and what actions are allowed. For example, a waiting payment may accept an incoming transfer, a paid payment may permit fulfillment, and an expired payment may require late-payment review. Each label needs a precise definition shared by API, dashboard, webhook, and support teams.

Payment state is different from Blockchain Status and transaction receipt status. A healthy chain does not mean an invoice is paid, and a successful transaction may still send the wrong asset or amount. Business rules must match the observed transfer to the expected order.

State changes should follow a Payment State Machine so invalid sequences are rejected. Duplicate webhooks, reorganizations, manual acceptance, and partial payments can otherwise produce contradictory records. Every transition should preserve its cause, event identity, timestamp, and prior state.

OxaPay documents distinct invoice states for newly created, waiting, paying, paid, underpaid, refunding, refunded, and expired conditions. Integrations should store the provider state and map it carefully to internal order states rather than assuming the two systems use identical meanings.

Internal order state should remain separate from provider payment state. A paid invoice can map to an order awaiting fraud review, stock confirmation, or manual fulfillment. Keeping the models distinct while linking them through controlled events prevents a provider callback from bypassing business checks.