Payments

Create, retrieve, and list payments.

POST /api/v1/payments is synchronous and auto-captured — when the response comes back, the funds are already on their way (or the card has been refused). Idempotency-Key is required.

The Payment object

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

Create a payment

POST /api/v1/payments

Required headers

Authorization: Bearer sk_test_...
Content-Type: application/json
Idempotency-Key: <unique-per-attempt>

Required body fields

payment_method (card)

Optional body fields

Example — successful Visa

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",
    "payment_method": {
      "type": "card",
      "number": "4111111111111111",
      "exp_month": 3,
      "exp_year": 2030,
      "cvc": "737",
      "holder_name": "Jane Doe"
    }
  }'

Example — with an inline customer

The customer is created if it doesn't already exist (matched by email within your account) and attached to the payment.

{
  "amount": 2999,
  "currency": "CHF",
  "reference": "order_1003",
  "customer": {
    "email": "new@example.com",
    "name": "New Customer",
    "external_id": "user_99"
  },
  "payment_method": { /* card */ }
}

Example — with fraud signals

{
  "amount": 2999,
  "currency": "CHF",
  "reference": "order_risk_1004",
  "shopper_ip": "203.0.113.42",
  "browser_info": {
    "user_agent": "Mozilla/5.0 (Macintosh) AppleWebKit/605",
    "accept_header": "text/html,application/xhtml+xml"
  },
  "risk_data": {
    "basket": { "value": 2999, "items_count": 2 },
    "customer_tenure_days": 184,
    "promo_code": "WELCOME"
  },
  "payment_method": { /* card */ }
}

These fields are forwarded to our upstream risk engine but not echoed back on the response. Confirm acceptance by checking HTTP 201 and status: "succeeded".

Example — 3-D Secure (automatic)

{
  "amount": 8999,
  "currency": "EUR",
  "reference": "order_3ds_visa",
  "authentication": "automatic",
  "success_url": "https://merchant.example/checkout/return",
  "failure_url": "https://merchant.example/checkout/return",
  "payment_method": {
    "type": "card",
    "number": "4871049999999910",
    "exp_month": 3,
    "exp_year": 2030,
    "cvc": "737",
    "holder_name": "Jane Doe"
  }
}

Two possible outcomes:

1. Frictionless. HTTP 201, status: "succeeded", identical to a normal sale.

2. Challenge required. HTTP 200, status: "requires_action", plus:

   "next_action": {
     "type": "redirect_to_url",
     "redirect_url": "https://app.swisspay.ai/checkout/3ds/3ds_..."
   }
   

   Redirect the customer to next_action.redirect_url. After they complete (or abandon) the challenge, we redirect them to success_url or failure_url with ?payment_id=pay_... appended.

The source of truth for the final state is GET /api/v1/payments/:id.

Collecting 3DS browser info

A 3-D Secure browser challenge needs more from the shopper's browser than the request headers alone can supply (screen size, language, color depth, time zone, etc.). The easiest way to collect those signals -- without writing the snippet yourself -- is to embed our hosted helper on your checkout page and pass the resulting browser_info_token to your server. See Browser info & 3-D Secure for the full integration.

Hosting checkout on your own domain

If you render the card form (and the 3DS challenge) on your own domain rather than redirecting to SwissPay-hosted checkout, pass that page's origin in origin so the 3DS2 request matches the shopper's browser origin:

{
  "amount": 8999,
  "currency": "EUR",
  "authentication": "automatic",
  "origin": "https://shop.example.com",
  "success_url": "https://shop.example.com/checkout/return",
  "failure_url": "https://shop.example.com/checkout/return",
  "payment_method": { "type": "card", "...": "..." }
}

Omit origin when you redirect shoppers to SwissPay-hosted checkout -- we will use our own origin.

Validation rules for return URLs

• success_url and failure_url are required on every card payment whenever the merchant's connection has 3-D Secure enabled — including the frictionless happy path and payments that never set authentication: "automatic". Adyen connections ship with 3DS enabled in both test and live mode, so treat these URLs as required unless you have explicitly disabled 3DS on the connection.
• Both must be HTTPS. No URL fragment (#...) allowed.
• payment_method.holder_name is required on every card payment.

Configuring 3DS

3DS is enabled per processor connection from Settings → Connected providers in the dashboard.

Retrieve a payment

GET /api/v1/payments/{id}

Returns the same Payment object as POST /payments.

curl https://app.swisspay.ai/api/v1/payments/pay_01HABCXYZ \
  -H "Authorization: Bearer sk_test_..."

Unknown IDs — including IDs that belong to another merchant — return 404 Not Found with no body.

List payments

GET /api/v1/payments?page=1&per_page=20

Example — payments for one customer

curl 'https://app.swisspay.ai/api/v1/payments?customer=cus_01HCUSXYZ' \
  -H "Authorization: Bearer sk_test_..."

Response:

{
  "data": [ /* payment objects */ ],
  "page": 1,
  "per_page": 20,
  "total_count": 156,
  "has_more": true
}

See also

• Idempotency — pick the right Idempotency-Key.
• Errors — every error code we return.
• Test cards — test-mode card numbers.