List settlements

GET

/v1/settlements

const url = 'https://api.sulpayments.ch/v1/settlements';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.sulpayments.ch/v1/settlements \
  --header 'Authorization: Bearer <token>'

Returns the authenticated merchant's completed settlements, newest first. The payload is the same merchant-visible slice as the settlement-completed webhook: it never includes internal pricing, spread revenue or partner commission.

Authorizations

api_key

Parameters

Query Parameters

limit

integer format: int64

Page size (1-200, default 50)

offset

integer format: int64

Rows to skip (0-10000, default 0)

Responses

200

A page of the merchant's settlements

application/json

object

limit

required

integer format: int64

offset

required

integer format: int64

settlements

required

Array<object>

One completed settlement, as the owning merchant sees it. Mirrors the settlement-completed webhook payload exactly — no internal figures.

object

completed_at

string | null format: date-time

conversion_rate

required

string

destination_reference

required

string

fee_fixed

required

string

fee_percentage

required

string

fee_percentage_amount

string | null

fixed_side

required

string

incoming_amount

required

string

incoming_currency

required

string

occurred_at

required

string format: date-time

outgoing_amount

string | null

outgoing_currency

required

string

payin_reference

required

string

payout_reference

string | null

settlement_id

required

string format: uuid

total

required

integer format: int64

Example

{
  "settlements": [
    {
      "conversion_rate": "1.1232",
      "fee_fixed": "0.5",
      "fee_percentage": "0.01",
      "fee_percentage_amount": "0.961538",
      "incoming_amount": "108",
      "outgoing_amount": "94.692307692307692308"
    }
  ]
}

401

Missing or invalid API key

application/json

The error envelope every 4xx/5xx response uses. The error.code is machine-stable across locales; error.message is localized via the request's Accept-Language (en by default). error.fields is present only for per-field validation failures.

object

error

required

The body of an [ErrorEnvelope].

object

code

required

Machine-stable error code (stable across locales).

string

Allowed values: invalid_credentials unauthenticated origin_not_allowed challenge_failed locked invalid_link invalid_code otp_enforced no_merchant no_partner not_found invalid_body internal_error provider_unavailable provider_call_failed quote_refused conversion_refused payout_refused payout_wallet_out_of_gas unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed forbidden issuance_not_enabled merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited end_user_reference_exists currency_not_enabled currency_not_supported required invalid_url unsafe_url unresolvable_host

fields

Per-field validation errors, present only for validation_failed.

Array<object> | null

One field-level validation failure inside [ApiError::fields].

object

code

required

The machine-stable reason code for this field.

string

field

required

The request field the error applies to (e.g. webhook_url).

string

message

required

Human-readable message, localized by Accept-Language.

string

Example

{
  "error": {
    "code": "invalid_credentials",
    "fields": [
      {
        "code": "invalid_credentials"
      }
    ],
    "message": "One or more fields are invalid."
  }
}