Partner

Healthcheck GET

Returns simple answer {"status":"OK"}.

Endpoint

GET https://switchere.com/api/v3/partner/healthcheck

Response

{
  status: "OK"
}
NameTypeDescription
statusstringSystem status.

Currencies GET

Return data about partner currencies.

Endpoint

GET https://switchere.com/api/v3/partner/currency

Response

[
  {
    "code": "AAVE",
    "currency": "AAVE",
    "is_crypto": true,
    "name": "Aave",
    "network": "ETH",
    "network_full": "Ethereum (ERC20)",
    "token": "ERC20"
  },
  {
    "code": "AUD",
    "currency": "AUD",
    "is_crypto": false,
    "name": "Australian dollar"
  },
  {
    "code": "AXS",
    "currency": "AXS",
    "is_crypto": true,
    "name": "Axie Infinity",
    "network": "ETH",
    "network_full": "Ethereum (ERC20)",
    "token": "ERC20"
  },
  {
    "code": "BNBBSC",
    "currency": "BNB",
    "is_crypto": true,
    "name": "Binance Coin",
    "network": "BSC",
    "network_full": "Binance Smart Chain (BEP20)",
    "token": "BSC"
  },
  ...
]
NameTypeDescription
codestringCurrency code.
currencystringCurrency name.
is_cryptobooleanFiat or Crypto.
namestringCurrency full name.
networkstringNetwork code. Only for crypto.
network_full_namestringNetwork full name. Only for crypto.
tokenstringNetwork token code. Only for crypto.

Payment channels GET

Return data about partner available channels.

Endpoint

GET https://switchere.com/api/v3/partner/channel/{modeName}

Parameters

NameTypeDescription
modeName requiredmodePayment mode.

Tip: Field parameters info

Response

{
  "in": [
    {
      "channel": "astropay",
      "info": "AstroPay",
      "list": [
        {
          "code": "USD",
          "currency": "USD",
          "is_crypto": false,
          "name": "US Dollar"
        },
        ...
        {
          "code": "ZAR",
          "currency": "ZAR",
          "is_crypto": false,
          "name": "South African rand"
        }
      ],
      "title": "AstroPay"
    },
    {
      "channel": "card",
      "info": "USD, EUR",
      "list": [
        {
          "code": "EUR",
          "currency": "EUR",
          "is_crypto": false,
          "name": "Euro"
        },
        ...
        {
          "code": "ZAR",
          "currency": "ZAR",
          "is_crypto": false,
          "name": "South African rand"
        }
      ],
      "title": "Credit/Debit Card"
    },
    ...
  ],
  "out": [
    {
      "channel": "crypto",
      "info": "BTC, ETH, LTC and more",
      "list": [
        {
          "code": "BTC",
          "currency": "BTC",
          "is_crypto": true,
          "name": "Bitcoin",
          "network_full_name": "Bitcoin"
        },
        ...
        {
          "code": "YFI",
          "currency": "YFI",
          "is_crypto": true,
          "name": "Yearn Finance",
          "network": "ETH",
          "network_full_name": "Ethereum (ERC20)",
          "token": "ERC20"
        }
      ],
      "title": "Crypto"
    }
  ]
}
NameTypeDescription
channelchannelPayment channel.
infostringInfo about channel.
listarrayArray objects contain: code, currency, is_crypto and name for all currencies. And additional network, network_full_name and token for crypto.
titlestringTitle for channel.

Tip: Field parameters info

  • channel
  • code - currency code
  • currency - currency name
  • is_crypto - fiat or crypto
  • name - currency full name
  • network - network code
  • network_full_name - network full name
  • token - network token code

Request create POST

Create a request with a set of parameters.

Endpoint

POST https://switchere.com/api/v3/partner/create_request

Parameters

