Managing Client Timeouts

This guide is for merchant integration engineers and backend or payment operations owners who implement or operate a Direct API /purchase orchestration. Use it to define a client-specific timeout, keep fulfillment safe when the client stops waiting, apply a pre-agreed shopper experience, and reconcile every attempt to a documented payment result.

A client timeout is an observation boundary, not proof that a payment failed. Keep the shopper-facing presentation separate from internal payment truth until reconciliation is complete.

Why timeout varies

End-to-end latency depends on the configured orchestration path. One payment may succeed with the first processor attempt. Another may require fraud analysis, receive a processor soft decline, and continue through fallback routing. Neither path establishes a universal latency bound.

DEUNA does not recommend one client-side timeout for every merchant. Define the value with your DEUNA Implementation Manager for your actual orchestration, then communicate the configured value to DEUNA so latency monitoring and alerting can align with the agreed behavior.

Prerequisites, environment, and authentication

Before implementing this flow, make sure you have:

• An existing authenticated Direct API integration that sends /purchase. This guide changes merchant-side waiting and reconciliation, not DEUNA request schemas or authentication.
• A merchant-owned order_id, original idempotency key, and retained identical request body for each eligible operation. These values preserve the original operation identity during recovery.
• A webhook consumer that can verify events where verification is enabled, process events idempotently, acknowledge them promptly, and update merchant order data. This makes webhooks the authoritative asynchronous outcome without duplicate merchant side effects.
• Access to the raw webhook body where signature verification is enabled. Follow Webhook verification before applying an event; do not invent a signature algorithm or payload field.
• A pre-agreed shopper UX policy: pending presentation or provisional decline presentation. Define the corresponding independent-reattempt control and how your existing merchant-owned status or notification experience will surface a pending attempt's final result.
• Agreement with your DEUNA Implementation Manager on the timeout, missing-webhook waiting window, reversal eligibility and provider behavior, operational escalation path, monitoring ownership, and any limitation that prevents enforcement of the duplicate-payment controls below. These details vary by merchant and must not be inferred from this guide.
• A sandbox or test integration in which you can simulate client timeouts, webhook outcomes, missing identifiers, and reversal outcomes without relying on production behavior.

Keep authentication material under your existing server-side controls. This guide does not publish hosts, credentials, headers, or request and response schemas.

Recommended flow

Both shopper UX policies start from the same internal state. When the Purchase request times out, the Merchant backend must Mark reconciliation pending with timeout_pending_reconciliation, retain the original correlation data, and Block fulfillment. The UX branch changes only what the shopper sees; it does not change payment truth or recovery precedence.

Pending presentation must Show payment pending and block an independent payment or route to the unresolved operation. Provisional decline presentation must Show provisional decline, then follow the agreed reattempt policy: either Hold new attempts until reconciliation or Correlate both attempts and reverse any late monetary outcome from the original. These labels describe shopper presentation and merchant controls only; the original payment truth remains unresolved.

Evaluate Active recovery needed and eligible?. If yes, Retry with same key and body, then ask whether the Retry returned a result?. A yes result enters Reconcile payment result. A no result, retry timeout, or transport error proceeds to Wait for verified webhook; it is not a payment failure. If the expected webhook is missing after the agreed window, Search Get Orders once. If no applicable result is found, Keep blocked and escalate. Verified webhooks remain the authoritative asynchronous outcome and must still be processed when a retry returns a result.

After reconciliation, apply the pre-agreed UX policy. Pending success must Show success and continue; pending failure must Show final failure through the merchant's existing status or notification experience. Under provisional decline, a documented failure means Keep decline final. A later authorized result means Void authorization, while processed or captured means Refund payment. When reversal is supported and the required identifiers are available, Start and track reversal. Close exception only after confirmation; otherwise, Keep blocked and escalate. A reversal request is not complete until its intended result is confirmed.

