Platform accounts

A platform account lets you onboard other businesses under your own SouthPay account, take payments on their behalf, and collect a fee on each one. Each business is a sub-merchant: a separate store with its own balances, payouts and verification state. Paths are relative to https://api.southpay.io/api/v2.

Platform mode is not self-serve. It is not enabled by default, and only SouthPay staff can turn it on for your store. Until it is enabled on your store, every endpoint on this page returns 403 with {"error": {"message": "This account is not a platform", "code": "not_a_platform"}}. Contact support before integrating.

Authentication and scope

Reads require accounts:read, writes require accounts:write, and acting on a sub-merchant requires accounts:act. None of the three are in the default API key scope set. A key created before your store became a platform will not hold them. Issue a new key with the platform scopes.

Create a sub-merchant

POST /platform/accounts. Scope accounts:write. All fields go inside a required account object.

string

required

The sub-merchant’s business name. Whitespace is trimmed; a blank value is rejected.

string

Your own identifier for this merchant. Creation is idempotent on this value. Posting the same external_id twice returns the existing account rather than creating a second one.

string

Your fee on this sub-merchant’s payments, as a decimal fraction ("0.015" is 1.5%).

string

ISO country code. Used once, to seed the new store’s defaults. Ignored on update.

curl -X POST https://api.southpay.io/api/v2/platform/accounts \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "account": {
      "name": "Blue Harbour Coffee",
      "external_id": "merchant_8812",
      "platform_fee_percentage": "0.015",
      "country": "PT"
    }
  }'

{
  "id": "c7d8e9f0-a1b2-4c3d-8e4f-506172839405",
  "name": "Blue Harbour Coffee",
  "external_id": "merchant_8812",
  "platform_fee_percentage": "0.015",
  "kyc_confirmed_at": null,
  "charges_enabled": false,
  "payouts_enabled": false,
  "created_at": "2026-05-12T09:00:00.000Z"
}

Response fields

string

required

The sub-merchant’s store id. Send this in X-Southpay-Account to act on their behalf.

string

required

string | null

Your identifier, as supplied at create time.

string | null

The effective fee as a string, not a number.

string | null

When verification was approved. Null until then.

boolean

required

True once KYC is confirmed. Until then the sub-merchant cannot take payments.

boolean

required

True once the sub-merchant has chosen a payout destination.

List sub-merchants

GET /platform/accounts. Scope accounts:read. Returns a bare array of active sub-merchants, newest first. No envelope, no pagination.

string

Exact match on your own identifier. The way to resolve one of your ids to a SouthPay account id.

Retrieve a sub-merchant

GET /platform/accounts/{id}. Scope accounts:read. Returns a bare account object. An unknown id returns 404 with a machine code: {"error": {"message": "Unknown sub-merchant account", "code": "account_not_found"}}.

Update a sub-merchant

PATCH /platform/accounts/{id}. Scope accounts:write. Applies name, platform_fee_percentage and external_id. Re-using an external_id that another of your sub-merchants already holds is refused with 422, and the account keeps its previous value.

country is accepted by the request and ignored. It only seeds default assets at creation time and cannot be changed afterwards.

curl -X PATCH https://api.southpay.io/api/v2/platform/accounts/c7d8e9f0-a1b2-4c3d-8e4f-506172839405 \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "account": { "platform_fee_percentage": "0.02" } }'

{
  "id": "c7d8e9f0-a1b2-4c3d-8e4f-506172839405",
  "name": "Blue Harbour Coffee",
  "external_id": "merchant_8812",
  "platform_fee_percentage": "0.02",
  "kyc_confirmed_at": "2026-05-14T11:02:00.000Z",
  "charges_enabled": true,
  "payouts_enabled": true,
  "created_at": "2026-05-12T09:00:00.000Z"
}

Delete a sub-merchant

DELETE /platform/accounts/{id}. Scope accounts:write. Retires a sub-merchant you own. The account is soft-deleted, its API keys and agent credentials are revoked, and its webhook endpoints are disabled. Ledger history is preserved, and a store.deleted platform event is emitted. Returns 204 with no body. The account stops appearing in GET /platform/accounts and can no longer be acted on through the X-Southpay-Account header.

curl -X DELETE https://api.southpay.io/api/v2/platform/accounts/c7d8e9f0-a1b2-4c3d-8e4f-506172839405 \
  -H "Authorization: Bearer sp_sk_live_…"

{
  "error": {
    "message": "Sub-merchant has active funds or in-flight money movement",
    "code": "account_has_active_funds",
    "blockers": [{ "type": "store_balance", "count": 1 }]
  }
}