NameTypeDescription
partner_order_idstringUnique partner id for the order, up to 64 characters [A-Za-z0-9-_] - you should make it up yourself - it should be UNIQ. Required if it is required for your account.
mode or mode_defaultmodePayment mode. Must be available for your account.
channel or channel_defaultchannelPayment channel.
payin_amount or payin_amount_defaultstringPayin amount, a number greater than 0.
payin_currency or payin_currency_defaultcurrencyPayin currency.
payout_currency or payout_currency_defaultcurrencyPayout currency.
dst_address or dst_address_defaultstringWallet address for the payout currency, up to 256 characters, without leading or trailing spaces. Must be a valid address for payout_currency. You should use address from testnet with sandbox.
extra_id or extra_id_defaultstringExtra id for wallet address (memo or destination tag for cryptos like XRP etc), up to 256 characters, without leading or trailing spaces.
refund_dst_address or refund_dst_address_defaultstringRefund wallet address for the payin currency, up to 256 characters, without leading or trailing spaces. Only for swap. Must be a valid address for payin_currency. You should use address from testnet with sandbox.
refund_extra_id or refund_extra_id_defaultstringExtra id for refund wallet address (memo or destination tag for cryptos like XRP etc), up to 256 characters, without leading or trailing spaces. Only for swap.
client_ip requiredstringClient IP address, IPv4 or IPv6.
client_countrycountry codeClient country.
http_return_failedstringRedirect URL for failed order: http:// or https:// URL with a host and without spaces, up to 2048 characters.
http_return_successstringRedirect URL for successful order: http:// or https:// URL with a host and without spaces, up to 2048 characters.
is_skip_first_stepbooleanSkip first step.
is_skip_second_stepbooleanSkip "dst address" step.

Fixed and default values

Parameters such as mode, channel, payin_amount, payin_currency, payout_currency, dst_address, extra_id, refund_dst_address and refund_extra_id can be passed in two ways:

  • Without the _default suffix (e.g. payin_amount) — the value is fixed: the corresponding field is locked in the widget and the client cannot change it.
  • With the _default suffix (e.g. payin_amount_default) — the value is only prefilled: the client can change it in the widget.

If both variants are passed, the parameter without the _default suffix takes priority and the _default value is ignored (it is not validated either). For example, if both payin_currency and payin_currency_default are passed, payin_currency will be used.

An empty string or a string of spaces means the parameter is not passed.

Linked parameters

Some parameters only make sense together with another one:

  • channel, payin_currency and payout_currency require mode;
  • payin_amount requires payin_currency;
  • dst_address requires payout_currency;
  • extra_id requires dst_address;
  • refund_dst_address requires payin_currency;
  • refund_extra_id requires refund_dst_address.

A requirement goes up the chain: e.g. extra_id requires dst_address, payout_currency and mode.

  1. If a parameter is passed, every parameter it requires must be passed too, fixed or with the _default suffix. Otherwise the error is <required>_or_<required>_default: REQUIRED.
  2. If a parameter is fixed, every parameter it requires must be fixed too: the client could change a prefilled value, and the fixed one would no longer fit. Otherwise the error is <required>: REQUIRED.
PassedError
payout_currency without modemode: REQUIRED
payin_currency_default without modemode_or_mode_default: REQUIRED
mode_default + payout_currencymode: REQUIRED
mode + payout_currency_default + dst_addresspayout_currency: REQUIRED
mode + payout_currency + dst_address_default + extra_iddst_address: REQUIRED
extra_id_default onlydst_address_or_dst_address_default, payout_currency_or_payout_currency_default, mode_or_mode_default: REQUIRED
mode=swap + payin_currency_default + refund_dst_addresspayin_currency: REQUIRED
mode=swap + payin_currency + refund_extra_idrefund_dst_address: REQUIRED

Skipped steps. The client can't change the parameters of a skipped step, so there their _default values count as fixed:

  • is_skip_first_step is true: mode, channel, payin_amount, payin_currency and payout_currency;
  • is_skip_second_step is true (not for sell): dst_address, extra_id, refund_dst_address and refund_extra_id.

For example, with is_skip_first_step both mode_default + payout_currency and payin_amount + payin_currency_default are allowed.

Mode and currencies

Currencies, fixed or with the _default suffix, must fit the mode, fixed or with the _default suffix. Otherwise the error is BAD_VALUE for the currency:

Modepayin_currencypayout_currency
buyfiatcrypto
sellcryptofiat
swapcryptocrypto

The same currency on both sides is not allowed: BAD_VALUE for both.

The channel, fixed or with the _default suffix, must fit the mode too: crypto only for swap, payment channels (card etc.) only for buy and sell. Otherwise the error is BAD_VALUE for the channel.

Wallet parameters are allowed only in some modes (the mode is fixed or with the _default suffix). In other modes the error is NOT_ALLOWED, both for the fixed and the _default variant:

Modedst_address, extra_idrefund_dst_address, refund_extra_id
buyallowednot allowed
sellnot allowednot allowed
swapallowedallowed

