Agentic API

The agentic API is a separate surface for autonomous agents acting on a store’s behalf. It lives under /api/v2/agentic, accepts only spa_ agent credentials, and returns records the calling credential created. An agent never sees another agent’s payments or payouts. For how credentials are issued and how authorization providers work, see agent credentials and authorization. This page is the endpoint reference. Paths are relative to https://api.southpay.io/api/v2.

Authentication

Authorization: Bearer spa_live_…

Only credentials matching spa_live_ or spa_test_ are accepted. API keys and OAuth tokens are rejected on every path here, and agent credentials are rejected everywhere else.

Status	Body	Cause
`401`	`{"error": {"message": "Agent credential required", "code": "agent_credential_required"}}`	Missing or non-`spa_` token.
`401`	`{"error": {"message": "Invalid or revoked agent credential", "code": "invalid_agent_credential"}}`	Unknown, expired or revoked credential.
`403`	`{"error": {"message": "Insufficient scope: payments:write required", "code": "insufficient_scope"}}`	Credential lacks the scope.

Every response on this surface uses the structured envelope {"error": {"message": …, "code": …}}. That is unlike the rest of the API, where the flat {"error": "<string>"} form is the common case.

Scopes

Eight agent scopes exist: payments:read, payments:write, payouts:read, payouts:write, assets:read, assets:write, x402:read, x402:write.

Rate limit

600 requests per minute per credential in live mode (120 in test), shared across all agentic paths except market data. 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.

What the default authorization provider blocks

Read this before you write any agent that moves money. The authorization provider is configured per store, and only SouthPay staff can set it. With no provider, which is the default for every store, payments work and most other writes are hard-blocked at 403.

Action	Default behaviour
`POST /agentic/payments`	Allowed. No mandate needed.
`POST /agentic/payments/{id}/cancel`	Allowed.
`POST /agentic/payments/{id}/refunds`	`403` `mandate_required`
`PATCH /agentic/tokens/{asset_id}`	`403` `mandate_required`
`POST /agentic/mandates`	`403` `mandate_required`
`POST /agentic/x402/settlements`	`403` `mandate_required`
`POST /agentic/payouts`	`403` `payout_controls_required`, unless a spend limit exists for that asset

Mandates are not optional hardening. Four write paths cannot be used at all without a configured authorization provider, and there is no API to configure one. If your agent needs refunds, token control or x402 settlement, talk to support before you build against them. Payouts are the one exception: an agent spend limit set in the dashboard unblocks them without a provider.

Read agent context

GET /agentic/account. No scope required. Call this first: it tells you which store you are on, which mode, what you are allowed to do, and whether mandates are available.

curl https://api.southpay.io/api/v2/agentic/account \
  -H "Authorization: Bearer spa_live_…"

{
  "store": {
    "id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
    "name": "Blue Harbour Coffee",
    "kyc_confirmed": true
  },
  "mode": "live",
  "livemode": true,
  "agent": {
    "name": "checkout-agent",
    "principal": "[email protected]",
    "token_prefix": "spa_live_4a2c9f1b",
    "scopes": ["payments:read", "payments:write", "assets:read"],
    "last_used_at": "2026-05-12T08:59:12.000Z",
    "expires_at": "2026-11-12T00:00:00.000Z"
  },
  "authorization": {
    "provider": "NullAuthorizationProvider",
    "mandates": false
  },
  "accepted_assets_count": 6
}

string

required

"live" or "test", derived from the credential prefix. There is no separate sandbox host.

object

required

Show properties

string

Identifies the authorization provider in force. "NullAuthorizationProvider" means no provider is configured.

boolean

False when the null provider is active. Treat false as “refunds, token changes, mandates and x402 will all return 403”.

Create a payment

POST /agentic/payments. Scope payments:write. Idempotency-Key optional. The same payment_intent envelope as the public endpoint, but a smaller field set and stricter amount validation. title, description, image_url and line_items are not accepted here.

string

required

Fiat major units. Must be finite, positive, at most 2 decimal places, and at most 100000000.00.

string

required

One of USD, EUR, GBP, HKD, SGD, JPY, DKK, CHF, SEK, NOK.

string

integer

default:"3600"

How long the payment stays payable, in seconds. Minimum 300, maximum 86400. Omit it for the 60 minute default.

object

At most 50 keys. Every value must be a string.

