Partner
Healthcheck GET
Returns simple answer {"status":"OK"}.
Endpoint
GET https://switchere.com/api/v3/partner/healthcheck
Response
{
status: "OK"
}
| Name | Type | Description |
|---|---|---|
| status | string | System 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"
},
...
]
| Name | Type | Description |
|---|---|---|
| code | string | Currency code. |
| currency | string | Currency name. |
| is_crypto | boolean | Fiat or Crypto. |
| name | string | Currency full name. |
| network | string | Network code. Only for crypto. |
| network_full_name | string | Network full name. Only for crypto. |
| token | string | Network 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
| Name | Type | Description |
|---|---|---|
| modeName required | mode | Payment 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"
}
]
}
| Name | Type | Description |
|---|---|---|
| channel | channel | Payment channel. |
| info | string | Info about channel. |
| list | array | Array objects contain: code, currency, is_crypto and name for all currencies. And additional network, network_full_name and token for crypto. |
| title | string | Title for channel. |
Tip: Field parameters info
- channel
code- currency codecurrency- currency nameis_crypto- fiat or cryptoname- currency full namenetwork- network codenetwork_full_name- network full nametoken- 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
| Name | Type | Description |
|---|---|---|
| partner_order_id | string | Unique 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_default | mode | Payment mode. Must be available for your account. |
| channel or channel_default | channel | Payment channel. |
| payin_amount or payin_amount_default | string | Payin amount, a number greater than 0. |
| payin_currency or payin_currency_default | currency | Payin currency. |
| payout_currency or payout_currency_default | currency | Payout currency. |
| dst_address or dst_address_default | string | Wallet 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_default | string | Extra 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_default | string | Refund 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_default | string | Extra 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 required | string | Client IP address, IPv4 or IPv6. |
| client_country | country code | Client country. |
| http_return_failed | string | Redirect URL for failed order: http:// or https:// URL with a host and without spaces, up to 2048 characters. |
| http_return_success | string | Redirect URL for successful order: http:// or https:// URL with a host and without spaces, up to 2048 characters. |
| is_skip_first_step | boolean | Skip first step. |
| is_skip_second_step | boolean | Skip "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
_defaultsuffix (e.g.payin_amount) — the value is fixed: the corresponding field is locked in the widget and the client cannot change it. - With the
_defaultsuffix (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_currencyandpayout_currencyrequiremode;payin_amountrequirespayin_currency;dst_addressrequirespayout_currency;extra_idrequiresdst_address;refund_dst_addressrequirespayin_currency;refund_extra_idrequiresrefund_dst_address.
A requirement goes up the chain: e.g. extra_id requires dst_address, payout_currency and mode.
- If a parameter is passed, every parameter it requires must be passed too, fixed or with the
_defaultsuffix. Otherwise the error is<required>_or_<required>_default: REQUIRED. - 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.
| Passed | Error |
|---|---|
payout_currency without mode | mode: REQUIRED |
payin_currency_default without mode | mode_or_mode_default: REQUIRED |
mode_default + payout_currency | mode: REQUIRED |
mode + payout_currency_default + dst_address | payout_currency: REQUIRED |
mode + payout_currency + dst_address_default + extra_id | dst_address: REQUIRED |
extra_id_default only | dst_address_or_dst_address_default, payout_currency_or_payout_currency_default, mode_or_mode_default: REQUIRED |
mode=swap + payin_currency_default + refund_dst_address | payin_currency: REQUIRED |
mode=swap + payin_currency + refund_extra_id | refund_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_stepistrue:mode,channel,payin_amount,payin_currencyandpayout_currency;is_skip_second_stepistrue(not forsell):dst_address,extra_id,refund_dst_addressandrefund_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:
| Mode | payin_currency | payout_currency |
|---|---|---|
buy | fiat | crypto |
sell | crypto | fiat |
swap | crypto | crypto |
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:
| Mode | dst_address, extra_id | refund_dst_address, refund_extra_id |
|---|---|---|
buy | allowed | not allowed |
sell | not allowed | not allowed |
swap | allowed | allowed |
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_addressis checked forpayout_currency(fixed or with the_defaultsuffix), together withextra_idif it is passed;refund_dst_addressis checked forpayin_currency(fixed or with the_defaultsuffix), together withrefund_extra_idif it is passed. Only forswap.
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_stepistrue:channel,payin_amount,payin_currencyandpayout_currencyare required, fixed or with the_defaultsuffix.modeis then required by the currencies (see linked parameters).is_skip_second_stepistrueand the mode is notsell:dst_addressis required, fixed or with the_defaultsuffix. Forswaprefund_dst_addressis required too.
Response
{
"request_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}
| Name | Type | Description |
|---|---|---|
| request_id | string | Created 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"
}
}
| Code | Description |
|---|---|
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_VALUE | The 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_ALLOWED | mode / 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_EXISTS | partner_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
| Name | Type | Description |
|---|---|---|
| page | integer | Page number. |
| rows | integer | Amount of rows returned per page. |
| timestamp | unix_timestamp_string | Select 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"
}
...
]
}
| Name | Type | Description |
|---|---|---|
| rows | integer | Amount of rows returned per page. |
| total | tinteger | Overall amount of rows. |
| data | array | Array objects contain: created_at, status and partner_order_id. |
TIP
created_at- timestampstatus- order statuspartner_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
| Name | Type | Description |
|---|---|---|
| partner_order_id required | string | Unique 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"
}
]
}
| Name | Type | Description |
|---|---|---|
| mode | mode | Payment mode. |
| channel | channel | Payment channel. |
| client_email | string | Client email. |
| client_nice_id | string | Unique client id. |
| partner_order_id | string | Unique partner order id. |
| client_order_id | string | Unique client order id. |
| payin_amount | float | Payin amount. |
| expected_payin_amount | float | Expected payin amount. |
| payout_amount | float | Payout amount. |
| expected_payout_amount | float | Expected payout amount. |
| payin_currency | currency | Payin currency. |
| payout_currency | currency | Payout currency. |
| payout_txid | string | TXID of payout transaction. |
| status | orderStatus | Current status of order. |
| dst_address | string | Wallet address where Switchere will send cryptocurrency. |
| dst_tag | integer[0..4294967295] | Tag for XRP address. |
| memo_id | string | MEMO_ID for EOS address. |
| memo_type | string | MEMO_TYPE for XLM address. |
| memo_value | string | MEMO_VALUE for XLM address. |
| client_country | country code | Client registration country. |
| country_by_ip | country code | Client last login country by IP. |
| created_at | unix_timestamp_string | Timestamp when order was created. |
| finished_at | unix_timestamp_string | Timestamp when order was finished. |
| status_log | order status log | Order status log. |
Fee POST
Return data about partner fee.
Endpoint
POST https://switchere.com/api/v3/partner/fee
Parameters
| Name | Type | Description |
|---|---|---|
| mode required | mode | Payment mode. |
| channel required | channel | Payment channel. |
| payin_currency required | currency | Payin currency. |
| payout_currency required | currency | Payout currency. |
| payin_amount required | float | Payin amount. |
Response
{
"network_fee": "string",
"payin_amount": "string",
"payin_max_amount": "string",
"payin_min_amount": "string",
"payout_amount": "string",
"rate": "string",
"service_fee": "string",
}
| Name | Type | Description |
|---|---|---|
| payin_amount | string | Payin amount. |
| payin_min_amount | string | Payin minimal amount. |
| payin_max_amount | string | Payin maximal amount. |
| payout_amount | string | Payout amount. |
| rate | string | Rate payin_currency/payout_currency. |
| network_fee | string | Network fee in payout currency. |
| service_fee | string | Service 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
| Name | Type | Description |
|---|---|---|
| payin_currency required | currency | Payin currency. Required only fiat. |
| payin_amount required | float | Payin amount. |
| payout_currency required | currency | Payout 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",
}
}
| Name | Type | Description |
|---|---|---|
| ... | dict of dicts | Payin 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
| Name | Type | Description |
|---|---|---|
| payin_currency required | currency | Payin currency. Required only crypto. |
| payin_amount required | float | Payin amount. |
| payout_currency required | currency | Payout 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",
}
}
| Name | Type | Description |
|---|---|---|
| ... | dict of dicts | Payout 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
| Name | Type | Description |
|---|---|---|
| payin_currency required | currency | Payin currency. Required only crypto. |
| payin_amount required | float | Payin amount. |
| payout_currency required | currency | Payout 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",
}
}
| Name | Type | Description |
|---|---|---|
| ... | dict of dicts | Crypto channel -> { Fee data for this Crypto channel } . |