# Основы
Mandarin – универсальное решение для работы с онлайн-платежами. API Mandarin построено на REST-принципах. С помощью него вы сможете принимать платежи с банковской карты, получать токен карты и использовать его для повторных списаний, делать возвраты, производить выплаты на карты, используя множество опций. Поддерживаются международные платежные системы МИР, Visa, MasterCard, UnionPay International (UPI) (opens new window).
API использует протокол HTTPS и TLS не ниже 1.2 (запросы с HTTP или TLS 1.0, 1.1 будут отклоняться), а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTPS-библиотеками.
API работает с POST и GET-запросами. POST-запросы принимают аргументы в JSON, GET-запросы работают со строками запросов. Ответ всегда будет в JSON, независимо от типа запроса.
API является асинхронным (незначительная часть запросов работает синхронно): на ваш запрос вы синхронно получите идентификатор платежа (запроса), а затем в асинхронном режиме получите callback-уведомление, включающее полученный ранее идентификатор платежа (запроса), а также статус операции и прочие данные по ней.
# Тестовое и боевое окружение
API реализовано на тестовом (sandbox) и боевом (production) окружениях. Запросы, создаваемые в тестовом окружении, никогда не передаются в банковские информационные системы и, следовательно, не приводят к возникновению реальных транзакций. Также в отдельных случаях возможна работа в боевом окружении API с моками, имитирующими поведение банковских систем.
Поведение зависит от сервиса:
- Основной Public API (платежи, выплаты, токенизация) — окружение определяется учетными данными: тестовый
Secretдает sandbox, боевой — production. URL API одинаковый. - УПРИД, самозанятые, BaaS и другие сервисы — доступ к тестовому окружению и OAuth-приложения настраивает Служба поддержки (opens new window). Уточняйте порядок подключения в разделе Тестирование.
Тестовые запросы не приводят к реальным транзакциям в банковских системах.
# Аутентификация запросов
Способ зависит от используемого API.
# X-Auth
Используется в основном Public API: прием платежей, выплаты, токенизация, упрощенная идентификация.
В каждом запросе передается заголовок X-Auth — строка из merchantId, подписи и уникального requestId. Подпись рассчитывается как SHA256 от merchantId, requestId и Secret. Так Mandarin проверяет, что запрос отправлен владельцем учетной записи, и защищает от повторного использования одного и того же запроса.
Учетные данные (merchantId и Secret) берутся из личного кабинета.
Аутентификация запросов происходит за счет авторизационной строки, которая передается в параметре заголовка 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}";
}
# OAuth 2.0 (Bearer)
Используется в Бизнес API, API самозанятых и BaaS (роутинг).
Сначала по протоколу OAuth 2.0 с грантом client_credentials запрашивается access_token, затем он передается в заголовке Authorization: Bearer {token}. Токен действует ограниченное время (обычно 10 часов), после истечения его нужно запросить снова.
client_id и client_secret выдает Служба поддержки (opens new window).
Подробнее: Бизнес API, Самозанятые, BaaS.
Запрос на получение токена
Включает в себя обязательные form-data параметры, которые передаются в теле запроса (параметры application.client_id и application.client_secret неизменны для приложения и хранятся на стороне клиента).
| Параметр | Описание | Пример |
|---|---|---|
| grant_type | Грант авторизации (всегда равен client_credentials). | client_credentials |
| client_id | Идентификатор клиента (равен значению application.client_id, предоставленному Mandarin). | VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n |
| client_secret | Секретный ключ-пароль клиента (равен значению application.client_secret, предоставленному Mandarin). | uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7 |
| scope | Запрашиваемые скоупы (области доступа): например, transactions.read - "Чтение транзакций". Разделитель - пробел. Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения. | transactions.read |
curl --request POST \
--url https://accounts.mandarinbank.com/oauth/token/ \
--form 'grant_type=client_credentials' \
--form 'client_id={{client_id}}' \
--form 'client_secret={{client_secret}}' \
--form 'scope=transactions.read'
Ответ
| Параметр | Описание | Пример |
|---|---|---|
| access_token | Токен (ключ доступа). | VnuxZiW14mXBedDeZO7d W7GBmzPxMn |
| expires_in | Срок действия токена (в секундах). Всегда равен 36 000 секунд (10 часов). | 36000 |
| token_type | Тип токена (всегда равен Bearer). | Bearer |
| scope | Разрешенные скоупы (области доступа): например, transactions.read - "Чтение транзакций". Разделитель - пробел. Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения. | transactions.read |
{
"access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "transactions.read"
}
Использование токена
Указывается в headers каждого запроса, в поле Authorization, после зарезервированного слова Bearer.
Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn
# X-Api-Key
Используется в API единой платежной формы (создание счетов/invoices).
API-ключ создается в личном кабинете в настройках платежной ссылки (раздел «Интеграция») и передается в заголовке Authorization: X-Api-Key: {ключ}.
Подробнее: Быстрый старт — единая платежная форма.
# Callback-уведомления
Уведомления от Mandarin на ваш callbackUrl подписываются полем sign. Проверяйте подпись на своей стороне перед обработкой статуса операции.
Для подтверждения того, что уведомление пришло именно от системы 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, авторизация auth, предавторизация preauth, выплата payout, возврат reversal), актуально только для транзакций. |
| 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 суток, или до получения ответа об успешной обработке (в зависимости от того, что наступит раньше).
# Запросы
# Точки входа
Точки входа для тестового (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
# Параметры запросов
Content-Type для запросов принимает значение application/json.
Вы можете загрузить коллекцию для Postman, в которую уже введены все запросы из данного раздела.
| Параметр | Тип | Описание и возможные значения | Где используется (action) |
|---|---|---|---|
| payment | object | Объект, содержащий данные о транзакции. | pay, auth, preauth, reversal, payout |
| payment.action | string | Тип транзакции. Возможные значения: pay - Платеж; auth - Авторизация; preauth - Предавторизация; reversal - Отмена транзакции; payout - Выплата. | pay, auth, preauth, reversal, payout |
| payment.orderId | string | Номер заказа в вашей системе. Должен быть уникальным среди успешных операций! | pay, auth, preauth, reversal, payout |
| payment.price | string | Сумма платежа. Разделитель - точка. | pay, auth, preauth, reversal, payout |
| payment. orderActualTill | string | Срок резервирования товара/услуги. После указанной даты платеж будет невозможен. Формат: 2020-02-20 12:34:56+00:00. Если параметр не указывается, то действует стандартный срок 48 часов. | pay, auth, preauth |
| customerInfo | object | Объект, содержащий данные о пользователе. | pay, auth, preauth, reversal, payout, card-binding |
| customerInfo. email | string | Email пользователя. Формат: user@example.com. | pay, auth, 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, auth, preauth, reversal, payout |
| customValues[]. name | string | Заголовок параметра (отображаемый в правом блоке платежной страницы). | pay, auth, preauth, reversal, payout |
| customValues[]. value | string | Значение параметра (отображаемое в правом блоке платежной страницы). | pay, auth, preauth, reversal, payout |
| metadata | object | Объект, содержащий список ваших параметров с любыми названиями и любыми значениями, которые будут отправлены в callback-уведомлении. Параметры не отображаются в пользовательском интерфейсе плательщика. Названия параметров не могут содержать пробелы! | pay, auth, preauth, reversal, payout |
| urls | object | Объект, содержащий url. Если отсутствует, то используются url из настроек. | pay, auth, preauth, reversal, payout, card-binding |
| urls.return | string | Url для редиректа пользователя после платежа. Редирект пользователя на указанный Url происходит после нажатия на кнопку "Вернуться на сайт" на платежной странице, либо автоматически после успешной оплаты. По умолчанию автоматический редирект отключен, для подключения обратитесь в Службу технической поддержки (opens new window). | pay, auth, preauth, reversal, payout, card-binding |
| urls.callback | string | Url для отправки callback-уведомления о статусе трaнзакции. | pay, auth, 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"
}
# Лимиты для запросов к 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)