curl -X POST https://api.southpay.io/api/v2/agentic/payments \
  -H "Authorization: Bearer spa_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": {
      "amount": "12.50",
      "currency": "EUR",
      "order_id": "agent_order_77",
      "metadata": { "session": "sess_9f2a" }
    }
  }'

{
  "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
  "reference": "A1B2C3D4E5F6G7H8",
  "hosted_url": "https://pay.southpay.io/A1B2C3D4E5F6G7H8",
  "status": "pending",
  "state_reason": null,
  "settlement_currency": "EUR",
  "settlement_amount": "12.50",
  "settlement_status": null,
  "auto_swap_status": null,
  "reconciliation_status": null,
  "terminal": false,
  "expires_at": "2026-05-12T10:00:00.000Z",
  "created_at": "2026-05-12T09:00:00.000Z",
  "order_id": "agent_order_77",
  "payment_addresses": [
    {
      "id": "2f9d8c7b-6a5e-4d3c-2b1a-0f9e8d7c6b5a",
      "address": "0x9a3f…c2d1",
      "status": "pending",
      "crypto_amount_atomic": "12500000",
      "exchange_rate_snapshot": "1.000000000000000000",
      "created_at": "2026-05-12T09:00:00.000Z",
      "supported_asset": {
        "asset_id": "ETH_USDC",
        "coin_symbol": "USDC",
        "chain_symbol": "ETH",
        "atomic_decimals": 6
      }
    }
  ]
}

exchange_rate_snapshot is a plain decimal string, not an object. There is no {rate, source} shape on a payment address.

The intent expires 60 minutes after creation, or after expires_in seconds when you send it. Send the customer to hosted_url and pay the exact crypto_amount_atomic to address.

Status	Code	Cause
`422`	`invalid_amount`	Missing, non-numeric, non-finite, non-positive, or more than 2 decimal places.
`422`	`amount_too_large`	Above `100000000.00`.
`422`	`invalid_currency`	`currency` blank.
`422`	`unsupported_currency`	Not one of the ten payment currencies.
`422`	`invalid_metadata`	Over 50 keys, or a non-string value.
`422`	`invalid_expires_in`	Not an integer, or outside 300 to 86400 seconds.
`403`	`authorization_denied`	The provider refused. Message is `Payment not authorized: <reason>`.

Retrieve a payment

GET /agentic/payments/{id}. Scope payments:read. Returns the detail view, identical in shape to the public retrieve endpoint: financials, transaction, overpayment, merchant, payment_events, timeline and the rest. An id the credential did not create returns 404.

List payments

GET /agentic/payments. Scope payments:read. Only this credential’s payments, newest first.

string

Exact match on the 16-character reference. Upcased before matching.

integer

default:"1"

integer

default:"10"

Between 1 and 100.

Response 200

{
  "data": [ { "id": "7b1f0c2e-…", "reference": "A1B2C3D4E5F6G7H8", "status": "completed", "…": "…" } ],
  "meta": { "total": 1, "page": 1, "per_page": 10, "total_pages": 1 }
}

Agentic payments use the meta envelope. Agentic payouts and x402 settlements use pagination, and refunds and mandates return data with no page information at all.

Cancel a payment

POST /agentic/payments/{id}/cancel. Scope payments:write. No body. Only a pending intent can be canceled. The intent moves to status: "expired" with state_reason: "canceled_by_agent", and 200 returns the full detail view.

Response 200

{
  "id": "7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f",
  "status": "expired",
  "state_reason": "canceled_by_agent",
  "terminal": true,
  "…": "…"
}

Status	Code	Body message
`422`	`not_cancelable`	`Only pending payments can be canceled (status is 'completed')`

Cancellation emits payment_intent.canceled, but that event is not in the subscribable catalogue, so no webhook endpoint can receive it. To observe agent cancellations, poll for status: "expired" with state_reason: "canceled_by_agent".

Refund a payment

POST /agentic/payments/{payment_intent_id}/refunds. Scope payments:write. Idempotency-Key required.

string

Decimal major units of the asset. Omit for a full refund.

string

Required when the payment received more than one asset.

There is no destination_address here. An agent cannot redirect a refund. Funds go back to the paying address. Returns 201 with {"data": [ … ]}, an array of refund objects, one per asset. GET on the same path lists existing refunds in the same wrapper, unpaginated. Unlike the merchant refund endpoint, this one returns machine-readable codes:

