API terms used across this documentation.
| Term | Definition |
|---|---|
| API key | A bearer credential issued from the dashboard and sent in the Authorization header on every request. sk_test_... keys run in test mode; sk_live_... keys run in live mode. |
| ARN | Acquirer Reference Number — a globally unique identifier for a card transaction, returned by some processors. |
| Authorisation | The issuing bank's reservation of funds against a card. Precedes capture. |
| AVS | Address Verification Service — issuer-side check of the billing address. |
| Bearer token | The authentication scheme SwissPay uses (Authorization: Bearer sk_test_...). |
| Capture | The movement of authorised funds into the processor's balance. SwissPay payments auto-capture on authorisation. |
| CNP | Card Not Present — an e-commerce transaction without a physical card swipe. |
| CVV / CVC | The three- or four-digit security code on a card. Never returned by the API. |
| HTTP 200 with status "failed" | How SwissPay reports a declined card. The HTTP request succeeded; the issuer declined. Always check status, not just HTTP code. |
| Idempotency-Key | A header you set on POST /api/v1/payments to make retries safe. See Idempotency. |
| ISO 4217 | The currency code standard (CHF, EUR, USD, etc.). |
| ISO 3166-1 alpha-2 | The country code standard (CH, DE, US, etc.). |
| Issuer | The bank that issued the cardholder's card. |
| last4 | The last four digits of the card number. The only part of the PAN the API ever returns. |
| MCP | Model Context Protocol — the open protocol that lets AI agents call APIs as tools. See Using the API with AI agents. |
| Minor units | Amounts are expressed in the smallest unit of the currency. CHF 29.99 = 2999. |
| OpenAPI | The machine-readable description of the SwissPay API. See OpenAPI specification. |
| PAN | Primary Account Number — the long card number. Never returned by the API. |
| Reference | Your own identifier for a payment, set in the reference field. Free text, opaque to SwissPay. |
| Scheme | A card network — Visa, Mastercard, AMEX, Diners, Discover, JCB. |
| Soft descriptor | The text that appears on your customer's card statement. |
| Stored payment method | A token that represents a previously seen card, usable on subsequent payments without resubmitting card details. |
| 3-D Secure (3DS) | The cardholder-authentication challenge step required by some issuers. Opted into via authentication: "automatic". |
| Webhook | A signed server-to-server notification SwissPay sends when a payment or refund changes state. |
| Dispute | A chargeback or related challenge raised against a payment. See Disputes. |
| Processor | The acquirer/PSP that actually moves funds. See Payment processors. |
| Rolling reserve | A configurable share of settled volume held back for a defined holding period to cover dispute exposure. Configured per merchant. |
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article