Payment Flow

This page walks through the complete lifecycle of a SohoPay payment: an order is created, the agent signs, the Policy Service validates and co-signs, and USDC settles on Base in approximately 1 second.

x402 in 60 seconds

HTTP has reserved the status code 402 Payment Required since 1997. The x402 protocol standardizes it for software: when a client requests a paid resource (an API, dataset, or compute job), the server responds with a 402 containing machine-readable payment terms. The client signs and pays, retrying with cryptographic payment proof. SohoPay integrates x402 with USDC on Base and adds crucial institutional infrastructure: revolving credit lines, real-time risk policies, and sanctions screening. Settlement utilizes ERC-3009 TransferWithAuthorization directly on USDC.

The payment lifecycle

Merchants always receive 100% of the order total. The 5% transaction fee is charged directly to the operator’s revolving credit facility.

Step 1: Create an order

The merchant’s backend creates an order when an agent requests a paid resource:

curl -X POST https://staging.api.sohopay.xyz/api/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"}
  }'

import { SohoPay } from "@sohopay/sdk";

const sohopay = new SohoPay({
  apiKey: process.env.SOHOPAY_API_KEY,
  baseUrl: "https://staging.api.sohopay.xyz/api/v1",
});

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

console.log("Order created:", order.orderId, order.expiresAt);

import os
from sohopay import SohoPay

sohopay = SohoPay(
    api_key=os.environ["SOHOPAY_API_KEY"],
    base_url="https://staging.api.sohopay.xyz/api/v1",
)

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

print("Order created:", order.order_id, order.expires_at)

Response (`201 Created`):

{
  "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 have a strict 10-minute TTL. Submitting a payment against an expired order returns 400 ORDER_EXPIRED. Always generate a fresh order rather than retrying expired ones.

Step 2: Submit the payment

The agent signs the order as EIP-712 typed data and submits the authorization signature. In the staging sandbox, pass "sandbox_auto" to test the loop without local key shares:

curl -X POST https://staging.api.sohopay.xyz/api/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", // In production, SDK provides EIP-712 signer
});

console.log("Payment status:", payment.paymentId, payment.status);

payment = sohopay.payments.submit(
    order_id=order.order_id,
    agent_id="agt_3f9a1c8e",
    signature="sandbox_auto",  # In production, SDK provides EIP-712 signer
)

print("Payment status:", payment.payment_id, payment.status)

For MCP Agent Builders: When using Cursor, Claude Desktop, or Windsurf, this step is handled autonomously behind the scenes by the SohoPay MCP server when calling spend_x402.

Step 3: Policy Service verification

Before co-signing, the Policy Service verifies four mandatory guardrails:

Merchant Allowlist: Validates that the merchant has approved this agent. Fails with 403 AGENT_NOT_ALLOWLISTED.
Agent Operational Status: Validates that the agent is not paused by its operator. Fails with 403 AGENT_PAUSED.
Credit & Velocity: Confirms the amount fits within available_credit and daily_limit. Fails with 402 INSUFFICIENT_CREDIT.
AML Screening: Real-time wallet sanctions screening. Fails with 402 AML_DECLINED.

Step 4: On-chain settlement & verification

Once the Policy Service co-signs, SohoPay broadcasts the ERC-3009 settlement to Base. Confirmation takes ~1 second:

curl https://staging.api.sohopay.xyz/api/v1/payments/pay_5c4b3a29 \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Response

{
  "payment_id": "pay_5c4b3a29",
  "order_id": "ord_9f8e7d6c",
  "status": "settled",
  "amount": "12.50",
  "settlement_tx": "0x4d5e...9a0b",
  "settled_at": "2026-08-22T12:01:05Z"
}

You can view the settlement on Sepolia Basescan and see the updated outstanding balance on the Borrower Portal.

Next steps

Error Handling

Explore idempotency, backoff retries, and decline playbooks.

Testing Guide

Run end-to-end sandbox tests and simulate failure modes.

x402 Protocol

Review the low-level HTTP 402 specifications.

Getting Started

Merchant Integration

Agent Wallet Setup

Protocol & Standards

Compliance & Risk

Operational Dashboards

Payment Flow

x402 in 60 seconds

The payment lifecycle

Step 1: Create an order

Response (`201 Created`):

Step 2: Submit the payment

Step 3: Policy Service verification

Step 4: On-chain settlement & verification

Next steps

Error Handling

Testing Guide

x402 Protocol

​x402 in 60 seconds

​The payment lifecycle

​Step 1: Create an order

​Response (201 Created):

​Step 2: Submit the payment

​Step 3: Policy Service verification

​Step 4: On-chain settlement & verification

​Next steps

Error Handling

Testing Guide

x402 Protocol

x402 in 60 seconds

The payment lifecycle

Step 1: Create an order

Response (`201 Created`):

Step 2: Submit the payment

Step 3: Policy Service verification

Step 4: On-chain settlement & verification

Next steps