flowchart TD
    A["Purchase request times out"] --> B["Mark reconciliation pending"]
    B --> BH["Block fulfillment"]
    BH --> C{"Shopper message"}
    C -->|Pending| D["Show payment pending"]
    C -->|Decline| E["Show provisional decline"]
    E --> EA{"Reattempt policy"}
    EA -->|Hold| EB["Hold new attempts"]
    EA -->|Allow| EC["Correlate both attempts"]
    D --> F{"Active recovery needed and eligible?"}
    EB --> F
    EC --> F
    F -->|Yes| Y["Retry with same key and body"]
    F -->|No| G["Wait for verified webhook"]
    Y --> Z{"Retry returned a result?"}
    Z -->|Yes| I
    Z -->|No| G
    G --> H{"Webhook received?"}
    H -->|Yes| I["Reconcile payment result"]
    H -->|No, after wait| J["Search Get Orders once"]
    J --> K{"Result found?"}
    K -->|Yes| I
    K -->|No| L["Keep blocked and escalate"]
    I --> M{"Shopper policy"}
    M -->|Pending| N{"Payment outcome"}
    N -->|Success| O["Show success and continue"]
    N -->|Failure| P["Show final failure"]
    M -->|Decline| Q{"Payment status"}
    Q -->|Failed| R["Keep decline final"]
    Q -->|Authorized| S["Void authorization"]
    Q -->|Processed or captured| T["Refund payment"]
    Q -->|Other| L
    S --> AA{"Reversal available?"}
    T --> AA
    AA -->|Yes| U["Start and track reversal"]
    AA -->|No| X
    U --> V{"Reversal complete?"}
    V -->|Yes| W["Close exception"]
    V -->|No| X["Keep blocked and escalate"]

1. Agree the timeout and shopper UX policy

1. Map the configured purchase paths, including a first-attempt processor success and paths that add fraud analysis, soft-decline handling, and fallback routing. This reveals why one timeout cannot safely represent every orchestration.
2. Agree the client timeout with your DEUNA Implementation Manager and configure it in the merchant backend. A merchant-specific value limits false timeout outcomes without implying a provider latency guarantee.
3. Communicate the configured timeout to DEUNA. This lets DEUNA align latency monitoring and alerting with the behavior your client implements.
4. Choose either pending presentation or provisional decline presentation before production, and document the matching reconciliation behavior. For pending presentation, define the enforced independent-payment control and the existing merchant-owned status or notification experience that will surface the final result. For provisional decline, pre-agree whether independent reattempts are held or allowed under the correlated-attempt process below. These decisions prevent different services or operators from making contradictory payment, fulfillment, and reversal decisions.
5. Agree the missing-webhook waiting window, escalation ownership, supported reversal behavior, and any duplicate-payment-control limitation with your DEUNA Implementation Manager. These operational values and provider capabilities are merchant-specific, so this guide does not assign defaults.

2. Enter the unresolved state on timeout

1. When the /purchase call exceeds the configured client timeout, store timeout_pending_reconciliation as a merchant-owned marker. Do not write denied or another canonical DEUNA status based only on the timeout, because DEUNA may still be processing.
2. Retain the merchant order_id, original idempotency key, and identical request body under your existing security controls. Recovery depends on correlating the original operation rather than creating a new one.
3. Suppress fulfillment while the marker is unresolved. Goods or services must not be released until the documented result and any required decline-policy reversal are resolved.
4. Apply the pre-agreed shopper presentation without changing internal payment truth:
   • Pending presentation: tell the shopper that payment is pending and confirmation will continue asynchronously. While timeout_pending_reconciliation remains active, block an independent payment attempt or route the shopper back to the existing unresolved operation. If your checkout cannot enforce either control, agree that limitation and the duplicate-payment handling with your DEUNA Implementation Manager before production.
   • Provisional decline presentation: tell the shopper that confirmation timed out and show the attempt as declined in the shopper experience. Keep timeout_pending_reconciliation internally because the presentation does not prove the payment failed, then enforce one of the pre-agreed independent-reattempt policies below.

For provisional decline presentation, choose one independent-reattempt policy before production:

3. Recover the original operation safely

