Интеграция с вашим сервисом

Мерчант: создание заявок обмена с вашего сайта и уведомления о статусе.

Схема работы мерчанта

Создать заявку

Используйте метод public/exchanger/order/create.

НазваниеОписаниеТип
routeIdid направления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, uk)STRING
agreementсогласие с правиламиBOOLEAN
hideOutDataскрыть реквизиты получателяBOOLEAN
clientCallbackUrlкуда вернуть клиента после завершения заявки: ?status=success или ?status=errorSTRING
ipnUrlURL уведомления о смене статуса заявкиSTRING
ipnSecretстрока для подписи уведомленияSTRING

Авторизация по API-ключу описана в личном кабинете, все методы — в документации API.

IPN — уведомление о смене статуса

Чтобы получать уведомления, при создании заявки передайте дополнительные параметры:

  • clientCallbackUrl — клиент увидит кнопку возврата на ваш сайт и попадёт на этот URL;
  • hideOutData — скрыть данные получателя;
  • ipnUrl — HTTP/HTTPS-адрес вашего сервера для уведомлений;
  • ipnSecret — случайная строка для подписи уведомления.
  1. Уведомление отправляется методом POST, Content-Type: application/x-www-form-urlencoded.
  2. Уведомление отправляется один раз.
  3. Доставка не гарантируется: если сервер не ответил, повтора не будет.

Поля уведомления

ПолеТипОписание
orderUIDNumberuid заявки
orderIdString(ObjectId)id заявки
newStatusStringтекущий статус заявки
inAmountString(number)сумма, которую отдаёт клиент
outAmountString(number)сумма, которую получает клиент
xml_fromStringкод отдаваемой валюты
xml_toStringкод получаемой валюты
timestampNumberunix-время уведомления
toValuesArray([{key,name,value}])реквизиты заявки

Статусы

СтатусОписание
newновая заявка
waitPaymentожидаем платёж от пользователя
errorPaymentошибка платежа пользователя
inProgressв обработке (ожидает оператора или оплату)
inProgressPayoutв очереди на выплату: платёж принят
errorPayoutошибка выплаты
holdзаявка заморожена
doneзаявка выплачена
returnedплатёж возвращён отправителю
deletedзаявка удалена (отменена)

Проверка подписи

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

const stringForHash = orderId + ":" + newStatus + ":" + inAmount + ":" + outAmount + ":" + xml_from + ":" + xml_to + ":" + timestamp + ":" + ipnSecret;
// пример строки: 5d8e6002b80b7b4cd75a6424:inProgress:2:317.42:ETH:WMZ:1571328406072:SECRET123

const hash = crypto.createHash('sha256').update(stringForHash).digest('hex');
// пример: af3acf947e6f0e0f2c267e300b8582e504dba12d1f2d058652b7414163c09f48

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

  1. Если создавать заявки с авторизацией по API-ключу, все они будут видны в вашем личном кабинете.
  2. Сохраните UID и secret заявки: по ним можно открыть заявку вручную.
  1. Страница оплаты для клиента:
    // схема
    https://111obmen.com/{lang}/payment/{order-uid}/{order-secret}/
    // пример
    https://111obmen.com/ru/payment/1409/dGqwF2M2eBPaSN1G5ljMS1cb/
  2. Либо обычная страница заявки, как её видят все клиенты: та же схема, но /order/ вместо /payment/.
  3. Метод создания умеет возвращать платёжные данные, чтобы показать оплату на вашем сайте. Важно: при предоплате после оплаты переведите заявку из waitPayment в inProgress.