The shortest working path
hosted_url. Redirect your customer there. When the payment confirms, a signed payment_intent.completed webhook arrives at your endpoint and you fulfil the order.
That is the whole integration. The quickstart walks the four steps with the real response bodies and a verified webhook handler.
Quickstart
Payment intent, checkout redirect, webhook verification. Copy-pasteable, in test mode.
Three things to know before you build
The base URL ishttps://api.southpay.io and every path sits under /api/v2. There is no /v1 and no other version.
Test and live mode are chosen by the credential, not by the host. An sp_sk_test_ key reads and writes test data on the same URL. Test mode has exactly one usable asset, Ethereum Sepolia.
Errors come back in three different JSON shapes. error is sometimes a string and sometimes an object. Write the parser first. Errors has one you can copy.
Core concepts
Payment intents
The one object. Creating it, reading it, and every field it carries.
Payment lifecycle
Six statuses, ten state reasons, a 60-minute expiry. Stated once, here.
Webhooks
Signing, retries, the event catalogue, and the five events that never fire.
Authentication
API keys, OAuth with PKCE, agent credentials, and what each scope grants.
Errors
Three response shapes, real status codes, and every error code that exists.
Idempotency
What
Idempotency-Key protects, and the three places it does not.Currencies and assets
Ten fiat currencies to price in, and the chains customers can pay on.
Payout destinations
Where your balance goes. A prerequisite for every payout.
Beyond one-off payments
Subscriptions
Products, prices and recurring invoices collected through the same checkout.
Platform accounts
Onboard your own merchants and take a fee. Admin-gated; read before you build.
Agentic commerce
Scoped credentials, mandates and spend limits for autonomous agents.
API reference
Every endpoint, parameter and response field.