# Основные принципы
# Схема взаимодействия
# Запросы
# Точки входа
Точки входа для тестового (sandbox) и боевого (production) окружения одинаковы.
Mandarin определяет окружение по аутентификационным данным (а именно, по значению секретного ключа Secret).
Важно использовать TLS не ниже 1.2 (запросы с TLS 1.0 или 1.1 будут отклоняться).
Точка входа для создания транзакций
Используется для всех основных операций (например, для приема платежей и выплат на карту).
POST https://secure.mandarinpay.com/api/transactions
Точка входа для токенизации карт
Используется только для токенизации карт.
POST https://secure.mandarinpay.com/api/card-bindings
Точка входа для упрощенной идентификации
Процесс идентификации значительно отличается от остальных и описан на отдельной странице. При этом используется стандартный для Mandarin способ аутентификации.
POST https://secure.mandarinpay.com/api/personidentification
# Аутентификация запросов
Аутентификация запросов происходит за счет авторизационной строки, которая передается в параметре заголовка X-Auth.
Значение X-Auth формируется по следующему шаблону:
merchantId-SHA256(merchantId-requestId-secret)-requestId, где:
merchantId– MID, указанный в личном кабинете.requestId– уникальный номер запроса. Для обеспечения уникальности рекомендуем использовать текущий таймстамп в миллисекундах, либо набор байт, сгенерированный криптографически-надёжным генератором случайных чисел.secret– Secret, указанный в личном кабинете.
API-запросы без заголовка или с некорректным заголовком, в том числе c некорректным X-Auth, будут отклонены без создания транзакций.
Примеры расчета X-Auth
<?php
function gen_auth($merchantId, $secret)
{
$reqid = time() ."_". microtime(true) ."_". rand();
$hash = hash("sha256", $merchantId ."-". $reqid ."-". $secret);
return $merchantId ."-".$hash ."-". $reqid;
}
?>
public static string GenerateXAuth(string secret)
{
var requestId = Guid.NewGuid().ToString("N");
string hash;
using (var sha256 = System.Security.Cryptography.SHA256.Create())
hash = BitConverter.ToString(sha256.ComputeHash(Encoding.UTF8.GetBytes($"{merchantId}-{requestId}-{secret}"))).ToLower().Replace("-", "");
return $"{merchantId}-{hash}-{requestId}";
}
DEPRECATED
Альтернативный способ аутентификации - Basic auth (opens new window). Не рекомендуем использовать его, особенно для запросов по выплатам на карту. В качестве логина используется значение merchantId, в качестве пароля - значение Secret.
# Параметры запросов
Content-Type для запросов принимает значение application/json.
Вы можете загрузить коллекцию для Postman, в которую уже введены все запросы из данного раздела.
| Параметр | Тип | Описание и возможные значения | Где используется (action) |
|---|---|---|---|
| payment | object | Объект, содержащий данные о транзакции. | pay, preauth, reversal, payout |
| payment.action | string | Тип транзакции. Возможные значения: pay - Платеж; preauth - Авторизация; reversal - Отмена транзакции; payout - Выплата. | pay, preauth, reversal, payout |
| payment.orderId | string | Номер заказа в вашей системе. Должен быть уникальным среди успешных операций! | pay, preauth, reversal, payout |
| payment.price | string | Сумма платежа. Разделитель - точка. | pay, preauth, reversal, payout |
| payment. orderActualTill | string | Срок резервирования товара/услуги. После указанной даты платеж будет невозможен. Формат: 2020-02-20 12:34:56+00:00. Если параметр не указывается, то действует стандартный срок 48 часов. | pay, preauth |
| customerInfo | object | Объект, содержащий данные о пользователе. | pay, preauth, reversal, payout, card-binding |
| customerInfo. email | string | Email пользователя. Формат: user@example.com. | pay, preauth, reversal, payout, card-binding |
| customerInfo. phone | string | Телефон пользователя в формате РФ: +79001234567. | |
| target | object | Объект, содержащий ссылку на существующую транзакцию/токен карты. | pay, reversal, payout, card-binding |
| target.transaction | string | Идентификатор существующей транзакции, на которую ссылается новая. | pay, reversal |
| target.card | string | Токен карты (например, для рекуррентных платежей). | pay, payout |
| target. knownCardNumber | string | Номер карты, на которую осуществляется выплата. | payout, card-binding |
| destination | object | Объект, содержащий ссылку на токен/номер карты, на которую осуществляется перечисление в рамках card2card транзакции. | card2card |
| destination.card | string | Токен карты, на которую осуществляется перечисление в рамках card2card транзакции. | card2card |
| destination.knownCardNumber | string | Номер карты, на которую осуществляется перечисление в рамках card2card транзакции. | card2card |
| source | object | Объект, содержащий ссылку на токен карты, c которой осуществляется списание в рамках card2card транзакции. | card2card |
| source.card | string | Токен карты, с которой осуществляется списание в рамках card2card транзакции. | card2card |
| allowinteractive | boolean | Индикатор интерактивного (с участием плательщика) платежа, если оплата без участия плательщика невозможна. Поддерживается только в Mandarin Custom Pay. При использовании всегда равен true: "allowinteractive": true | pay |
| interactive | boolean | Индикатор интерактивного (с участием плательщика) платежа. Поддерживается только в Mandarin Custom Pay. При использовании всегда равен true: "interactive": true | pay |
| customValues[] | array | Массив, содержащая дополнительную информацию о платеже. Может содержать до 8 пар параметров. Каждый параметр отображается плательщику в правом блоке платежной страницы. | pay, preauth, reversal, payout |
| customValues[]. name | string | Заголовок параметра (отображаемый в правом блоке платежной страницы). | pay, preauth, reversal, payout |
| customValues[]. value | string | Значение параметра (отображаемое в правом блоке платежной страницы). | pay, preauth, reversal, payout |
| metadata | object | Объект, содержащий список ваших параметров с любыми названиями и любыми значениями, которые будут отправлены в callback-уведомлении. Параметры не отображаются в пользовательском интерфейсе плательщика. Названия параметров не могут содержать пробелы! | pay, preauth, reversal, payout |
| urls | object | Объект, содержащий url. Если отсутствует, то используются url из настроек. | pay, preauth, reversal, payout, card-binding |
| urls.return | string | Url для редиректа пользователя после платежа. Редирект пользователя на указанный Url происходит после нажатия на кнопку "Вернуться на сайт" на платежной странице, либо автоматически после успешной оплаты. По умолчанию автоматический редирект отключен, для подключения обратитесь в Службу технической поддержки (opens new window). | pay, preauth, reversal, payout, card-binding |
| urls.callback | string | Url для отправки callback-уведомления о статусе трaнзакции. | pay, preauth, reversal, payout, card-binding |
| fiscalInformation | object | Объект, содержащий фискальную информацию для онлайн-кассы. | pay |
| fiscalInformation. taxationSystem | string | Система налогообложения. Возможные значения: Common - Общая (ОСН); Simplified - Упрощенная (УСН) "Доходы"; SimplifiedMinusOutlay - Упрощенная (УСН) "Доходы минус расходы"; UnifiedImputedIncome - Единый налог на вмененный доход (ЕНВД); UnifiedAgricultural - Единый сельскохозяйственный налог (ЕСХН); Patent - Патентная (ПСН). | pay |
| fiscalInformation. items[] | array | Массив строк в чеке. | pay |
| fiscalInformation. items[].description | string | Наименование товара. | pay |
| fiscalInformation. items[].quantity | string | Количество или вес. Разделитель - точка. | pay |
| fiscalInformation. items[].totalPrice | string | Сумма (цена * количество). Разделитель - точка. | pay |
| fiscalInformation. items[].vat | string | Ставка НДС. Возможные значения: None - Без НДС; Vat0 - НДС по ставке 0%; Vat10 - НДС по ставке 10%; Vat20 - НДС по ставке 20%. | pay |
ТЕСТИРОВАНИЕ
Данные для тестирования платежных продуктов находятся в отдельном разделе.
# Сохранение дополнительной информации
Вы можете передавать в запросе дополнительную информацию о платеже.
Массив customValues может содержать до 8 пар параметров, которые отображаются плательщику в правом блоке платежной страницы. Объект metadata может содержать json с любыми названиями полей и их значениями, при этом плательщику они не отображаются.
Например, кредитная организация принимает ежемесячные платежи от своих клиентов.
Массив customValues может содержать номер договора и сумму комиссии с плательщика. Объект metadata пусть содержит источник (source), из которого плательщик открыл платежную страницу, и дату отправки уведомления (sent_at).
Синхронный ответ и асинхронное callback-уведомление могут содержать более широкий набор параметров по сравнению с примером.
Запрос
POST https://secure.mandarinpay.com/api/transactions
{
"payment": {
"action": "pay",
"orderId": "your_unique_order_id",
"price": "1030.00"
},
"customerInfo": {
"email": "user@example.com",
"phone": "+79001234567"
},
"customValues": [
{"name": "Номер договора", "value": "К-12345-789"},
{"name": "Комиссия", "value": "30.00"}
],
"metadata": {
"source": "email",
"sent_at": "2020-01-31"
},
"urls": {
"callback": "http://...",
"return": "http://..."
}
}
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725",
"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
"jsOperationId": "9874694yr87y73e7ey39ed80"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
ОБРАБОТКА ДАННЫХ
Значения value из массива customValues сохраняются в параметрах cs2, cs3, cs4, cs5, cs6, cs7, cs8, cs9 в том порядке, в которым они были переданы (если не переданы, то значения - пустые). Они являются частью платежной транзакции и доступны из личного кабинета, в callback-уведомлении и т.д.
Блок metadata может иметь сложную структуру. Он возвращается только в callback-уведомлении точно в таком же виде, в котором был передан. В дальнейшем эта информация не сохраняется.
# Синхронные ответы
# HTTP-коды
Mandarin использует стандартные HTTP-коды статуса для индикации успешности или неуспешности API-запросов.
| Код | Описание |
|---|---|
2хх | Запрос обработан. |
4хх | Параметры, переданные клиентом, некорректны (отсутствие нужного формата, неверно сформированный заголовок и т.д.). Например, 401 при ошибке авторизации. |
5хх | Внутренняя ошибка на стороне Mandarin (довольно редкий случай). |
# Параметры ответов
| Параметр | Обязателен | Описание |
|---|---|---|
| id | Да | Идентификатор созданной операции или токен карты |
| userWeblink | Нет | Ссылка для перенаправления пользователя при работе с платежной страницей |
| jsOperationId | Нет | Идентификатор операции для использования с Mandarin Custom Pay |
| error | Нет | Текстовое описание ошибки |
Каждый вызов API имеет ассоциируемый с ним идентификатор, который называется ID транзакции и передается в синхронном ответе как значение параметра id. Для запроса токенизации он является токеном карты, а для запроса платежа/выплаты его называют ID транзакции. Он также присутствует в составе callback-уведомления в качестве значения поля transaction (для платежей/выплат) или card_binding (для токенизаций).
ID транзакции (его также называют ID платежа) также доступен в таблице транзакций по ссылке в личном кабинете (opens new window) и в интерфейсе HeartBeat.
СОВЕТ
При обращении в Cлужбу поддержки (opens new window) по вопросам с конкретной транзакцией, сообщите ее ID транзакции! Это существенно ускорит получение ответа.
После получения синхронного ответа могут быть три варианта действий:
- Для использования платежной страницы
Перенаправить пользователя по ссылке, полученной в качествеuserWebLink(подробнее) - Для использования встраиваемой формы Mandarin Custom Pay
Использовать значение изjsOperationIdв качествеoperationId(подробнее) - Дальнейшие действия не требуются
В этом случае в синхронном ответе будет получен толькоid.
Ответ в случае успешного создания транзакции (200 ОК)
{
"id": "43913ddc000c4d3990fddbd3980c1725",
"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
"jsOperationId": "9874694yr87y73e7ey39ed80"
}
Ответ в случае успешной токенизации (200 ОК)
{
"id": "0eb51e74-e704-4c36-b5cb-8f0227621518",
"userWebLink": "https://secure.mandarinpay.com/CardBindings/New?id=0eb51e74-e704-4c36-b5cb-8f0227621518",
"jsOperationId": "binding-4994591t5-194t694159t-43t5345"
}
Ответ в случае, если транзакция не создана (400 Bad request)
{
"error": "Invalid request"
}
# Асинхронные уведомления о статусе (callbacks)
# Аутентификация уведомлений
Для подтверждения того, что уведомление пришло именно от системы Mandarin, а также того факта, что данные, переданные в уведомлении, не были искажены, необходимо проверять значение параметра sign.
Поле sign представляет из себя хэш SHA256 от значений всех параметров уведомления, отсортированных по алфавиту и значения secret, разделённых символом -.
ОБРАТИТЕ ВНИМАНИЕ
Для проверки sign, все параметры уведомления должны быть отсортированы в алфавитном порядке с использованием стандартного алгоритма сортировки вашего языка программирования.
Для проверки корректности расчета значения sign можете воспользоваться специальной утилитой (opens new window).
- Вставьте тело
callbackв поле (1); - Вставьте
secretв поле (2); - Значение
signбудет рассчитано автоматически в поле (3).
# Параметры уведомлений
Content-Type для асинхронных уведомлений принимает значение application/x-www-urlencoded.
Уведомления высылаются в виде POST-запроса на адрес, который был передан в соответствующем запросе в опциональном параметре urls.callback.
Если параметр не был передан, то для отправки POST-запроса используется адрес, который был указан в личном кабинете на закладке Интеграция.
ВАЖНО!
Количество параметров в callback-уведомлении может меняться. Могут добавляться новые параметры. Кроме того, в каждом уведомлении присутствует "соль" (параметр и значение со случайными данными).
Поэтому важно не хардкодить набор параметров!
Перечень и описание параметров, передаваемых в составе callback-уведомления
Параметр object_type хранит в себе тип: transaction (Платеж / Выплата) или card_binding(Токенизация карты). В зависимости от его значения, меняется набор других параметров!
Параметры в POST-запросе передаются в формате x-www-form-urlencoded.
| Параметр | Обязателен | Описание |
|---|---|---|
| 16797d04-d688-4a55-8190-861224243701 | Да | Соль (UUID для названия и для значения параметра генерируются случайным образом). |
| 3dsecure | Нет | Индикатор подтверждения платежа с помощью ввода кода 3-D Secure. |
| action | Нет | Действие (платеж pay, выплата payout, возврат reversal, предавторизация preauth ), актуально только для транзакций. |
| callbackUrl | Нет | Адрес для отправки callback. |
| card_binding | Нет | Токен карты в системе, актуален только для токенизаций. |
| card_expiration_month | Нет | Месяц срока действия карты. |
| card_expiration_year | Нет | Год срока действия карты. |
| card_holder | Нет | Владелец карты (в формате URL-encoded). |
| card_id | Нет | Хэш от полного номера карты (для токенизаций и платежей). |
| card_info_bank | Нет | Название банка-эмитента карты (в формате URL-encoded). |
| card_info_country | Нет | Страна банка-эмитента карты (в формате ISO 3166-1 alpha-3 (opens new window)). Например, RUS. |
| card_info_type | Нет | Название международной платежной системы карты. Например, mastercard. |
| card_info_card_type | Нет | Тип карты. Например, Debit. |
| card_info_product_name | Нет | Название продукта карты. Например, Visa Rewards. |
| card_info_product_code | Нет | Код продукта карты. Например, N1. |
| card_info_issuing_bank | Нет | Банк эмитент. Например, Tinkoff Bank. |
| card_info_iso_country_a3 | Нет | Страна выпуска карты. Например, RUS. |
| card_number | Нет | Номер карты (маскированный). |
| cb_customer_creditcard_number | Нет | Номер карты (маскированный), поле будет убрано в следующих версиях. |
| cb_processed_at | Нет | Дата и время обработки операции. |
| customer_fullName | Нет | ФИО пользователя. |
| customer_email | Нет | Адрес email пользователя. |
| customer_phone | Нет | Телефон пользователя. |
| customName0 | Нет | Имя первого параметра (в формате URL-encoded), переданного в массиве customValues в составе запроса на оплату или токенизацию. Может существовать до 8 параметров: customName0, customName1, ... , customName7. |
| customValue0 | Нет | Значение первого параметра (в формате URL-encoded), переданного в массиве customValues в составе запроса на оплату или токенизацию. Может существовать до 8 параметров: customValue0, customValue1, ... , customValue7. |
| Нет | Email пользователя. | |
| error_code | Нет | Код ошибки. Отсутствие кода не гарантирует успешность операции! |
| error_description | Нет | Описание ошибки. |
| gw_channel | Нет | Название канала для перевода средств. |
| gw_id | Нет | ID канала для перевода средств. |
| initial_hold_amount | Нет | Сумма авторизации, обязательна только для токенизаций. |
| merchantId | Да | ID мерчанта. |
| metadata_* | Нет | Параметры, переданные в объекте metadata в составе запроса на оплату или токенизацию. Имеют префикс metadata_. |
| object_type | Да | Тип объекта (платеж/выплата transaction или токенизация card_binding). |
| orderActualTill | Нет | Срок резервирования товара/услуги. После указанной даты оплата будет невозможна. |
| orderId | Да | Уникальный номер заказа в вашей системе. |
| payment_system | Нет | Константа mandarinpayv1, поле будет убрано в следующих версиях. |
| price | Нет | Сумма платежа, обязательна только для транзакций. |
| returnUrl | Нет | Адрес магазина для переадресации по окончанию операции. |
| status | Да | Статус операции: success, failed, payout-only. Только статус success однозначно указывает на успешность операции! |
| transaction | Нет | ID транзакции в системе. Актуален только для транзакций. |
| transaction_rrn | Нет | RRN транзакции. |
| sign | Да | Подпись для аутентификации (всегда последним). |
# Параметры в объекте metadata
Запрос на токенизацию или оплату может включать в себя объект metadata, который содержит список ваших параметров с любыми названиями и любыми значениями, которые будут отправлены в callback-уведомлении.
При этом на платежной странице они не будут показаны пользователю.
Например, для запроса на токенизацию:
POST https://secure.mandarinpay.com/api/card-bindings
{
"customerInfo": {
"email": "user@example.com",
"phone": "+79001234567"
},
"metadata": {
"first_param": "p1",
"second_param": "p2"
}
}
Подробнее про использование объекта metadata в запросах можно прочитать в главе Сохранение дополнительной информации.
Callback-уведомление, наряду с остальными параметрами, будет включать в себя параметры из запроса, но с префиксом metadata_:
metadata_first_param=p1&metadata_second_param=p2
# Примеры уведомлений
Пример callback-уведомления об оплате
merchantId=1&orderId=e75c444d-22b4-4e1c&email=79691112211%40mail.ru&orderActualTill=2024-01-30%2006%3A59%3A28Z&price=100.00&callbackUrl=https%3A%2F%2test.ru%2Fpayment%2F60e70526%2Fe75c444d-22b4-4e1c%2Fpayment%2F&action=pay&customer_fullName=%20%20&customer_phone=%2B79691112211&customer_email=79691112211%40test.ru&transaction=1a79f7d8122048929299a7ee87aed&object_type=transaction&status=failed&payment_system=mandarinpayv1&card_number=220220XXXXXX1111&cb_customer_creditcard_number=220220XXXXXX1111&gw_channel=psb_direct&transaction_rrn=402822221111&error_code=51&error_description=Not%20sufficient%20funds&gw_id=107211111&card_id=7c5d587672909558a075fd11111111&e72d8031-d96f-4d1f-953d-779cb693ad7d=65ce05ec-f35a-4f1f-b00c&sign=b6c39660225e7e4d22b7ce535edc
Пример callback-уведомления о токенизации полных карточных данных
card_binding=a7446082-02a4&card_holder=ALEKSANDR%20IVANOV%20&card_number=427605XXXXXX1111&card_expiration_year=2023&card_expiration_month=2&object_type=card_binding&status=success&merchantId=1&initial_hold_amount=1.00000&3dsecure=true&gw_id=1072811&card_id=99bb78de64def70b063c11111&card_info_country=RUS&card_info_type=visa&card_info_bank=SBERBANK&card_info_product_name=Visa%20Classic&card_info_product_code=F&card_info_card_type=Debit&card_info_issuing_bank=SBERBANK&card_info_iso_country_a3=RUS&9870f8a5=8f5b0fe8-a587-4de0ea9808dc&sign=8eada97da58c5287f4b08a2e75dd0fe1111
Пример callback-уведомления о токенизации со статусом payout-only
card_binding=9b2980ab-6247&card_holder=HALVA%20CARD&card_number=553609XXXXXX1111&card_expiration_year=27&card_expiration_month=1&object_type=card_binding&status=payout-only&merchantId=1&initial_hold_amount=1.00000&3dsecure=true&gw_id=1111&card_id=3e8dd9d3265221111111&card_info_country=RUS&card_info_type=mastercard&card_info_bank=Sovcombank&card_info_product_name=Mastercard%20World%20Card&card_info_product_code=MNW&card_info_card_type=Credit&card_info_issuing_bank=Sovcombank&card_info_iso_country_a3=RUS&0e5d3ca6-=9317d7e6-6d29-4d34-af62-1&sign=e8867ef06f61ab00465336275c5b1111111
Пример callback-уведомления о выплате с использованием токена карты
merchantId=1&orderId=112244&email=test%40mail.ru&orderActualTill=2024-01-30%2007%3A33%3A39Z&price=100&action=payout&customer_fullName=%20%20&customer_phone=%2B7911111111&customer_email=test%40mail.ru&transaction=3d1d4a7c2f794e479e2cdd351111111&object_type=transaction&status=failed&payment_system=mandarinpayv1&gw_channel=psb_direct&transaction_rrn=4028471111111&error_code=51&error_description=Not%20sufficient%20funds&gw_id=107281111&card_id=811d78e08b41ce51e450eb81111111&fe18a06c-e010-4a07-985e-1111111=3bd5e84b-f3f2-41d7-86ed-e994a7336144&sign=91feebac525892a32d8effe11111111
Пример callback-уведомления о выплате с использованием номера карты
merchantId=1&orderId=9537D957-AC43-4853-AB47-4E39BCFFF3FC&email=sadukin%40mail.ru&orderActualTill=2021-02-22%2010%3A48%3A17Z&price=2000.0&callbackUrl=http%3A%2F%2Fmail.example.com%3A4000%2Fapi%2Fmandarin%2Fpayout%2Fcallback&action=payout&customName0=manager_id&customValue0=E099D738-CED4-48F2-A21C-36C0EA25A549&customName1=dealer_id&customValue1=BD251868-EACA-483D-91F3-954543576F93&customName2=customer_id&customValue2=A54856FA-3A81-4742-AA73-743389D536A9&customer_fullName=%20%20&customer_phone=%2B79273884129&customer_email=sadukin%40mail.ru&transaction=52f1874b9bd846e7ab14c9f96fb9bc17&object_type=transaction&status=success&payment_system=mandarinpayv1&cb_processed_at=2021-02-20T10%3A48%3A22.7232790Z&card_number=546906XXXXXX1568&cb_customer_creditcard_number=546906XXXXXX1568&gw_channel=open_way4&transaction_rrn=105199356489&error_code=51&error_description=Not%20sufficient%20funds&gw_id=39104021&709b674c-1f5e-424d-841e-1244d7b71041=9ee4b553-f961-4da9-b9dc-0924c0260d33&sign=a63189b75147a8bd2326baaacdd482d902206b5b6fe6de5f0df464e698b47912
Пример callback-уведомления об авторизации при двухстадийной оплате
merchantId=1&orderId=11&email=test%40mail.ru&orderActualTill=2024-01-24%2017%3A22%3A24&price=1&callbackUrl=https%3A%2F%2Fwww.test.ru%2Fother%2Fcompany%2Fpaymenthold.php&action=preauth&customName0=tcustomValue0=test&customer_fullName=test&customer_phone=%2B797881111111&customer_email=test%40mail.ru&metadata_inv_id=36&transaction=3c35c083f7eb4bed8373b9341111111&object_type=transaction&status=failed&payment_system=mandarinpayv1&sandbox=false&error_code=888&error_description=Order%20expired&faeef3a9-1095-4513-b6f9-504cf3920c0a=ae7db577-1fac-4154-9a8e-11111111&sign=b57daf7804f7e252235f6901c435ac8f1e10063aba518d034617db31111111
Пример callback-уведомления о возврате
merchantId=1&orderId=11&email=test%40mail.ru&orderActualTill=2024-03-10%2004%3A55%3A08Z&price=999.00&action=reversal&customer_fullName=%20%20&customer_phone=%2B79690000099&customer_email=test%40mail.ru&transaction=2f0006a3ed00000fae177e29aba7bb00&object_type=transaction&status=success&payment_system=mandarinpayv1&cb_processed_at=2024-03-08T05%3A01%3A17.7798144Z&gw_channel=psb_direct&transaction_rrn=401117511111&gw_id=111111143&card_id=d8632ed1111148b37a11111010611111&433a288b-de02-461c-aac6-9d328311111=e93e7a57-1111-1111-1111-37ae0da11111&sign=85b5a211111b2b9482111118c5035311111f856a111a83c89ee111116cbfc8
Примеры проверки sign
<?php
function check_sign($secret, $req)
{
$sign = $req['sign'];
unset($req['sign']);
$to_hash = '';
if (!is_null($req) && is_array($req)) {
ksort($req);
$to_hash = implode('-', $req);
}
$to_hash = $to_hash .'-'. $secret;
$calculated_sign = hash('sha256', $to_hash);
return $calculated_sign == $sign;
}
check_sign("123", $_POST);
?>
public static string Calculate(string secret, IDictionary<string, string> values)
{
using (var sha256 = System.Security.Cryptography.SHA256.Create())
return BitConverter.ToString(sha256.ComputeHash(Encoding.UTF8.GetBytes(string.Join("-", values.OrderBy(x => x.Key, StringComparer.Ordinal).Select(x => x.Value)) + "-" + secret))).ToLower().Replace("-", "");
}
public static bool CheckSign(string secret, HttpRequest request)
{
var sign = request.Form["sign"];
if(string.IsNullOrWhiteSpace(sign))
return false;
return sign ==
Calculate(secret, request.Form.Keys.Where(k => k != "sign").ToDictionary(k => k, k => request.Form[k]));
}
# Повторная отправка уведомлений
В качестве ответа, обозначающего, что callback успешно обработан на вашей стороне, необходимо вернуть в Mandarin ответ с HTTP-кодом 200 и телом OK.
ВАЖНО!
Любой другой ответ будет означать, что callback не обработан. В этом случае Mandarin повторяет отправку callback-запроса в течение 3 суток, или до получения ответа об успешной обработке (в зависимости от того, что наступит раньше).
# Лимиты для запросов к API
Ограничения и лимиты для запросов к API:
На рекуррентные платежи: не более 10 запросов в секунду, и не более 300 запросов в минуту.
На возвраты: максимальная сумма возврата, и максимальное количество возвратов (устанавливается по заявке клиента).
На платежи: лимит на покупку (устанавливается по заявке клиента).
# Подготовка и инструменты
# Аутентификационные данные
Чтобы начать работать с Mandarin, вам нужно зарегистрироваться, получить активацию учетной записи клиентским менеджером и зайти по ссылке в личный кабинет (opens new window).
Для получения MID и Secret в Личном кабинете следуйте инструкции (opens new window)
ВАЖНО!
Обратите внимание, что секретный ключ (Secret) ни в каком виде не должен покидать вашего сервера. В случае если он передаётся как часть HTML или каким-либо образом используется в JavaScript, это является проблемой безопасности и даёт злоумышленнику возможность делать вызовы к платёжной системе от вашего имени.
Для дополнительной безопасности для каждого MID можно включить опцию по приему запросов только от IP-адресов из белого списка (opens new window) (white list). Возможность включается по заявке в Cлужбу поддержки (opens new window).
# Мониторинг запросов и уведомлений (HeartBeat)
HeartBeat (opens new window) - инструмент для мониторинга платежных транзакций и асинхронных уведомлений (callbacks). Для входа используется стандартная авторизация.
Возможности:
Мониторинг запросов на платежные транзакции: ссылка для перехода в HeartBeat - Транзакции (opens new window).
Мониторинг токенизаций банковских карт: ссылка для перехода в HeartBeat - Токены (opens new window).
Мониторинг callback-уведомлений, на которые Mandarin не получил от вас ответ со статусом
200 OK: ссылка для перехода в HeartBeat - Уведомления (opens new window).Сервис выплат по реестрам: ссылка для перехода в HeartBeat - Выплаты (opens new window).
Более подробная информация содержится в инструкции (opens new window)