List rails

GET

/v1/rails

const url = 'https://api.sulpayments.ch/v1/rails';
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/rails \
  --header 'Authorization: Bearer <token>'

Returns the authenticated merchant's active rails: the asset pair, the reference to pay into (inbound_reference), where the funds land and the merchant's fee terms. Chained rails resolve to the final destination; the intermediate legs are internal routing and are not exposed. Commercial internals (spread, institutional price) are never part of this payload.

Authorizations

api_key

Responses

200

The merchant's active rails

application/json

object

rails

required

Array<object>

One rail as the owning merchant sees it: the asset pair, the reference to pay into, where the funds land, and the merchant's own fee terms. The spread lives inside the conversion rate by design and is NEVER a field here — same masking contract as [MerchantSettlement].

object

destination_reference

Where the funds ultimately land. For chained rails this is the FINAL leg's external destination — the intermediate hops are internal routing the merchant does not see.

string | null

fee_fixed

required

string

fee_percentage

required

string

fixed_side

required

string

inbound_reference

The account/wallet the merchant pays into for this rail (a vIBAN for fiat, a wallet address for crypto).

string | null

incoming_kind

required

string

incoming_network

string | null

incoming_symbol

required

string

outgoing_kind

required

string

outgoing_network

string | null

outgoing_symbol

required

string

rail_id

required

string format: uuid

Example

{
  "rails": [
    {
      "fee_fixed": "0.5",
      "fee_percentage": "0.01"
    }
  ]
}

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."
  }
}