A sell order pays out fiat and has no wallet step, so with sell is_skip_second_step is ignored.

Wallet addresses

If the mode is passed (fixed or with the _default suffix), wallet addresses are checked to be valid for their currency. Otherwise the error is BAD_VALUE for the address, fixed or with the _default suffix — the variant that was passed:

  • dst_address is checked for payout_currency (fixed or with the _default suffix), together with extra_id if it is passed;
  • refund_dst_address is checked for payin_currency (fixed or with the _default suffix), together with refund_extra_id if it is passed. Only for swap.

Wallet addresses and extra ids are not trimmed: leading or trailing spaces are an error (BAD_VALUE). An address is not checked if it, its currency or its extra id already has an error.

Skipping steps

  • is_skip_first_step is true: channel, payin_amount, payin_currency and payout_currency are required, fixed or with the _default suffix. mode is then required by the currencies (see linked parameters).
  • is_skip_second_step is true and the mode is not sell: dst_address is required, fixed or with the _default suffix. For swap refund_dst_address is required too.

Tip: Field parameters info

Response

{
  "request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}
NameTypeDescription
request_idstringCreated request's ID.

Errors

If the parameters are invalid, the request is not created and the response is HTTP 400. The error object contains errcode and an error code for every invalid parameter:

{
  "success": 0,
  "error": {
    "errcode": 400,
    "client_ip": "REQUIRED",
    "payout_currency": "BAD_VALUE"
  }
}
CodeDescription
REQUIRED<param>: REQUIRED — the parameter must be passed fixed (without the _default suffix): client_ip, partner_order_id if it is required for your account, or see linked parameters.
<param>_or_<param>_default: REQUIRED — the parameter must be passed, fixed or with the _default suffix: see linked parameters and skipping steps.
BAD_VALUEThe value has a wrong format, is too long, is out of range (e.g. payin_amount is not greater than 0) or is not in the list of allowed values; a currency or the channel doesn't fit the mode; the same currency on both sides; a wallet address is not valid for its currency; dst_address, extra_id, refund_dst_address or refund_extra_id has leading or trailing spaces.
NOT_ALLOWEDmode / mode_default is not available for your account; or the parameter can't be used with this mode: dst_address, extra_id with sell; refund_dst_address, refund_extra_id with buy and sell.
ALREADY_EXISTSpartner_order_id has already been used for your account.

If the request body is not a valid JSON object, the response is HTTP 400 with "error": {"error": "Invalid JSON."}.

Order list GET

Return all patner orders info.

Endpoint

GET https://switchere.com/api/v3/partner/order/list

Parameters

NameTypeDescription
pageintegerPage number.
rowsintegerAmount of rows returned per page.
timestampunix_timestamp_stringSelect orders created only from a ceratin timestamp.

Response

{
  "rows": 50,
  "total": 110,
  "data": [
    {
      "created_at": "1763194869.324230",
      "partner_order_id": "9c077655-xxxx-xxxx-xxxx-a7ff776856f4",
      "status": "expired"
    }
  ...
  ]
}
NameTypeDescription
rowsintegerAmount of rows returned per page.
totaltintegerOverall amount of rows.
dataarrayArray objects contain: created_at, status and partner_order_id.

TIP

  • created_at - timestamp
  • status - order status
  • partner_order_id - external order id

Order data GET

Returns the data of a specific patner order.

Endpoint

GET https://switchere.com/api/v3/partner/order/{partner_order_id}

Parameters

NameTypeDescription
partner_order_id requiredstringUnique partner order id.

Response

{
  "channel": "card",
  "client_country": "US",
  "client_email": "[email protected]",
  "client_nice_id": "XXXXXXXX",
  "client_order_id": "XXXXX-XXXXXX",
  "country_by_ip": "US",
  "created_at": "1786309195.365966",
  "dst_address": "3MMn....vpJE",
  "expected_payin_amount": "150.000000000000000000",
  "expected_payout_amount": "0.002118740000000000",
  "finished_at": "1786309859.000000",
  "mode": "buy",
  "partner_order_id": "01ff1f6a-xxxx-xxxx-xxxx-1c8e18eeb7ea",
  "payin_amount": "150.000000000000000000",
  "payin_currency": "USD",
  "payout_amount": "0.002107260000000000",
  "payout_currency": "BTC",
  "payout_txid": "1340....bccb",
  "status": "finished",
  "status_log": [
    {
      "at": "1786309195.000000",
      "status": "payin_pending"
    },
    {
      "at": "1786309859.000000",
      "status": "finished"
    }
  ]
}
NameTypeDescription
modemodePayment mode.
channelchannelPayment channel.
client_emailstringClient email.
client_nice_idstringUnique client id.
partner_order_idstringUnique partner order id.
client_order_idstringUnique client order id.
payin_amountfloatPayin amount.
expected_payin_amountfloatExpected payin amount.
payout_amountfloatPayout amount.
expected_payout_amountfloatExpected payout amount.
payin_currencycurrencyPayin currency.
payout_currencycurrencyPayout currency.
payout_txidstringTXID of payout transaction.
statusorderStatusCurrent status of order.
dst_addressstringWallet address where Switchere will send cryptocurrency.
dst_taginteger[0..4294967295]Tag for XRP address.
memo_idstringMEMO_ID for EOS address.
memo_typestringMEMO_TYPE for XLM address.
memo_valuestringMEMO_VALUE for XLM address.
client_countrycountry codeClient registration country.
country_by_ipcountry codeClient last login country by IP.
created_atunix_timestamp_stringTimestamp when order was created.
finished_atunix_timestamp_stringTimestamp when order was finished.
status_logorder status logOrder status log.

Tip: Field parameters info

Fee POST

Return data about partner fee.

Endpoint

POST https://switchere.com/api/v3/partner/fee

Parameters

NameTypeDescription
mode requiredmodePayment mode.
channel requiredchannelPayment channel.
payin_currency requiredcurrencyPayin currency.
payout_currency requiredcurrencyPayout currency.
payin_amount requiredfloatPayin amount.

Tip: Field parameters info

Response

{
  "network_fee": "string",
  "payin_amount": "string",
  "payin_max_amount": "string",
  "payin_min_amount": "string",
  "payout_amount": "string",
  "rate": "string",
  "service_fee": "string",
}
NameTypeDescription
payin_amountstringPayin amount.
payin_min_amountstringPayin minimal amount.
payin_max_amountstringPayin maximal amount.
payout_amountstringPayout amount.
ratestringRate payin_currency/payout_currency.
network_feestringNetwork fee in payout currency.
service_feestringService fee in payin currency.

Fee buy POST

Return data about partner fee for buy crypto.

Endpoint

POST https://switchere.com/api/v3/partner/fee/buy

Parameters

NameTypeDescription
payin_currency requiredcurrencyPayin currency. Required only fiat.
payin_amount requiredfloatPayin amount.
payout_currency requiredcurrencyPayout currency. Required only crypto.

Tip: Field parameters info

Response

{
  "...": {
    "network_fee": "string",
    "payin_amount": "string",
    "payin_max_amount": "string",
    "payin_min_amount": "string",
    "payout_amount": "string",
    "rate": "string",
    "service_fee": "string",
  }
}
NameTypeDescription
...dict of dictsPayin channel -> { Fee data for this Payin channel } .

Fee sell POST

Return data about partner fee for sell crypto.

Endpoint

POST https://switchere.com/api/v3/partner/fee/sell

Parameters

NameTypeDescription
payin_currency requiredcurrencyPayin currency. Required only crypto.
payin_amount requiredfloatPayin amount.
payout_currency requiredcurrencyPayout currency. Required only fiat.

Tip: Field parameters info

Response

{
  "...": {
    "network_fee": "string",
    "payin_amount": "string",
    "payin_max_amount": "string",
    "payin_min_amount": "string",
    "payout_amount": "string",
    "rate": "string",
    "service_fee": "string",
  }
}
NameTypeDescription
...dict of dictsPayout channel -> { Fee data for this Payout channel } .

Fee swap POST

Return data about partner fee for swap crypto.

Endpoint

POST https://switchere.com/api/v3/partner/fee/swap

Parameters

NameTypeDescription
payin_currency requiredcurrencyPayin currency. Required only crypto.
payin_amount requiredfloatPayin amount.
payout_currency requiredcurrencyPayout currency. Required only crypto.

Tip: Field parameters info

Response

{
  "...": {
    "network_fee": "string",
    "payin_amount": "string",
    "payin_max_amount": "string",
    "payin_min_amount": "string",
    "payout_amount": "string",
    "rate": "string",
    "service_fee": "string",
  }
}
NameTypeDescription
...dict of dictsCrypto channel -> { Fee data for this Crypto channel } .
Last Updated: