Skip to main content

Order Lifecycle & Payment States

The /submit call represents an authorized order, not a captured one. Capture happens only after your /submit endpoint returns a 2xx response — so a failed submission never charges the shopper. If /submit fails terminally, the authorization is held so the order can be recovered: the merchant can inspect the failure, retry the submission, or cancel the authorization and release the hold from the Simpler Merchant Dashboard — see Failed Orders: Debug, Retry, or Cancel. For synchronous methods the authorize/capture distinction rarely matters in practice; for asynchronous methods (MultiBanco, MBway, Sequra) it's central to the partner integration.

Synchronous payment methods​

Card, Apple Pay, Google Pay, PayPal and similar methods are authorized before /submit and captured as soon as /submit succeeds.

  1. Shopper completes payment in the Simpler checkout.
  2. Simpler calls /submit. The order in your system is created with status: COMPLETED.
  3. No webhook is sent for payment confirmation — a COMPLETED order is paid.

Asynchronous payment methods​

MultiBanco, MBway, and Sequra require the shopper to take additional action after the checkout completes. The order is created at /submit time but funds haven't moved yet.

  1. Shopper selects the async method in Simpler checkout and sees a "Success" screen (e.g. a MultiBanco voucher).
  2. Simpler calls /submit. Create the order in your system with status: PENDING.
  3. Shopper completes payment offline (e.g. pays the voucher at an ATM or via home banking).
  4. Simpler receives the payment confirmation from the PSP and fires an ORDER_UPDATED webhook with status: PAYMENT_SUCCESS.
  5. Your webhook handler moves the order to its final state (e.g. processing).

If the shopper never completes payment, an ORDER_UPDATED webhook with status: PAYMENT_FAILED fires instead.

Settlement windows​

MethodTypical settlementExpiration
MultiBanco1–3 days depending on when the shopper pays72 hours; PAYMENT_FAILED webhook on expiry
MBwayTypically same-day (confirm with Simpler for your region)—
SequraRisk-check + instalment plan; confirm with Simpler for your region—

Cancellation semantics (MultiBanco specific)​

Once a MultiBanco voucher has been issued, the transaction cannot be programmatically canceled. Only the shopper can effectively cancel by letting the voucher expire. No funds are moved until the shopper pays, so no auto-return is required for expired vouchers.

Partner UI guidance​

For async methods, render a "Pending Payment" or "Awaiting Payment" badge on the partner order-detail page until the PAYMENT_SUCCESS webhook arrives. Do not treat the order as ready for fulfillment based on /submit alone — the funds haven't moved yet.

See also​