SouthPay for n8n

The SouthPay node for n8n creates and reads payments, manages billing, triggers payouts, and starts workflows from payment events. You connect once with OAuth, and the trigger node registers its own webhook endpoint rather than making you copy a URL and a secret. The package is published on npm as n8n-nodes-southpay. It is a community node, versioned and released independently of the API, so treat the operation list below as indicative and the node’s own release notes as authoritative for a given version.

​

Install the node

Install it from the GUI like any other n8n community node. On n8n Cloud, once the node is verified it appears in the nodes panel with no install step.

​

Connect your account

The node authenticates with OAuth 2.0, authorization code plus PKCE. SouthPay requires PKCE with S256 on every authorization request, so a client that cannot do PKCE cannot connect at all. Click Connect my account and approve the consent screen. The resulting access token is bound to one store and one mode, so you never pass a store id and never set a mode header. The grant carries both. Live mode works: the mode is chosen when you authorize, not fixed to test. An access token issued alongside a refresh token lives for 1 hour, so the credential relies on the refresh token to stay connected; a connection that stops working after an hour is a refresh problem, not a scope problem. You can revoke the connection from either side: n8n’s credential screen, or the connected apps list in the SouthPay dashboard. If you would rather use your own OAuth client than the first-party one, register an OAuth app and set its client id on the n8n credential.

​

React to payment events

Add a SouthPay Trigger node and pick the events you want. Activating the workflow registers a webhook endpoint on your store, stores the signing secret, and verifies the Southpay-Signature header on every delivery. Deactivating removes the endpoint. These payment events are emitted and can be subscribed to:

• payment_intent.created
• payment_intent.processing
• payment_intent.completed
• payment_intent.expired
• payment_intent.failed
• payment_intent.refunded

Deliveries are not deduplicated for you. The envelope’s top-level id stays the same across every retry of one delivery, so deduplicate on it if a repeated run would double-charge, double-ship or double-notify. Payout events are not available. payout.created, payout.confirmed and payout.failed pass subscription validation but no code path emits them, so a workflow waiting on one waits forever. Poll the payout instead. See webhooks for the full envelope, the signature scheme and the retry schedule.

​

Wait for a payment

The Wait for a Payment operation polls until the payment reaches a terminal status or the timeout elapses, so a single node can block a workflow until the customer pays. The terminal statuses are completed, expired, failed and refunded. There is no overpaid status. An overpayment arrives as completed with state_reason: "completed_overpaid", so a check for status === "completed" catches it. Read state_reason if you need to treat it differently. Intents expire 60 minutes after creation by default, so a timeout longer than an hour buys you nothing unless the intent was created with a longer expires_in. For production, prefer the trigger over polling.

​

Operations

​

When an operation fails

Every operation is limited by the scopes granted at consent. A call outside them returns 403 insufficient_scope, and the fix is to reconnect the credential with the scope included, since n8n cannot widen a token in place. Two other refusals catch people out:

• Fiat payouts need a verified store. 403 until KYC is confirmed on the store, and only USDT and USDC are eligible for the fiat rail.
• Payouts and refunds require an Idempotency-Key. The node sends one; if you are calling the API directly alongside the node, omitting it returns 422.

SouthPay does not use one error shape. Most endpoints return {"error": "<string>"}, some return {"error": {"message": "...", "code": "..."}}, and validation failures return {"errors": ["...", "..."]}. If you parse an error message inside a Function node, handle all three. See errors.

​

Self-hosting n8n

The connection works out of the box on a public domain, because the redirect must be reachable by the browser completing the consent flow. On a private or localhost instance, expose n8n on a public URL first, or register your own OAuth app with a redirect URI your instance can actually serve.