Payment intents

A payment intent is how you charge a customer. You post a fiat amount, SouthPay locks an exchange rate and allocates one on-chain deposit address per asset your store accepts, and you send the customer to the hosted checkout page. Which assets appear is decided by your store settings, not by anything in the request. For the walkthrough, see the payment intents guide. This page is the field-level reference. Every path below is relative to https://api.southpay.io/api/v2. All amounts you send are fiat major units; all crypto amounts you read back are atomic-unit strings.

Authentication and scope

Reads require payments:read, writes require payments:write. A secret API key (sp_sk_…), an OAuth token, or a dashboard session all work. A publishable key (sp_pk_…) can call POST /payments and nothing else. Any other path returns 403 publishable_key_forbidden.

Create a payment intent

POST /payments. Scope payments:write. Publishable keys allowed. Idempotency-Key optional. All fields go inside a required payment_intent object.

string

required

Fiat amount in major units, as a decimal string ("49.99"). Must be greater than zero. Multiplied by 100 and stored as settlement_amount_cents.

string

required

Uppercase ISO 4217 code. One of USD, EUR, GBP, HKD, SGD, JPY, DKK, CHF, SEK, NOK. This prices the payment; it does not restrict which crypto assets the customer may pay with.

string

Where checkout sends the customer after a successful payment.

string

Where checkout sends the customer after a failure or expiry.

string

Your own order reference. Maximum 255 characters. Filterable on the list endpoint.

string

Short label shown on the checkout page. Maximum 150 characters.

string

Longer description shown on the checkout page. Maximum 500 characters.

string

Product or order image shown on checkout. Must be https and at most 2048 characters. Surfaces as display_image_url on the detail view.

integer

default:"3600"

How long the payment stays payable, in seconds. Minimum 300 (5 minutes), maximum 86400 (24 hours). Omit it for the 60 minute default. The resolved deadline comes back as expires_at.

object

Key-value pairs echoed back on the intent and in every payment webhook. At most 50 keys, and every value must be a string. Numbers and booleans are rejected.

object[]

Order breakdown shown on checkout. At most 50 items.

Show line item properties

string

required

Maximum 255 characters.

integer

required

Must be a positive integer.

integer

required

Minor units of currency. Must be a non-negative integer.

string

Must be https.

curl -X POST https://api.southpay.io/api/v2/payments \
  -H "Authorization: Bearer sp_sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1043" \
  -d '{
    "payment_intent": {
      "amount": "49.99",
      "currency": "USD",
      "order_id": "order_1043",
      "title": "Order #1043",
      "success_url": "https://example.com/orders/1043/thanks",
      "failed_url": "https://example.com/orders/1043/retry",
      "line_items": [
        { "description": "Widget", "quantity": 2, "unit_amount_cents": 1999 },
        { "description": "Gadget", "quantity": 1, "unit_amount_cents": 1001 }
      ],
      "metadata": { "cart_id": "cart_abc" }
    }
  }'

{
  "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
  "reference": "A1B2C3D4E5F6G7H8",
  "hosted_url": "https://pay.southpay.io/A1B2C3D4E5F6G7H8",
  "status": "pending",
  "state_reason": null,
  "settlement_currency": "USD",
  "settlement_amount": "49.99",
  "settlement_status": null,
  "auto_swap_status": null,
  "reconciliation_status": null,
  "terminal": false,
  "expires_at": "2026-04-10T13:00:00.000Z",
  "created_at": "2026-04-10T12:00:00.000Z",
  "success_url": "https://example.com/orders/1043/thanks",
  "failed_url": "https://example.com/orders/1043/retry",
  "order_id": "order_1043",
  "title": "Order #1043",
  "description": null,
  "payment_addresses": [
    {
      "id": "2f9d8c7b-6a5e-4d3c-2b1a-0f9e8d7c6b5a",
      "address": "0x9a3f…c2d1",
      "status": "pending",
      "crypto_amount_atomic": "49990000",
      "exchange_rate_snapshot": "1.000000000000000000",
      "created_at": "2026-04-10T12:00:00.000Z",
      "supported_asset": {
        "asset_id": "ETH_USDC",
        "coin_symbol": "USDC",
        "chain_symbol": "ETH",
        "token_standard": "ERC20",
        "settlement_currency": "USD",
        "atomic_decimals": 6,
        "min_withdrawal_atomic": "1000000",
        "chain_name": "Ethereum",
        "network": "ethereum",
        "fiat_eligible": true
      }
    }
  ]
}

