> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant integration

> Accept an x402 credit payment by verifying and capturing the agent's voucher, then polling until the batch confirms.

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.ai/api/v1/facilitator` (staging) or `https://api.sohopay.ai/api/v1/facilitator` (production, after cutover). Authenticate with [a merchant JWT or `sk_live_` key](/authentication).

## Capture

`POST /capture` is the money call. Body:

```json
{
  "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:

```json
{
  "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.

> [!WARNING]
>
> 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.

## Next steps

> [card] [Settlements](/guides/settlements-payouts.md)
>
> Poll statuses and when to fulfill.

> [card] [Merchant onboarding](/guides/merchant-onboarding.md)
>
> How a merchant account is created.
