Merchant integration

Your server returns HTTP 402. The agent comes back with a PAYMENT-SIGNATURE header carrying a credit-scheme voucher. You submit that envelope to the SohoPay facilitator and poll. You do not settle on-chain yourself. Base URL: https://staging.api.sohopay.xyz/api/v1/facilitator. Authenticate with a merchant JWT or sk_live_ key.

Capture

POST /capture is the money call. Body:

{
  "x402Version": 2,
  "paymentPayload": {},
  "paymentRequirements": {}
}

x402Version must be 2. paymentPayload is the standard x402 credit-scheme envelope the agent presented (scheme: "credit", plus the voucher and the agent’s Ed25519 signature). paymentRequirements is optional and should echo what you advertised on the 402. Send a UUID v4 Idempotency-Key. A replay of the same key and body returns the original receipt with replayed: true while that receipt is still valid. A successful response:

{
  "success": true,
  "replayed": false,
  "receipt": {
    "paymentId": "0x…",
    "orderRef": "0x…",
    "amount": "1000000",
    "expiresAt": "…",
    "signature": "0x…",
    "signer": "0x…"
  }
}

receipt.paymentId is the poll key from this moment. Amounts are strings in asset base units.

A 200 from capture means the payment is queued for the next settleBatch. It is not CONFIRMED. Release the resource on CONFIRMED unless you have deliberately chosen capture-then-deliver and accept the settlement risk.

A Protocol V1 PaymentIntent is refused. If you see X402_AGENT_VOUCHER_REQUIRED, the client sent the old envelope. POST /verify is the optional pre-check. It returns { "isValid": true } or { "isValid": false, "invalidReason": "…" }. Verify does not capture and does not start settlement. There is no POST /settle.

Limits

Each merchant may call verify up to 120 times per minute and capture up to 30 times per minute. Burst limits still apply on top of those.

Discovery

GET /supported lists the credit scheme, x402Version: 2, network eip155:84532 on staging, and the settlement asset. GET /health is liveness.

Getting Started