Send the customer to hosted_url. It is https://pay.southpay.io/{reference} unless your store has a verified custom domain.

An intent expires 60 minutes after creation unless you send expires_in. Do not create the intent until the customer is ready to pay.The crypto amounts are quoted when the intent is created and stay fixed for the whole window, so a longer expires_in leaves you exposed to more exchange-rate movement. A customer who funds the payment by card can push expires_at out to 6 hours regardless of what you set, because the card leg needs that time to settle.

Response fields

string

required

Bare UUID. There is no prefixed-id scheme anywhere in this API.

string

required

16 uppercase alphanumeric characters. This is the checkout token and the value that appears as data.object.id in webhooks.

string

The customer-facing checkout page.

string

required

One of pending, processing, completed, expired, failed, refunded. See lifecycle.

string | null

Why the intent reached its current status. See payment lifecycle.

string

required

Fiat amount as a string with exactly two decimals, for example "49.99". Note that the webhook envelope carries settlement_amount_cents as an integer instead.

string

required

The fiat currency the intent is priced in.

boolean

required

True when status is completed, expired, refunded or failed. The intent will not change again.

string

required

ISO 8601. 60 minutes after created_at, or expires_in seconds after it when you sent that on create.

string | null

The underlying settlement record: pending, processing, completed, failed, or null. It is never "settled".

string | null

completed, pending, failed, skipped, or null when no auto-swap applies.

string | null

Status of the most recent reconciliation snapshot. See Reconciliation.

object[]

One deposit address per asset your store accepts. Returned by create and retrieve.

Show properties

string

Address record UUID.

string

The on-chain deposit address. Send funds here.

string

pending or confirmed.

string

Exact amount to send, in atomic units of the asset.

string

The locked rate as a plain decimal string, for example "2217.000000000000000000". It is a number, not an object.

object

asset_id, coin_symbol, chain_symbol, token_standard, settlement_currency, atomic_decimals, min_withdrawal_atomic, chain_name, network, fiat_eligible.

Create errors

Validation failures on this endpoint return 422 with the flat envelope {"error": "<message>"}.

Message	Cause
`amount is required and must be positive`	`amount` missing or blank.
`amount must be positive`	`amount` rounds to zero or below.
`title must be at most 150 characters`	Over the limit.
`description must be at most 500 characters`	Over the limit.
`order_id must be at most 255 characters`	Over the limit.
`image_url must be a valid https URL`	Not `https`, no host, or over 2048 characters.
`line_items must be an array`	Sent as an object or scalar.
`line_items must have at most 50 items`	Over the limit.
`each line item requires a description`	Blank `description`.
`line item quantity must be a positive integer`	Zero, negative or non-integer.
`line item unit_amount_cents must be a non-negative integer`	Negative or non-integer.
`metadata must have at most 50 keys`	Over the limit.
`metadata values must be strings`	A value was a number, boolean or nested object.
`expires_in must be an integer number of seconds`	Not parseable as an integer.
`expires_in must be between 300 and 86400 seconds`	Under 5 minutes or over 24 hours.

An unsupported currency also returns 422, but through the global handler, so it uses the structured envelope: {"error": {"message": "Unsupported settlement currency: XYZ", "code": null}}. Write your client to handle both shapes.

Omitting currency entirely, or omitting the payment_intent wrapper, currently returns 500 rather than a validation error. Always send both.

POST /payments is rate limited to 1,200 requests per minute in live mode, with a burst of 200, counted against your store rather than the individual key. Over the limit you get 429 {"error": {"message": "Too many requests", "code": "rate_limited"}} with a Retry-After header in seconds. See Rate limits for every throttled path.

Retrieve a payment intent

GET /payments/{id}. Scope payments:read. {id} is the intent UUID, not the reference. Returns the detail view: everything from create, plus ledger-derived financials, the on-chain transaction, and the full event history.

curl https://api.southpay.io/api/v2/payments/7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f \
  -H "Authorization: Bearer sp_sk_test_…"

