> For the complete documentation index, see [llms.txt](https://support.swisspay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.swisspay.ai/api-reference/quickstart.md).

# 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

{% hint style="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.
{% endhint %}

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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](/api-reference/errors.md#decline-handling).

## 4. Save a customer for next time

```bash
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:

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

Reuse the customer on subsequent payments:

```json
{
  "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](/api-reference/authentication.md) before you commit anything to production.
* Read [Idempotency](/api-reference/idempotency.md) before you write retry logic.
* Browse the full [Payments](/api-reference/payments.md) and [Customers](/api-reference/customers.md) references.
* If you want an AI agent to handle integration for you, see [Using the API with AI agents (MCP)](/api-reference/using-with-ai-agents.md).