Settlement on Sui

Immediate-payment rails transfer value before the upstream call runs. A facilitator does not trust transaction inputs alone: it checks finalized Sui events for the expected package and function, challenge-derived payment hash, offer-derived terms hash, amount, asset, parties, and rail authority. Only then may the gateway deliver the resource.

Agent path (spend account, MPP)

For the spend-account agent rail:

1. Build and sign spend_account::settle_policy_payment (delegate as sender).
2. Wait for finality.
3. Retry the paid URL with an MPP PaymentProof carrying the finalized digest, payer, challenge, and offer.
4. Gateway / facilitator verify the event and deliver.

x402 direct flows may carry signed transaction bytes for provider-side submission on rails that support that mode. Current spend-account resources reject transaction credentials and require MPP proof.

Receipts are immutable evidence of settlement, even if delivery later fails. Verify digests on Suiscan (or your network's explorer).

One settlement per authorization

Both dialects of one offer share a challenge and economic terms. Settlement claims one canonical right atomically so racing dialects cannot legitimately charge twice. On chain, the spend account also records an account-scoped payment_id_hash so the same payment id cannot be spent twice through different grants on one spend account.

Refundable offers

A normal immediate payment is final and does not promise delivery escrow. Sui Agent Payments also supports opt-in refundable offers. Such an offer signs refundable, a refund window, a shorter delivery-decision window, chain ID, payment salt, and refund destination. Settlement opens a shared RefundVault instead of paying the merchant immediately.

The gateway records successful delivery durably before the decision deadline. During the decision window, an operator can return funds for a classified post-settlement delivery failure. After the refund window, an unrefunded vault can release to the merchant. A canonical payment key and single-winner state machine prevent both refund and release from succeeding.

Refundability is per offer and requires production durability and a real refund operator. Never infer it from the rail name or promise it when the 402 does not carry the signed refundable terms.

Ambiguous outcomes

If a timeout, disconnect, or 5xx happens after signing or submission may have started, treat the result as ambiguous. Reconcile by challenge ID, transaction digest, receipt feed, and chain state before creating another payment. Do not blind-retry a new payment for the same work unit.