Payouts

A payout moves money off your SouthPay balance. You can send crypto on-chain to a wallet you control, or off-ramp USDT and USDC to a bank account. Payouts arrive two ways: on demand through POST /payouts, or automatically from a payout schedule. Both produce the same resource. Paths are relative to https://api.southpay.io/api/v2.

Before you can pay out

POST /payouts needs a payout destination: a saved bank account or wallet address, referenced by fiat_payout_detail_id or crypto_payout_detail_id. You cannot create one over the public API; they are configured in the dashboard. See payout destinations for what each kind is, where the ids come from, and what a fiat destination requires. The crypto path also accepts a raw destination_address instead of a saved detail id, which skips the saved-destination requirement but not the address validation.

Authentication and scope

Reads require payouts:read, writes require payouts:write. Publishable keys cannot call any of these endpoints.

Creating a crypto payout runs a step-up MFA check. For API keys and OAuth tokens that check is a no-op and never fires. It only gates dashboard sessions, which return 403 mfa_required without two-factor enabled, or 503 mfa_check_unavailable if the identity provider is down. The same applies to POST /balance_swaps and POST /payout_schedules/{id}/run.

Create a payout

POST /payouts. Scope payouts:write. Idempotency-Key is required. Parameters are sent at the top level, not wrapped in an object.

string

required

The asset to send, for example ETH_USDC. Must be an active asset in your current mode.

string

required

Amount in atomic units of asset_id, as a string. Must be positive.

string

Off-ramp to this saved bank account. Sending this selects the fiat path.

string

Send on-chain to this saved wallet. Its network must match the asset’s network.

string

Send on-chain to a raw address. Used only when crypto_payout_detail_id is absent.

Send exactly one destination. If fiat_payout_detail_id is present the payout takes the fiat path; otherwise it takes the crypto path and needs either crypto_payout_detail_id or destination_address.

curl -X POST https://api.southpay.io/api/v2/payouts \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout_2026_05_12_a" \
  -d '{
    "asset_id": "ETH_USDC",
    "amount_atomic": "250000000",
    "crypto_payout_detail_id": "3c2b1a09-8f7e-4d6c-b5a4-93827160fed5"
  }'

curl -X POST https://api.southpay.io/api/v2/payouts \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout_2026_05_12_b" \
  -d '{
    "asset_id": "ETH_USDT",
    "amount_atomic": "250000000",
    "fiat_payout_detail_id": "5e4d3c2b-1a09-4f8e-9d6c-b5a493827160"
  }'

{
  "id": "0a1b2c3d-4e5f-4061-8273-849506172839",
  "status": "pending",
  "payout_rail": "crypto",
  "payout_schedule_id": null,
  "amount_atomic": "250000000",
  "amount_decimal": "250",
  "destination_address": "0xabcd…",
  "provider_tx_id": null,
  "tx_hash": null,
  "fiat_currency": null,
  "paid_fiat_amount_cents": null,
  "paid_fx_rate": null,
  "paid_fee_cents": null,
  "paid_at": null,
  "paid_external_reference": null,
  "network_fee_decimal": null,
  "state_transitions": [
    { "from": null, "to": "pending", "at": "2026-05-12T09:00:00Z", "note": null }
  ],
  "failure_reason": null,
  "failure_code": null,
  "livemode": true,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z",
  "asset": {
    "asset_id": "ETH_USDC",
    "coin_symbol": "USDC",
    "chain_symbol": "ETH",
    "atomic_decimals": 6
  }
}

Live-mode payouts are irreversible once broadcast. A replayed Idempotency-Key returns the original payout with status 201, so a retry after a network timeout is safe, but only if you send the same key. A new key sends a second payout.

Fiat off-ramp constraints

The store must have confirmed KYC. Otherwise 403 {"error": "Store KYC verification required"}.
Only USDT and USDC can be off-ramped. Anything else returns 422 {"error": "BTC is not eligible for fiat off-ramp"}.
Minimums are 10 USDT and 0.1 USDC. Below that: 422 {"error": "Minimum amount for USDT fiat payout is 10 USDT"}.

Response fields

string

required

Bare UUID.

string

required

pending, submitted, confirmed, failed, retrying or requires_review. See lifecycle.

string

required

crypto (on-chain), fiat_manual (off-ramp from an existing stablecoin balance) or fiat_autoswap (swap to a stablecoin, then off-ramp). POST /payouts produces crypto or fiat_manual; fiat_autoswap comes from schedules.

string | null

Set when the payout was created by a schedule.

string

required

Atomic units of asset.asset_id.

string

required

The same amount as a human decimal string with trailing zeros stripped.

string | null

On-chain destination. Null on fiat payouts.

string | null

On-chain hash, once broadcast.

string | null

Custody provider’s own reference.

string | null

Network fee charged for a crypto payout, as a decimal string. Null until known.

string | null

Currency of the receiving bank account. Fiat payouts only.

integer | null

What actually landed in the bank account, in minor units. Only known after settlement.

string | null

The rate actually applied, which may differ from the quoted rate.

integer | null

Off-ramp fee actually charged.

string | null

The bank reference on the outgoing transfer. Use this to match a SouthPay payout to a line on your bank statement.

string | null

Settlement timestamp.

object[]

required

Synthesized history, oldest first. Retries append a further submitted/failed pair rather than replacing earlier entries.

Show entry properties

string | null

Previous status. Null on the first entry.

string

pending, submitted, confirmed or failed. Note that retrying and requires_review never appear here.

string

ISO 8601 timestamp.

string | null

Provider error message on a failed entry, otherwise null.

string | null

