Settle an x402 payment
Settles an x402 payment. Facilitator Service validates the buyer’s signed
authorization, screens both parties, records the payment, and submits
the USDC transfer onchain. For exact, the transfer is an EIP-3009
authorization submitted through a Circle relayer. For upto, it is a
Permit2 transfer submitted from the facilitator wallet the buyer signed
in witness.facilitator.
A settlement outcome always uses HTTP 200; there is no pending status
code. A terminal result means settlement resolved within the HTTP wait
window. If the outcome is unresolved at the wait deadline, the 200
response carries success: false with
errorReason: settlement_pending and a paymentId. Pending is not
failure: settlement continues, and
Get payment status
reconciles the outcome. Do not fulfill on pending.
A rejected request or an internal failure uses the 4xx and 5xx codes below instead, and carries no settlement outcome.
Include a payment-identifier extension in the request body for
idempotency scoped to your seller account. Retries with the same
identifier converge on the same payment. Without an identifier, a
retry must reuse the exact same signed buyer authorization or the
retry is treated as a new charge.
For the upto scheme, paymentRequirements.amount is the actual
amount to charge, from 0 up to the maximum the buyer signed. The rest
of paymentPayload must be the same signed payload sent to verify.
Facilitator Service checks the buyer’s USDC balance and Permit2
allowance against the actual amount. If the payload carries an
eip2612GasSponsoring permit, Facilitator Service submits it with the
settlement, so the buyer needs no approval transaction. A settlement of
0 completes without an onchain transaction. upto settlement requires
a Circle API key.
Each upto authorization settles at most once. A repeat request from
the same seller for the same authorization returns the original
payment, even with a different amount, provided the other request
terms match (such as resource.url, maxTimeoutSeconds, and
extra.name and extra.version). Otherwise it returns 409
payment_identifier_conflict. A request for that authorization from a
different seller returns 409 credential_bound_elsewhere.
Example signatures come from a public test key. Never fund it.
Authorizations
Bearer token authentication with a Circle API key. Use this for
production settlement. Settling with an API key also binds the payTo
to your Circle account, which ends the keyless trial allowance.
Body
x402 protocol version. Facilitator Service supports version 2.
2 x402 v2 payment payload. Includes the payment terms the buyer accepted and
the signed authorization for the USDC transfer: an EIP-3009 authorization
for exact, or a Permit2 authorization for upto.
Payment terms the seller advertises for an x402 resource. Facilitator Service validates that the buyer's authorization matches these requirements.
Response
Terminal or unresolved settlement result
Whether the transfer settled onchain within the wait window. Check the
settlement-status extension to distinguish failed from pending.
true
Buyer address recovered from the signed authorization.
"0x9aE2..."
Transaction hash on terminal success. Empty string when settlement is
still pending or failed before submission. Also empty for an upto
settlement of 0, which completes without an onchain transaction.
"0x6f9e1d..."
CAIP-2 network identifier for the settled payment.
"eip155:5042002"
Amount in atomic USDC units. For upto, this is the amount actually
settled, not the maximum the buyer signed.
"1000000"
Reason code. Present whenever success is false, either because the
payment failed terminally or because the outcome was unresolved at the
wait deadline (settlement_pending).
settlement_pending, invalid_x402_version, unsupported_scheme, invalid_network, invalid_payment_requirements, invalid_payload, invalid_exact_evm_payload_recipient_mismatch, invalid_exact_evm_payload_authorization_value_mismatch, invalid_exact_evm_payload_authorization_valid_after, invalid_exact_evm_payload_authorization_valid_before, invalid_exact_evm_payload_signature, invalid_transaction_state, insufficient_funds, invalid_permit2_spender, invalid_permit2_recipient_mismatch, permit2_token_mismatch, invalid_upto_evm_payload_settlement_exceeds_amount, permit2_not_yet_valid, permit2_deadline_expired, upto_facilitator_mismatch, invalid_permit2_signature, permit2_invalid_nonce, invalid_eip2612_extension_format, eip2612_from_mismatch, eip2612_asset_mismatch, eip2612_spender_not_permit2, eip2612_deadline_expired, permit2_2612_amount_mismatch, permit2_simulation_failed "invalid_exact_evm_payload_signature"
x402 extensions. Facilitator Service returns a settlement-status
extension only after a payment has been recorded — on
settlement_pending and on terminal failures that have a
paymentId. Pre-recording validation failures (invalid_x402_version,
unsupported_scheme, invalid_network,
invalid_payment_requirements, invalid_payload, and the other
request-validation errorReason values) return success: false with
an errorReason and no extension, because there is no paymentId to
reconcile. When present, the extension carries status, paymentId,
and statusUrl. Settlement returns no poll hints.