Troubleshooting

The agent cannot prepare a payment

Confirm the host is https://staging.mcp.sohopay.xyz/mcp.
X402_AGENT_KEY_NOT_REGISTERED: generate a workload key and call register_agent_workload_key, then retry the same order and idempotency key.
AGENT_AUTHORIZATION_REQUIRED: open the grant consent_url and wait until get_agent_authorization is ACTIVE.
The borrower has no handle: finish claim_handle before treating onboarding as done.
Token near expiry: call request_borrower_token. Do not use whoami scopes as the refresh signal.

x402Version must be 2. A V1 intent returns X402_AGENT_VOUCHER_REQUIRED.
The bearer token must be a merchant JWT or an sk_live_ key for that merchant. There is no sk_test_ key, and api-sandbox.sohopay.xyz is not the API.
HTTP 429: you are over 30 captures per minute. Retry with the same Idempotency-Key.

CREATED for about a minute is the flush interval, not a failure.
SUBMITTED means the batch is on chain and still gaining confirmations.
FAILED, TIMED_OUT, or DISPUTED: do not fulfill. Check the merchant is ACTIVE in the registry, then contact support with the paymentId.
Production will not settle. Protocol V2 is disabled there.

Available credit moves when the batch entry is CONFIRMED, not when the voucher is signed. Read get_outstanding_balance after that status.