Authentication

Requests to the Sulpayments API are authenticated with an API key. Keys are provisioned in the merchant console; each key belongs to your merchant account and can be revoked at any time.

Sending a key

Send the key as a Bearer token in the Authorization header:

curl https://api.sulpayments.ch/v1/settlements \
  -H "Authorization: Bearer sk_your_api_key"

The key looks like sk_ followed by a hexadecimal string. A request with a missing, malformed, revoked, or unknown key is rejected with 401 and the standard error body {"error":{"code":"invalid_credentials","message":"Invalid credentials."}} — nothing distinguishes the failure reasons.

Every error response uses the same envelope: error.code is a machine-stable identifier that never changes across languages, and error.message is a human-readable text localized from the request’s Accept-Language header (English by default; pt-BR, es and de are supported). Validation failures add an error.fields array, each entry naming the offending field and its own code. Match on error.code, not on the message text.

Every request is automatically scoped to the merchant that owns the key: you can only ever read your own data.

Managing keys

• Create and revoke keys in the merchant console. The secret is shown once, at creation; store it securely and never commit it.
• Revocation is immediate.
• Treat a key as a secret. If one leaks, revoke it and create a new one.

What you can call

The authenticated surface today:

• GET /v1/settlements — your completed settlements, with the same figures the settlement notifications carry (amounts, the quoted rate, your fees). Internal pricing is never exposed.
• GET / PUT /v1/webhook — read and configure your settlement-notification endpoint and its signing secret (see settlement notifications).

See the API reference for the full contract.