Customer risk holds

Customer risk holds protect a merchant from repeat loss after a dispute finishes with a final merchant-loss outcome. They are customer-scoped controls: the gateway evaluates the current active holds every time checkout providers are selected and again immediately before a payment-side effect.

This is different from an unresolved dispute. Open or under-review disputes temporarily block checkout with CHECKOUT_BLOCKED_BY_DISPUTE. A final lost or accepted dispute can create a durable customer risk hold; a final won dispute does not.

Policies

An active hold has one of three actions:

• Block all prevents a new payment for the customer.
• Manual review blocks payment until an operator reviews and updates or releases the hold.
• Allow provider types limits the customer to an explicit intersection of provider types, typically lower-risk manual methods such as wire transfer or Wise. A provider must also be enabled and assigned to the current Site. If no allowed provider remains, checkout is blocked.

When several active holds apply, block-all takes precedence, followed by manual review. If neither applies, the gateway intersects their provider allowlists. Restriction is enforced server-side even when a caller uses a direct billing-request endpoint or an older checkout session contains stale provider metadata.

Automatic and manual holds

Automatic holds are created idempotently when a supported provider webhook or an operator records a final merchant-loss dispute. Dispute resolution remains committed if hold creation later fails; the transaction view reports the hold outcome as created, existing, skipped, or failed so an operator can recover safely.

Editors and administrators can create a manual hold from the customer context. The Admin API accepts a tenant-scoped clientId; the stable customer identity is resolved server-side. Email search hashes and other matching internals are never part of the public request or response.

Each hold records its source, action, allowed provider types, optional expiry and notes, version, status, and append-only audit history. Updates use optimistic concurrency. Operators can release a hold early, expire it, or retry a failed automatic outcome without creating duplicates.

Admin workflow

Use the customer or transaction detail view to inspect current holds and their history. Before changing a hold:

1. Confirm the dispute outcome and customer identity.
2. Choose Block all, Manual review, or the minimum safe provider types.
3. Add an operational note and optional expiry.
4. Save the hold, then verify the resulting status and audit entry.

If the UI reports a version conflict, reload the current record before retrying. If a dispute shows a failed hold outcome, correct the underlying configuration or data problem and use the recovery action. Do not recreate the dispute or reverse its final status solely to retry a hold.

Checkout and integration behavior

The runtime returns a safe 409 Conflict response with a correlation requestId:

• CHECKOUT_BLOCKED_BY_CUSTOMER_HOLD when payment cannot proceed.
• CHECKOUT_RESTRICTED_BY_CUSTOMER_HOLD when the requested provider is outside the current allowlist.

The hosted checkout displays customer-safe guidance and only renders eligible providers. The official WooCommerce and aMember plugins recognize these codes, show a support-safe message, and include the requestId when available. Malformed, unknown, or oversized upstream error bodies continue to use the plugins' generic failure handling.

Evaluation or identity-hash failures return a generic server error and do not call provider SDKs, create a transaction, consume a session, or enqueue payment work. Public responses and plugin logs must not expose customer hashes, internal policy details, credentials, or raw checkout payloads.

Rollout notes

Deploy the shared domain contracts before the admin and main backends, then deploy the admin and checkout frontends and update the official plugins. Existing sessions are not trusted as the source of truth: current holds are evaluated at payment time. Monitor failed automatic outcomes and the two typed checkout codes during rollout.

See Checkouts for the buyer flow and E-commerce integrations for plugin setup and error behavior.