Agent authorization

Read this before you write any agent code, because the default is more restrictive than most integrations expect. On a store with no extra configuration, an agent credential can read everything in its scopes, create payments, and cancel them. It cannot refund a payment, change which tokens the store accepts, issue a session mandate, or pay out. Those four write paths return 403 and keep returning 403 until a human configures a control. There is no request you can send, and no header you can add, that changes this from the agent side. The denials are the system working as designed. Treat them as a configuration state to report, not an error to retry.

What happens by default

SouthPay resolves an authorization provider per store. No provider is configured by default, so every store gets a permissive stub that approves every verification it is asked for. Each endpoint then checks whether the approval came from a real provider, and refuses if it did not.

Agent action	Default behavior
`GET` account, payments, payouts, balances, tokens, payout limits, exchange rates, mandates, settlements	Allowed, subject to scope
`POST /agentic/payments`	Allowed
`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`. Needs a usable mandate, which cannot be issued
`POST /agentic/payouts`	403 `payout_controls_required`, unless a spend limit exists for that asset

Payment creation is the deliberate exception. Charging a customer creates a receivable rather than an outflow, so it needs no mandate. Check which provider you are on with GET /api/v2/agentic/account (the get_account MCP tool). authorization.provider identifies the authorization provider in force and authorization.mandates is a boolean:

Response 200

{
  "authorization": {
    "provider": "NullAuthorizationProvider",
    "mandates": false
  }
}

"mandates": false means you are on the defaults described above.

Unblocking payouts with spend limits

Spend limits are per-credential, per-asset payout caps. They are the only control a merchant can configure without SouthPay staff involvement, and they are what makes agent payouts possible at all. A spend limit does two things:

It unlocks the asset. With the default provider, a payout in an asset that has no spend limit is refused with payout_controls_required before any balance check happens.
It caps the payout. Every payout is checked against a per-transaction cap and against a daily counter that resets at midnight UTC. Breaching either returns 403 with per_tx_cap_exceeded or daily_cap_exceeded.

Limits are set on the credential in the dashboard, under Agents. Both caps are optional individually. A limit row with only a daily cap still unlocks the asset. An agent reads its own headroom with GET /api/v2/agentic/payout_limits (or get_payout_limits over MCP), which returns per_tx_cap_atomic, daily_cap_atomic, daily_spent_atomic, daily_remaining_atomic and controls_configured per asset, plus the utc_day the counter belongs to. controls_configured: false on an asset is a reliable predictor that a payout in it will be denied. Size the payout from this endpoint rather than discovering the cap through a 403.

Unblocking refunds, token changes and mandates

Refunds, token toggles and mandate issuance need a real authorization provider. Spend limits do not help here; the check is specifically “is this store’s provider something other than the default”. A provider is configured per store. There is no API for this. It is not exposed on any merchant endpoint and it is not a dashboard toggle. SouthPay support enables it for your store. Until then, the three actions stay at 403 mandate_required regardless of credential scopes.

If you are building an agent for merchants generally, assume the provider is absent. Discover it at runtime from GET /agentic/account and gate your own tool exposure on authorization.mandates, rather than offering the agent a refund capability that will always fail.

With a provider enabled

Once a provider is configured, the model changes in both directions. The three blocked actions become available, and payment creation stops being unconditional. It is verified per call like everything else, and can now be denied with authorization_denied. The agent presents a mandate on gated requests in the X-Mandate header, base64-encoded JSON:

curl -X POST https://api.southpay.io/api/v2/agentic/payments/{id}/refunds \
  -H "Authorization: Bearer spa_live_..." \
  -H "Idempotency-Key: refund-order-1042" \
  -H "X-Mandate: eyJwcmVzZW50YXRpb24iOiAi..." \
  -H "Content-Type: application/json" \
  -d '{"refund": {}}'

SouthPay forwards the presentation and the action’s parameters (action type, amount, currency, asset, destination) to the provider, which returns allow or deny. The decision and receipt are stored with the resulting payment, payout or mandate. Two details worth planning for:

The header is capped at 32768 bytes, and a value that is missing, oversized or not valid base64 JSON is treated as no mandate at all. On a gated action that produces a denial rather than a parse error, so a malformed header and an absent one look identical from the outside.
Spend limits still apply. A payout must pass provider verification and stay inside any configured per-transaction and daily caps.

Error codes

Every agentic endpoint uses the structured envelope, with code populated:

Response 403

{
  "error": {
    "message": "Refunding a payment requires a configured authorization provider (mandate)",
    "code": "mandate_required"
  }
}

Code	Status	Meaning	What to do
`agent_credential_required`	401	Missing or malformed bearer token	Send `Authorization: Bearer spa_...`
`invalid_agent_credential`	401	Token matches no active credential	Check for revocation or expiry
`insufficient_scope`	403	Credential lacks the scope for this endpoint	The merchant issues a credential with the scope
`mandate_required`	403	Refund, token change, mandate issuance or settlement on a store with no authorization provider	Report it; the merchant contacts support to enable a provider
`authorization_denied`	403	A provider evaluated the action and denied it; the message carries the reason	Surface the reason to the principal, do not retry
`payout_controls_required`	403	Payout with no provider and no spend limit for the asset	The merchant sets a spend limit on that asset
`per_tx_cap_exceeded`	403	Payout above the per-transaction cap	Reduce the amount
`daily_cap_exceeded`	403	Payout would pass the cap for the current UTC day	Wait for the day to roll over, or reduce the amount
`spend_cap_exceeded`	403	x402 settlement above the mandate’s per-call cap, or the envelope is exhausted	Issue a new mandate or reduce the charge
`idempotency_key_required`	422	Payout, refund or settlement sent without `Idempotency-Key`	Send a unique key per logical operation
`rate_limited`	429	Over 120 requests per minute on this credential	Back off; no `Retry-After` header is set

Retrying an identical gated request produces an identical denial and burns rate-limit budget. Read error.code, explain it, and stop.

Audit trail

Each gated decision is recorded. Payments, payouts and mandates persist the provider’s decision and receipt on the record itself. Every agent action (created, denied, cap exceeded) is emitted as telemetry keyed by credential id. Merchants see the resulting payments, payouts and settlements per credential in the dashboard under Agents.

Getting started

Authentication

Core resources

Recurring

Checkout

Agentic commerce

Platform

Integrations

Building reliably

Changelog

Agent authorization

What happens by default

Unblocking payouts with spend limits

Unblocking refunds, token changes and mandates

With a provider enabled

Error codes

Audit trail

​What happens by default

​Unblocking payouts with spend limits

​Unblocking refunds, token changes and mandates

​With a provider enabled

​Error codes

​Audit trail

What happens by default

Unblocking payouts with spend limits

Unblocking refunds, token changes and mandates

With a provider enabled

Error codes

Audit trail