Settlements & Payouts

Every payment an agent makes settles on-chain directly to your payout address — there is no batching, holding period, or T+1 cycle. This guide covers the settlement lifecycle, where funds land, how to read the fee breakdown, and how to reconcile your books.

Settlement lifecycle

When an agent pays an order, settlement happens in the same flow: the Policy Service co-signs, and an ERC-3009 TransferWithAuthorization moves USDC on Base to your payout address with ~1 second finality. You are paid the moment the payment succeeds. A settlement (stl_ ID) moves through three states:

State	Meaning
`initiated`	The co-signed transaction has been broadcast to Base. Usually lasts under 2 seconds.
`completed`	The transaction is final. USDC is in your payout wallet. `settlement.completed` and `merchant.settlement.completed` webhooks fire.
`failed`	The transaction reverted or a policy check failed at the last moment. No funds moved. `settlement.failed` fires with a reason.

Failed settlements are terminal — SohoPay never silently retries a settlement. The agent must resubmit the payment (orders expire after 10 minutes), and the failure reason tells you which side needs to act.

Payout destinations

Settlements pay out to the USDC wallet address on Base you registered during onboarding. You can change it under Settings → Payout in the dashboard; changes to the payout address on mainnet require re-confirmation by your authorized signer.

Bank off-ramp is on the roadmap, not shipped. Today the only payout destination is a Base USDC address. Fiat off-ramping (USDC → bank account) is planned post-mainnet — until then, use an exchange or off-ramp provider of your choice.

Fee breakdown per settlement

SohoPay’s fee is 5%, charged to the operator’s credit line — you always receive the full order amount. Fetch any settlement to see the exact math:

curl https://api-sandbox.sohopay.xyz/v1/settlements/stl_1e6f8a02 \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

const settlement = await sohopay.settlements.retrieve("stl_1e6f8a02");
console.log(settlement.grossAmount, settlement.merchantAmount);

settlement = sohopay.settlements.retrieve("stl_1e6f8a02")
print(settlement.gross_amount, settlement.merchant_amount)

Settlement

{
  "settlement_id": "stl_1e6f8a02",
  "payment_id": "pay_5c4b3a29",
  "merchant_id": "mch_4a2b9c31",
  "agent_id": "agt_7d1e5b2f",
  "status": "completed",
  "gross_amount": "100.00",
  "merchant_amount": "100.00",
  "operator_fee": "5.00",
  "fee_breakdown": {
    "lp_yield": "3.00",
    "protocol_revenue": "2.00"
  },
  "currency": "USDC",
  "onchain_tx": "0x4d5e...9a0b",
  "settled_at": "2026-08-22T12:31:07Z"
}

merchant_amount always equals gross_amount. The operator_fee (3% LP yield + 2% protocol revenue) is informational for you — it’s drawn from the operator’s credit line, not your payout. Full policy is in Fees.

CSV export

For accounting, export settlements over any date range. The export runs asynchronously and returns a download URL:

curl -X POST https://api-sandbox.sohopay.xyz/v1/settlements/export \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-2026-08" \
  -d '{
    "merchant_id": "mch_4a2b9c31",
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-31T23:59:59Z",
    "status": "completed"
  }'

const job = await sohopay.settlements.export({
  merchantId: "mch_4a2b9c31",
  from: "2026-08-01T00:00:00Z",
  to: "2026-08-31T23:59:59Z",
  status: "completed",
});
console.log(job.downloadUrl); // valid for 24 hours

job = sohopay.settlements.export(
    merchant_id="mch_4a2b9c31",
    from_="2026-08-01T00:00:00Z",
    to="2026-08-31T23:59:59Z",
    status="completed",
)
print(job.download_url)  # valid for 24 hours

The CSV contains one row per settlement with settlement_id, payment_id, agent_id, amounts, onchain_tx, and timestamps. The same export is available in the dashboard under Settlements → Export.

Reconciliation tips

Reconcile against the chain, not the API. Every completed settlement has an onchain_tx; the USDC Transfer event in that transaction is the ground truth for your books.
Key on settlement_id. Payments and settlements are 1:1, but treat stl_ as your ledger primary key and pay_/ord_ as references.
Consume webhooks, sweep with exports. Use merchant.settlement.completed webhooks for real-time ledger entries, then run a daily CSV export as a completeness check — webhook delivery is at-least-once, not guaranteed-exactly-once.
Expect exact amounts. USDC settlements have no FX, spread, or merchant-side fee. Any discrepancy between merchant_amount and the on-chain transfer is a bug — report it with the request_id.

Disputes

Because settlement is instant and on-chain, there is no chargeback mechanism — disputes are handled between you and the operator, with the operator liable for its agents’ transactions. See the trust model for how liability is assigned and what SohoPay will and won’t arbitrate.

Test it

Settle a sandbox payment and fetch its settlement — confirm merchant_amount equals gross_amount and fee_breakdown sums to operator_fee
Open the onchain_tx on Sepolia Basescan and match the USDC transfer to your payout address
Receive merchant.settlement.completed on your webhook endpoint
Run a CSV export for today and confirm the settlement appears in it

Next steps

Webhooks

Real-time settlement notifications with HMAC verification.

Fees

The full 5% fee policy and how the operator side works.

Trust Model

Liability, dispute handling, and what’s enforced on-chain.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Settlements & Payouts

Settlement lifecycle

Payout destinations

Fee breakdown per settlement

CSV export

Reconciliation tips

Disputes

Test it

Next steps

Webhooks

Fees

Trust Model

​Settlement lifecycle

​Payout destinations

​Fee breakdown per settlement

​CSV export

​Reconciliation tips

​Disputes

​Test it

​Next steps

Webhooks

Fees

Trust Model

Settlement lifecycle

Payout destinations

Fee breakdown per settlement

CSV export

Reconciliation tips

Disputes

Test it

Next steps