Skip to main content

Order Lifecycle & Payment States

The /submit call represents an authorized order, not necessarily a captured one. Capture happens after /submit succeeds — so a terminal submit failure never leaves funds in an inconsistent state: the authorization is simply released, with no manual reconciliation required on the partner side. 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 settle within the /submit call itself.

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

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​