API-документация
RateON Exchange API v1
Эта документация объясняет, как интегрировать обменный сервис RateON в кошелёк, мониторинг, приложение или партнёрский сервис. API позволяет получать направления обмена, рассчитывать суммы, создавать заявки и отслеживать их статусы.
https://rateon.io/api/userapi/v1/{method}
Направления обмена
Создание заявки
Отслеживание статуса
Формат endpoint
https://rateon.io/api/userapi/v1/{method}
Content type
Для параметров в теле запроса рекомендуется использовать application/x-www-form-urlencoded.
curl -X POST "https://rateon.io/api/userapi/v1/test"
-H "API-LOGIN: YOUR_API_LOGIN"
-H "API-KEY: YOUR_API_KEY"
-H "API-LANG: ru_RU"
| Header | Обязательно | Описание |
|---|---|---|
API-LOGIN | Да | API-логин, выданный для вашего интеграционного аккаунта. |
API-KEY | Да | Приватный API-ключ, выданный для вашего интеграционного аккаунта. |
API-LANG | Нет | Принудительный язык ответа. Примеры значений: en_US, ru_RU. |
Загрузить валюты и направления
Вызовите get_direction_currencies и get_directions, чтобы показать доступные пары обмена.
Получить детали направления
Вызовите get_direction, чтобы получить курс, резерв, лимиты, комиссии и обязательные поля.
Рассчитать сумму
Вызовите get_calc непосредственно перед созданием заявки, чтобы рассчитать актуальные суммы отправки и получения.
Создать и отслеживать заявку
Вызовите create_bid, затем используйте bid_info, get_exchanges или callbacks для отслеживания статуса.
1. Собрать выбор пары
Используйте get_direction_currencies и get_directions, чтобы получить валюты, пары и direction_id.
2. Отрисовать динамические поля
Используйте get_direction, чтобы отобразить обязательные поля give_fields, get_fields и dir_fields.
3. Рассчитать перед отправкой
Используйте get_calc прямо перед созданием заявки, чтобы показать актуальную сумму и отследить возможные изменения.
4. Создать заявку и сохранить ID
Используйте create_bid и сохраните возвращённые id, hash, status и данные платёжного действия.
5. Отслеживать статус
Используйте callback_url для push-уведомлений, затем проверяйте статус через bid_info или get_exchanges.
6. Учитывать API-действия
Вызывайте pay_bid и cancel_bid только если возвращённый api_actions явно разрешает действие через API.
| Метод | Назначение | Типичное использование |
|---|---|---|
test | Проверяет API-доступ. | Используйте первым, чтобы проверить credentials и IP allowlist. |
get_direction_currencies | Возвращает валюты, доступные для обмена. | Построение селекторов валют. |
get_directions | Возвращает доступные направления обмена. | Построение списка пар и получение direction_id. |
get_direction | Возвращает подробную информацию о направлении. | Показ курса, лимитов, резерва и обязательных полей. |
get_calc | Рассчитывает сумму обмена. | Показ актуальной суммы перед созданием заявки. |
create_bid | Создаёт заявку на обмен. | Отправка финального запроса на обмен. |
bid_info | Возвращает платёжную информацию и статус одной заявки, созданной через API. | Проверка по id или hash. |
get_exchanges | Возвращает заявки, созданные текущим API-ключом. | Показ истории заявок или синхронизация статусов. |
pay_bid | Отмечает заявку как оплаченную, если это разрешено. | Используйте только если api_actions.pay = api. |
cancel_bid | Отменяет заявку, если это разрешено. | Используйте только если api_actions.cancel = api. |
Параметры запроса
Обязательных параметров нет.
Необязательные параметры
currency_id_give, currency_id_get.
Ответ
Возвращает доступные валюты для стороны отправки и получения. Используйте этот метод для построения селекторов валют.
Необязательные параметры
currency_id_give, currency_id_get.
Ответ
Каждое направление содержит direction_id, ID валют отправки/получения, названия валют и логотипы.
Обязательный параметр
direction_id — ID направления обмена.
Поля ответа
Используйте такие поля ответа, как reserve, course_give, course_get, min_give, max_give, min_get, max_get, give_fields, get_fields и dir_fields.
Обязательные параметры
direction_id, calc_amount, calc_action.
Значения calc_action
1 сумма отправки, 2 сумма получения, 3 сумма отправки с комиссией, 4 сумма получения с комиссией.
Поля ответа
Используйте sum_give, sum_give_com, sum_get, sum_get_com, com_give, com_get, лимиты и флаг changed.
Основные параметры
direction_id, calc_amount, calc_action, account1, account2, пользовательские поля cf1–cf99.
Необязательные параметры
api_id, partner_id, callback_url. Используйте callback_url, если хотите, чтобы RateON уведомлял ваш сервер при изменении статуса заявки.
Поля ответа
Сохраните возвращённые id и hash. Используйте status, status_title, поля сумм, платёжную инструкцию и api_actions.
Параметры
Передайте id или hash. Используйте этот метод после callback-уведомлений и когда пользователь открывает экран заявки.
Необязательные фильтры
start_time, end_time, ip, id, api_id, status_history, limit, offset.
api_actions.pay
Если значение равно api, кошелёк может вызвать pay_bid. Если возвращается платёжная ссылка или инструкция, покажите её пользователю.
api_actions.cancel
Если значение равно api, кошелёк может вызвать cancel_bid. В противном случае отмена может быть недоступна для этой заявки.
api_actions. Некоторые действия могут обрабатываться автоматически через merchant-модули или быть недоступны для конкретной заявки.Используйте callbacks как server-to-server уведомление о том, что заявка могла измениться. Кошелёк всегда должен проверять финальное состояние через API перед обновлением интерфейса пользователя.
Включить callbacks
Передайте callback_url при вызове create_bid. URL должен быть доступен по HTTPS и принимать POST-запросы от RateON.
Получить callback-данные
Callback payload может включать bid_id, account1, account2 и пользовательские поля заявки cf1–cf99, в зависимости от выбранного направления и полей заявки.
Проверить статус заявки
После получения callback вызовите bid_info, используя id или hash заявки. Если нужно синхронизировать несколько заявок, используйте get_exchanges.
Обновить интерфейс кошелька
Обновляйте экран заявки только после проверки через API. Это предотвращает некорректное изменение статуса, если callback задержался, продублировался или был отправлен повторно.
bid_info или get_exchanges.| Ошибка | Возможная причина | Рекомендуемое действие |
|---|---|---|
Api disabled | Неверные credentials или API-доступ отключён. | Проверьте API-LOGIN, API-KEY, API-доступ и IP allowlist. |
Empty response | Запрошенные данные не найдены или параметры указаны неверно. | Проверьте обязательные параметры и ID. |
No bid exists | Запрошенная заявка не существует. | Проверьте id или hash заявки. |
Method not supported | Выбранный API-метод не включён для этого API-ключа. | Запросите доступ к нужному методу. |
Direction not found | Запрошенное направление обмена недоступно через API. | Проверьте доступность направления и API-права. |
FAQ
get_calc непосредственно перед create_bid, чтобы рассчитать актуальную сумму обмена.bid_info для одной заявки, get_exchanges для истории заявок или передавайте callback_url при создании заявки.Готовы к интеграции?
Отправьте ваш сценарий использования, необходимые API-методы и IP-адреса серверов. Мы подготовим credentials и поможем с первым тестовым запросом.
Связаться с поддержкой