Payment Flow

This page walks the full lifecycle of a SohoPay payment: an order is created, the agent signs, the Policy Service checks and co-signs, and USDC settles on Base in about a second. Read it before wiring payments into your agent — it explains what each API call does and what can stop a payment.

x402 in 60 seconds

HTTP has had a 402 Payment Required status code since 1997, reserved but never standardized. x402 makes it a first-class protocol: when a client hits a paid resource, the server responds 402 with machine-readable payment terms; the client pays and retries with proof of payment. No checkout page, no card form, no human — which is exactly what autonomous agents need. SohoPay implements x402 with USDC on Base and adds what raw x402 lacks: credit lines (so agents don’t hold funds), policy enforcement, and compliance screening. Settlement uses ERC-3009 TransferWithAuthorization on USDC — see ERC-3009.

The flow at a glance

Merchants are always paid in full; the 5% fee is charged to the operator’s credit line.

Step 1: Create an order

Any party with an API key for the merchant creates the order — typically the merchant’s backend when the agent requests a paid resource:

curl -X POST https://api-sandbox.sohopay.xyz/v1/orders \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-invoice-8841" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "agent_id": "agt_3f9a1c8e",
    "amount": "12.50",
    "metadata": {"invoice": "8841"}
  }'

const order = await sohopay.orders.create({
  merchantId: "mch_sandbox_demo",
  agentId: "agt_3f9a1c8e",
  amount: "12.50",
  metadata: { invoice: "8841" },
});

order = sohopay.orders.create(
    merchant_id="mch_sandbox_demo",
    agent_id="agt_3f9a1c8e",
    amount="12.50",
    metadata={"invoice": "8841"},
)

Response

{
  "order_id": "ord_9f8e7d6c",
  "merchant_id": "mch_sandbox_demo",
  "agent_id": "agt_3f9a1c8e",
  "amount": "12.50",
  "status": "pending",
  "settlement_address": "0x2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "expires_at": "2026-08-22T12:10:00Z",
  "created_at": "2026-08-22T12:00:00Z"
}

Orders expire 10 minutes after creation. A payment against an expired order fails with 400 ORDER_EXPIRED — create a fresh order rather than retrying.

Step 2: Submit the payment

The agent signs the order as EIP-712 typed data and submits the signature. In sandbox, pass "sandbox_auto" and SohoPay signs on the agent’s behalf, so you can test the full flow before implementing signing:

curl -X POST https://api-sandbox.sohopay.xyz/v1/payments \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-ord-9f8e7d6c" \
  -d '{
    "order_id": "ord_9f8e7d6c",
    "agent_id": "agt_3f9a1c8e",
    "signature": "sandbox_auto"
  }'

const payment = await sohopay.payments.submit({
  orderId: order.orderId,
  agentId: "agt_3f9a1c8e",
  signature: "sandbox_auto", // sandbox only; SDK handles EIP-712 in production
});

console.log(payment.paymentId, payment.status);

payment = sohopay.payments.submit(
    order_id=order.order_id,
    agent_id="agt_3f9a1c8e",
    signature="sandbox_auto",  # sandbox only; SDK handles EIP-712 in production
)

print(payment.payment_id, payment.status)

A 202 means the payment is accepted for settlement; payment.created fires immediately and payment.settled (with the settlement_tx hash) typically follows within ~1 second. Subscribe via webhooks rather than polling in production.

What the Policy Service checks

Before co-signing, the Policy Service runs four checks on every payment:

Allowlist — the merchant has allowlisted this agent, verified on-chain. Fails with 403 AGENT_NOT_ALLOWLISTED.
Credit — the amount plus fee fits within the agent’s available credit and daily limit. Fails with 402 INSUFFICIENT_CREDIT.
Rate limits — per-agent transaction velocity is within bounds. Fails with 429 RATE_LIMITED. See Rate Limits.
AML — Didit wallet screening on the counterparties. Fails with 402 AML_DECLINED. See AML Screening.

Fail-closed by design

Signing is MPC 2-of-3, and the Policy Service holds a mandatory share. If the Policy Service is down or cannot complete its checks, no settlements happen — payments queue or fail rather than bypass policy. You should treat a burst of 500 INTERNAL responses on POST /payments as a signal to back off and retry, not to route around; see Error Handling.

You never touch MPC signing

The 2-of-3 ceremony — share coordination, co-signing, key custody — happens entirely inside SohoPay’s MPC infrastructure. Your integration surface is two REST calls (POST /orders, POST /payments) and, in production, one EIP-712 signature that the SDKs produce for you. There are no key files to manage and no signing servers to run.

Next steps

Error Handling

Retries, idempotency, and the errors this flow can return.

Testing

Run this flow end to end in the sandbox, including failure cases.

x402 Protocol

The full protocol spec behind the flow.

Getting Started

Merchant Integration

Agent Wallet Setup

Protocol & Standards

Compliance & Risk

Operational Dashboards

Payment Flow

x402 in 60 seconds

The flow at a glance

Step 1: Create an order

Step 2: Submit the payment

What the Policy Service checks

Fail-closed by design

You never touch MPC signing

Next steps

Error Handling

Testing

x402 Protocol

​x402 in 60 seconds

​The flow at a glance

​Step 1: Create an order

​Step 2: Submit the payment

​What the Policy Service checks

​Fail-closed by design

​You never touch MPC signing

​Next steps

Error Handling

Testing

x402 Protocol

x402 in 60 seconds

The flow at a glance

Step 1: Create an order

Step 2: Submit the payment

What the Policy Service checks

Fail-closed by design

You never touch MPC signing

Next steps