# 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 on the sandbox.** Sandbox Adyen connections have 3-D Secure enabled by default, 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://staging.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://staging.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://staging.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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.swisspay.ai/api-reference/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.