Order Status Model

Order Statuses

Every order goes through a series of statuses during its lifecycle. The table below describes each status, whether it is terminal (final), and the actions available to the merchant.

• The merchant creates the order via POST /api/v1/order — the order gets registered status.
• The customer completes the payment.
• Once the payment is successfully processed, the system moves the order to completed.

Status	Terminal	Description	Available Actions
registered	No	The order has been created and saved in the system. Processing has not yet started. This is a technical status — no callback is sent for it.	None — processing begins automatically
review	No	The order is paused for manual antifraud review by the merchant. See Antifraud Manual Review.	POST /api/v1/order/review/result (accept / decline)
in_progress	No	The order is being actively processed — from the moment processing begins until a final status is reached.	POST /api/v1/order/cancel
completed	Yes	The order has been successfully processed. The sum of completed payments equals the order amount.	POST /api/v1/order/refund (full or partial)
cancelled	Yes	The order was cancelled. This may happen by merchant action, customer action, or system timeout on the payment page.	None — terminal status
failed	Yes	The order has failed due to a business or technical error. This includes provider-side declines, validation errors, antifraud blocks, processing timeouts, and customer cancellations on the provider's payment page.	None — terminal status
need_action	No	The order requires additional action to proceed. Typically caused by a mismatch between the order amount and the sum of completed payments, or other inconsistencies.	Manual resolution via Merchant Account dashboard only
partially_refunded	No	A partial refund has been processed on a completed order. This status is not terminal — additional refunds can still be issued until the full amount is refunded.	POST /api/v1/order/refund (additional or remaining)
refunded	Yes	A full refund has been processed on a completed order. No further actions are available.	None — terminal status

Transition Summary

From	To	Trigger
registered	in_progress	Processing begins automatically
registered	review	Antifraud rule with review action triggered
review	in_progress	Merchant accepts via Review Decision API
review	failed	Merchant declines or review timeout expires
in_progress	completed	Payment successfully processed by provider
in_progress	cancelled	Cancelled by merchant via Cancel Order API, by customer, or by system timeout
in_progress	failed	Business or technical error during processing
in_progress	need_action	Inconsistency detected (e.g. amount mismatch)
need_action	completed / failed / cancelled	Manual resolution via Merchant Account
completed	partially_refunded	Partial refund via Refund Order API
completed	refunded	Full refund via Refund Order API
partially_refunded	partially_refunded	Additional partial refund processed
partially_refunded	refunded	Remaining balance refunded
partially_refunded	need_action	Refund fails or times out at provider
refunded	need_action	Refund fails or times out at provider

---

Cancellation & Failure

Cancellation

An order can be cancelled only while it is in in_progress status. To cancel an order, call POST /api/v1/order/cancel.

Scenario	Resulting Status
Merchant cancels via API	cancelled
Customer cancels on the payment page	cancelled
Payment page timeout expires (customer did not submit payment data)	cancelled

Failure

The system moves the order to failed when a business or technical error occurs (e.g., provider decline, invalid card data, processing error). This also includes cases where the customer cancels or times out on the provider's payment page — these are treated as failed, not cancelled, because the payment has already been sent to the provider.

---

Antifraud Manual Review

When a transaction triggers an antifraud rule configured with the review action, the order is paused for your manual decision.

How it works:

1. The system pauses the transaction and sets the order status to review
2. You receive a callback notification containing reviewTimeout (in minutes)
3. You submit your decision via POST /api/v1/order/review/result:
   • accept → order proceeds to in_progress and continues normal processing
   • decline → order moves to failed
4. If no decision is submitted within the timeout period, the order is automatically declined (status: failed)

tip

Transactions in review status do not expire based on the standard timeLimit parameter. They wait exclusively for your decision or the review timeout.

For complete details on setting up review rules and the callback structure, see Antifraud Manual Review.

---

Need Action (need_action)

The need_action status indicates that the order requires manual intervention to resolve an inconsistency or unexpected condition.

Common Scenarios

Scenario	Description
Amount mismatch	The sum of completed payments does not match the order amount.
Unexpected provider callback	The provider sends a new terminal status for a payment that is already in a terminal status, and the new status differs from the current one.
Cancel/capture/reject processing error	An unexpected condition occurs during cancel, capture, or reject operations.
Refund processing error	A refund request fails or times out at the provider.
Provider response timeout	The system does not receive a response from the provider within the expected timeframe.

The order can also move to need_action from completed or partially_refunded if a refund request fails or times out at the provider.

Resolution

Orders in need_action status do not transition automatically to another status. They must be resolved manually through the Merchant Account dashboard:

1. Navigate to the order details in the Merchant Account dashboard
2. Inspect the payment attempts to identify which payment triggered the issue (marked with an alert icon)
3. Use the Change Status action to move the order to the appropriate terminal status (completed, failed, or cancelled)

warning

While an order is in need_action, incoming payment status updates from the provider will still update the individual payment status and trigger callbacks, but the order status will remain need_action until manually resolved.

---

Refunds

Refunds can be processed on orders in completed or partially_refunded status.

Full Refund

A full refund returns the entire order amount to the customer.

• Preconditions: Order status is completed, the order has at least one successful payment.
• Result: Order status changes to refunded.
• API: POST /api/v1/order/refund.

Partial Refund

A partial refund returns a portion of the order amount.

• Preconditions: Order status is completed or partially_refunded, the refund amount does not exceed the remaining order balance.
• Result: Order status changes to partially_refunded.
• API: POST /api/v1/order/refund.

note

Refunds are processed to the same payment method used for the original payment.

If a refund request fails or times out at the provider, the order moves to need_action and requires manual resolution.

---

Payment Statuses

Each order contains one or more payment attempts. The payment status reflects the state of an individual payment within the order.

Status	Terminal	Description
in_progress	No	The payment is being processed. This is the initial status after the payment attempt is created.
completed	Yes	The payment has been successfully processed by the provider.
cancelled	Yes	The payment was cancelled before it reached the provider.
failed	Yes	The payment has failed due to a decline, error, or timeout.
partially_refunded	No	A partial refund has been processed against this payment. Further refunds can still be issued against this payment until its full amount is refunded.
refunded	Yes	A full refund has been processed against this payment. No further refund actions are available for this payment.

Relationship Between Order and Payment Statuses

When an order has a single payment, the order status directly mirrors the payment status:

Payment Status	Order Status
in_progress	registered or in_progress
completed	completed
cancelled	cancelled
failed	failed
partially_refunded	partially_refunded
refunded	refunded

note

need_action is not a payment status — it is an order-level status triggered by specific conditions (e.g. amount mismatch). It can occur regardless of individual payment statuses.

When an order has multiple payments, the order status is determined by the following rules, evaluated in order:

1. If any payment has a need_action condition detected → order status is need_action
2. If any payment is in_progress → order status is in_progress
3. If all payments are in terminal statuses (completed, failed, cancelled):
   • At least one completed payment and the sum equals the order amount → completed
   • At least one completed payment but the sum does not equal the order amount → need_action
   • No completed payments → order takes the status of the most recently created payment

---

---

Callbacks

The system sends a POST request to your configured callback URL whenever an order status changes. For complete details on callback configuration, delivery rules, payload format, signature verification see Configuring Callback.