x402 Payment Modes

Standard x402 payments use DIRECT mode: the buyer pays the merchant's own receiving address, and delivery is gated on verified payment. DELEGATE is a separate payment mode, available on request, for the narrower set of flows where a payment must also trigger on-chain execution.

Each merchant has one receive_type; after receiving addresses or callback contracts are configured, switching modes is rejected until that configuration is removed.

DIRECT (standard)

DIRECT is the default and recommended mode for almost every integration.

Best fit

• paid APIs
• content gating
• routes where the user should pay the merchant directly

Characteristics

• settlement target is the merchant's own address
• no callback contract flow
• Hosted QuickPay can run without merchant API keys
• QuickPay links can also offer merchant-defined products with token-agnostic pricing — the buyer picks which token to pay with at pay time
• programmatic x402 uses merchant API keys; merchant-side Machine Payments Protocol (MPP) setup is configured in the merchant portal, and MPP buyer challenge/verify routes are public
• simpler operator model and lower integration complexity

DELEGATE (available on request)

DELEGATE exists for flows that need post-payment on-chain execution — for example NFT minting or staking — driven by a Bob-authorized MerchantCallback contract. Funds route through delegated protocol infrastructure instead of settling directly to the merchant address.

Characteristics

• settlement target is delegated infrastructure on a configured EVM chain
• callback-capable flow
• API-keyed only — via signed create-order or signed hosted checkout; not the no-key QuickPay flow or MPP
• requires API keys and a Bob-authorized MerchantCallback

Comparison

How to Choose

Default to DIRECT. It is the shortest path to production, covers payment-gated access, Hosted QuickPay without merchant API keys, API-keyed programmatic x402, and merchant-portal MPP setup, with fewer backend and contract dependencies.

Consider DELEGATE only when all of the following hold:

• payment must trigger on-chain logic beyond unlocking a response (mint, stake)
• you can run an API-keyed integration via signed create-order or signed hosted checkout
• your merchant account has been enabled for DELEGATE after the eligibility and compliance review

DELEGATE Callback Integration (advanced)

This section applies only to merchants enabled for DELEGATE. The end-to-end flow:

1. User requests an action (e.g. mint NFT).
2. Backend creates an order with callback_calldata.
3. User signs the EIP-712 payload and pays to the TSS address.
4. Bob submits the spend to MerchantCallback through x402SpentEip3009, x402SpentPermit2, or a ...WithCalldata variant.
5. Your contract executes the business logic (mint, stake, etc.).
6. Core returns success or proof to the backend.
7. DApp confirms the result to the user.

Integration outline

• Deploy the reference MerchantCallback from goatx402-contract (script DeployMerchantCallback.s.sol), or implement the IX402Callback interface yourself — its four entrypoints are x402SpentEip3009, x402SpentPermit2, and their ...WithCalldata variants.
• Register merchant_id, chain_id, and spent_address with the x402 operator; optional fields include spent_permit2_func_abi, spent_erc3009_func_abi, eip712_name, and eip712_version.
• Keep eip712_name, eip712_version, and spent_address consistent across the backend, the callback contract, and the operator records.
• Authorize the platform submitter on your callback contract with setAuthorizedCaller(bob, true).
• Test the full flow end to end: calldataSignRequest -> signature submit -> payment -> callback.

Callback contract security checklist

• Only allow the authorized platform submitter to call the x402Spent... entrypoints.
• Validate that originalPayer and owner are non-zero and that amount matches the expected payment.
• Validate the token address, not only the amount.
• Validate the structure and bounds of calldata_.
• Reject expired callbacks when the payload includes a deadline, and reject replayed callbacks using nonce or order-ID tracking.
• Bind the callback payload to the expected payer or order when applicable, and do not trust frontend-provided calldata without backend or contract validation.
• Use reentrancy guards if your callback invokes external contracts, and emit events for off-chain tracking and audit.

Production Notes

• Confirm the authorized x402 caller for the target environment before accepting production DELEGATE payments.
• For GOAT mainnet, use 0x211514377efE034E1E0410388cCE1a2bF10131F2 unless the x402 operator provides an updated address.
• For GOAT testnet3, use 0xA58917dB2712F1c09D0078aeee1BA3ED8eD3565a unless the x402 operator provides an updated address.
• Register callback metadata, and wait for platform operations to approve the callback-contract configuration, before accepting production DELEGATE payments.
• Treat payment confirmation and callback execution as separate states.
• Persist order IDs, callback results, and settlement proofs for auditability.

Related Guides

• Developer Quick Start
• API Reference
• Merchant Onboarding