API reference

The merchant API is https://api.settlane.com. Every route is under /v1, and the explorer below lists each one with its parameters, its request and response, and an example of both.

Download the OpenAPI file (OpenAPI 3.1, JSON). Feed it to a client generator such as openapi-generator or openapi-typescript to get typed calls in your own language. It also describes every webhook Settlane sends, under webhooks. It is generated from the API's own code, so it changes only when the API does.

Authentication

Authorization: Bearer sk_live_…

A sk_test_ key sees only test-mode objects and creates only test-mode objects; a sk_live_ key the reverse. There is no way to cross that line with one key, and a route that changes live configuration refuses a test key outright with LIVE_MODE_REQUIRED. A test key cannot create an invoice or a payout today: see the quickstart.

Scopes are per key: invoices:read, invoices:write, payouts:read, payouts:write, payouts:approve, customers:read, customers:write, screenings:write, events:read, wallets:read, webhooks:read, webhooks:write. A key missing the scope a route needs is refused FORBIDDEN, and the message names the scope. payouts:approve is never implied by payouts:write, and it does nothing until approval through the API is switched on for your account. See payouts.

Conventions

• Money is integers, and comes back as strings. amount_cents is US cents. Token amounts are in base units. Both are decimal strings on responses because a token amount does not fit a JavaScript number, so parse them with BigInt.
• Ids are <prefix>_<26 characters>, time-sortable. inv_, po_, cus_, evt_, we_.
• Timestamps are ISO-8601 strings in UTC.
• Lists are a page: { "data": [...], "has_more": bool }, newest first, with limit and starting_after.
• Retries are safe when you make them safe. POST /v1/invoices, POST /v1/webhook_endpoints and POST /v1/webhook_endpoints/{id}/test require an Idempotency-Key header. POST /v1/payouts is idempotent on the reference you supply, and POST /v1/customers on the external_id. A key or a reference is remembered for 24 hours per mode: the same value under a sk_test_ key and a sk_live_ key is two separate requests.
• Every response carries Settlane-Request-Id. Quote it when you ask for help.
• Errors are { "error": { "code", "message", "param"? } }. See the errors reference.

Explorer

The explorer is read-only: it shows each call and does not send one. Use curl or your own code with your key to make a call.