1. If active recovery is needed and the operation is eligible, retry the original operation with the same idempotency key and identical body to prevent a second payment operation. An already completed operation can then return its stored result without deliberate reprocessing.
2. Implement retry behavior by following Idempotent Requests, Step 3. That page owns retry implementation, counts, delays, concurrency, degradation, and error behavior, so this guide does not repeat or simplify them.
3. If the retry returns a matching, applicable documented payment result, record retry as the merchant-owned reconciliation source and send that result to the same UX-specific reconciliation handler used for verified webhooks and bounded search. Reusing one handler prevents the result source from changing payment, fulfillment, or reversal rules.
4. If the retry returns no applicable result, times out again, or fails at the transport layer, keep timeout_pending_reconciliation and the fulfillment hold. Continue waiting for the verified webhook because another client observation failure is not a payment failure.
5. Continue consuming verified webhooks even when the retry returns an applicable result. Idempotency does not replace the authoritative asynchronous channel or idempotent event handling.

4. Reconcile through webhooks and bounded search

Use one common reconciliation handler for an applicable documented result returned by same-key retry, a verified webhook, or the bounded Get Orders fallback. The handler records the result source, updates the merchant-owned order record, and applies the selected UX-specific rules so equivalent payment truth cannot produce source-dependent outcomes.

1. Consume webhooks for every purchase attempt, including asynchronous 3DS and APM flows. Webhooks remain the authoritative asynchronous outcome and keep the merchant order record current after the synchronous wait ends.
2. Where verification is enabled, apply the documented webhook verification process before updating payment truth. Process each accepted event idempotently and acknowledge it promptly so merchant handling remains safe and does not delay delivery handling.
3. When a verified webhook supplies a documented payment result, replace timeout_pending_reconciliation with that result and record the reconciliation source and timestamp. This closes the observation gap using authenticated asynchronous evidence.
4. Only if the expected webhook remains missing after the merchant-specific waiting window, run one delayed Get Orders search using order_id. This is a paginated, rate-limited search fallback, not a polling mechanism.
5. If that one search returns the matching order with an applicable documented payment result, use the result to replace timeout_pending_reconciliation and continue the same UX-specific handling as for a verified webhook. Require both a match and an applicable result to prevent an uncertain search response from driving payment decisions.
6. If no match exists or the result is absent, ambiguous, or unresolved, keep timeout_pending_reconciliation, keep fulfillment blocked, and escalate through the agreed DEUNA operational/support path. The fallback did not establish payment truth, so repeated search requests are not a safe substitute.
7. Do not use Get Order by token, GET /merchants/orders/{order_token}, as the initial timeout-recovery mechanism when no order_token was returned. The endpoint requires a token that the timed-out response may not have supplied.

5. Apply the reconciled result to the shopper UX

For pending presentation:

1. On a documented successful outcome, update the merchant-owned order record, clear the unresolved marker, surface success through the merchant's existing status or notification experience, and continue the normal post-payment flow. This delivers the final result to the shopper without prescribing a new DEUNA endpoint or payload.
2. On a documented final failure or decline, update the merchant-owned order record, clear the unresolved marker, and surface the final failure through the same existing status or notification experience. This replaces the temporary pending presentation with payment truth where the shopper already expects merchant-owned updates.
3. For any unresolved or unsupported outcome, retain the marker and fulfillment hold and escalate. Do not infer a final mapping that the status reference does not document.

For provisional decline presentation:

1. On a documented final failure, clear the unresolved marker and retain the shopper decline as final. No reversal is needed because reconciliation did not establish an authorized or charged outcome.
2. On authorized, enter the reversal flow and initiate an eligible void once the required identifiers are available. The shopper was told the attempt was declined, so reserved funds must not remain without operational follow-through.
3. On processed or captured, enter the reversal flow and initiate an eligible refund once the required identifiers are available. The shopper must not remain charged for an order the merchant treated as declined.
4. For any other, ambiguous, or unresolved status, keep fulfillment blocked and escalate through the agreed operational/support path. This guide does not create reversal mappings for undocumented or unsupported states.

6. Complete status-aware reversal handling

