What does x402 settlement_pending mean?

settlement_pending is a non-terminal settlement result. A transaction was broadcast, but confirmation could not be established before the receipt wait ended. The payment may still confirm, so it must not be treated as a normal failure.

Should an x402 client retry immediately after settlement_pending?

Do not create a fresh payment blindly. Preserve the transaction hash and network, reconcile that broadcast against the chain or the facilitator's documented idempotent settlement path, and only create a new authorization if the prior economic effect is known not to have occurred.

Does settlement_pending include a transaction hash?

Yes. The x402 v2 specification requires a SettleResponse with errorReason settlement_pending to carry a non-empty transaction hash and network so the caller can reconcile the unresolved broadcast.

Is settlement_pending the same as duplicate_settlement?

No. settlement_pending means confirmation is unresolved after broadcast. duplicate_settlement indicates the payment has already been submitted or consumed according to the scheme or facilitator. Both require state-aware handling rather than generating a new payment automatically.

Editorial

Research guide · x402 payment operations · 13 September 2026

x402 settlement_pending: reconcile a broadcast before retrying

An x402 settlement timeout is dangerous precisely because it can happen after the transaction has already been broadcast. Since x402 v2 now has a specific settlement_pending state, autonomous buyers and sellers should stop collapsing “the receipt wait timed out” into “payment failed”. The safe path is to preserve the broadcast evidence, reconcile it, and only then decide whether another authorization is justified.

Published 13 September 2026 · sources checked 13 September 2026

non-terminal

settlement_pending means the broadcast outcome is unresolved

hash required

x402 v2 requires a non-empty transaction hash and network for this state

reconcile first

do not turn an RPC timeout into a second economic authorization

Protocol boundary

A broadcast timeout is an uncertainty state, not a rejection

The x402 v2 specification defines settlement_pending for the case where a settlement transaction was broadcast but confirmation could not be established — for example because a node or RPC timed out while waiting for the receipt. A pending response must include the broadcast transaction hash and CAIP-2 network so the caller has something authoritative to reconcile.

The x402 Python SDK changed this behavior in version 2.20.0 on 18 August 2026 for EVM exact, upto and batch-settlement. Receipt-wait failures after broadcast now return settlement_pending instead of a terminal settlement error. That matters for agents whose retry policy was written around the older assumption that an error means the payment did not happen.

This is also an application-delivery problem. A seller should not release a protected result merely because verification passed if its payment contract requires confirmed settlement. Conversely, a buyer that did not receive the application result cannot assume the payment failed. Payment outcome and useful delivery are separate verdicts.

Reconciliation runbook

Persist the purchase in an unresolved state until the economic effect is known

Observed state	Operator action	Safety rule
No transaction broadcast	Terminal failure can be evaluated from the returned reason.	Do not invent a chain result.
settlement_pending	Persist transaction, network, payment fingerprint and facilitator response; mark the purchase unresolved.	Pending is not failed.
Chain confirms expected transfer	Promote payment state to settled only after amount, asset, destination and network match the purchase.	Then reconcile application delivery separately.
Chain proves failure / replacement	Use the provider's documented retry path or create a new authorization only after the original economic effect is ruled out.	Do not reuse stale assumptions.
Still unknown	Keep the purchase quarantined from automatic repayment and continue reconciliation with bounded backoff.	Unknown is a durable state, not permission to spend again.

What to persist

Reconcile the payment, not just the HTTP response

The original logical purchase ID or request fingerprint, including method/tool, canonical resource and request parameters.
The accepted x402 payment requirements: scheme, network, asset, amount or ceiling, payTo and relevant extension terms.
The signed payment payload identity without logging private keys or other reusable secrets.
The settlement_pending response, transaction hash, network and observation timestamp.
The eventual chain/facilitator evidence and a separate application-delivery verdict.

For duplicate-safe logical-request retries, pair this with the x402 payment-identifier guide. The idempotency key answers “is this the same purchase?”; settlement_pending answers “did the already-broadcast economic action finish?”

Retry policy

Do not make “retry” synonymous with “sign another payment”

A facilitator may offer an idempotent way to re-submit the identical settlement request and poll the outcome. PayAI, for example, documents settlement_pending as unresolved and instructs callers to re-submit the identical body; its facilitator also documents an optional Idempotency-Key contract. Those are provider-specific behaviors, not universal x402 requirements, so check the facilitator you actually use.

If the authoritative chain evidence shows the expected value transfer confirmed, the payment side is settled even if the original HTTP response was lost. The next question is whether the paid resource was successfully delivered. If the transaction failed or was definitively not included, then follow the scheme/provider's documented retry path. If evidence remains ambiguous, keep the purchase unresolved rather than spending again.

For upto or channel-style schemes, also reconcile the actual settled amount or cumulative state rather than assuming the original maximum equals the economic effect. See the x402 upto metered-billing guide for that boundary.

Buyer and seller checks

The minimum controls for autonomous wallets

Model payment as at least unpaid → authorized → broadcast → pending → settled/failed; do not compress it to a boolean.
Quarantine a logical purchase from fresh authorization while a broadcast is pending.
Verify network, asset, destination and amount before promoting a chain transaction to “settled”.
Keep wallet-level per-call, per-vendor and time-window spend caps even when retry logic is correct.
Separate settlement evidence from delivery evidence so support and automated recovery can reason about both.

For the broader verify/settle/delivery model, read how to verify an x402 API before paying. Qualified buyers can inspect zFinia's machine-service catalogue at /api.

Primary sources