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

Мерчант

Merchant API та інструкція з інтеграції інвойсів

Сторінка merchant-документації пояснює, як інтернет-магазини та платіжні сервіси можуть інтегрувати ObminMe у власний checkout або сценарій оплати інвойсів. Вона охоплює створення заявок, callback URL, стани виплат, перевірку підпису та параметри, які потрібні для передачі даних між стороною мерчанта та сервісом обміну.

Цей гайд корисний технічним командам, яким потрібні надійні платіжні нотифікації, власні return URL і зрозуміла модель статусів для інвойсів з обміном. Попереднє ознайомлення з документацією допомагає уникнути помилок у форматі запитів, обробці callback і звірці платежів.

  • Параметри для створення заявок на обмін із системи мерчанта.
  • IPN callback, обробка статусів і логіка перевірочного хешу.
  • Деталі платіжного потоку для магазинів, інвойсів і автоматизації.

Використовуйте merchant-документацію разом із тестуванням на staging, щоб перевірити callback URL, статуси заявок і підписи до виходу в production.

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

Використовуйте метод 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 мова STRING
agreement договір BOOLEAN
hideOutData приховати реквізити BOOLEAN
clientCallbackUrl зворотний виклик, коли програма буде завершена, клієнт побачить кнопку для повернення на сайт, і клієнт буде перенаправлений на цей URL. ?status=success або на ?status=error STRING
ipnUrl URL-адреса сповіщення про миттєвий платеж (буде викликаний при зміні статусу ордера) STRING
ipnSecret рядок для створення безпечного хешу в ipn url STRING

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

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

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

  • clientCallbackUrl - зворотний виклик, коли програма буде завершена, клієнт побачить кнопку для повернення на сайт, і клієнт буде перенаправлений на цей 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 запиту та секрет і вручну перейти до запиту, вказавши ці дані в адресному рядку

Оплата

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

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

Центр підтримки