Overview

The SwissPay API lets you create payments and manage customers from your own application or scripts.

Base URL

There is a single base URL. Test mode and live mode are selected by the API key you send, not by the host:

• sk_test_... keys run in test mode — use the test cards; no money moves.
• sk_live_... keys run in live mode — real cards, real settlement.

See Authentication for how keys map to modes.

What's available

Read the docs in order

1. Quickstart â your first payment in under five minutes.
2. Authentication â how to issue and use API keys.
3. Idempotency â safe retries.
4. Errors â every error code we return and what to do.
5. Test cards â test-mode card numbers for the common authorisation outcomes.
6. Payments â the full endpoint reference.
7. Customers â the full endpoint reference.
8. Refunds â refund a payment in full or in part.

Machine-readable spec

We publish an OpenAPI 3.1 specification covering every endpoint here.

• OpenAPI specification
• Using the API with AI agents (MCP)

Conventions

• HTTPS only. TLS 1.2 or higher.
• JSON in and out. Content-Type: application/json on every request body; responses are JSON.
• UTC timestamps in ISO 8601 (2026-05-20T13:00:00Z).
• Amounts in minor units. A CHF 29.99 payment is "amount": 2999, "currency": "CHF".
• Stable IDs. Object IDs are prefixed (pay_..., cus_...) and stable.
• Pagination uses ?page= and ?per_page= (max 100).

Conventions we really care about

These trip up most new integrations:

• Declined cards return HTTP 200. Look at status: "failed" and the failure object â not just the HTTP code.
• payment_method.holder_name is required on every card payment, not only when 3-D Secure is enabled.
• Unknown IDs return 404 â and so do IDs belonging to a different merchant.
• Idempotency-Key is required on POST /payments and strongly recommended on POST /customers.