Payout schedules

A payout schedule answers two questions for a single asset: how often the accumulated balance leaves SouthPay, and where it goes. When next_payout_at passes and the balance clears minimum_fiat_cents, a payout is created for you. One schedule exists per store, asset and mode. Creating a second for the same asset is rejected. Edit the existing one instead. Paths are relative to https://api.southpay.io/api/v2.

Before you can create one

A schedule needs a payout destination: a saved bank account (fiat_payout_detail_id) or a saved wallet (crypto_payout_detail_id). Neither can be created over the public API. Both are configured in the dashboard. See payout destinations. A fiat destination must be verified, and the store must have confirmed KYC.

Authentication and scope

Reads require payouts:read, writes require payouts:write. Publishable keys are rejected.

List schedules

GET /payout_schedules. Scope payouts:read. Returns a bare array with no envelope and no pagination, oldest first. Only active schedules are returned; deleting one hides it from this list permanently.

curl https://api.southpay.io/api/v2/payout_schedules \
  -H "Authorization: Bearer sp_sk_live_…"

[
  {
    "id": "b4c5d6e7-f809-4a1b-8c2d-3e4f50617283",
    "frequency": "weekly",
    "minimum_fiat_cents": 50000,
    "minimum_fiat_currency": "EUR",
    "destination_address": null,
    "destination_type": "fiat",
    "payout_rail": "fiat_manual",
    "next_payout_at": "2026-05-18T02:00:00.000Z",
    "last_payout_at": "2026-05-11T02:00:00.000Z",
    "last_skip_reason": null,
    "active": true,
    "livemode": true,
    "fiat_payout_detail_id": "5e4d3c2b-1a09-4f8e-9d6c-b5a493827160",
    "crypto_payout_detail_id": null,
    "created_at": "2026-03-02T10:00:00.000Z",
    "updated_at": "2026-05-11T02:00:04.000Z",
    "asset": {
      "asset_id": "ETH_USDT",
      "coin_symbol": "USDT",
      "chain_symbol": "ETH"
    }
  }
]

Create a schedule

POST /payout_schedules. Scope payouts:write. Idempotency-Key is not used here. All fields go inside a required payout_schedule object.

string

required

The asset whose balance this schedule drains. Cannot be changed later.

string

required

daily, weekly or monthly.

string

Off-ramp to this saved bank account. Must be verified, and the store must have confirmed KYC.

string

Send on-chain to this saved wallet.

integer

Skip the run when the accrued balance is worth less than this. Minor units of minimum_fiat_currency.

string

One of USD, EUR, GBP, HKD, SGD, JPY. Falls back to USD.

string

ISO 8601. When the first run is due.

string

Swap the balance into this asset before paying out, producing a fiat_autoswap payout. Write-only: it does not appear in the response.

boolean

default:"true"

Set false to pause the schedule without deleting it.

string

Legacy raw address. Prefer crypto_payout_detail_id.

minimum_fiat_currency accepts six currencies. A payment intent accepts ten, and DKK, CHF, SEK and NOK are valid there but not here. Sending one of the extra four on a schedule silently falls back to USD, so a threshold you meant as 500 DKK becomes 500 USD.

curl -X POST https://api.southpay.io/api/v2/payout_schedules \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_schedule": {
      "asset_id": "ETH_USDT",
      "frequency": "weekly",
      "minimum_fiat_cents": 50000,
      "minimum_fiat_currency": "EUR",
      "fiat_payout_detail_id": "5e4d3c2b-1a09-4f8e-9d6c-b5a493827160",
      "next_payout_at": "2026-05-18T02:00:00Z"
    }
  }'

{
  "id": "b4c5d6e7-f809-4a1b-8c2d-3e4f50617283",
  "frequency": "weekly",
  "minimum_fiat_cents": 50000,
  "minimum_fiat_currency": "EUR",
  "destination_address": null,
  "destination_type": "fiat",
  "payout_rail": "fiat_manual",
  "next_payout_at": "2026-05-18T02:00:00.000Z",
  "last_payout_at": null,
  "last_skip_reason": null,
  "active": true,
  "livemode": true,
  "fiat_payout_detail_id": "5e4d3c2b-1a09-4f8e-9d6c-b5a493827160",
  "crypto_payout_detail_id": null,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z",
  "asset": { "asset_id": "ETH_USDT", "coin_symbol": "USDT", "chain_symbol": "ETH" }
}

Response fields

string

required

Bare UUID.

string

required

daily, weekly or monthly.

string

required

fiat, crypto, or legacy for a schedule created against a raw destination_address before saved destinations existed.

string

required

fiat_manual for fiat destinations, crypto otherwise, including legacy. This is the rail the produced payouts will carry.

