Інтеграція з вашим сервісом

Документація для мерчантів

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

Використайте метод public/exchanger/order/create

Назва Опис Тип
routeId id напрямку ObjectID
partner посилання партнера STRING
amount сума в FLOAT
fromValues[0][key] назва ключа ObjectID
fromValues[0][value] значення для цього поля STRING
toValues[0][key] назва ключа STRING
toValues[0][value] значення для цього поля STRING
routeValues[0][key] назва ключа ObjectID
routeValues[0][value] значення для цього поля STRING
lang мова клієнта (ru, en) STRING
agreement згода BOOLEAN
hideOutData захистити вихідні реквізити BOOLEAN
clientCallbackUrl callback після завершення заявки: клієнт побачить кнопку повернення на сайт і буде перенаправлений на цю URL ?status=success або ?status=error STRING
ipnUrl url миттєвого сповіщення про оплату (буде викликано, коли заявка змінить статус) STRING
ipnSecret рядок для створення захищеного хешу в ipn url STRING

Документацію щодо системи авторизації ви знайдете в особистому кабінеті. Докладніше про роботу з методами та додатковими даними — на

IPN (Сповіщення про зміну статусу платіжної заявки)

Щоб отримувати сповіщення про зміну статусу заявки під час її створення, потрібно передати додаткові параметри:

  • clientCallbackUrl - callback після завершення заявки: клієнт побачить кнопку повернення на сайт і буде перенаправлений на цю URL
  • hideOutData - приховати реквізити отримувача
  • ipnUrl - HTTP/HTTPS-посилання для сповіщення вашого сервера.
  • ipnSecret - Випадковий рядок для створення підпису запиту (для збереження цілісності запиту)
  1. Запит буде надіслано методом POST
  2. IPN буде надіслано один раз
  3. Доставка IPN не гарантується (якщо сервер не відповів на запит, його не буде надіслано повторно)

Приклад IPN

  • POST
  • ['Content-Type'] = 'application/x-www-form-urlencoded'


  • orderUID :Number() - заявка uid
  • orderId :String(ObjectId) -заявка id
  • newStatus :String() - заявка поточний статус
  • inAmount :String(number) - order in sum
  • outAmount :String(number) - order out sum
  • xml_from :String() - заявка uid
  • xml_to :String() - заявка uid
  • timestamp :Number() - unix-час сповіщення ipn
  • toValues :Array([{key,name,value}]) - реквізити заявки

Список статусів

  • new - нова заявка
  • waitPayment - очікування оплати від користувача
  • errorPayment - помилка оплати користувача (мерчант надіслав помилку)
  • inProgress - в обробці (очікує підтвердження адміністратора або оплати заявки)
  • inProgressPayout - у черзі на виплату (оплату успішно прийнято) (якщо у валюті налаштовано автовиплату, її буде ініційовано)
  • errorPayout - помилка виплати (під час виплати сталася помилка)
  • hold - заморожено (проблеми із заявкою)
  • done - заявку успішно завершено
  • returned - заявку було оплачено, але не всі умови обміну виконано, і кошти повернуто відправнику
  • deleted - заявку видалено (скасовано)

Перевірка контрольної суми запиту (IPN)

sha256(orderId:newStatus:inAmount:outAmount:xml_from:xml_to:timestamp:ipnSecret)

        
const stringForHash = orderId+":"+newStatus+":"+inAmount+":"+outAmount+":"+xml_from+":"+xml_to+":"+timestamp+":"+ipnSecret;
// example string for hash 5d8e6002b80b7b4cd75a6424:inProgress:2:317.42:ETH:WMZ:1571328406072:SECRET123

const hash = crypto.createHash('sha256').update(stringForHash).digest('hex')
// example hash af3acf947e6f0e0f2c267e300b8582e504dba12d1f2d058652b7414163c09f48

Контроль оплати

  1. Якщо вам потрібно контролювати статус заявок, створюйте їх з авторизацією — тоді всі заявки відображатимуться в особистому кабінеті;
  2. Ви можете зберегти UID заявки та secret і вручну перейти до заявки, вказавши ці дані в адресному рядку

Оплата

  1. Ви можете використати /payment/ для показу сторінки оплати

    // schema
    https://hellchange.top/user-lang/payment/order-uid/order-secret
    // example result
    https://hellchange.top/en/payment/1409/dGqwF2M2eBPaSN1G5ljMS1cb
  2. Також ви можете просто дати посилання на обмін у тому вигляді, як його бачать усі клієнти, за тією ж схемою, що вказана в першому варіанті, лише /payment/ слід замінити на /order/
  3. У методі є параметри, які дозволяють відобразити дані оплати або форму оплати на вашому сайті — ви можете їх використовувати. ВАЖЛИВО: якщо метод із ручною оплатою, після оплати потрібно оновити статус заявки з waitPayment на inProgress.

Інформація