API-документація

RateON Exchange API v1

Ця документація пояснює, як інтегрувати обмінний сервіс RateON у гаманець, моніторинг, застосунок або партнерський сервіс. API дозволяє отримувати напрями обміну, розраховувати суми, створювати заявки та відстежувати їхні статуси.

Запросити API-доступ Переглянути методи

Base URL

/api/userapi/v1/

https://rateon.io/api/userapi/v1/{method}

Запит / відповідь

POST → JSON

Усі параметри передаються в тілі запиту. Відповіді повертаються у форматі JSON.

Напрями обміну

Отримуйте доступні пари, резерви, ліміти та обов’язкові поля для кожного напряму обміну.

Створення заявки

Створюйте заявки на обмін зі свого інтерфейсу та безпечно передавайте дані гаманця користувача через API.

Відстеження статусу

Відстежуйте статус заявки через API-методи або отримуйте server-to-server callback-сповіщення.

Швидкий старт

Формат 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`.

Безпека: зберігайте API-ключ лише на серверній стороні. Не розміщуйте його в браузерному JavaScript, публічному коді мобільного застосунку або клієнтських застосунках.

Рекомендований сценарій інтеграції

Завантажити валюти та напрями

Викличте 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`.

Довідник методів

POST testПеревіряє, чи працюють API-credentials і доступ. ⌄

Параметри запиту

Обов’язкових параметрів немає.

POST get_direction_currenciesПовертає валюти, доступні для обміну. ⌄

Необов’язкові параметри

currency_id_give, currency_id_get.

Відповідь

Повертає доступні валюти для сторони відправлення та отримання. Використовуйте цей метод для побудови селекторів валют.

POST get_directionsПовертає напрями обміну, доступні через API. ⌄

Необов’язкові параметри

currency_id_give, currency_id_get.

Відповідь

Кожен напрям містить direction_id, ID валют відправлення/отримання, назви валют і логотипи.

POST get_directionПовертає повну інформацію про вибраний напрям обміну. ⌄

Обов’язковий параметр

direction_id — ID напряму обміну.

Поля відповіді

Використовуйте такі поля відповіді, як reserve, course_give, course_get, min_give, max_give, min_get, max_get, give_fields, get_fields і dir_fields.

POST get_calcРозраховує суми обміну для вибраного напряму. ⌄

Обов’язкові параметри

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.

POST create_bidСтворює нову заявку на обмін. ⌄

Основні параметри

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.

POST bid_infoПовертає платіжну інформацію та статус однієї заявки, створеної через API. ⌄

Параметри

Передайте id або hash. Використовуйте цей метод після callback-сповіщень і коли користувач відкриває екран заявки.

POST get_exchangesПовертає заявки, створені поточним API-ключем. ⌄

Необов’язкові фільтри

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-модулі або бути недоступними для конкретної заявки.

Статуси заявок

newНова заявка

coldnewОчікує перевірки

payedКористувач позначив заявку як оплачену

realpayПлатіж отримано

verifyНа перевірці

successЗаявку виконано

cancelЗаявку скасовано

errorПомилка заявки

partpayЧасткова оплата

payouterrorПомилка виплати

mercherrorПомилка merchant-модуля

deleteЗаявку видалено

Callback-сповіщення

Використовуйте 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 затримався, продублювався або був відправлений повторно.

Важливо: сприймайте callbacks як сповіщення, а не як єдине джерело істини. Поточний статус заявки потрібно підтверджувати через 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

Як отримати API-credentials?

Зв’яжіться з підтримкою RateON і надайте назву компанії, сценарій використання, потрібні API-методи та IP-адреси серверів. Credentials видаються після схвалення.

Чи можна обмежити API-доступ за IP?

Так. З міркувань безпеки API-доступ може бути обмежений лише схваленими IP-адресами серверів.

Чи потрібно викликати get_calc перед створенням заявки?

Так. Ми рекомендуємо викликати get_calc безпосередньо перед create_bid, щоб розрахувати актуальну суму обміну.

Як відстежувати статус заявки?

Використовуйте bid_info для однієї заявки, get_exchanges для історії заявок або передавайте callback_url під час створення заявки.

Готові до інтеграції?

Надішліть ваш сценарій використання, потрібні API-методи та IP-адреси серверів. Ми підготуємо credentials і допоможемо з першим тестовим запитом.

Зв’язатися з підтримкою