Agentic quickstart

This walks from an empty store to an agent charging a customer. You need a SouthPay account with at least one accepted crypto asset. See the payments quickstart if you are starting fresh. Do this in test mode. Test mode has exactly one usable asset, SETH on Ethereum Sepolia, and the API surface is otherwise identical to live.

Create an agent credential

Agent credentials are created in the dashboard under Agents. There is no API-key call that creates one; the endpoint behind that screen accepts dashboard sessions only.Choose:

Mode. test to start. The mode is baked into the token prefix and cannot be changed later.
Name and principal. Who the agent is, for your audit trail, for example Support bot / [email protected].
Scopes. payments:read and payments:write are enough for this guide. Omitting scopes grants all eight.
Expiry. Optional, recommended.

The full token is shown once, in the form spa_test_ followed by 48 hex characters. SouthPay stores only a SHA-256 digest and a 16-character display prefix, so a lost token cannot be recovered. Revoke it and create another.If you are connecting an MCP client and would rather not handle a key at all, skip this step and use browser login instead, which mints the credential for you.

Connect a client

Over MCP, point the client at the hosted server and pass the credential as a bearer token:

claude mcp add --transport http southpay https://mcp.southpay.io/mcp \
  --header "Authorization: Bearer spa_test_..."

{
  "mcpServers": {
    "southpay": {
      "url": "https://mcp.southpay.io/mcp",
      "headers": {
        "Authorization": "Bearer spa_test_..."
      }
    }
  }
}

Confirm the connection by having the agent call get_account. It returns the store, the mode, the credential’s scopes, and which authorization provider is in effect.Over plain HTTP, send the same token to the REST API and skip MCP entirely:

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

Create a payment

curl -X POST https://api.southpay.io/api/v2/agentic/payments \
  -H "Authorization: Bearer spa_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": {
      "amount": "49.99",
      "currency": "USD",
      "order_id": "ORDER-1042"
    }
  }'

{
  "id": "5f2c9d84-1b7a-4c3e-9a10-8d4f6b21c907",
  "reference": "N2BD0BZJUVH0XGUD",
  "status": "pending",
  "state_reason": null,
  "settlement_amount": "49.99",
  "settlement_currency": "USD",
  "order_id": "ORDER-1042",
  "hosted_url": "https://pay.southpay.io/N2BD0BZJUVH0XGUD",
  "expires_at": "2026-07-12T13:00:00.000Z",
  "terminal": false,
  "payment_addresses": [
    {
      "id": "b04c1f6e-2a53-4d18-91cf-77e0a3d5b2aa",
      "address": "0x8f3C4a91B7e0D2Ff5A6c81b4E3d9077aC2b15E4d",
      "status": "pending",
      "crypto_amount_atomic": "22541000000000000",
      "exchange_rate_snapshot": "2217.000000000000000000",
      "supported_asset": {
        "asset_id": "SETH",
        "coin_symbol": "ETH",
        "chain_symbol": "SETH",
        "atomic_decimals": 18
      }
    }
  ]
}

A few things to note about the response. reference is always 16 uppercase alphanumeric characters and is what appears in webhooks and on the hosted page; id is a bare UUID. crypto_amount_atomic is a string of base units, so divide by 10 ** atomic_decimals for a human amount. exchange_rate_snapshot is a plain numeric string, not an object.Give the customer the hosted_url, or the deposit address and the exact crypto amount.The amount is a decimal string in major units, with at most two decimal places and a ceiling of 100000000.00. Idempotency-Key is optional here but not on refunds, payouts or settlements, where it is required.

Wait for it to complete

Intents expire 60 minutes after creation. Send expires_in on create to choose a different window, in seconds, between 300 and 86400.Over MCP, wait_for_payment takes the payment id or its reference and polls server-side until the payment is completed, expired, failed or refunded, returning {done: true, status, polls, payment}. If the budget runs out first it returns {done: false, timed_out: true, status, polls, hint, payment}. A timeout is not a failed payment, so call it again.Over REST, poll GET /api/v2/agentic/payments/{id}, or configure a webhook for push delivery, which is the better choice for anything long-running.There are six payment statuses: pending, processing, completed, expired, failed, refunded. An overpayment lands as completed with state_reason: "completed_overpaid". There is no overpaid status. An agent cancel lands as expired with state_reason: "canceled_by_agent".

Expect the money-movement denials

Reads, payment creation and cancellation work with nothing further configured. Refunds, token changes, mandates and payouts do not:

Response 403

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

These are configuration states, not bugs in your integration. Payouts unlock when the merchant sets a per-asset spend limit on the credential. Refunds, token changes and mandate issuance need an authorization provider, which SouthPay support enables per store. See agent authorization for the full picture.

Getting started

Authentication

Core resources

Recurring

Checkout

Agentic commerce

Platform

Integrations

Building reliably

Changelog

Agentic quickstart

Next steps

MCP tool reference

Authorization model

​Next steps

MCP tool reference

Authorization model

Next steps