Use the documented order and payment status, Manage orders guidance, supported operation, and available identifiers to choose the reversal. Do not choose from the shopper message or the timeout itself.

1. Confirm reversal eligibility and required identifiers before calling the supported operation. Get Orders does not guarantee that every required reversal identifier is available, and processor or payment-method support can vary.
2. After initiating the void or refund, set a merchant-owned reversal-pending state and keep an operational exception open. Submission does not prove that the intended reversal completed.
3. Track the documented result until the intended reversal is confirmed complete. For asynchronous refunds, refunding or partial_refunding is intermediate; supported configurations communicate final refunded, partial_refunded, or denied outcomes by webhook.
4. Close the operational exception only when the intended reversal is confirmed complete. A partial_refunded result must be evaluated against the intended eligible reversal rather than assumed to satisfy it.
5. If the reversal is intermediate, denied, unsupported, cannot be initiated, lacks required identifiers, or is otherwise unconfirmed, keep fulfillment blocked and escalate through the agreed operational/support path. This prevents an unresolved monetary outcome from being mistaken for successful recovery.

Observe the flow

The following values are merchant-owned records, not claimed DEUNA request or response fields.

Create merchant-owned dashboards and alerts for timeout rate, latency relative to the agreed timeout, count and age of unresolved timeout markers, retry-result source and unresolved retry failures, pending shopper sessions, blocked or routed independent-payment attempts, correlated provisional-decline reattempts, pending final-result delivery failures, webhook delay, backup-search activation, reversal-pending age, reversal failures, and open operational exceptions. Agree thresholds and ownership with your DEUNA Implementation Manager; no universal values are established here.

Handle errors and edge cases

Avoid these anti-patterns

Validate in sandbox

Run these checks in the merchant's sandbox or test integration. They validate merchant behavior and observability; they do not promise production provider behavior, webhook timing, search availability, reversal support, or fund-availability timing.

Implementation checklist

• Map the actual orchestration paths and agree the client timeout with your DEUNA Implementation Manager.
• Communicate the configured timeout to DEUNA for latency-monitoring and alert alignment.
• Pre-agree pending or provisional decline presentation, independent-reattempt controls, the missing-webhook window, provider-specific reversal behavior, and escalation ownership.
• Persist order_id, the original idempotency key, the identical request body, timeout_pending_reconciliation, and the fulfillment hold.
• Under pending presentation, block an independent payment operation or route the shopper to the existing unresolved operation; agree any enforcement limitation and duplicate-payment handling before production.
• Under provisional decline, hold independent reattempts until reconciliation or correlate every allowed reattempt with the unresolved original and reverse any late monetary outcome from the original.
• Retry eligible operations only with the same key and identical body under the linked Step 3 guidance.
• Route an applicable documented retry result through the common reconciliation handler; keep a retry timeout, transport error, or non-applicable result unresolved.
• Verify webhooks where enabled, process accepted events idempotently, and acknowledge promptly.
• Use one delayed Get Orders search by order_id only when the webhook remains missing; never poll.
• Never depend initially on GET /merchants/orders/{order_token} when no order_token was returned.
• Under provisional decline, map only authorized to eligible void and processed or captured to eligible refund.
• Under pending presentation, update the merchant-owned order record and surface every final result through the existing status or notification experience.
• Keep the merchant-owned reversal-pending state and fulfillment hold until the intended reversal is confirmed.
• Escalate intermediate, denied, unsupported, ambiguous, unconfirmed, or missing-identifier outcomes through the agreed path.
• Validate both UX policies and every supported recovery and reversal branch in sandbox before production.
• Configure merchant-specific dashboards, alerts, exception ownership, and operational runbooks without inventing universal thresholds.

Next steps

• Implement timeout retry with Idempotent Requests, Step 3.
• Review Webhooks and Webhook verification for asynchronous outcomes.
• Use Get Orders for the bounded order_id fallback and Get Order by token only when order_token is available.
• Confirm status behavior in Order and payment status and reversal behavior in Manage orders.
• Implement eligible void and Refund V2 operations, then track supported asynchronous refund outcomes to completion.