Code Examples

The sohopay-examples repository collects small, runnable projects that demonstrate each core flow end to end. Every example ships with a README, works against the sandbox out of the box, and is the fastest way to see a pattern working before you adapt it.

git clone https://github.com/sohopay/sohopay-examples
cd sohopay-examples
export SOHOPAY_API_KEY="sk_test_..."

Every example runs in CI against the live sandbox on each commit. If it’s in the repo, it works against the current API.

What’s in the repo

Example	Description	What you learn
`quickstart`	Your first API call in 5 minutes — create an agent and read it back.	Client initialization, authentication, response shapes.
`full-flow`	The complete create → pay → settle lifecycle for one payment.	Orders, payment submission, polling vs. webhooks, the 10-minute order TTL.
`error-handling`	Deliberately triggers errors and recovers with retries.	`SohoPayError` handling, exponential backoff, safe retries with idempotency keys.
`webhook-express`	Express.js webhook receiver with signature verification.	HMAC verification, fast 2xx responses, dedupe by `event_id`.
`webhook-flask`	The same receiver in Python with Flask.	Identical pattern in Python idiom.
`aml-decline-test`	Uses a sandbox test wallet that triggers `AML_DECLINED`.	How AML screening surfaces in the API and the `agent.aml_declined` event.
`rate-limit-test`	Hammers an endpoint until `429`, then recovers cleanly.	`Retry-After`, `X-RateLimit-*` headers, backoff and circuit-breaker patterns.

TypeScript and Python variants exist for each example unless the framework implies the language (Express.js, Flask).

Taster: Express.js webhook receiver

The full webhook-express example, inlined. It verifies the HMAC-SHA256 signature, dedupes by event_id, acknowledges fast, and processes asynchronously — the four things every production receiver must do. See the webhooks guide for the why behind each step.

import express from "express";
import { SohoPay, SohoPayError } from "@sohopay/sdk";

const sohopay = new SohoPay({ apiKey: process.env.SOHOPAY_API_KEY });
const app = express();

// SohoPay retries at 5s, 30s, 2m, 10m, 1h, then hourly up to 24h —
// so the same event can arrive more than once. Dedupe by event_id.
const seen = new Set<string>(); // use Redis or your DB in production

app.post(
  "/webhooks/sohopay",
  express.raw({ type: "application/json" }), // raw body — needed for HMAC
  (req, res) => {
    let event;
    try {
      event = sohopay.webhooks.verify({
        payload: req.body,
        signature: req.header("Sohopay-Signature"),
        timestamp: req.header("Sohopay-Timestamp"),
        secret: process.env.SOHOPAY_WEBHOOK_SECRET,
      });
    } catch (err) {
      if (err instanceof SohoPayError) return res.sendStatus(400); // bad signature
      throw err;
    }

    if (seen.has(event.eventId)) return res.sendStatus(200); // duplicate
    seen.add(event.eventId);

    // Acknowledge immediately; anything slower than a few seconds
    // risks a timeout and an unnecessary retry.
    res.sendStatus(200);

    // Process async, after the response is sent.
    setImmediate(() => {
      switch (event.type) {
        case "payment.settled":
          console.log("Settled:", event.data.paymentId, event.data.settlementTx);
          break;
        case "payment.failed":
          console.warn("Failed:", event.data.paymentId, event.data.failureCode);
          break;
        default:
          console.log("Unhandled event:", event.type);
      }
    });
  }
);

app.listen(3000, () => console.log("Listening on :3000"));

Test it locally by registering the endpoint (use a tunnel like ngrok, or inspect payloads first with webhook.site) and firing a test delivery:

curl -X POST https://api-sandbox.sohopay.xyz/v1/webhooks/whk_1a2b3c4d/test \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Contributing

The repo accepts pull requests. If you built an integration pattern others would benefit from — a queue-backed receiver, a Next.js route handler, a LangChain tool — open a PR. Examples must pass the CI suite against the sandbox before merging.

Go and CLI examples will land alongside the Go SDK and sohopay CLI, both of which are on the roadmap and not yet shipped.

Next steps

TypeScript SDK

Full method reference and error handling for Node.js.

Python SDK

The same client surface in Python idiom.

Testing Guide

Sandbox test wallets, edge cases, and CI patterns.

SDKs

Tools

What’s in the repo

Taster: Express.js webhook receiver

Contributing

Next steps

TypeScript SDK

Python SDK

Testing Guide

​What’s in the repo

​Taster: Express.js webhook receiver

​Contributing

​Next steps

TypeScript SDK

Python SDK

Testing Guide

What’s in the repo

Taster: Express.js webhook receiver

Contributing

Next steps