Quickstart

You need a test secret API key. Create one in the dashboard under Settings → API keys, choosing Test and Secret. It starts with sp_sk_test_. Everything below runs against https://api.southpay.io/api/v2. There is no separate sandbox host. Test and live mode are selected by which key you send.

In test mode your store has exactly one usable asset: Ethereum Sepolia (SETH). Every test payment intent returns one deposit address on Sepolia. Live mode returns one address per asset your store has enabled. See Environments, and Sepolia test wallet to get the test ETH you need to pay an intent.

1. Create a payment intent

You price in fiat. SouthPay locks an exchange rate and works out the crypto amount.

curl -X POST https://api.southpay.io/api/v2/payments \
  -H "Authorization: Bearer sp_sk_test_YOUR_API_KEY" \
  -H "Idempotency-Key: test-8f14e45f-order-8721" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": {
      "amount": "49.99",
      "currency": "USD",
      "success_url": "https://yourapp.example/success",
      "failed_url": "https://yourapp.example/cancel",
      "order_id": "order_8721",
      "metadata": { "order_id": "order_8721" }
    }
  }'

{
  "id": "9c1d7f42-6a3b-4e58-9f10-2b8c5d4e7a91",
  "reference": "K4TP9WQZ2XR7HB3M",
  "hosted_url": "https://pay.southpay.io/K4TP9WQZ2XR7HB3M",
  "status": "pending",
  "state_reason": null,
  "settlement_currency": "USD",
  "settlement_amount": "49.99",
  "expires_at": "2026-08-07T15:00:00.000Z",
  "created_at": "2026-08-07T14:00:00.000Z",
  "success_url": "https://yourapp.example/success",
  "failed_url": "https://yourapp.example/cancel",
  "order_id": "order_8721",
  "title": null,
  "description": null,
  "terminal": false,
  "settlement_status": null,
  "auto_swap_status": null,
  "reconciliation_status": null,
  "payment_addresses": [
    {
      "id": "3f2a8b19-40cd-4c7e-8a55-11d9e6b0c342",
      "address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
      "status": "pending",
      "crypto_amount_atomic": "22533243243243243",
      "exchange_rate_snapshot": "2218.500000000000000000",
      "created_at": "2026-08-07T14:00:00.000Z",
      "supported_asset": {
        "asset_id": "SETH",
        "coin_symbol": "ETH",
        "chain_symbol": "SETH",
        "token_standard": "Native",
        "chain_name": "Ethereum Sepolia",
        "network": "ethereum",
        "atomic_decimals": 18,
        "min_withdrawal_atomic": "100000000000000",
        "fiat_eligible": false
      }
    }
  ]
}

Three fields to store against your order right now:

id is the UUID you use on every later API call. All SouthPay ids are bare UUIDs; there is no pi_ prefix scheme.
reference is 16 uppercase alphanumeric characters. This is the customer-facing identifier and the checkout token, and it is what arrives in webhooks.
expires_at is 60 minutes from creation by default. Send expires_in (seconds, 300 to 86400) on create for a different window. See Payment lifecycle.

crypto_amount_atomic is the exact amount the customer must send, in the asset’s smallest unit. Divide by 10 ** atomic_decimals for a human amount, here 0.022533243243243243 ETH. The Idempotency-Key header is optional on this endpoint but retrying without one creates a second intent. Read Idempotency before you build a retry loop; the behaviour has edges.

2. Send the customer to checkout

Redirect to the hosted_url on the response. Do not build the URL yourself.

https://pay.southpay.io/K4TP9WQZ2XR7HB3M

The page shows a QR code and the exact amount for each address on the intent, tracks confirmations live, and redirects to your success_url when the payment completes. There is no frontend work to do.

3. Register a webhook endpoint

curl -X POST https://api.southpay.io/api/v2/webhook_endpoints \
  -H "Authorization: Bearer sp_sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "url": "https://yourapp.example/webhooks/southpay",
      "description": "Order fulfillment",
      "subscribed_events": [
        "payment_intent.completed",
        "payment_intent.failed",
        "payment_intent.expired",
        "payment_intent.refunded"
      ]
    }
  }'

{
  "id": "b7e4c210-5d83-4f16-9c02-6ea1f3d85b47",
  "url": "https://yourapp.example/webhooks/southpay",
  "description": "Order fulfillment",
  "status": "active",
  "subscribed_events": [
    "payment_intent.completed",
    "payment_intent.failed",
    "payment_intent.expired",
    "payment_intent.refunded"
  ],
  "signing_secret": "whsec_4f8b1c...",
  "delivery_success_rate": null,
  "created_at": "2026-08-07T14:01:00.000Z"
}

