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

# Payment flow

> How an agent turns an HTTP 402 into a signed voucher and a confirmed USDC settlement.

A paywalled request is consent to pay that order. Complete the 402 path in one turn. Do not ask the borrower to approve the same merchant again when they already sent the agent to pay.

The agent calls MCP. The merchant calls the facilitator. Those are different credentials and different retries.

![x402 payment sequence from HTTP 402 through voucher signing, facilitator capture, batched Base settlement, and confirmation](/images/payment-light.png)

## Agent

**1. Read the 402**

Use the merchant's payment requirement as-is. Keep `orderRef` stable. One `orderRef` uses one payment `Idempotency-Key` for every retry, including after a policy accept or an expired intent.

**2. Prepare**

Call `prepare_x402_payment`. It creates or resumes the spend intent, runs [policy](/protocol/policy-service.md), reserves credit, and on allow returns `VOUCHER_ISSUED` with an **unsigned** voucher.

`get_context` can say a payment looks allowed. Prepare still rechecks. Do not skip prepare because context looked fine.

**3. Sign**

Sign with [`@sohopay/agent-signer`](/sdks/agent-signer) and send the `PAYMENT-SIGNATURE` header back to the merchant. If the signature field on the voucher is null, that is expected before you sign.

**4. Wait for the merchant**

You do not submit the batch. Poll `get_settlement_status` about every 2 seconds if you need to tell the borrower the payment landed. `CONFIRMED` means the batch entry settled. Available credit updates after that, not at voucher signing.

`create_spend_intent` and `evaluate_spend_policy` remain for spend that is not an x402 402. Do not use them to reimplement prepare, and do not call `execute_payment` on a 402.

## Recoverable stops

| Result | What you do |
| - | - |
| `X402_AGENT_KEY_NOT_REGISTERED` | Register the workload key, then retry the same order and the same idempotency key. |
| `AGENT_AUTHORIZATION_REQUIRED` | Finish the grant. If a payment is already in flight, retry the same order and key after the grant is `ACTIVE`. |
| `POLICY_DECISION_DENIED` with `RISK_FIRST_TIME_MERCHANT` on a 402 | Treat the pay request as acceptance and retry the same order and key. Do not ask again. |
| Other `POLICY_DECISION_DENIED` | Stop and surface the code. |
| `X402_INTENT_EXPIRED` | Retry the same order and the same key. Do not fetch a new merchant challenge. |
| `PENDING` or `FAILED` from prepare | Stop and surface the status. Do not invent a signature. |

## Merchant side of the same payment

The merchant posts the signed envelope to `POST /api/v1/facilitator/capture` and polls by `paymentId`. Capture returning 200 means the payment is queued for the next batch, which flushes about every 60 seconds. Fulfillment waits for `CONFIRMED`. See [Merchant integration](/guides/merchant-integration.md).

## Next steps

> [card] [Settlements](/guides/settlements-payouts.md)
>
> Status values and when to release goods.

> [card] [Errors](/api-reference/errors.md)
>
> Codes you will actually see.