{
  "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
  "reference": "A1B2C3D4E5F6G7H8",
  "status": "completed",
  "state_reason": "completed_exact",
  "settlement_amount": "49.99",
  "settlement_currency": "USD",
  "terminal": true,
  "paid_at": "2026-04-10T12:09:44.000Z",
  "amount_paid": "49.99",
  "checkout_url": "https://api.southpay.io/api/v2/checkout/A1B2C3D4E5F6G7H8",
  "display_image_url": "https://cdn.example.com/orders/1043.png",
  "customer_pays_fee": false,
  "metadata": { "cart_id": "cart_abc" },
  "line_items": [
    { "description": "Widget", "quantity": 2, "unit_amount_cents": 1999 }
  ],
  "fee": {
    "fee_atomic": "499900",
    "fee_percentage": "0.01",
    "asset_id": "ETH_USDC"
  },
  "financials": {
    "gross_amount": "49.99",
    "fee_amount": "0.50",
    "net_amount": "49.49",
    "fee_percentage": "1.00",
    "currency": "USD",
    "asset_id": "ETH_USDC",
    "exchange_rate": "1.0"
  },
  "transaction": {
    "tx_hash": "0x9f8e…",
    "from_address": "0x1234…",
    "deposit_address": "0x9a3f…c2d1",
    "confirmations": 24,
    "required_confirmations": 12,
    "status": "confirmed",
    "coin_symbol": "USDC",
    "chain_symbol": "ETH",
    "chain_name": "Ethereum",
    "network": "ethereum",
    "explorer_url": "https://etherscan.io/tx/0x9f8e…",
    "confirmed_at": "2026-04-10T12:09:40.000Z"
  },
  "overpayment": null,
  "onramp_session": null,
  "onramp_unavailable": null,
  "merchant": {
    "name": "Example Store",
    "legal_name": "Example Trading Ltd",
    "country": "PT",
    "registration_number": "512345678",
    "tax_id": "PT512345678",
    "website": "https://example.com",
    "support_email": "[email protected]"
  },
  "auto_swap_status": "completed",
  "auto_swap_detail": {
    "status": "completed",
    "sell_amount": "49.49",
    "sell_coin_symbol": "USDC",
    "sell_chain_symbol": "ETH",
    "buy_amount": "49.41",
    "buy_coin_symbol": "USDT",
    "buy_chain_symbol": "ETH",
    "estimated": false,
    "expected_buy_amount": "49.45",
    "actual_buy_amount": "49.41",
    "slippage_bps": 8
  },
  "payment_addresses": [ { "…": "…" } ],
  "payment_events": [ { "…": "…" } ],
  "timeline": [
    { "type": "payment_intent.processing", "from": "pending", "to": "processing", "at": "2026-04-10T12:04:11.000Z", "payload": {} },
    { "type": "payment_intent.completed", "from": "processing", "to": "completed", "at": "2026-04-10T12:09:44.000Z", "payload": {} }
  ]
}

Detail-only fields

string

The API-hosted checkout endpoint, https://api.southpay.io/api/v2/checkout/{reference}. Distinct from hosted_url, which is the customer-facing page.

string | null

The image_url you supplied on create.

object[] | null

The line items you supplied on create.

string

Fiat value of confirmed funds, two decimals. "0.00" when nothing has confirmed.

string | null

Timestamp of the transition into completed, falling back to the last transition.

boolean

When true the customer was charged the SouthPay fee on top of the order amount.

object | null

Null until fee revenue is booked.

Show properties

string

Fee in atomic units of the paid asset.

string

Rate applied, as a fraction ("0.01" is 1%).

string

Asset the fee was taken in.

object | null

Ledger-derived fiat view. Null until crypto is received.

Show properties

string

Two decimals.

string

Two decimals, "0.00" when no fee is booked.

string

Gross minus fee.

string

Percentage points ("1.00" is 1%), unlike fee.fee_percentage.

string

Settlement currency.

string

Asset received.

string | null

Rate applied.

object | null

The confirmed deposit transaction, or the most recent one if none has confirmed. Null when nothing has arrived.

Show properties

string

On-chain hash.

string | null

Sender, used as the default refund destination.

string | null

The SouthPay address that received the funds.

integer

Confirmations seen so far.

integer

Threshold for this chain.

string

pending, confirming, submitted, confirmed or failed. These are transaction statuses, not intent statuses.

string | null

For example USDC.

string | null

For example ETH.

string | null

For example Ethereum.

string | null

For example ethereum.

string | null

Block explorer link for tx_hash.

string

Derived from the transaction record’s last update, not a separate confirmation timestamp.

