Custom Integrations — FAQ
Short answers to the questions prospects and partners ask most often. Each answer links into a reference page for canonical data (retry tables, event catalog, error codes) so numbers live single-sourced and stay correct.
Integration flow & behavior
What happens if my /submit endpoint is slow or fails?
Simpler retries /submit up to 4 times total (1 initial + 3 retries) with 1–3 second exponential backoff between attempts. After exhaustion, the order is marked failed in the Simpler dashboard and queued for manual review; Simpler Integrations Support will reach out for troubleshooting.
See Retries & Timeouts for the full schedule.
Does Simpler enforce a per-request timeout on my handlers?
Yes. /submit has a 30-second per-attempt response timeout. A handler that exceeds 30 seconds is cut off and the attempt counts as a failure — with 4 attempts total, the worst-case /submit window is about 2 minutes. Aim well under 30 seconds (a practical ceiling of ~15s) so retries remain meaningful.
Webhooks have a more generous 2-minute per-attempt timeout. See Retries & Timeouts.
Are 4xx responses retried?
No. 4xx responses are treated as terminal and do not retry. Only 5xx responses, network errors, and connection timeouts trigger a retry on /submit. Webhook delivery is more aggressive — any non-2xx retries there, including 410 Gone.
How should my /quote handler signal a failure to the shopper?
Return a JSON body shaped as { code, message } with HTTP 400. The code must be one of the canonical values in the Error Codes reference if you want Simpler to render a specific shopper-facing message. Unknown codes fall back to a neutral generic message.
Order lifecycle & payment states
When /submit fires, has the shopper paid?
The payment is authorized at the card-network level, not necessarily captured. For synchronous methods (card, wallets) the order is effectively paid. For asynchronous methods (MultiBanco, MBway, Sequra) funds have not moved yet — create the order with status: PENDING and wait for an ORDER_UPDATED webhook with status: PAYMENT_SUCCESS before treating it as paid.
See Order Lifecycle for the per-method progression.
Can a shopper cancel a MultiBanco order after the voucher is issued?
No. Once issued, the MultiBanco transaction is locked at the PSP level. If the shopper does not pay within 72 hours, the voucher expires and an ORDER_UPDATED webhook with status: PAYMENT_FAILED fires. No funds have moved, so no refund is required.
Should my order-detail page show an async order as confirmed once /submit returns?
No. Render a "Pending Payment" badge until the PAYMENT_SUCCESS webhook arrives. Do not treat the order as ready for fulfillment on /submit alone — the funds have not moved for async methods.
Webhooks & async events
What events does Simpler send?
Today there is one event type: ORDER_UPDATED. The payload carries a status field (PAYMENT_SUCCESS or PAYMENT_FAILED) that encodes the specific transition.
See Webhook Event Catalog for payload details.
How does Simpler retry a failed webhook delivery?
7 attempts with attempt⁴ ± 10% jitter backoff (~56 minutes total window), 2-minute per-attempt timeout. Any non-2xx response or network error retries — there are no terminal status codes. After exhaustion the delivery dead-letters internally at Simpler with no partner-facing re-drive API.
See Retries & Timeouts.
How do I verify a webhook came from Simpler?
Compute HMAC-SHA1 of the raw request body using your app secret and compare to the X-Simpler-CRC header. This is the same signing pattern used on inbound Platform Interface calls.
See the Handling Webhooks tutorial for a working example.
Webhooks are retried — how do I avoid processing the same event twice?
Delivery is at-least-once, so duplicates are expected under retry. Simpler ships an Idempotency-Key HTTP header with each webhook — dedupe on that key in your handler.
What happens if my webhook endpoint fails all 7 retries?
The delivery dead-letters to Simpler's internal queue. There is no re-drive API and no partner-facing visibility into the failed delivery. Simpler's internal monitoring alerts the team to facilitate manual synchronization in the rare case a critical event does not land — reach out to Integrations Support if you suspect a missed event.
More categories (testing & environments, API versioning) arrive in a follow-up documentation update.