Перейти к основному содержимому

Инструкция: как корректно обрабатывать выплаты через API Mandarin

Общие принципы​

Интеграция с API выплат Mandarin предполагает два этапа:

  1. Синхронное создание запроса на выплату.
  2. Асинхронное получение статуса выплаты.

Корректная реализация этих этапов критически важна для исключения задвоений, потерь данных и ошибок при выплатах.

1. Создание выплаты​

Если ваш запрос прошёл успешно, в ответ вы получите HTTP 200 и поле id (это и есть transactionId). Пример:

{
"id": "43913ddc000c4d3990fddbd3980c1725"
}

Если в ответе возник таймаут или вернулся код отличный от 200 (например, 502, 504), вы обязаны повторить запрос с тем же значением orderId.

Это безопасно: если операция уже была получена и создана ранее, вы получите ошибку Duplicate order id.

Пример ответа на повторный запрос:

{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}

Такой ответ говорит о том, что операция уже была создана и находится в обработке — повторной выплаты не произойдёт.

Важно: orderId должен быть уникальным в пределах всех успешных операций. Это ключевой параметр, по которому ведётся идентификация операции.

2. Проверка создания запроса (если вы не получили id)​

Если вы не получили id, либо не уверены, был ли успешно создан запрос, проверьте это через сервис мониторинга:

https://secure.mandarinpay.com/admin/heartbeat/transactions

Там доступен поиск по orderId. Если операция найдена — значит, мы получили ваш запрос, и он обрабатывается. Если не найдена — повторите запрос.

3. Получение статуса выплаты​

Все выплаты обрабатываются асинхронно. Статус приходит в виде callback-уведомления на ваш urls.callback. Если вы не получили callback, проверить статус вручную можно через API:

GET [https://secure.mandarinpay.com/api/operations/{transactionId}](https://secure.mandarinpay.com/api/operations/%7BtransactionId%7D)

Пример ответа:

{
  "operationType": "Transaction",
  "state": "Success",
  ...
}

Возможные значения поля state:

  • success — операция завершена успешно
  • failed — операция завершена с ошибкой
  • pendingExecution, none, unknown — операция еще не завершена

Только статус success подтверждает успешное завершение выплаты.

Повтор выплат​

Если вы повторно инициируете выплату, обязательно:

  • использовать тот же orderId, если не уверены, прошла ли операция.
  • корректно обрабатывать оба возможных ответа: с id (выплата создана) и с Duplicate order id (выплата уже создана ранее).

Это позволит избежать задвоения выплат.

Отладка и поддержка​

Все инциденты и технические сбои анонсируются в канале @mandarin_alerts. В случае вопросов обращайтесь в техническую поддержку: support@mandarin.io или в чат поддержки.

Ссылки​

API Документация

Мониторинг API

Содержание