object | null

Present once an address is confirmed. excess_atomic is clamped to "0" for exact and under payments, so a non-zero value here is the only reliable signal of a genuine overpayment.

Show properties

string

Amount the intent asked for.

string

Amount confirmed.

string

Received minus required, floored at "0".

string

integer

object

Your own store details, for rendering receipts. legal_name, country, registration_number, tax_id and website are null until a verification is approved.

object | null

The most recent card-to-crypto funding session, when card payments are enabled for your store. Null when the customer paid from their own wallet.status here is the funding session, not the payment. A paid session means the card charge went through; the intent still settles from the on-chain deposit that follows.

Show onramp_session

string

Opaque provider identifier. Do not branch on it.

string

Display name of the provider.

string

pending, paid, expired or failed. failed also covers refunded and cancelled at the provider.

integer

What the customer’s card was charged, in minor units of currency.

string

Currency of amount_cents.

string | null

The provider’s own transaction identifier, for support requests.

string

The deposit address the purchased crypto is delivered to.

string | null

When the card charge completed.

string

When the funding session stops being payable.

string

When the session was created.

object | null

Why no card option could be offered for this intent. Always null once a funding session exists, whatever its outcome.Carries reason and a human-readable message. below_min_amount and above_max_amount also carry charge_amount_cents, min_amount_cents, max_amount_cents and currency, so you can name the actual bound. See Card payments for the full list of reasons.

object | null

Populated only when an auto-swap has moved past pending and has not failed. Keys: status, sell_amount, sell_coin_symbol, sell_chain_symbol, buy_amount, buy_coin_symbol, buy_chain_symbol, estimated, expected_buy_amount, actual_buy_amount, slippage_bps.

object[]

Same rows as the events endpoint: id, event_type, from_status, to_status, payload, created_at.

object[]

The same events under different key names: type, from, to, at, payload. No id.

An unknown or out-of-mode id returns 404 with {"error": {"message": "…", "code": null}}.

List payment intents

GET /payments. Scope payments:read. Returns the list view: the create fields plus settlement_status and auto_swap_status, without payment_addresses. Ordered newest first.

string

Filter by status. Unrecognized values are ignored rather than rejected.

string

Case-insensitive substring match on reference.

string

Exact match on the order_id you set at create time.

string

ISO date. Includes intents created on or after this day.

string

ISO date. Includes intents created up to and including this day.

integer

default:"1"

integer

default:"10"

Between 1 and 100.

curl "https://api.southpay.io/api/v2/payments?status=completed&per_page=25" \
  -H "Authorization: Bearer sp_sk_test_…"