Status	Code	Cause
`422`	`idempotency_key_required`	Header missing.
`403`	`mandate_required`	No authorization provider configured. Message: `Refunding a payment requires a configured authorization provider (mandate)`.
`403`	`authorization_denied`	The provider refused.
`422`	`not_refundable`	Status is not `completed`, `failed` or `expired`.
`422`	`nothing_to_refund`	No confirmed funds remain.
`422`	`invalid_amount`	Amount unparseable, or above the refundable balance, or sent for a non-`completed` intent.
`404`/`422`	`asset_not_found`	`asset_id` does not match a confirmed deposit.
`422`	`ambiguous_asset`	Multi-asset payment without `asset_id`.
`422`	`invalid_destination`	The paying address is missing or fails validation.
`422`	`insufficient_balance`	Store ledger balance is short.

Create a payout

POST /agentic/payouts. Scope payouts:write. Idempotency-Key required. Crypto only, to a raw address. Agents cannot use saved payout destinations and cannot off-ramp to fiat. Parameters are top-level.

string

required

Active asset in the credential’s mode.

string

required

Atomic units. Must be positive.

string

required

Where the funds go. Must be valid for the asset’s chain.

curl -X POST https://api.southpay.io/api/v2/agentic/payouts \
  -H "Authorization: Bearer spa_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent_payout_0041" \
  -d '{
    "asset_id": "ETH_USDC",
    "amount_atomic": "5000000",
    "destination_address": "0xabcd…"
  }'

{
  "id": "0a1b2c3d-4e5f-4061-8273-849506172839",
  "status": "pending",
  "payout_rail": "crypto",
  "amount_atomic": "5000000",
  "amount_decimal": "5",
  "destination_address": "0xabcd…",
  "tx_hash": 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 }
}

The response is the same payout object merchants see. Idempotency keys are namespaced per credential, so two agents can use the same key without colliding.

Status	Code	Cause
`422`	`idempotency_key_required`	Header missing.
`404`	`asset_not_found`	Unknown or inactive asset.
`422`	`invalid_amount`	`amount_atomic` not positive.
`422`	`destination_required`	`destination_address` blank.
`403`	`payout_controls_required`	No provider and no spend limit for this asset. Message: `Agent payouts require a configured authorization provider or a spend limit on this asset`.
`403`	`authorization_denied`	The provider refused.
`403`	`per_tx_cap_exceeded`	Above the per-transaction limit.
`403`	`daily_cap_exceeded`	Above the remaining daily limit.
`422`	`payout_rejected`	Insufficient balance or below the network minimum.

Check headroom before you call, with payout limits.

Retrieve and list payouts

GET /agentic/payouts/{id}. Scope payouts:read. Bare payout object. Unknown id returns 404 not_found. GET /agentic/payouts. Scope payouts:read. Accepts page (default 1) and per_page (default 25, max 100).

Response 200

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

Read payout limits

GET /agentic/payout_limits. Scope assets:read. Spend caps and remaining headroom for the current UTC day. Call this before a payout rather than discovering a cap through a 403.

string

Limit the response to one asset.

Response 200

{
  "limits": [
    {
      "asset_id": "ETH_USDC",
      "coin_symbol": "USDC",
      "chain_symbol": "ETH",
      "atomic_decimals": 6,
      "per_tx_cap_atomic": "10000000",
      "daily_cap_atomic": "50000000",
      "daily_spent_atomic": "12000000",
      "daily_remaining_atomic": "38000000",
      "controls_configured": true
    }
  ],
  "utc_day": "2026-05-12"
}

boolean

required

False when neither cap is set. With the default authorization provider, false here means POST /agentic/payouts will return 403 payout_controls_required for this asset.

string | null

Null when there is no daily cap, meaning unlimited rather than zero.

Counters reset at 00:00 UTC. utc_day tells you which day the figures belong to.

Read balances

GET /agentic/balances. Scope assets:read.

string

Filter the balances array. settlement_balance is always computed across all assets regardless.

Response 200

{
  "balances": [
    {
      "asset_id": "ETH_USDC",
      "coin_symbol": "USDC",
      "chain_symbol": "ETH",
      "atomic_decimals": 6,
      "balance_atomic": "1499870000"
    }
  ],
  "settlement_balance": { "currency": "EUR", "amount_cents": 137940 }
}

This differs from the merchant balances endpoint: there is no stablecoin_summary, and an asset_id filter is available. amount_cents is null when a rate could not be resolved.

