x402 Merchant Onboarding
This page covers the public merchant setup path for x402. It is not the full internal portal operations manual.
Overall Flow
Register the merchant
Select the environment you want to configure and prepare the basic business and technical details required for approval.
Configure settlement
Decide which chain, token, address, and payment mode should receive funds.
Generate API credentials when needed
Create the API key and secret for programmatic x402 or the DELEGATE mode (available on request). DIRECT Hosted QuickPay does not require merchant API keys.
Integrate and test
Connect the SDK or backend flow with the credentials for the selected environment. Validate payment handling, proof retrieval, and any callback path before launch.
Environment Options
x402 supports separate test and production merchant configurations.
- use the merchant ID, API key, and API secret issued for the selected environment
- use the supported tokens and chains from that merchant configuration
- keep test callback contracts separate from production callback contracts when you use both environments
- submit callback metadata for platform review in both test and production environments
- validate DIRECT or DELEGATE behavior end to end for the environment you plan to launch
What You Need to Decide
| Area | Decision |
|---|---|
| Settlement chain | where merchant funds should arrive |
| Settlement token | which supported asset should settle |
| Receiving address | merchant destination for DIRECT; spent_address callback target for DELEGATE |
| Payment mode | DIRECT (standard); DELEGATE is a separate mode available on request, disabled by default — contact the platform to enable after review |
| Callback logic | Bob-authorized MerchantCallback, required only for DELEGATE |
A merchant has one receive_type; after receiving addresses or callback contracts are configured, mode switches are rejected until that configuration is removed.
If you need DELEGATE, contact the platform or request it during merchant onboarding; enablement follows the eligibility and compliance review.
Credential Handling
Store API secrets on the server only. Use separate environments for testing and production.
- keep separate test and production credentials for programmatic x402 and, if enabled, DELEGATE
- rotate secrets when needed
- audit who has access to merchant credentials
Go-Live Checklist
- settlement address is configured correctly
- selected payment mode matches the intended UX
- DIRECT Hosted QuickPay or the programmatic backend can create orders successfully
- signature and payment flow are validated end to end
- proof retrieval is tested where applicable
- if using DELEGATE: API credentials and a Bob-authorized
MerchantCallbackare in place - fee and balance monitoring is in place