# Основные принципы

# Схема взаимодействия

Diagram

# Запросы

# Точки входа

Точки входа для тестового (sandbox) и боевого (production) окружения одинаковы. Mandarin определяет окружение по аутентификационным данным (а именно, по значению секретного ключа Secret).

Точка входа для создания транзакций

Используется для всех основных операций (например, для приема платежей и выплат на карту).

POST https://secure.mandarinpay.com/api/transactions

Точка входа для токенизации карт

Используется только для токенизации карт.

POST https://secure.mandarinpay.com/api/card-bindings

Точка входа для упрощенной идентификации

Процесс идентификации значительно отличается от остальных и описан на отдельной странице. При этом используется стандартный для Mandarin способ аутентификации.

POST https://secure.mandarinpay.com/api/personidentification

Точка входа для Routes

Решение для маркетплейсов Mandarin Routes (Роутинг) также значительно отличается от остальных.

Для тестового и боевого окружения используются различные точки входа. При этом нужно использовать соответствующие аутентификационные данные (значения секретного ключа Secret для тестового и боевого окружений разные).

Боевое окружение (prod)

POST https://api.mandarinpay.com/v1/...

Тестовое окружение (stage)

POST https://api-sandbox.mandarinpay.com/v1/...

Способ аутентификации при этом тоже стандартный для продуктов Mandarin.

# Параметры запросов

Content-Type для запросов принимает значение application/json.

Параметры запросов для приема платежей, токенизации и выплат на банковские карты описаны в отдельном разделе.

# Аутентификация запросов

Аутентификация запросов происходит за счет авторизационной строки, которая передается в параметре заголовка 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.

# Синхронные ответы

# HTTP-коды

Mandarin использует стандартные HTTP-коды статуса для индикации успешности или неуспешности API-запросов.

Код Описание
2хх Запрос обработан.
4хх Параметры, переданные клиентом, некорректны (отсутствие нужного формата, неверно сформированный заголовок и т.д.).
5хх Внутренняя ошибка на стороне Mandarin (довольно редкий случай).

# Параметры ответов

Параметр Обязателен Описание
id Да id созданной операции
userWeblink Нет Ссылка для перенаправления пользователя при работе с платежной страницей
jsOperationId Нет Идентификатор операции для использования с Mandarin Custom Pay
error Нет Текстовое описание ошибки

Каждый вызов API имеет ассоциируемый с ним идентификатор, который называется ID транзакции и передается в синхронном ответе как значение параметра id. Для запроса токенизации он является токеном карты, а для запроса платежа/выплаты его называют ID транзакции. Он также присутствует в составе callback-уведомления в качестве значения поля transaction (для платежей/выплат) или card_binding (для токенизаций).

ID транзакции (его также называют ID платежа) также доступен в таблице транзакций в личном кабинете(opens new window) и в интерфейсе HeartBeat.

Transaction ID

СОВЕТ

При обращении в Cлужбу поддержки(opens new window) по вопросам с конкретной транзакцией, сообщите ее ID транзакции! Это существенно ускорит получение ответа.

После получения синхронного ответа могут быть три варианта действий:

  1. Для использования платежной страницы
    Перенаправить пользователя по ссылке, полученной в качестве userWebLink (подробнее)
  2. Для использования встраиваемой формы Mandarin Custom Pay
    Использовать значение из jsOperationId в качестве operationId (подробнее)
  3. Дальнейшие действия не требуются
    В этом случае в синхронном ответе будет получен только 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)

# Параметры уведомлений

Content-Type для асинхронных уведомлений принимает значение application/x-www-urlencoded.

Уведомления высылаются на адрес, который был передан в соответствующем запросе в опциональном параметре urls.callback. Если параметр не был передан, то используется адрес, который был указан в личном кабинете на закладке Интеграция.

ВАЖНО!

Количество параметров в callback-уведомлении может меняться. Могут добавляться новые параметры. Кроме того, в каждом уведомлении присутствует "соль" (параметр и значение со случайными данными).
Поэтому важно не хардкодить набор параметров!

Перечень и описание параметров, передаваемых в составе callback-уведомления

Параметр object_type хранит в себе тип: transaction (Платеж / Выплата) или card_binding(Токенизация карты). В зависимости от его значения, меняется набор других параметров!

