Testing

Before taking your integration to production, validate the entire flow in the sandbox. This guide walks through a full end-to-end payment test on Base Sepolia, demonstrates how to trigger deterministic error modes on demand, and concludes with the production-readiness checklist. The sandbox (https://staging.api.sohopay.xyz/api/v1, keys sk_test_...) skips KYB requirements and comes pre-funded with sandbox credit lines.

End-to-end sandbox walkthrough

Provision a test agent

Create an operational agent with a sandbox credit line:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-agent-e2e-01" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "name": "e2e-test-agent",
    "credit_limit": "50.00",
    "daily_limit": "25.00",
    "operator_acknowledgment": true
  }'

Confirm the response returns status: "active" and an agent_id.

Allowlist the agent

Before the Policy Service will co-sign payments, the merchant must approve the agent. In the sandbox, manage allowlists via the Merchant Dashboard under Merchant → Allowlist.

Create a test order

Generate an order for 1.00 USDC:

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: test-order-e2e-01" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "agent_id": "agt_3f9a1c8e",
    "amount": "1.00"
  }'

Record the generated order_id (valid for 10 minutes).

Execute payment

Submit payment with "sandbox_auto" to test the settlement pipeline:

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-test-order-e2e-01" \
  -d '{
    "order_id": "ord_9f8e7d6c",
    "agent_id": "agt_3f9a1c8e",
    "signature": "sandbox_auto"
  }'

Poll GET /api/v1/payments/{payment_id} until status transitions to settled.

Verify on Base Sepolia & Borrower Portal

Open the settlement_tx hash on Sepolia Basescan to inspect the ERC-3009 USDC transfer. Then, check the Borrower Portal to confirm your available credit decreased by 1.05 USDC (1.00 USDC order + 5% protocol fee).

Simulating error modes with magic amounts

The sandbox provides deterministic test amounts. Creating an order with one of these amounts triggers the corresponding failure mode automatically:

Order Amount	Simulated Error Code	What Your Integration Should Verify
`"402.00"`	`402 INSUFFICIENT_CREDIT`	Integration alerts operators without blind retries.
`"429.00"`	`429 RATE_LIMITED`	Integration waits for the `Retry-After` window.
`"666.00"`	`402 AML_DECLINED`	Integration aborts retries and routes to compliance review.

# Example: Trigger deterministic AML decline
curl -X POST https://staging.api.sohopay.xyz/api/v1/orders \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mch_sandbox_demo",
    "agent_id": "agt_3f9a1c8e",
    "amount": "666.00"
  }'

Simulating `AGENT_PAUSED` (403)

Test your emergency freeze handling:

Pause your test agent:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/pause \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Submit a payment for the agent. The gateway should immediately reject it with 403 AGENT_PAUSED.
Resume the agent via POST /api/v1/agents/agt_3f9a1c8e/resume.

Production readiness checklist

Complete this verification checklist before promoting your service to mainnet:

Webhook signature validation: Verified HMAC-SHA256 signatures, validated timestamps, and deduplicated by event_id.
Idempotency keys implemented: Stable pay-{order_id} keys on all payment submissions.
Backoff & jitter: Implemented exponential backoff with full jitter on 429 and 500 responses.
Circuit breaker active: Local fallback stops spamming the API when upstream service fails closed.
Secrets management: Production sk_live_ credentials loaded strictly from secrets managers (AWS Secrets Manager, Doppler, Vault).
Merchant KYB verified: Approved merchant KYB for live USDC settlement.

Next steps

Error Handling

Review the full status map and retry playbooks.

Webhooks Guide

Handle real-time settlement and rotation events.

Payment Flow

Revisit the end-to-end payment rail architecture.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

End-to-end sandbox walkthrough

Simulating error modes with magic amounts

Simulating `AGENT_PAUSED` (403)

Production readiness checklist

Next steps

Error Handling

Webhooks Guide

Payment Flow

​End-to-end sandbox walkthrough

​Simulating error modes with magic amounts

​Simulating AGENT_PAUSED (403)

​Production readiness checklist

​Next steps

Error Handling

Webhooks Guide

Payment Flow

End-to-end sandbox walkthrough

Simulating error modes with magic amounts

Simulating `AGENT_PAUSED` (403)

Production readiness checklist

Next steps