Read exchange rates

GET /agentic/exchange_rates. Scope assets:read. SouthPay’s own rates, the ones applied when pricing a payment. For public market data, use market data instead.

string

Fiat currency to quote against. Defaults to the store’s settlement currency.

string

Quote a single asset instead of all accepted assets.

Response 200

{
  "currency": "EUR",
  "rates": [
    {
      "asset_id": "ETH_USDC",
      "coin_symbol": "USDC",
      "chain_symbol": "ETH",
      "currency": "EUR",
      "rate": "0.9176",
      "source": "coingecko"
    }
  ]
}

rate is a string. Assets whose rate cannot be resolved are omitted from the array rather than returned with a null rate, so a shorter list than you expected is a lookup failure, not an empty balance.

Status	Code	Cause
`422`	`unsupported_currency`	Not one of the ten payment currencies.
`404`	`asset_not_found`	Unknown or inactive `asset_id`.

Manage accepted tokens

GET /agentic/tokens. Scope assets:read.

Response 200

{
  "accepted": [
    { "asset_id": "ETH_USDC", "coin_symbol": "USDC", "chain_symbol": "ETH", "active": true }
  ],
  "available": [
    { "asset_id": "TRON_USDT", "coin_symbol": "USDT", "chain_symbol": "TRON", "active": false }
  ]
}

accepted is what customers can currently pay with. available is everything else active in this mode. The two arrays never overlap, and active mirrors which array the entry is in. PATCH /agentic/tokens/{asset_id}. Scope assets:write.

boolean

required

True to accept the asset, false to stop accepting it.

Response 200

{
  "asset_id": "TRON_USDT",
  "active": true,
  "provider": "HumanosAuthorizationProvider"
}

Status	Code	Cause
`422`	`invalid_active`	`active` is not a boolean.
`404`	`asset_not_found`	Unknown asset.
`403`	`mandate_required`	No authorization provider. Message: `Managing accepted tokens requires a configured authorization provider (mandate)`.
`403`	`authorization_denied`	The provider refused.
`422`	`asset_change_rejected`	The store rejected the change, for example the last accepted asset cannot be removed.

Mandates

A mandate is a signed spending envelope an agent draws down against, used by x402 settlements. Concepts are covered in the authorization guide. POST /agentic/mandates. Scope x402:write. Parameters are top-level.

string

required

Asset the cap is denominated in.

string

required

Total the mandate may spend, in atomic units. Must be positive.

string

required

Your reference for this mandate. Settlements name it to draw against the envelope.

string

Ceiling for any single settlement.

string

default:"x402"

What the mandate authorizes.

integer

default:"3600"

Lifetime from creation.

Response 201

{
  "id": "f0a1b2c3-d4e5-4f60-8172-839405162738",
  "scope": "x402",
  "mandate_ref": "session-9f2a",
  "status": "active",
  "asset_id": "ETH_USDC",
  "total_cap_atomic": "50000000",
  "per_call_cap_atomic": "1000000",
  "spent_atomic": "0",
  "remaining_atomic": "50000000",
  "authorization_provider": "HumanosAuthorizationProvider",
  "expires_at": "2026-05-12T10:00:00.000Z",
  "revoked_at": null,
  "livemode": true,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z"
}

status is active, revoked, expired or exhausted. remaining_atomic is the figure to check before settling. GET /agentic/mandates. Scope x402:read. Returns {"data": [ … ]}, capped at 100 and not paginated: there are no page parameters and no total. GET /agentic/mandates/{id}. Scope x402:read. Bare mandate object. Unknown id returns 404 not_found.

Status	Code	Cause
`404`	`asset_not_found`	Unknown asset.
`422`	`invalid_cap`	`total_cap_atomic` not positive.
`422`	`mandate_ref_required`	`mandate_ref` blank.
`403`	`mandate_required`	No authorization provider. Message: `Session mandates require a configured authorization provider`.
`403`	`authorization_denied`	The provider refused.

x402 settlements

POST /agentic/x402/settlements. Scope x402:write. Idempotency-Key required. Parameters are top-level.

string

required

string

required

Atomic units. Zero is accepted. The check rejects negatives only.

string

required

The mandate to draw against. Must be active, unexpired and have headroom.

string

Replay guard. Generated for you if omitted.

string

Recipient identifier from the x402 challenge.

