# Выплаты
# Выплаты на карту
ОБРАТИТЕ ВНИМАНИЕ!
Значение orderId должно быть уникальным в пределах успешных операций выплаты на карту.
В случае, если при отправке запроса на выплату вы не получили синхронный ответ с HTTP-кодом 200 и id операции, или же получили ответ с HTTP-кодом, отличным от 200 (например, 502 или 504) и хотите повторно запросить ту же самую выплату, необходимо использовать тот же самый номер orderId.
Таким образом в случае, если первоначальный запрос все-таки был завершен успешно, или находится в процессе, вы получите ответ с HTTP-кодом 400 и ошибкой "Duplicate order id", и повторная выплата произведена не будет. В случае, если первоначальный запрос завершен неуспешно - операция пройдет в стандартном режиме.
Следование данной инструкции позволит вам избежать задвоения операций по выплате на карту при возникновении любых сетевых проблем между сервером вашего приложения и сервером Mandarin.
Также рекомендуем вам выставить таймаут в 600 секунд при отправке запросов по API.
Например, первоначальный запрос на выплату содержал orderId, равный "5f2fdcf6-0b78-4dd7-be9f-212c7c058001".
Если она завершена успешно, то при повторном запросе на выплату с тем же значением orderId, в синхронном ответе будет возвращена ошибка. Выплата повторно создана не будет.
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Выплата с использованием токена карты
В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения card передается id ранее совершенной успешной токенизации полных карточных данных или номера карты.
Транзакция осуществляется в асинхронном режиме. В результате запроса вам синхронно придет id выплаты, а затем асинхронно придет callback-уведомление.
| Параметр | Обязателен | Параметр | Обязателен | |
|---|---|---|---|---|
| payment | Да | target | Да | |
| payment.action | Да | target.card | Да | |
| payment.orderId | Да | customValues[] | Нет | |
| payment.price | Да | customValues[].name | Нет |
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"payment": {
"action": "payout",
"orderId": "your_unique_order_id",
"price": "1000.00"
},
"customerInfo": {
"email": "user@example.com",
"phone": "+79001234567"
},
"target": {
"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
},
"customValues": [
{"name": "first parameter to save and show", "value": "p1"},
{"name": "second parameter to save and show", "value": "p2"}
],
"metadata": {
"first_parameter_to_callback_and_not_to_show": "p1",
"second_parameter_to_callback_and_not_to_show": "p2"
},
"urls": {
"callback": "http://...",
"return": "http://..."
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Выплата с использованием номера карты
В рамках данного запроса к стандартному вызову добавляется блок target, где в качестве значения knownCardNumber передается номер карты, на которую осуществляется перевод.
Значение orderId должно быть уникальным в пределах успешных операций вывода средств. Если Вы не получили успешный callback и хотите повторно запросить ту же самую выплату, рекомендуем использовать тот же самый номер orderId. Это предотвратит дублирование выплаты, если первоначальная выплата была произведена, но успешный callback не дошел.
Транзакция осуществляется в асинхронном режиме. В результате запроса вам синхронно придет id выплаты, а затем асинхронно придет callback-уведомление.
| Параметр | Обязателен | Параметр | Обязателен | |
|---|---|---|---|---|
| payment | Да | target | Да | |
| payment.action | Да | target.knownCardNumber | Да | |
| payment.orderId | Да | customValues[] | Нет | |
| payment.price | Да | customValues[].name | Нет | |
| customerInfo | Да | customValues[].value | Нет | |
| customerInfo.email | Да | metadata | Нет | |
| customerInfo.phone | Да | urls | Нет |
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"payment": {
"action": "payout",
"orderId": "your_unique_order_id",
"price": "1000.00"
},
"customerInfo": {
"email": "user@example.com",
"phone": "+79001234567"
},
"target": {
"knownCardNumber": "4012888888881881"
},
"customValues": [
{"name": "first parameter to save and show", "value": "p1"},
{"name": "second parameter to save and show", "value": "p2"}
],
"metadata": {
"first_parameter_to_callback_and_not_to_show": "p1",
"second_parameter_to_callback_and_not_to_show": "p2"
},
"urls": {
"callback": "http://...",
"return": "http://..."
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Выплата со вводом карты на платежной странице
Транзакция осуществляется в асинхронном режиме. В результате запроса вам синхронно придет id выплаты, а затем асинхронно придет callback-уведомление.
| Параметр | Обязателен | Параметр | Обязателен | |
|---|---|---|---|---|
| payment | Да | customValues[] | Нет | |
| payment.action | Да | customValues[].name | Нет | |
| payment.orderId | Да | customValues[].value | Нет | |
| payment.price | Да | metadata | Нет | |
| customerInfo | Да | urls | Нет | |
| customerInfo.email | Да | urls.callback | Нет | |
| customerInfo.phone | Да | urls.return | Нет |
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"payment": {
"action": "payout",
"orderId": "your_unique_order_id",
"price": "1000.00"
},
"customerInfo": {
"email": "user@example.com",
"phone": "+79001234567"
},
"customValues": [
{"name": "first parameter to save and show", "value": "p1"},
{"name": "second parameter to save and show", "value": "p2"}
],
"metadata": {
"first_parameter_to_callback_and_not_to_show": "p1",
"second_parameter_to_callback_and_not_to_show": "p2"
},
"urls": {
"callback": "http://...",
"return": "http://..."
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725",
"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Выплаты через СБП
Система быстрых платежей (СБП) - сервис, который позволяет мгновенно переводить средства со счёта по номеру телефона получателя.
Особенности сервиса выплат СБП:
Для подключения сервиса выплат СБП необходимо направить запрос в Службу поддержки (opens new window) или клиентскому менеджеру;
Выплаты производятся с указанием номера телефона и ФИО получателя, либо без, а также выбора банка из списка банков;
Привязка данных, для последующих рекуррентных платежей и автосписаний по СБП в настоящий момент не предусмотрено.
# Получение списка банков
Для того, чтобы передавать банк, необходимо получить его данные bankId и bankBic из списка банков.
Авторизация - XAuth (opens new window).
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
| bankName | string | Нет | Наименование банка по которому необходимо проводить фильтрацию, можно указать неполное название, метод вернет все подходящие варианты. При фильтрации регистр игнорируется |
Запрос на получение списка банков:
GET https://secure.mandarinpay.com/api/sbp/banks/
Ответ в случае успешного создания запроса:
{
"banks": [
{
"bankId": "100000000111",
"bankName": "Сбербанк",
"bankBic": "044525225"
},
{
"bankId": "100000000008",
"bankName": "Альфа-Банк",
"bankBic": "044525593"
},
{
"bankId": "100000000010",
"bankName": "Промсвязьбанк",
"bankBic": "044525555"
}
]
}
Запрос на получение определённого банка:
GET https://secure.mandarinpay.com/api/sbp/banks?bankName=Сбербанк
Ответ в случае успешного создания запроса:
{
"banks": [
{
"bankId": "100000000111",
"bankName": "Сбербанк",
"bankBic": "044525225"
}
]
}
Если банки не найдены, то вернётся ответ:
{
"banks": []
}
# Создание выплаты с ФИО
В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения sbp передаются параметры банка bankId и bankBic.
Транзакция осуществляется в асинхронном режиме. В результате запроса вам синхронно придет id выплаты, а затем асинхронно придет callback-уведомление.
| Параметр | Обязателен |
|---|---|
| customerInfo | Да |
| customerInfo.phone | Да |
| customerInfo.email | Да |
| customerInfo.firstName | Да |
| customerInfo.lastName | Да |
| customerInfo.middleName | Да, если в паспорте у получателя указано отчество |
| payment | Да |
| payment.action | Да |
| payment.orderId | Да |
| payment.price | Да |
| target | Да |
| target.sbp | Да |
| target.sbp.bankId | Да |
| target.sbp.bankBic | Да |
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"customerInfo": {
"phone": "+79111111111",
"email": "test@test.com",
"firstName": "Иванов",
"lastName": "Петр",
"middleName": "Сергеевич"
},
"payment": {
"orderId": "your_unique_order_id",
"price": "10.00",
"action": "payout"
},
"target": {
"sbp": {
"bankId": "100000000111",
"bankBic": "044525225"
}
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Создание выплаты без ФИО
В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения sbp передаются параметры банка bankId и bankBic.
Транзакция осуществляется в асинхронном режиме. В результате запроса вам синхронно придет id выплаты, а затем асинхронно придет callback-уведомление.
Выплаты без ФИО требуют подтверждения или отмены после создания транзакции и получения от банка успешного статуса.
| Параметр | Обязателен |
|---|---|
| customerInfo | Да |
| customerInfo.phone | Да |
| customerInfo.email | Да |
| payment | Да |
| payment.action | Да |
| payment.orderId | Да |
| payment.price | Да |
| target | Да |
| target.sbp | Да |
| target.sbp.bankId | Да |
| target.sbp.bankBic | Да |
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"customerInfo": {
"phone": "+79111111111",
"email": "test@test.com"
},
"payment": {
"orderId": "your_unique_order_id",
"price": "10.00",
"action": "payout"
},
"target": {
"sbp": {
"bankId": "100000000111",
"bankBic": "044525225"
}
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
Ответ в случае попытки создания выплаты с уже существующим значением orderId (400 Bad Request)
{
"error": "Duplicate order id 5f2fdcf6-0b78-4dd7-be9f-212c7c058001 found for incomplete payout transaction",
"errorCode": -2
}
# Проверка статуса запроса без ФИО
Запрос на проверку статуса
После создания выплаты без ФИО необходимо проверить статус, подтвердить выплату возможно будет только после того, как статус будет success.
GET https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/status
Ответ в случае успешного создания транзакции (200 ОК)
{
"status": "success",
"fio": "Петр Иванович С."
}
Ответ в случае ожидания проверки получателя банком
{
"status": "pending",
"fio": null
}
# Подтверждение выплаты без ФИО
Запрос на подтверждение выплаты
После получения успешного статуса необходимо подтвердить выплату, чтобы получателю ушли средства.
POST https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/confirm
Ответ в случае успешного подтверждения выплаты (200 ОК)
# Отмена выплаты без ФИО
Выплату можно отменить, если еще не был отправлен запрос на подтверждение confirm.
Запрос на отмену выплаты
POST https://secure.mandarinpay.com/api/sbp/43913ddc000c4d3990fddbd3980c1725/reject
Ответ в случае успешной отмены выплаты (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725"
}
# Проверка баланса для выплат
Данный запрос позволяет проверить баланс счета, с которого осуществляются массовые выплаты.
Запрос
GET https://secure.mandarinpay.com/api/account/channels/{name}/balance
В качестве значения {name} необходимо передать параметр из таблицы ниже:
| Параметр | Описание параметра |
|---|---|
| openbank_direct | Для запроса баланса расчетного счета, открытого в ПАО Банк «ФК Открытие» (Открытие) |
| psb_direct | Для запроса баланса расчетного счета, открытого в ПАО Промсвязьбанк (ПСБ) |
Пример кода для проверки баланса
<?php
$merchantId=0;
$secret='******';
$reqid = time() ."_". microtime(true) ."_". rand();
$hash = hash("sha256", $merchantId ."-". $reqid ."-". $secret);
$auth= $merchantId ."-".$hash ."-". $reqid;
$url_transaction = "https://secure.mandarinpay.com/api/account/channels/openbank_direct/balance";
$ch = curl_init($url_transaction);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"X-Auth:" . $auth
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
var_dump($result);
?>
# Получение статуса транзакции
Метод API дает возможность по идентификатору операции получить её статус, а также информацию о карте.
Авторизация - XAuth (opens new window).
Запрос:
operationId - id платежа (opens new window).
GET https://secure.mandarinpay.com/api/operations/{operationId}
Пример ответа:
{
"operationType": "Transaction",
"state": "Success",
"card": {
"cardNumber": "519261XXXXXX3242",
"cardHolder": "CARD HOLDER",
"expireDate": "25/01",
"cardId": "a3a5c49e1385e5096d05075d636f7baf",
"country": "TUR",
"productName": "Standard Mastercard Card",
"productCode": "MCS",
"brand": "mastercard",
"bank": "ODEA BANK A.S.",
"cardType": "Credit"
}
}
Параметры ответа:
| Параметр | Описание |
|---|---|
| operationType | тип операции, транзакция/привязка |
| state | Статус операции: success, failed, payout-only, pendingExecution/none/unknown - операция не завершена и находится в обработке (может потребоваться сверка с банком-эквайером). Только статус success однозначно указывает на успешность операции! |
| cardNumber | маскированный номер карты |
| cardHolder | держатель карты |
| expireDate | срок действия карты |
| cardId | уникальный хэш полного номера карты |
| country | страна выпуска карты |
| productName | карточный продукт/категория карты |
| productCode | код карточного продукта/категории карт |
| brand | платежная система карты |
| bank | банк, выпустивший карту |
| cardType | тип карты (дебетовая/кредитная) |
← Токенизация Роутинг →