Параметр Обязателен Описание
16797d04-d688-4a55-8190-861224243701 Да Соль (UUID для названия и для значения параметра генерируются случайным образом).
3dsecure Нет Индикатор подтверждения платежа с помощью ввода кода 3-D Secure.
action Нет Действие (платеж pay или выплата payout), актуально только для транзакций.
callbackUrl Нет Адрес для отправки callback.
card_binding Нет Токен карты в системе, актуален только для токенизаций.
card_expiration_month Нет Месяц срока действия карты.
card_expiration_year Нет Год срока действия карты.
card_holder Нет Владелец карты.
card_number Нет Номер карты (маскированный).
cb_processed_at Нет Дата и время обработки операции.
customer_fullName Нет ФИО пользователя.
customer_email Нет Адрес email пользователя.
customer_phone Нет Телефон пользователя.
destinationWallet Нет id аккаунта получателя. Только для Routes.
email Нет Email пользователя.
error_code Нет Код ошибки. Отсутствие кода не гарантирует успешность операции!
error_description Нет Описание ошибки.
gw_channel Нет Название канал для перевода средств.
gw_id Нет ID канала для перевода средств.
initial_hold_amount Нет Сумма авторизации, обязательна только для токенизаций.
merchantId Да ID мерчанта.
metadata Нет Данные в формате json, переданные при создании объекта.
object_type Да Тип объекта (платеж/выплата transaction или токенизация binding).
orderActualTill Нет Срок резервирования товара/услуги. После указанной даты оплата будет невозможна.
orderId Да Уникальный номер заказа в вашей системе.
price Нет Сумма платежа, обязательна только для транзакций.
returnUrl Нет Адрес магазина для переадресации по окончанию операции.
sourceWallet Нет id аккаунта отправителя. Только для Routes.
status Да Статус операции: success, failed, payout-only. Только статус success однозначно указывает на успешность операции!
transaction Нет ID транзакции в системе. Актуален только для транзакций.
transaction_rrn Нет RRN транзакции.
sign Да Подпись для аутентификации (всегда последним).

# Аутентификация уведомлений

Для подтверждения того, что уведомление пришло именно от системы Mandarin, а также того факта, что данные, переданные в уведомлении, не были искажены, необходимо проверять значение параметра sign.

Поле sign представляет из себя хэш SHA256 от значений всех параметров уведомления, отсортированных по алфавиту и значения secret, разделённых символом -.

ОБРАТИТЕ ВНИМАНИЕ

Для проверки sign, все параметры уведомления должны быть отсортированы в алфавитном порядке с использованием стандартного алгоритма сортировки вашего языка программирования.

Для проверки корректности расчета значения sign можете воспользоваться специальной утилитой(opens new window) .

Sign Calculator UI

  • Вставьте тело callback в поле (1);
  • Вставьте secret в поле (2);
  • Значение sign будет рассчитано автоматически в поле (3).

# Повторная отправка уведомлений

В качестве ответа, обозначающего, что callback успешно обработан на вашей стороне, необходимо вернуть в Mandarin ответ с HTTP-кодом 200 и телом OK.

ВАЖНО!

Любой другой ответ будет означать, что callback не обработан. В этом случае Mandarin повторяет отправку callback-запроса в течение 3 суток, или до получения ответа об успешной обработке (в зависимости от того, что наступит раньше).

# Примеры уведомлений

Пример callback-уведомления об оплате

merchantId=1&orderId=03917&email=sadukin%40mail.ru&price=11040&action=pay&customer_fullName=%20%20&customer_phone=%2B79189271304&customer_email=sadykin%40mail.ru&transaction=60a186c112e24b90ad839bb7bc65a9ff&object_type=transaction&status=success&payment_system=mandarinpayv1&card_number=403841XXXXXX6022&cb_customer_creditcard_number=403841XXXXXX6022&card_holder=RUSLAN%20SADYKOV&card_expiration_year=19&card_expiration_month=05&transaction_rrn=718791158407&d000d97e-a0db-4e56-9460-6934e4bec050=4d3bb82f-fd4f-43c6-b809-2aec91e0de8a&sign=ca3f0443a3fc60d96d2197f8dbf93deb5d6e3922a5854ed526e2c11ca723eb3

Пример callback-уведомления о токенизации

card_binding=abbd431d-fb01-4bf9-9eb9-773b794c2df9&card_holder=RULSAN%20MALYGIN&card_number=427638XXXXXX3811&card_expiration_year=2018&card_expiration_month=11&object_type=card_binding&status=success&merchantId=1&initial_hold_amount=1&orderId=1147710&f9d6c9d1-f4d4-4a3e-8ccf-9421eb483792=0ac5dff9-7aea-4d2f-90ac-c16d730cf2a1&sign=ee8d74a8b80c407a662dcf3ddf2260ba9de0cbb0bb455e8a429b7035205782c6

Пример callback-уведомления со статусом payout-only

card_binding=abbd431d-fb01-4bf9-9eb9-773b794c2df9&card_holder=RULSAN%20MALYGIN&card_number=427638XXXXXX3811&card_expiration_year=2018&card_expiration_month=11&object_type=card_binding&status=payout-only&merchantId=1&initial_hold_amount=1&orderId=1147710&f9d6c9d1-f4d4-4a3e-8ccf-9421eb483792=0ac5dff9-7aea-4d2f-90ac-c16d730cf2a1&sign=ee8d74a8b80c407a662dcf3ddf2260ba9de0cbb0bb455e8a429b7035205782c6

Примеры проверки 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]));
}