An account still holding money is refused with 409 and a blockers list naming what is in the way: store_balance, pending_payout, in_flight_payment_intent or pending_refund. Settle or pay out those first, then retry. There is no force flag on this endpoint. Funds are never stranded by a platform call.

Restore a sub-merchant

POST /platform/accounts/{id}/restore. Scope accounts:write. Reverses a delete and returns the account object. Revoked API keys are not reissued and disabled webhook endpoints stay disabled; re-create those as needed. Restoring an account that was never deleted returns 422 with code account_not_deleted.

Attest verification

POST /platform/accounts/{account_id}/verification. Scope accounts:write. Submits KYB details you have already collected, so the sub-merchant does not have to re-enter them. Fields may be sent inside a verification_request object or at the top level.

string

Returns 201 with the verification request: id, status, the submitted fields, plus rejection_reason, submitted_at, reviewed_at, created_at, updated_at. status is pending, approved or rejected. Approval is a human review. Attesting does not approve anything by itself. Subscribe to store.verification.approved and store.verification.rejected to learn the outcome; both fan out to the platform’s own webhook endpoints.

Status	Body	Cause
`409`	`{"error": {"message": "…", "code": "verification_already_pending"}}`	A submission is already awaiting review.
`422`	`{"error": {"message": "…", "code": "invalid_verification"}}`	Validation failure.
`404`	`{"error": {"message": "Unknown sub-merchant account", "code": "account_not_found"}}`	Unknown `account_id`.

Issue an onboarding link

POST /platform/accounts/{account_id}/onboarding_links. Scope accounts:write. Creates a single-use dashboard link the sub-merchant opens to complete a step themselves. Fields may be sent inside an onboarding_link object or at the top level.

string

onboarding, kyb or payout_destination. Pick payout_destination when the only thing missing is where their money goes. A platform is not allowed to set that itself.

string

Where the sub-merchant lands after finishing.

integer

Link lifetime in seconds. Defaults to 7 days and is capped at 30 days.

Response 201

{
  "id": "d8e9f0a1-b2c3-4d4e-9f50-617283940516",
  "account_id": "c7d8e9f0-a1b2-4c3d-8e4f-506172839405",
  "purpose": "payout_destination",
  "return_url": "https://platform.example.com/merchants/8812",
  "token_prefix": "spob_4a2c",
  "token": "spob_4a2c…",
  "url": "https://app.southpay.io/onboarding/spob_4a2c…",
  "expires_at": "2026-05-19T09:00:00.000Z",
  "completed_at": null,
  "created_at": "2026-05-12T09:00:00.000Z"
}

token and url are returned only on create. Retrieving the link later gives you token_prefix and nothing usable. Hand the URL to the sub-merchant immediately or store it securely.

A validation failure returns 422 {"error": {"message": "…", "code": "invalid_onboarding_link"}}.

Platform overview

GET /platform/overview. Scope accounts:read. Aggregate figures across your sub-merchants for a date range.

string

ISO date. Defaults to 29 days before to.

string

ISO date. Defaults to today.

Ranges longer than 365 days are clamped. Unparseable dates fall back to the defaults.

Response 200

{
  "from": "2026-04-13",
  "to": "2026-05-12",
  "livemode": true,
  "sub_merchant_count": 42,
  "activated_count": 31,
  "completed_payments": 1874,
  "volume_by_currency": [
    { "currency": "EUR", "amount_cents": 9481200 },
    { "currency": "USD", "amount_cents": 2210400 }
  ],
  "platform_fee_earned": [
    { "asset_id": "ETH_USDC", "amount_atomic": "142218000" }
  ],
  "top_sub_merchants": [
    { "account_id": "c7d8e9f0-a1b2-4c3d-8e4f-506172839405", "name": "Blue Harbour Coffee", "amount_cents": 1204800 }
  ]
}

activated_count is the number of sub-merchants with confirmed KYC. platform_fee_earned is your accrued fee per asset in atomic units, net of debits. top_sub_merchants is capped at five.

Platform payments

GET /platform/payments. Scope accounts:read. Payments across every sub-merchant, newest first. This is a purpose-built summary, not the payment intent shape. There is no reference lookup, no addresses and no metadata.

string

Limit to one sub-merchant.

string

pending, processing, completed, failed, expired or refunded. Unrecognized values are ignored rather than rejected.

integer

default:"1"

integer

default:"25"

Between 1 and 100.

Response 200