Null unless status is failed. One of insufficient_funds, destination_invalid, temporarily_unavailable, unknown. Branch on this, not on failure_reason.

string | null

The provider’s raw error text. Free-form and not stable. For humans only.

object

required

Show properties

string

integer

Quote a fiat payout

POST /payouts/quote. Scope payouts:write. Fiat only. Creates nothing.

string

required

Must be a USDT or USDC asset.

string

required

Atomic units. Must be positive.

string

required

The bank account you would pay out to. Its currency drives the quote.

curl -X POST https://api.southpay.io/api/v2/payouts/quote \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "ETH_USDT",
    "amount_atomic": "250000000",
    "fiat_payout_detail_id": "5e4d3c2b-1a09-4f8e-9d6c-b5a493827160"
  }'

{
  "asset_id": "ETH_USDT",
  "coin_symbol": "USDT",
  "amount_atomic": "250000000",
  "estimated_fiat_cents": 22940,
  "estimated_fee_cents": 250,
  "exchange_rate": "0.9176",
  "fiat_currency": "EUR",
  "source_currency": "USD",
  "minimum_atomic": "10000000",
  "meets_minimum": true,
  "expires_at": "2026-05-12T09:05:00.000Z"
}

estimated_fiat_cents and estimated_fee_cents are estimates. What actually lands is reported as paid_fiat_amount_cents and paid_fee_cents on the payout. Check meets_minimum before creating: a quote is still returned when the amount is below the minimum, but the payout would be rejected.

Retrieve a payout

GET /payouts/{id}. Scope payouts:read. Returns a bare payout object. Unknown id returns 404 {"error": "Payout not found"}.

List payouts

GET /payouts. Scope payouts:read. Newest first.

string

Filter by payout status.

string

crypto, fiat_manual or fiat_autoswap.

string

Only payouts produced by one schedule.

string

Only payouts of one asset.

integer

default:"1"

integer

default:"25"

Between 1 and 100.

Response 200

{
  "data": [ { "id": "0a1b2c3d-4e5f-4061-8273-849506172839", "status": "confirmed", "…": "…" } ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Payouts wrap the page in pagination, while payments and billing use meta, and balances and payout schedules return bare arrays. A shared client helper that assumes one envelope will silently read an empty page.

Retry a payout

POST /payouts/{id}/retry. Scope payouts:write. No body, no MFA check. Only a failed payout whose funds have not already been returned to your balance can be retried. Returns 200 with the updated payout.

Status	Body	Cause
`409`	`{"error": "Payout retry already in progress", "code": "retry_in_progress"}`	A retry is already in flight.
`422`	`{"error": "Payout is not in a failed state (current: confirmed)", "code": "not_retryable"}`	Wrong status.
`422`	`{"error": "This payout was returned to your balance. Send a new payout to try again.", "code": "not_retryable"}`	Ledger entries were already reversed. Create a fresh payout.
`422`	`{"error": "Original payout already succeeded at provider (confirmed)", "code": "not_retryable"}`	The provider settled it after all.
`404`	`{"error": "Payout not found"}`	Unknown id.

Lifecycle

Status	Terminal	Meaning
`pending`	No	Created, funds reserved, queued.
`submitted`	No	Handed to the rail, awaiting confirmation.
`confirmed`	Yes	Crypto confirmed on-chain, or fiat settled.
`failed`	Yes	Rejected. Ledger entries are reversed and the balance returns.
`retrying`	No	A retry is in flight after a prior failure.
`requires_review`	No	Held for manual review.

There are no payout webhooks. payout.created, payout.confirmed and payout.failed appear in the subscribable event list and pass validation, but no code path ever emits them. Subscribing to them produces silence. Poll GET /payouts/{id} or GET /payouts?status=… instead.

Create errors

Status	Body	Cause
`422`	`{"error": "Idempotency-Key header is required"}`	Header missing.
`404`	`{"error": "Asset not found"}`	Unknown or inactive `asset_id`.
`422`	`{"error": "amount_atomic must be positive"}`	Zero, negative or missing.
`422`	`{"error": "destination_address required"}`	Crypto path with no destination.
`404`	`{"error": "Crypto payout detail not found or not active"}`	Bad `crypto_payout_detail_id`.
`422`	`{"error": "Address network bsc does not match the ethereum network for USDC"}`	Saved wallet is on another chain.
`403`	`{"error": "Store KYC verification required"}`	Fiat path without approved KYC.
`404`	`{"error": "Fiat payout detail not found or not active"}`	Bad `fiat_payout_detail_id`.
`422`	`{"error": "Insufficient balance"}` or `{"error": "No balance found for ETH_USDC"}`	Not enough funds.

Every one of these uses the flat {"error": "<message>"} envelope, except the retry responses above, which add a code. Errors raised deeper in the service layer, most notably from POST /payout_schedules/{id}/run, surface through the global handler as {"error": {"message": "…", "code": null}}. Handle both.

Payments

Balances

Billing

Webhooks

Platform

Agentic

Reports

Payouts

Before you can pay out

Authentication and scope

Create a payout

Fiat off-ramp constraints

Response fields

Quote a fiat payout

Retrieve a payout

List payouts

Retry a payout

Lifecycle

Create errors

​Before you can pay out

​Authentication and scope

​Create a payout

​Fiat off-ramp constraints

​Response fields

​Quote a fiat payout

​Retrieve a payout

​List payouts

​Retry a payout

​Lifecycle

​Create errors

Before you can pay out

Authentication and scope

Create a payout

Fiat off-ramp constraints

Response fields

Quote a fiat payout

Retrieve a payout

List payouts

Retry a payout

Lifecycle

Create errors