BjornTech Swish Platform API

Append every documented route directly to the production base URL. Requests and responses use JSON unless otherwise noted.

Before onboarding, the merchant needs a Swish Handel number from their bank with BjornTech AB (id 9872884581) as technical provider. See Get started for bank-by-bank instructions.

Onboarding links a merchant account to the integration and returns the credentials required for signed API requests.

Start onboarding

Confirm and exchange

GET /v1/onboarding/confirm?token=... returns the browser to the stored URL with swish_onboarding_code and state. Validate state server-side, exchange the transient code immediately, and clean it from the URL.

POST /v1/onboarding/exchange
Content-Type: application/json

{ "code": "ex-opaque" }

Store the returned base64 HMAC secret and access key securely on the server. Codes are single-use and expire after 15 minutes by default. Unknown, expired and used codes return 404, 410 and 409 respectively.

Sign every payment, refund, status and cancellation request with HMAC-SHA256. Build exactly seven fields, separated by LF newlines, with no trailing newline.

METHOD
PATH
QUERY
ACCESS_KEY_ID
TIMESTAMP
NONCE
BODY_SHA256_HEX

Use the uppercase method, exact transmitted pathname and encoded query substring, and the lowercase SHA-256 digest of the exact UTF-8 body. Hash the empty string for a bodyless request.

Create a payment

{
  "payeePaymentReference": "ORDER-10001",
  "callbackUrl": "https://merchant.example/swish/callback",
  "payerAlias": "46712345678",
  "payeeAlias": "1233801768",
  "amount": "100.00",
  "currency": "SEK",
  "message": "Order 10001"
}

Payment statuses

Cancel a payment

Send Content-Type: application/json-patch+json and the exact patch below. A payment can only be cancelled before reaching a final state.

[
  { "op": "replace", "path": "/status", "value": "cancelled" }
]

Create a refund

{
  "originalPaymentReference": "652ED6A2BCDE4BA8AD11D7334E9567B7",
  "callbackUrl": "https://merchant.example/swish/refund-callback",
  "payerAlias": "1233801768",
  "amount": "100.00",
  "currency": "SEK",
  "payerPaymentReference": "REFUND-10001",
  "message": "Refund for order 10001"
}

A successful response means Swish accepted the refund for processing. The body may be empty. Retrieve the refund for authoritative status.

Refund statuses

Callbacks are enabled only when an individual request includes callbackUrl. Polling-only is supported by omitting it.

On 429 Too Many Requests, read Retry-After, pause the affected source IP for at least that duration, then continue with bounded backoff and jitter. Do not assume the response body is JSON.

Application errors are generally JSON, but upstream and rate-limit responses may be JSON, non-JSON or empty. Use HTTP status as the primary signal and parse bodies defensively.