Quickstart

Make your first payment with the SwissPay API in under five minutes.

1. Get a test API key

• Sign in to your SwissPay account.
• Go to Developers → API keys.
• Click Create test key.
• Copy the key (it begins with sk_test_...). You'll only see the plaintext once — store it in your secrets manager.

2. Take a successful test payment

⚠️ Warning

success_url and failure_url are required whenever the connection has 3-D Secure enabled. Adyen connections ship with 3-D Secure enabled by default — in both test and live mode — and when 3DS is enabled on the connection these two URLs are required on every card payment — not only payments that opt into 3DS via authentication: "automatic". Both must be valid HTTPS URLs with no fragment (#…). Omitting them returns 422 invalid_params. The example below includes them so it works on the first try.

curl -X POST https://app.swisspay.ai/api/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 2999,
    "currency": "CHF",
    "reference": "order_1001",
    "success_url": "https://example.com/checkout/success",
    "failure_url": "https://example.com/checkout/failure",
    "payment_method": {
      "type": "card",
      "number": "4111111111111111",
      "exp_month": 3,
      "exp_year": 2030,
      "cvc": "737",
      "holder_name": "Jane Doe"
    }
  }'

A successful response looks like:

{
  "id": "pay_01HABCXYZ...",
  "status": "succeeded",
  "amount": 2999,
  "currency": "CHF",
  "reference": "order_1001",
  "payment_method": {
    "type": "card",
    "brand": "visa",
    "last4": "1111",
    "exp_month": 3,
    "exp_year": 2030
  },
  "created_at": "2026-05-20T12:00:00Z"
}

You just took your first SwissPay payment.

3. Try a declined card

Use the Refused test card to see what a failure looks like:

curl -X POST https://app.swisspay.ai/api/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 2999,
    "currency": "CHF",
    "reference": "order_decline",
    "payment_method": {
      "type": "card",
      "number": "4000300011112220",
      "exp_month": 3,
      "exp_year": 2030,
      "cvc": "737",
      "holder_name": "Jane Doe"
    }
  }'

Important: declined payments come back as HTTP 200, not 4xx. Check status and the failure object:

{
  "id": "pay_01HABCDEF...",
  "status": "failed",
  "failure": {
    "code": "refused",
    "reason": "Refused by issuer"
  },
  "amount": 2999,
  "currency": "CHF",
  "reference": "order_decline"
}

If your test framework asserts on HTTP code alone, declines will look like successes — see Errors.

4. Save a customer for next time

curl -X POST https://app.swisspay.ai/api/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe"
  }'

Response:

{
  "id": "cus_01HCUSXYZ...",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "created_at": "2026-05-20T12:01:00Z"
}

Reuse the customer on subsequent payments:

{
  "amount": 2999,
  "currency": "CHF",
  "reference": "order_1002",
  "customer": "cus_01HCUSXYZ...",
  "payment_method": { "type": "card", "number": "4111111111111111", "exp_month": 3, "exp_year": 2030, "cvc": "737", "holder_name": "Jane Doe" }
}

What's next

• Read Authentication before you commit anything to production.
• Read Idempotency before you write retry logic.
• Browse the full Payments and Customers references.
• If you want an AI agent to handle integration for you, see Using the API with AI agents (MCP).