string

Payer identifier.

object

The raw requirements object from the x402 challenge, stored alongside the settlement.

Response 201

{
  "id": "a1b2c3d4-e5f6-4071-8283-940516273849",
  "status": "pending",
  "asset_id": "ETH_USDC",
  "amount_atomic": "250000",
  "mandate_ref": "session-9f2a",
  "nonce": "3f2a91c8b7d64e05",
  "pay_to": "0xabcd…",
  "payer": "0x1234…",
  "tx_ref": null,
  "failure_reason": null,
  "livemode": true,
  "created_at": "2026-05-12T09:00:00.000Z",
  "updated_at": "2026-05-12T09:00:00.000Z"
}

Settlements are ledger-only by default. On-chain dispatch is off unless SouthPay staff enable it for your store. A confirmed settlement without dispatch enabled means the internal ledger moved, not that a transaction was broadcast. tx_ref stays null.

status is pending, submitted, confirmed or failed. GET /agentic/x402/settlements. Scope x402:read. Accepts page and per_page (default 25, max 100), and returns the pagination envelope. GET /agentic/x402/settlements/{id}. Scope x402:read. Unknown id returns 404 not_found.

Status	Code	Cause
`422`	`idempotency_key_required`	Header missing.
`404`	`asset_not_found`	Unknown asset.
`422`	`invalid_amount`	Negative amount. Message: `amount_atomic must be zero or positive`.
`422`	`mandate_ref_required`	`mandate_ref` blank.
`403`	`mandate_required`	No usable mandate. Either `An active session mandate is required to settle x402 charges` or `The session mandate is expired, revoked, or exhausted`.
`403`	`spend_cap_exceeded`	Over the per-call cap, or over the mandate’s remaining envelope.
`422`	`insufficient_balance`	Store balance is short.

Market data

GET /agentic/market_data. Unauthenticated. No credential, no scope. Public reference prices from CoinGecko. It touches no SouthPay funds and reads no store data, which is why it needs no credential.

string

required

Ticker or CoinGecko id, for example btc or bitcoin.

string

default:"usd"

Currency to quote in.

Response 200

{
  "query": "btc",
  "coin_id": "bitcoin",
  "vs_currency": "usd",
  "price": 64211.42,
  "market_cap": 1264800000000,
  "volume_24h": 28410000000,
  "change_24h_pct": -1.24,
  "source": "coingecko"
}

Rate limited to 30 requests per minute per IP, separately from the 120-per-credential agentic limit.

Status	Code	Cause
`422`	`missing_parameter`	`symbol_or_id` blank.
`404`	`token_not_found`	Unknown identifier, or no data for it.
`429`	`rate_limited`	Over 30 requests per minute from your IP.
`429`	`upstream_rate_limited`	The upstream provider throttled us. Retry with backoff.
`502`	`market_data_error`	Upstream unavailable.

These are public market prices, not the rates SouthPay applies. For the rate used to price a payment intent, use exchange rates.

Payment statuses

Agentic payments use the same six statuses as merchant payments: pending, processing, completed, expired, failed, refunded. There is no overpaid status. An overpayment is status: "completed" with state_reason: "completed_overpaid", and the excess is in the overpayment object on the detail view. state_reason has ten values, including canceled_by_agent, which only this API produces. See payment lifecycle.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Authentication

Scopes

Rate limit

What the default authorization provider blocks

Read agent context

Create a payment

Retrieve a payment

List payments

Cancel a payment

Refund a payment

Create a payout

Retrieve and list payouts

Read payout limits

Read balances

Read exchange rates

Manage accepted tokens

Mandates

x402 settlements

Market data

Payment statuses

​Authentication

​Scopes

​Rate limit

​What the default authorization provider blocks

​Read agent context

​Create a payment

​Retrieve a payment

​List payments

​Cancel a payment

​Refund a payment

​Create a payout

​Retrieve and list payouts

​Read payout limits

​Read balances

​Read exchange rates

​Manage accepted tokens

​Mandates

​x402 settlements

​Market data

​Payment statuses

Authentication

Scopes

Rate limit

What the default authorization provider blocks

Read agent context

Create a payment

Retrieve a payment

List payments

Cancel a payment

Refund a payment

Create a payout

Retrieve and list payouts

Read payout limits

Read balances

Read exchange rates

Manage accepted tokens

Mandates

x402 settlements

Market data

Payment statuses