string | null

When the next run is due.

string | null

When this schedule last produced a payout. Null if it never has.

string | null

Why the last run produced nothing: no_balance, below_minimum or below_network_minimum. Check this first when a schedule looks stuck. A non-null value means the schedule ran and declined, not that it failed.

integer | null

Threshold in minor units of minimum_fiat_currency.

boolean

required

False once the schedule is paused or deleted.

string | null

object

required

Show properties

string

Unlike the payout object’s asset, this one carries no atomic_decimals.

swap_target_asset_id can be written but is never returned. To confirm it took effect, look at the payout_rail of the payouts the schedule produces. An auto-swap schedule yields fiat_autoswap.

Retrieve a schedule

GET /payout_schedules/{id}. Scope payouts:read. Returns the schedule plus a payouts array of every payout it has produced, in full payout shape.

Response 200

{
  "id": "b4c5d6e7-f809-4a1b-8c2d-3e4f50617283",
  "frequency": "weekly",
  "…": "…",
  "payouts": [
    {
      "id": "0a1b2c3d-4e5f-4061-8273-849506172839",
      "status": "confirmed",
      "payout_rail": "fiat_manual",
      "amount_atomic": "250000000",
      "amount_decimal": "250",
      "paid_fiat_amount_cents": 22940,
      "paid_external_reference": "SP-2026-05-11-0042",
      "…": "…"
    }
  ]
}

Update a schedule

PATCH /payout_schedules/{id}. Scope payouts:write. Accepts the same payout_schedule fields as create, except asset_id, which is ignored. Null values are dropped rather than clearing a field, so you cannot unset a destination this way. Switch it to the other destination type instead. Returns 200 with the updated schedule.

Delete a schedule

DELETE /payout_schedules/{id}. Scope payouts:write. A soft delete: the schedule is set active: false and stops running. Returns 204 with no body. It disappears from the list endpoint and cannot be reactivated through the API. Create a new schedule instead.

Run a schedule now

POST /payout_schedules/{id}/run. Scope payouts:write. No body. Evaluates the schedule immediately, ignoring next_payout_at. The minimum-balance rule still applies, so a run can legitimately produce nothing.

curl -X POST https://api.southpay.io/api/v2/payout_schedules/b4c5d6e7-f809-4a1b-8c2d-3e4f50617283/run \
  -H "Authorization: Bearer sp_sk_live_…"

{
  "triggered": true,
  "payout": {
    "id": "0a1b2c3d-4e5f-4061-8273-849506172839",
    "status": "pending",
    "payout_rail": "fiat_manual",
    "amount_atomic": "250000000",
    "…": "…"
  }
}

{
  "triggered": false,
  "skip_reason": "below_minimum"
}

Both outcomes are 200. Branch on triggered, not on the status code. skip_reason is no_balance, below_minimum or below_network_minimum. This endpoint runs a step-up MFA check. For API keys and OAuth tokens it is a no-op; dashboard sessions without two-factor get 403 {"error": "Enable two-factor authentication to run a payout", "code": "mfa_required"}.

Errors

Validation failures on create and update use the array envelope {"errors": ["…"]}, which is a third shape distinct from the flat string and the structured object used elsewhere.

Status	Body	Cause
`422`	`{"errors": ["You already have a payout schedule for this balance. Edit it instead."]}`	A schedule already exists for that asset and mode.
`422`	`{"errors": ["Must specify exactly one destination type"]}`	Both or neither destination id supplied.
`422`	`{"errors": ["Must reference an explicit fiat or crypto payout destination"]}`	Create with no saved destination.
`422`	`{"errors": ["Fiat payout detail must be verified before use in a payout schedule"]}`	Bank account not yet verified.
`422`	`{"errors": ["Store KYC must be confirmed before creating a fiat payout schedule"]}`	KYC outstanding.
`404`	`{"errors": ["Asset not found"]}`	Unknown `asset_id` on create.
`404`	`{"error": "Payout schedule not found"}`	Unknown id. Note the singular key here.

Service-level failures on run surface through the global handler as {"error": {"message": "…", "code": null}} at 422.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Before you can create one

Authentication and scope

List schedules

Create a schedule

Response fields

Retrieve a schedule

Update a schedule

Delete a schedule

Run a schedule now

Errors

​Before you can create one

​Authentication and scope

​List schedules

​Create a schedule

​Response fields

​Retrieve a schedule

​Update a schedule

​Delete a schedule

​Run a schedule now

​Errors

Before you can create one

Authentication and scope

List schedules

Create a schedule

Response fields

Retrieve a schedule

Update a schedule

Delete a schedule

Run a schedule now

Errors