Skip to content
Sulpayments

List rails

GET
/v1/rails
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

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The merchant’s active rails

Media typeapplication/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

Section titled “401”

Missing or invalid API key

Media typeapplication/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 whitelist_not_permitted unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered inbound_shared_by_corridors payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured client_certificate_exists client_certificate_required client_certificate_unknown client_certificate_mismatch allowed_ips_empty address_not_allowed allowed_ip_malformed allowed_ip_whole_internet allowed_ip_unroutable allowed_ip_duplicate access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed corridor_inbound_held forbidden issuance_not_enabled account_opening_merchant_only account_opening_partner_only merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited provider_account_limit_reached end_user_reference_exists account_activating currency_not_enabled currency_not_supported operations_not_shared 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
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 whitelist_not_permitted unexpected_failure provider_still_processing database_grant_missing rail_inactive fx_accounts_missing sender_not_registered inbound_shared_by_corridors payout_outcome_unknown conversion_outcome_unknown validation_failed webhook_endpoint_not_configured client_certificate_exists client_certificate_required client_certificate_unknown client_certificate_mismatch allowed_ips_empty address_not_allowed allowed_ip_malformed allowed_ip_whole_internet allowed_ip_unroutable allowed_ip_duplicate access_token_missing access_token_malformed access_token_invalid access_verification_unavailable conflict admin_validation_failed corridor_inbound_held forbidden issuance_not_enabled account_opening_merchant_only account_opening_partner_only merchant_identity_incomplete issuance_quota_exceeded issuance_rate_limited provider_account_limit_reached end_user_reference_exists account_activating currency_not_enabled currency_not_supported operations_not_shared required invalid_url unsafe_url unresolvable_host
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."
  }
}