{
  "data": [
    {
      "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
      "reference": "A1B2C3D4E5F6G7H8",
      "status": "completed",
      "settlement_currency": "EUR",
      "settlement_amount_cents": 4999,
      "platform_fee_percentage": "0.015",
      "created_at": "2026-05-11T14:21:58Z",
      "account": {
        "id": "c7d8e9f0-a1b2-4c3d-8e4f-506172839405",
        "name": "Blue Harbour Coffee"
      }
    }
  ],
  "meta": { "total": 1874, "page": 1, "per_page": 25, "total_pages": 75 }
}

settlement_amount_cents is an integer here, unlike the two-decimal settlement_amount string on a payment intent. platform_fee_percentage is the rate snapshotted at payment time, as a string, and may be null on older payments.

Acting on a sub-merchant

To call any other endpoint as a sub-merchant, add the header:

X-Southpay-Account: c7d8e9f0-a1b2-4c3d-8e4f-506172839405

Your credential must hold accounts:act in addition to the scope the target endpoint needs. Everything then behaves as if the sub-merchant made the call, against their balances, their payments and their webhooks.

Request

curl -X POST https://api.southpay.io/api/v2/payments \
  -H "Authorization: Bearer sp_sk_live_…" \
  -H "X-Southpay-Account: c7d8e9f0-a1b2-4c3d-8e4f-506172839405" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8812_1043" \
  -d '{ "payment_intent": { "amount": "12.50", "currency": "EUR" } }'

Guardrails

Two things a platform can never do while acting, regardless of scope:

Status	Body	Blocked action
`403`	`{"error": {"message": "…", "code": "platform_cannot_issue_credentials"}}`	Creating, rotating or revoking the sub-merchant’s API keys or agent credentials.
`403`	`{"error": {"message": "…", "code": "platform_cannot_change_payout_destination"}}`	Changing where the sub-merchant’s money goes.

For payout destinations, issue an onboarding link with purpose: "payout_destination" and let the sub-merchant set it themselves.

Header errors

Status	Body	Cause
`403`	`{"error": {"message": "This account is not a platform", "code": "not_a_platform"}}`	Your store is not platform-enabled.
`403`	`{"error": {"message": "Insufficient scope: accounts:act required", "code": "insufficient_scope"}}`	Credential lacks `accounts:act`.
`403`	`{"error": {"message": "Unknown sub-merchant account", "code": "account_not_found"}}`	The id is not one of your sub-merchants. Note this is `403`, not `404`.

Webhook fan-out

Payment and store-verification events for a sub-merchant are delivered twice: once to the sub-merchant’s own endpoints, and once to yours with an extra top-level account key holding the sub-merchant’s store id. Use that key to route the event. Billing events do not fan out to platforms.

Create and update errors

Status	Body	Cause
`422`	`{"error": {"message": "Name can't be blank", "code": "invalid_account"}}`	Missing or blank `name`.
`422`	`{"error": {"message": "A sub-merchant with external_id merchant_8812 already exists", "code": null}}`	Duplicate `external_id` that could not be adopted, on create or update.
`422`	`{"error": {"message": "Validation failed: Platform fee percentage must be a decimal fraction between 0 and 1 (0.0125 means 1.25%)", "code": "invalid_account"}}`	`platform_fee_percentage` sent as a percent rather than a fraction.
`409`	`{"error": {"message": "Sub-merchant has active funds or in-flight money movement", "code": "account_has_active_funds", "blockers": […]}}`	Delete attempted while the account still holds money.
`404`	`{"error": {"message": "Unknown sub-merchant account", "code": "account_not_found"}}`	The id is not one of your sub-merchants.
`403`	`{"error": {"message": "This account is not a platform", "code": "not_a_platform"}}`	Platform mode not enabled on your store.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Platform accounts

Authentication and scope

Create a sub-merchant

Response fields

List sub-merchants

Retrieve a sub-merchant

Update a sub-merchant

Delete a sub-merchant

Restore a sub-merchant

Attest verification

Issue an onboarding link

Platform overview

Platform payments

Acting on a sub-merchant

Guardrails

Header errors

Webhook fan-out

Create and update errors

​Authentication and scope

​Create a sub-merchant

​Response fields

​List sub-merchants

​Retrieve a sub-merchant

​Update a sub-merchant

​Delete a sub-merchant

​Restore a sub-merchant

​Attest verification

​Issue an onboarding link

​Platform overview

​Platform payments

​Acting on a sub-merchant

​Guardrails

​Header errors

​Webhook fan-out

​Create and update errors

Authentication and scope

Create a sub-merchant

Response fields

List sub-merchants

Retrieve a sub-merchant

Update a sub-merchant

Delete a sub-merchant

Restore a sub-merchant

Attest verification

Issue an onboarding link

Platform overview

Platform payments

Acting on a sub-merchant

Guardrails

Header errors

Webhook fan-out

Create and update errors