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.

Client certificate

The key alone is not enough. The integration surface also requires a client certificate that we issue: our edge asks for it during the TLS handshake and refuses the request before it reaches the API when it is missing, not ours, or revoked. Two independent things are needed to call the API, and either can be revoked on its own.

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

A request without a valid certificate is answered with 403 by the edge, as an HTML page rather than the JSON envelope above — it never reaches the API, so there is nothing to report in our format.

Certificates are per environment, and you issue them yourself on the Certificate tab of the console: one for the Sandbox (api.sulpayments.dev) and one for production (api.sulpayments.ch), one live certificate in each. You download the certificate and its private key once, at issuance; we never store the key, so if you lose it, revoke that certificate and issue another.

The certificate is yours in the strict sense: it is bound to your account, and a request signed with your API key is refused if it presents anybody else’s.

The console endpoints your browser uses — signing in, your profile, managing keys — carry no certificate: they are a session, not an integration.

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.