{
  "data": [
    {
      "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
      "reference": "A1B2C3D4E5F6G7H8",
      "hosted_url": "https://pay.southpay.io/A1B2C3D4E5F6G7H8",
      "status": "completed",
      "state_reason": "completed_exact",
      "settlement_currency": "USD",
      "settlement_amount": "49.99",
      "settlement_status": "completed",
      "auto_swap_status": null,
      "reconciliation_status": "final",
      "terminal": true,
      "order_id": "order_1043",
      "title": "Order #1043",
      "description": null,
      "success_url": "https://example.com/orders/1043/thanks",
      "failed_url": "https://example.com/orders/1043/retry",
      "expires_at": "2026-04-10T13:00:00.000Z",
      "created_at": "2026-04-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

status=confirming is accepted by the filter but confirming is not a payment intent status. It always matches zero rows. confirming exists only as a transaction status inside the transaction object. Do not use it as a filter.

Pagination is not uniform across this API. Payments, billing, agentic payments and platform endpoints wrap the page in meta. Payouts, agentic payouts, balance swaps and x402 settlements use pagination instead. Balances, payout schedules, webhook endpoints, billing products, prices and subscriptions return bare arrays with no pagination at all.

Summarize payments

GET /payments/summary. Scope payments:read. Aggregates order counts, volume and success rate over a date range, bucketed by day. Useful for dashboards; it is not a substitute for reports, which are ledger-accurate PDFs.

string

ISO date. Defaults to 29 days before to.

string

ISO date. Defaults to today.

A range longer than 366 days is silently clamped to 366, and from later than to is clamped to to. Unparseable dates fall back to the defaults instead of erroring.

curl "https://api.southpay.io/api/v2/payments/summary?from=2026-04-01&to=2026-04-07" \
  -H "Authorization: Bearer sp_sk_test_…"

{
  "range": { "from": "2026-04-01", "to": "2026-04-07", "granularity": "day" },
  "livemode": false,
  "currencies": ["USD", "EUR"],
  "totals": {
    "order_count": 412,
    "order_count_by_currency": { "USD": 380, "EUR": 32 },
    "volume_cents": { "USD": 1904500, "EUR": 158000 },
    "avg_order_value_cents": { "USD": 5012, "EUR": 4938 },
    "status_counts": { "completed": 361, "expired": 44, "pending": 7 },
    "success_rate": 0.8762,
    "success_rate_by_currency": { "USD": 0.8789, "EUR": 0.8438 }
  },
  "timeseries": [
    {
      "date": "2026-04-01",
      "order_count": 58,
      "order_count_by_currency": { "USD": 54, "EUR": 4 },
      "volume_cents": { "USD": 271200, "EUR": 19800 }
    }
  ]
}

currencies is sorted by descending volume. timeseries has one zero-filled entry per day in the range. success_rate is a fraction rounded to four places, not a percentage.

List payment events

GET /payments/{payment_intent_id}/events. Scope payments:read. The immutable transition log behind your webhook deliveries. Use it to backfill history or to reconcile after a webhook outage. Returns a bare array, oldest first, with no pagination.

curl https://api.southpay.io/api/v2/payments/7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f/events \
  -H "Authorization: Bearer sp_sk_test_…"

[
  {
    "id": "c3a1b2d4-5e6f-4708-9a1b-2c3d4e5f6071",
    "event_type": "payment_intent.processing",
    "from_status": "pending",
    "to_status": "processing",
    "payload": {
      "address": "0x9a3f…c2d1",
      "tx_hash": "0x9f8e…",
      "amount_atomic": "49990000"
    },
    "created_at": "2026-04-10T12:04:11.000Z"
  },
  {
    "id": "d4b2c3e5-6f70-4819-ab2c-3d4e5f607182",
    "event_type": "payment_intent.completed",
    "from_status": "processing",
    "to_status": "completed",
    "payload": {},
    "created_at": "2026-04-10T12:09:44.000Z"
  }
]

event_type is the public event name, matching the webhook event catalogue. Some events appear here that no webhook endpoint can subscribe to, notably payment_intent.canceled from the agentic cancel endpoint.

Download the invoice PDF

GET /payments/{id}/invoice. Scope payments:read. Returns application/pdf as an attachment named invoice-{reference}.pdf. There is no JSON variant, and no status check. An unpaid intent still renders. The only failure is 404 for an unknown id.

Request

curl https://api.southpay.io/api/v2/payments/7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f/invoice \
  -H "Authorization: Bearer sp_sk_test_…" \
  -o invoice.pdf

Lifecycle

The status field has exactly six values. There is no created, no confirming and no overpaid.

Status	Terminal	Meaning
`pending`	No	Created, waiting for the customer to send funds.
`processing`	No	Funds detected on-chain, confirmations in progress.
`completed`	Yes	Required funds received and confirmed.
`expired`	Yes	The 60-minute window elapsed, or an agent canceled the intent.
`failed`	Yes	The payment could not be accepted.
`refunded`	Yes	Funds were returned to the customer.

An overpayment is not a separate status: it is status: "completed" with state_reason: "completed_overpaid", and the excess is in the overpayment object. For the allowed transitions, all ten state_reason values and how statuses map to webhook events, see payment lifecycle.

Sub-resources

Refunds: GET and POST /payments/{id}/refunds.
Reconciliation: GET /payment_intents/{id}/reconciliation. Note the path segment is payment_intents, not payments, for that route only.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Authentication and scope

Create a payment intent

Response fields

Create errors

Retrieve a payment intent

Detail-only fields

List payment intents

Summarize payments

List payment events

Download the invoice PDF

Lifecycle

Sub-resources

​Authentication and scope

​Create a payment intent

​Response fields

​Create errors

​Retrieve a payment intent

​Detail-only fields

​List payment intents

​Summarize payments

​List payment events

​Download the invoice PDF

​Lifecycle

​Sub-resources

Authentication and scope

Create a payment intent

Response fields

Create errors

Retrieve a payment intent

Detail-only fields

List payment intents

Summarize payments

List payment events

Download the invoice PDF

Lifecycle

Sub-resources