signing_secret is returned only here and on secret rotation. Store it before you close the terminal. No endpoint will show it to you again.

subscribed_events is required and must list every event you want by name. Wildcards are not supported. "*" and "payment_intent.*" both fail validation. See the full event list.

4. Verify and handle the delivery

When the payment confirms, SouthPay POSTs this to your URL:

Webhook body

{
  "id": "d31a5c88-9b74-4c02-b6ff-7e2a4d190c65",
  "type": "payment_intent.completed",
  "created": 1786125600,
  "livemode": false,
  "api_version": "2026-04-14",
  "data": {
    "object": {
      "id": "K4TP9WQZ2XR7HB3M",
      "status": "completed",
      "settlement_amount_cents": 4999,
      "settlement_currency": "USD",
      "from_status": "processing",
      "to_status": "completed",
      "metadata": { "order_id": "order_8721" }
    }
  }
}

data.object.id is the reference, not the payment intent UUID. There is no reference key in the payload, and the amount is settlement_amount_cents (an integer in minor units), not settlement_amount. Look the intent up by reference, or fetch it by UUID from your own order record.

Verify the signature against the raw request body before you trust anything in it.

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: Buffer, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map(p => p.split("=", 2) as [string, string])
  );
  if (!parts.t || !parts.v1) return false;

  const computed = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody.toString("utf8")}`)
    .digest("hex");

  const a = Buffer.from(computed);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

const app = express();

app.post(
  "/webhooks/southpay",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const sig = req.headers["southpay-signature"] as string | undefined;
    if (!sig || !verify(req.body, sig, process.env.SOUTHPAY_WEBHOOK_SECRET!)) {
      return res.status(401).end();
    }

    const event = JSON.parse(req.body.toString());
    res.json({ received: true });

    if (await alreadyProcessed(event.id)) return;
    await markProcessed(event.id);

    if (event.type === "payment_intent.completed") {
      await fulfillOrder(event.data.object.metadata.order_id, event.data.object.id);
    }
  }
);

import hashlib
import hmac
import os

from flask import Flask, jsonify, request

app = Flask(__name__)


def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, v1 = parts.get("t"), parts.get("v1")
    if not timestamp or not v1:
        return False

    computed = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(computed, v1)


@app.post("/webhooks/southpay")
def webhook():
    sig = request.headers.get("Southpay-Signature", "")
    if not verify(request.data, sig, os.environ["SOUTHPAY_WEBHOOK_SECRET"]):
        return jsonify(error="Invalid signature"), 401

    event = request.get_json()
    if already_processed(event["id"]):
        return jsonify(received=True)
    mark_processed(event["id"])

    if event["type"] == "payment_intent.completed":
        obj = event["data"]["object"]
        fulfill_order(obj["metadata"]["order_id"], obj["id"])

    return jsonify(received=True)

Return 2xx within 30 seconds. Any non-2xx response is retried, up to 10 attempts over roughly 18 hours, including a 400 or 404 your framework returns by accident. Deduplicate on the event id. Test the whole path without paying anything:

curl -X POST https://api.southpay.io/api/v2/webhook_endpoints/{endpoint_id}/send_test \
  -H "Authorization: Bearer sp_sk_test_YOUR_API_KEY"

Polling instead

If you cannot receive webhooks, fetch the intent by UUID and read status.

curl https://api.southpay.io/api/v2/payments/9c1d7f42-6a3b-4e58-9f10-2b8c5d4e7a91 \
  -H "Authorization: Bearer sp_sk_test_YOUR_API_KEY"

terminal: true means the outcome is settled. It does not mean the record is frozen. A terminal intent can still become refunded later.

Payment lifecycle

The six statuses, the ten state reasons, and what each one means for an order.

Webhooks

Signing, retries, the event catalogue, and the five events that never fire.

Errors

Three response shapes, and why error.message will throw if you assume one.

Payout destinations

Where the money goes, and how to configure it before your first payout.

Getting started

Authentication

Core resources

Recurring

Checkout

Agentic commerce

Platform

Integrations

Building reliably

Changelog

1. Create a payment intent

2. Send the customer to checkout

3. Register a webhook endpoint

4. Verify and handle the delivery

Polling instead

Next

Payment lifecycle

Webhooks

Errors

Payout destinations

​1. Create a payment intent

​2. Send the customer to checkout

​3. Register a webhook endpoint

​4. Verify and handle the delivery

​Polling instead

​Next

Payment lifecycle

Webhooks

Errors

Payout destinations

1. Create a payment intent

2. Send the customer to checkout

3. Register a webhook endpoint

4. Verify and handle the delivery

Polling instead

Next