NAV
PHP C#

Introduction

Параметр Значение Комментарий
Номер карты 4929509947106878 Для имитации успешных транзакций без 3DSecure
Номер карты 4692065455989192 Для имитации успешных транзакций с 3DSecure
Номер карты 4485913187374384 Для имитации неуспешных транзакций без 3DSecure
Номер карты 4556058936309366 Для имитации неуспешных транзакций с 3DSecure
Имя держателя карты CARD HOLDER
CVV 123
Название Описание Cсылка
Приложение платежного шлюза Приложение позволяет ознакомиться с основными принципами и методами работы платежного API GitHub
Callback модуль платежного шлюза Данный модуль может перехватывать Callback вызовы, складывать из в БД, а так же отправлять email потранзакционно/реестром о совершенных операциях. Имеет API для запроса реестров из БД GitHub
Приложение информационного шлюза Приложение позволяет ознакомиться с основными принципами и методами работы информационного шлюза, в т.ч. упрощенной идентификации GitHub

HeartBeat

Для мониторинга транзакци/колбэков во время отладки лучше всего использовать HeartBeat.

Для входа используйте MerchantID и Secret в качестве логина и пароля соответственно.

HeartBeat - Транзакции - Мониторинг транзакций

HeartBeat - Привязки - Мониторинг привязок банковских карт

HeartBeat - Уведомления - Мониторинг callback-уведомлений, по которым наша система не получила от вашей 200й ответ - подробнее

API платежных форм

General items

Перечень и описание возможных полей при использовании API платежный форм (в т.ч. виджета и встроенной формы оплаты) приведены в таблице.

Поле Обяз-ть Описание
merchantId Да Id мерчанта
price Да Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId Да Номер заказа в системе Клиента. Должен быть УНИКАЛЬНЫМ внутри переводов транзакций типа payout
customer_email Да Email пользователя
sign Да Контрольная подпись данных о платеже. Методику подсчёта см. ниже
customNameX Нет X - Число от 1 до 4. Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа и отображается Плательщику на платежной странице в правом блоке. Передается совместно с customValueX
customValueX Нет X - Число от 1 до 4. Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа и отображается Плательщику на платежной странице в правом блоке. Передается совместно с customNameX.
extra_* Нет Данные поля используются в случае, если необходимо передать дополнительную информацию серверу и не видны Плательщику. Должны иметь вид extra_[A-Za-z0-9_]+
customer_phone Да/Нет Телефон пользователя в формате +XXXXXXXXXXX
callbackUrl Нет Url для отправки уведомления о статусе трназакции
returnUrl Нет Url для редиректа пользователя после оплаты
orderActualTill Нет Срок резервирования товара/услуги. После указанной даты оплата будет невозможна

Payment page (платежная страница)

<form action="https://secure.mandarinpay.com/Pay" method="POST"> 
<input type="hidden" name="merchantId" value="812" />  
<input type="hidden" name="price" value="12.34" /> 
<input type="hidden" name="orderId" value="325GVD" />
<input type="hidden" name="customer_email" value="test@test.com" /> 
<input type="hidden" name="customName1" value="client name 1" /> 
<input type="hidden" name="customValue1" value="client value 1" /> 
<input type="hidden" name="callbackUrl" value="http://yourdomnain.ru" />
<input type="hidden" name="returnUrl" value="http://yourdomnain.ru" />
<input type="hidden" name="sign" value="d41d8cd98f00b204e9800998ecf8427e" /> 
<input type="hidden" name="orderActualTill" value="2016-10-29 12:34:56+00:00" />
<input type="submit" value="Оплатить" /> 
</form>

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

POST запрос на адрес https://secure.mandarinpay.com/Pay

Необходимо сгенерировать и отправить форму.

Транзакция будет осуществлена в асинхронном режиме. Описание Callback-уведомлений представлено ниже.

Payment Widget (платежный виджет)

Скрипт

<script src="https://secure.mandarinpay.com/api/widget.js?version=2" type="text/javascript"></script>

Форма

<form onsubmit="return false;"> 
<input type="hidden" name="merchantId" value="812" />  
<input type="hidden" name="price" value="12.34" /> 
<input type="hidden" name="orderId" value="325GVD" />
<input type="hidden" name="customName1" value="client name 1" /> 
<input type="hidden" name="customValue1" value="client value 1" /> 
<input type="hidden" name="callbackUrl" value="http://yourdomnain.ru" />
<input type="hidden" name="returnUrl" value="http://yourdomnain.ru" /> 
<input type="hidden" name="action" value="pay" />
<input type="hidden" name="sign" value="d41d8cd98f00b204e9800998ecf8427e" />

<a href="#" onclick="return mandarin.payForm(this);">Оплатить</a>

</form>

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

Виджет оплаты представляет из себя окно, открываемое в iframe на стороне Продавца. Последующее открытие страницы с 3DS также происходит в iframe

Для использования виджета необходимо подключить скрипт, после чего использовать mandarin.payForm("#id_формы"); для показа виджета с оплатой. Форма генерируется тем же способом, что и при работе с API платежной страницы.

Так же можно использовать onclick="return mandarin.payForm(this);" в качестве обработчика ссылок и кнопок внутри формы оплаты.

Binding Widget (привязка через виджет)

<form onsubmit="return false;">
<input type="hidden" name="merchantId" value="812" />
<input type="hidden" name="orderId" value="325GVD" />
<input type="hidden" name="action" value="preauth" />
<input name='customer_phone' type="hidden" value='+71234567890' />
<input name='customer_email' type="hidden" value='user@example.com'/>
<input type="hidden" name="sign" value="d41d8cd98f00b204e9800998ecf8427e" />

<a href="#" onclick="return mandarin.bindCardForm(this);">Привязать</a>

</form>

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

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

Так же можно использовать mandarin.bindCardForm("#id");

Hosted Fields

<form id="form-hosted-pay">
  <input name="price" type="hidden" value="12.34" />
  <input name="orderId" type="hidden" value="123321" />
  <input name="merchantId" value="1" type="hidden" />
  <input name="sign" value="testing" type="hidden" />
  <input name='customer_phone' type="hidden" value='+71234567890' />
  <input name='customer_email' type="hidden" value='user@example.com' />
  <div style="margin: 10px; padding: 10px; border: 1px solid gray">
    Card Number:
    <div class="mandarinpay-field-card-number hosted-field"><div class="glyphicon glyphicon-check"></div></div>
    Card Holder:
    <div class="mandarinpay-field-card-holder hosted-field"><div class="glyphicon glyphicon-check"></div></div>
    Card Expiration:
    <div class="mandarinpay-field-card-expiration hosted-field"><div class="glyphicon glyphicon-check"></div></div>
    CVV:
    <div class="mandarinpay-field-card-cvv hosted-field"><div class="glyphicon glyphicon-check"></div></div>
    <br/>
    <a href="#" onclick="return mandarinpay.hosted.process(this);" class="btn btn-default">Оплатить</a>
  </div>
</form>
<script>
mandarinpay.hosted.setup("#form-hosted-pay", {
  onsuccess: function(data) {
    alert("Success, id: " + data.transaction.id);
  },
  onerror: function(data) {
    alert("Error: " + data.error);
  }
});
</script>

CSS для полей

.hosted-field
{
    background: #f0f0f0;
    height: 40px;
    padding: 5px;
    border: 1px solid gray;
    border-radius: 10px;
}

.hosted-field {
    position: relative;
}

.hosted-field .glyphicon {
    visibility: hidden;
    position: absolute;
    right: 5px;
    top: 5px;
    color: green;
    float: right;
}

.mandarinpay-field-state-error
{
    background: #fff0f0;
    border: 1px solid #900000;
}

.mandarinpay-field-state-focused
{
    background: #ffffff;
    border: 1px solid yellowgreen;
}

.mandarinpay-field-state-valid {
    background: #c0ffc0 !important;
    border: 1px solid green !important;
}

.mandarinpay-field-state-valid  .glyphicon{
    visibility: visible;
}

Безопасная встройка базируется на форме с полями, которые на самом деле являются отдельными страницами в iframe-ах. Соответственно, вы можете стилизовать всё, что эти самые iframe-ы окружает. Логически такая форма состоит из 3 частей:

Для начала работы необходимо подключить <script src="https://secure.mandarinpay.com/api/hosted.js"></script>, затем вызвать mandarinpay.hosted.setup, передав ему селектор формы, а так же функции для вызова при успехе либо ошибке. В обработчике события нажатия на кнопку следует вызвать return mandarinpay.hosted.process(this); (вместо this можно использовать селектор формы).

По мере взаимодействия формы с пользователем div-ам могут быть присвоены классы mandarinpay-field-state-error, mandarinpay-field-state-focused и mandarinpay-field-state-valid.

Пример:

screen

Тип операции

Тип операции указывается полем data-mandarinpay-object-type на теге form. Доступные значения: transaction, card-binding

Стилизация текстовых полей

Стилизация осуществляется посредством добавления соответствующего поля в объект, передаваемый mandarinpay.hosted.setup. Для изменения доступны плейсхолдер и ряд CSS-стилей

Пример стилизации

mandarinpay.hosted.setup("#form-hosted-pay",
{
    onsuccess: function(data) {alert("Success, id: " + data.transaction.id);},
    onerror: function(data) {alert("Error: " + data.error);},
    fields:
    {
        "card-number": {
            settings: {
                placeholder: "НОМЕР КАРТЫ",
                styles: {
                    "font-size": "20px",
                    "font-family": "Helvetica",
                    "color": "#0000c0"
                },
                placeholderStyles: {
                    "color": "pink"  
                },
            }
        }
    }
});

Для использования доступны

Pay By Loan (покупка в кредит/рассрочку)

<form action="https://secure.mandarinpay.com/Pay" method="POST"> 
<input type="hidden" name="merchantId" value="812" />  
<input type="hidden" name="price" value="12.34" /> 
<input type="hidden" name="orderId" value="325GVD" />
<input type="hidden" name="customer_email" value="test@test.com" />
<input type="hidden" name='customer_phone' value='+71234567890' /> 
<input type="hidden" name="customName1" value="client name 1" /> 
<input type="hidden" name="customValue1" value="client value 1" /> 
<input type="hidden" name="orderActualTill" value="2016-10-29 12:34:56+00:00" />
<input type="hidden" name="paymentMethod" value="credit" />
<input type="hidden" name="sign" value="d41d8cd98f00b204e9800998ecf8427e" /> 
<input type="submit" value="Оплатить" /> 
</form>

POST запрос на адрес https://secure.mandarinpay.com/Pay

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

Данный метод используется для подключения оплаты в кредит/рассрочку.

Необходимо сгенерировать и отправить форму.

Транзакция будет осуществлена в асинхронном режиме. Описание Callback-уведомлений представлено ниже.

Подсчёт поля sign

Пример генерации поля sign и формирования формы

<?php
function calc_sign($secret, $fields)
{
        ksort($fields);
        $secret_t = '';
        foreach($fields as $key => $val)
        {
                $secret_t = $secret_t . '-' . $val;
        }
        $secret_t = substr($secret_t, 1) . '-' . $secret;
        return hash("sha256", $secret_t);
}

function generate_form($secret, $fields)
{
        $sign = calc_sign($secret, $fields);
        $form = "";
        foreach($fields as $key => $val)
        {
                $form = $form . '<input type="hidden" name="'.$key.'" value="' . htmlspecialchars($val) . '"/>'."\n";
        }
        $form = $form . '<input type="hidden" name="sign" value="'.$sign.'"/>';
        return $form;
}

$f = generate_form("123", $values = array(
   "email" => "user@example.com",
   "merchantId" => "1",
   "orderId" => "123",
   "price" => "123.00",
));
echo $f;
?>

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("-", "");
}

Calculator.Calculate("123", new Dictionary<string, string>
{
   ["email"] = "user@example.com",
   ["merchantId"] = "1",
   ["orderId"] = "123",
   ["price"] = "123.00",
});

Контрольная сумма вычисляется от всех полей, присутствующих в запросе, перечисленных в алфавитном порядке и Secret (уникальный код, который знает только платёжная система и Продавец) и разделённых символом “-”.

Например: sign = sha256(email + "-" + merchantId + "-" + orderId + "-" + price + "-" + secret)

REST API payments

General items

Перечень и описание возможных полей при использовании API платежный форм (в т.ч. виджета и встроенной формы оплаты) приведены в таблице.

Поле Обяз-ть Описание
merchantId Да Id мерчанта
price Да Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId Да Номер заказа в системе Клиента. Должен быть УНИКАЛЬНЫМ внутри переводов транзакций типа payout
customer_email Да Email пользователя
sign Да Контрольная подпись данных о платеже. Методику подсчёта см. ниже
customNameX Нет X - Число от 1 до 4. Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа и отображается Плательщику на платежной странице в правом блоке. Передается совместно с customValueX
customValueX Нет X - Число от 1 до 4. Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа и отображается Плательщику на платежной странице в правом блоке. Передается совместно с customNameX.
extra_* Нет Данные поля используются в случае, если необходимо передать дополнительную информацию серверу и не видны Плательщику. Должны иметь вид extra_[A-Za-z0-9_]+
customer_phone Да/Нет Телефон пользователя в формате +XXXXXXXXXXX
callbackUrl Нет Url для отправки уведомления о статусе трназакции
returnUrl Нет Url для редиректа пользователя после оплаты
orderActualTill Нет Срок резервирования товара/услуги. После указанной даты оплата будет невозможна

Генерация requestId

<?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}";
}

Все запросы должны быть с заголовком Content-Type: application/json Аутентикация запросов происходит посредством заголовка X-Auth следующего содержания: merchantId-SHA256(merchantId-requestId-secret)-requestId

requestId - уникальный номер запроса, представляющий из себя текущий таймстамп в миллисекундах, либо набор байт, сгенерированный криптографически-надёжным генератором случайных числел.

Transaction types

Типы транзакций и их описание/назначение представлены в таблице

Тип транзакции Описание
pay списание денег с карты (purchase)
payout зачисление денег на карту (moneysend)
preauth блокировка суммы на карте (предавторизация суммы)
confirmauth подтверждение списания заблокированной (предавторизованной) суммы
reversal возврат заблокированной (предавторизованной) суммы
refund отмена операции покупки
rebill повторное (автоматическое) списание на основании ранее совершенной транзакции pay

Для совершения вышеуказанных транзакций необходимо отправить POST запрос на https://secure.mandarinpay.com/api/transactions

Все транзакции осуществляются в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже

- Card pay / payout

Создание транзакции по непривязанной карте

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay/payout",
    "price": "10",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"

}

Создание транзакции по привязанной карте

{
  "payment":
  {
      "orderId": "123321",
      "action": "pay/payout",
      "price": "10"
  },
  "target":
  {
      "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

В поле action допустимы значения:

Значение Описание
pay списание денег с карты
payout зачисление денег на карту

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

Создание транзакции по непривязанной карте (no-binding transaction)

Для совершения транзакции необходимо перенаправить пользователя на url, полученный в поле userWebLink.

Создание транзакции по привязанной карте (binding transaction)

Используйте Id привязки в качестве значения для target->card

- Preauth

{
  "payment":
  {
      "orderId": "123321",
      "action": "preauth",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "customValues":
  [
   {"name": "custom field 0", "value": "123321"},
   {"name": "custom field 1", "value": "123321"}
  ]
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"

}

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

Предавторизация производится аналогично обычной покупке как через API платежной страницы, так и через REST API. Необходимо в поле action передать значение preauth.

После того как придёт уведомление об успехе предавторизации полученый в нём Id транзакции можно использовать для полного или частичного списания (action->pay), а также разблокировки (action->reversal) денежных средств через REST API в качестве значения для target->preauth

Для совершения транзакции необходимо перенаправить пользователя на url, полученный в поле userWebLink.

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- ConfirmAuth

{
  "payment":
  {
      "orderId": "123321",
      "action": "pay",
      "price": "10"
  },
  "target":
  {
      "preauth": "43913ddc000c4d3990fddbd3980c1725"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Для полного или частичного списания используйте action->pay и полученный в уведомлении об успешной предавторизации Id в качестве значения для target->preauth

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- Reversal

{
  "payment":
  {
      "orderId": "123321",
      "action": "reversal"
  },
  "target":
  {
      "preauth": "43913ddc000c4d3990fddbd3980c1725"
  }
}

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

Для разблокировки предавторизованной суммы используйте action->reversal и полученный в уведомлении об успешной предавторизации Id в качестве значения для target->preauth

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- Refund

{
  "payment":
  {
      "orderId": "123321",
      "action": "reversal",
      "price": "10"
  },
  "target":
  {
      "transaction": "43913ddc000c4d3990fddbd3980c1725"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}

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

Для отмены успешной транзакции на списание средств с карты (pay/rebill/confirmauth) используйте actiion->reversal и Id ранее проведённой транзакции в качестве target->transaction

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

Для отмены всей суммы транзакции параметр price является необязательным.

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- Rebill

{
  "payment":
  {
      "orderId": "123321",
      "action": "pay",
      "price": "10"
  },
  "target":
  {
      "rebill": "43913ddc000c4d3990fddbd3980c1725"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Для создания повторного списания средств с карты используйте actiion->pay и Id ранее проведённой успешной транзакции (pay/preauth/rebill/confirmauth) в качестве target->rebill

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

Прочие вызовы (other)

Типы транзакций и их описание/назначение представлены в таблице

Тип транзакции Описание
knownCardNumber зачисление денег на известный номер карты
phone зачисление денег на номер мобильного телефона
bestmt перевод денег в систему денежных переводов БЭСТ / Unistream
yandexMoney зачисление денег на кошелек Яндекс.Деньги
webMoney зачисление денег на кошелек Webmoney
paybyloan оплата в кредит/рассрочку
bank-account зачисление денег на банковский счет физ.лица

Для совершения вышеуказанных транзакций необходимо отправить POST запрос на https://secure.mandarinpay.com/api/transactions

Все транзакции осуществляются в асинхронном режиме. В результате запроса вам синхронно придет id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже

- knownCardNumber

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target":
  {
      "knownCardNumber": "4012888888881881"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- Phone

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target": "phone"
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- Bestmt

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567",
    "firstName": "Василий",
    "middleName": "Иванович",
    "lastName": "Пупкин",
    "document":
    {
        "rfnspDocId": 21,
        "docSeria": "7709",
        "docNum": "543987",
        "docIssuer":  "УПРАВЛЕНИЕ ФЕДЕРАЛЬНОЙ МИГРАЦИОННОЙ СЛУЖБЫ РОССИИ ПО ГОР.МОСКВЕ",
        "docIssuerCode": "770-001",
        "docIssuingDate": "2011-01-01",
    },
    "birthDate": "1980-01-01",
    "birthPlace": "г. Москва",
    "countryCode": "643",
    "taxInfo":
    {
          "isRussianFederationTaxResident": true
    }
  },
  "target": "bestmt"
}

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

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- yandexMoney

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target":
  {
    "yandexMoney": "123456789091"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- webMoney

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target":
  {
    "webMoney": "R111222333444"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

В настоящий момент доступно пополнение исключительно рублевого кошелька.

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

- PayByLoan (покупка в кредит/рассрочку)

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10",
    "method": "credit",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "metadata": 
  {
     "picture_url": "http://yourdomain.ru/bestgood.png",
     "description": "Это замечательный товар! <br> Лучше него ничего не бывает и мы его рекомендуем абсолютно всем!"
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"

}

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

Данный метод используется для подключения оплаты в кредит/рассрочку.

В данном вызове появился блок metadata, в который можно передавать дополнительную информацию и которую увидит покупатель при офррмлении кредита рассрочки. На текущий момент доступны слудющие поля:

Название параметра Описание
picture_url ссылка на картинку товара/услуги
description описание товара (возможно использование html-тегов)
type тип запроса - кредит (значение = credit) или рассрочка (значение = installments)
discount размер скидки, предоставляемой продавцом, в формате 0.00 от суммы покупки

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

Для совершения транзакции необходимо перенаправить пользователя на url, полученный в поле userWebLink.

- bank-account

{
  "action": "payout",
  "orderId": "123321",
  "price": "123",
  "target": "bank-account",
  "reason": "Назначение",
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567",
    "firstName": "Иван",
    "middleName": "Иванович",
    "lastName": "Иванов",
    "bankAccount":
    {
       "number": "40101810800000010041",
       "bic": "044583001"
    }
  }
}
Standard HTTP 200 JSON response:
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
Standard HTTP 400 Bad request:
{
  "error": "Invalid request"
}

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

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id транзакции, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

REST API bindings

Генерация requestId

Смотри Генерация requestId из REST API payments

Binding types

Привязка карты (binding) используется для целей списания/зачисления на карту без участия пользователя, а также для проверки того, что пользователь имеет доступ к данной карте (списание контрольной суммы, проверка через 3DS)

Типы привязок и их краткое описание представлены в таблице

Тип привязок Описание
card-binding Полноценная привязка карты
one-side-binding одностороння привязка карты

Для совершения вышеуказанных транзакций необходимо отправить POST запрос на https://secure.mandarinpay.com/api/card-bindings

- Card-binding

{
    "customerInfo":
    {
        "email": "user@example.com",
        "phone": "+79001234567"
    }
}
Standard HTTP 200 JSON response:
{
    "id": "0eb51e74-e704-4c36-b5cb-8f0227621518",
    "userWebLink": "https://secure.mandarinpay.com/CardBindings/New?id=0eb51e74-e704-4c36-b5cb-8f0227621518"
}

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

Данный вызов можно использовать в следующих целях:

Транзакция будет осуществлена в асинхронном режиме. В результате запроса вам синхронно придет Id привязки, и асинхронно придет Callback-уведомление. Описание Callback-уведомлений представлено ниже.

Полученный Id следует сохранить, а пользователя перенаправить по ссылке, полученной в поле userWebLink.

Привязанную карту можно будет использовать только после получения callback-уведомления об её успешной привязке.

- One-side-binding

{
    "customerInfo":
    {
        "email": "user@example.com",
        "phone": "+79001234567"
    },
  "target":
    {
      "knownCardNumber": "4012888888881881"
    }
}
Standard HTTP 200 JSON response:
{
    "id": "0eb51e74-e704-4c36-b5cb-8f0227621518"
}

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

Данный вызов по сути представляет из себя токенизацию известного номера карты и используется для того, чтобы не хранить в вашей системе номер карты. Данная привязка осуществляется в синхронном режиме - в ответ вы получите Id привязки.

В отличие от предыдущего вызова, такая привязка может быть использована исключительно для зачисления (action=payout) денежных средств на карту.

Callback-уведомления

General items

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

Уведомления высылаются на указанный в клиентском интерфейсе CallbackUrl в теле POST-запроса с Content-Type: application/x-www-urlencoded.

Для подтверждения того, что уведомление пришло именно от системы MandarinPay необходимо проверять значение поля sign, являющегося SHA256-суммой от значений всех параметров запроса, отсортированных алфавитно по именам и Secret, разделённых символом -.

В качестве ответа, обозначающего, что callback успешно обработан, ваше ПО должно вернуть MandarinPay HTTP-код 200 и тело ответа OK.

В зависимости от значения object_type уведомления бывают следующих видов:

Тип Описание
card_binding привязка карты
transaction транзакция

Card_binding callback

Callback-уведомления, присылаемые при привязке банковской карты.

Поле Пример Описание
card_binding 38467cb0-da73-4755-84da-2acb7f638a59 Идентификационный номер привязки
card_holder VASILY PUPKIN Держатель карты
card_number 123456XXXXXX7890 Номер карты
card_expiration_year 18 Год срока действия карты
card_expiration_month 9 Месяц срока действия карты
status success Статус привязки

Transaction callback

Callback-уведомления, присылаемые при проведении транзакций.

Поле Пример Описание
transaction 05991602ed7c47d996ca7ab119b07f66 ID транзакции в системе
status success, failed Статус операции
action pay, payout Действие (покупка или выплата на карту)
merchantId 42 Id мерчанта
price 12.34 Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId 1234OR Уникальный номер заказа в системе Продавца.
customer_email user@example.com Email пользователя
customer_phone +71234567890 Телефон пользователя
card_holder VASILY PUPKIN Держатель карты
card_number 123456XXXXXX7890 Номер карты
card_expiration_year 18 Год срока действия карты
card_expiration_month 9 Месяц срока действия карты
error_code 59 Код ошибки
error_description Transaction Declined Описание ошибки
transaction_rrn 704191744222 Retrieval Reference Number - уникальный идентифкатор транзакции в системе Банка-эмитента банковской карты

XML API MandarinInfo

Данный протокол используется для запросов к системе MandarinInfo.

Точки входа (endpoints)

Точка входа для боевых запросов к API - https://id01.mandarinpay.com/infoapi

Точка входа для тестовых запросов к API - https://id01.mandarinpay.com/infoapi_test

Способ отправки запроса (sending methods)

Пример запроса через cURL

curl_setopt($ch, CURLOPT_INFILE, $xml); 
curl_setopt($ch, CURLOPT_INFILESIZE, 
strlen($xml)); curl_exec($ch);

Передача XML-запросов шлюзу может осуществляться одним из двух способов:

$ch – дескриптор сURL;

$xml – переменная, содержащая заранее сформированный XML-запрос.

Контрольная сумма (hash)

Пример расчета значения hash для Python 2.7

hashstr = '-'.join([secret, str(opcode), Product])
return md5(hashstr).hexdigest()

Для идентификации пользователя API используются дополнительные обязательные параметры product и hash, передаваемые в запросе как подэлементы элемента request.

Параметр Пример Описание
product 000001-0001-0001 Идентификатора пользователя API (клиента) в системе MandarinInfo
hash 1d2a5a126bfc3ad88435c1628b0d314a33e95802 Контрольная сумма

Пример расчета контрольной суммы

Контрольная сумма рассчитывается методом md5('secret-opcode-product'), где

Параметр Пример Описание
secret 24t5fRTGH Кодовая фраза, известная обеим сторонам коммуникации
opcode 752 Идентификатор выполняемого запроса
product 000001-0001-0001 Идентификатора пользователя API (клиента) в системе MandarinInfo

Чтобы проверить правильное значение хэша, воспользуйтесь онлайн-сервисом

Эмиссия банковских карт (co-branding)

Вариант с rawaddress (подключается сервис авторазбора адреса)

<?xml version="1.0" encoding="utf-8"?> 
<request>
<Opcode>752</Opcode> 
<Product>000001-0001-0001</Product> 
<hash>683419922c51c2c1edc367fae6ae39b0</hash> 
<source>503</source>
<Person>
  <Family>Шариков</Family> 
  <Name>Полиграф</Name> 
  <Patronim>Полиграфович</Patronim> 
  <Sex>муж</Sex> 
  <BirthDay>1975-05-19</BirthDay> 
  <BirthPlace>Москва</BirthPlace> 
  <Email>sharikov@narod.ru</Email> 
  <Phone>+79091000000</Phone> 
  <Document>
    <RFNSPDocid>21</RFNSPDocid>
    <Docseria>7709</Docseria>
    <Docnum>543987</Docnum>
    <Docissuingdate>2011-01-01</Docissuingdate>
    <Docissuer>УПРАВЛЕНИЕ ФЕДЕРАЛЬНОЙ МИГРАЦИОННОЙ СЛУЖБЫ РОССИИ ПО ГОР.МОСКВЕ</Docissuer>
    <Docissuercode>770-001</Docissuercode> 
  </Document>
  <Address>
    <rawaddress>Москва, Большая Садовая, 10, кв. 50</rawaddress> 
  </Address>
  <Card>
    <num>6705721234567895</num>
    <passphrase>Шарик</passphrase> 
  </Card>
</Person> 
</request>

Вариант с известными параметрами адреса (сервис разбора адреса не подключается):

<?xml version="1.0" encoding="utf-8"?> 
<request>
<Opcode>752</Opcode> 
<Product>000001-0001-0001</Product> 
<hash>683419922c51c2c1edc367fae6ae39b0</hash> 
<source>503</source>
<Person>
  <Family>Шариков</Family> 
  <Name>Полиграф</Name> 
  <Patronim>Полиграфович</Patronim> 
  <Sex>муж</Sex> 
  <BirthDay>1975-05-19</BirthDay> 
  <BirthPlace>Москва</BirthPlace> 
  <Email>sharikov@narod.ru</Email> 
  <Phone>+79091000000</Phone> 
  <Document>
    <RFNSPDocid>21</RFNSPDocid>
    <Docseria>7709</Docseria>
    <Docnum>543987</Docnum>
    <Docissuingdate>2011-01-01</Docissuingdate>
    <Docissuer>УПРАВЛЕНИЕ ФЕДЕРАЛЬНОЙ МИГРАЦИОННОЙ СЛУЖБЫ РОССИИ ПО ГОР.МОСКВЕ</Docissuer>
    <Docissuercode>770-001</Docissuercode> 
  </Document>
  <Address>
    <rupostindex>125047</rupostindex> 
    <kladrstreet>77000000000254200</kladrstreet> 
    <house>10</house>
    <flat>50</flat>
  </Address>
  <Card>
    <num>6705721234567895</num>
    <passphrase>Шарик</passphrase> 
  </Card>
</Person> 
</request>

Пример ответа в случае УСПЕШНОЙ операции:

<?xml version="1.0" encoding="utf-8"?> 
<response>
<code>1100</code> 
<hash>2135417f4aac4896ae4464a6eabfab07</hash> 
<entities>
  <provider_desc>Проведен</provider_desc> 
  <actionName>FINDPAY</actionName> 
  <billNumber>8827044265228463343</billNumber> 
  <provider_code></provider_code> 
  <result_desc>Проведен</result_desc> 
  <result_finish>true</result_finish> 
  <result_code>1</result_code>
</entities>
<request_id>478</request_id> 
<date>2016-07-15T06:31:34+00:00</date> 
<message>OK</message>
</response>

Примеры ответов в случае НЕУДАЧНОЙ операции:

в поле <entities><provider_desc> содержится расшифровка причины неудачи
<?xml version="1.0" encoding="utf-8"?> 
<response>
<code>1100</code> 
<hash>eb4c9665c85a4567af1a486c91ec58cd</hash>
<entities>
  <provider_desc>Не найдена карта</provider_desc> 
  <actionName>FINDPAY</actionName> 
  <billNumber>7582787236450035160</billNumber> 
  <provider_code>2</provider_code> 
  <result_desc>Ошибочный номер абонента</result_desc> 
  <result_finish>true</result_finish> 
  <result_code>-20140</result_code>
</entities>
<request_id>479</request_id> 
<date>2016-07-15T06:33:05+00:00</date> 
<message>OK</message>
</response>

Дополнительный запрос GetResult (повторный запрос результата)

<?xml version="1.0" encoding="utf-8"?> 
<request>
<Opcode>751</Opcode> 
<Product>111111-1111-0001</Product> 
<hash>aaf81e42d03b4034e1b128d1d081f1b9</hash> 
<source>503</source>
<request_id>478</request_id>
</request>

Набор используемых полей:

Параметр Уровень Описание
Family 1 Фамилия
Name 1 Имя
Patronim 1 Отчество
Sex 1 Пол в формате муж, жен
Patronim 1 Отчество
BirthDay 1 Дата рождения в формате YYYY-MM-DD
BirthPlace 1 Место рождения (текстовая строка на русском языке)
Email 1 Email
Phone 1 Номер мобильного телефона в формате +79091000000
Document 1 Документ физического лица; контейнер, подэлементы приведены ниже
RFNSPDocid 2 Идентификатор типа документа в соответствии с классификатором (Приказ от 12.04.2006 N САЭ-3-13/224 «Об утверждении форматов файлов информации, представляемой в налоговые органы от органов, учреждений и организаций, перечисленных в пунктах 1, 2, 3, 8 статьи 85 части первой налогового кодекса российской федерации» в ред. Приказа ФНС РФ от 15.08.2007 N ММ-3-13/488); см. также раздел 13 «Допустимые значения параметров и элементов запроса»
Docseria 2 Серия документа без пробелов
Docnum 2 Номер документа без пробелов
Docissuingdate 2 Дата выдачи документа a форрмате YYYY-MM-DD
Docissuer 2 Наименование органа, выдавшего документ
Docissuercode 2 Код подразделения органа, выдавшего документ
Card 1 Данные о карте; контейнер, подэлементы приведены ниже
num 2 PAN (номер) карты без пробелов
passphrase 2 Кодовая фраза
Address 1 Адрес получателя карты; контейнер, подэлементы приведены ниже
rawaddress 2 Адрес одной строкой (авторазбор на стороне MandarinInfo
rupostindex 2 Индекс
kladrstreet 2 Идентификатор по КЛАДРу
house 2 Номер дома
flat 2 Номер квартиры

Упрощенная идентификация СМЭВ (id-smev)

Набор используемых полей:

Параметр Уровень Описание
Family 1 Фамилия
Name 1 Имя
Patronim 1 Отчество
SNILS 1 Номер СНИЛС
Phone 1 Номер мобильного телефона в формате +79091000000
Document 1 Документ физического лица; контейнер, подэлементы приведены ниже
RFNSPDocid 2 Всегда 21, так как паспорт гражданина РФ
Docseria 2 Серия документа без пробелов
Docnum 2 Номер документа без пробелов

- Опкод 761 IdentPreauth

Формат запроса

<?xml version="1.0" encoding="utf-8"?>
<request>
<Opcode>761</Opcode>
<Product>111111-1111-0001</Product>
<hash>2a7e6c16927a0c2ec729bc901bf4fdbb</hash>
<source>205</source>
<Person>
  <Family>Иванов</Family>
  <Name>Иван</Name>
  <Patronim>Иванович</Patronim>
  <SNILS>98765432101</SNILS>
  <Phone>+79091001216</Phone>
  <Document>
    <RFNSPDocid>21</RFNSPDocid>
    <Docseria>7701</Docseria>
    <Docnum>123456</Docnum>
  </Document>
</Person>
</request>

Ответ системы в случае успешного завершения операции:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <date>2016-04-26T17:33:37+00:00</date>
  <message>OK</message>
  <code>1100</code>
  <request_id>[ID для следующих операций]</request_id>
  <pincodeformat>[формат кода, отправленного на телефон Phone посредством SMS]</pincodeformat>
</response>

В случае ошибки код возврата отличается от 1100, и в message содержится сообщение об ошибке.

Инициирует процедуру упрощенной идентификации физического лица с применением СМЭВ в соответствии с ФЗ №115-ФЗ

Данный опкод требует жесткого указания источника данных, при помощи которого производится идентификация. В текущей реализации это подразумевает source_group_id = 3 и source = 205.

- Опкод 762 IdentConfirmath

Формат запроса

<?xml version="1.0" encoding="utf-8"?>
<request>
  <Opcode>762</Opcode>
  <Product>111111-1111-0001</Product>
  <hash>48822176d8aa2b5fc36726f00504b219</hash>
  <source>205</source>
  <request_id>[ID запроса, выданный в ответе на опкод 761]</request_id>
  <pincode>[введенный пользователем код подтверждения] </pincode>
</request>

Ответ системы в случае успешного завершения операции:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <date>2016-04-26T17:33:37+00:00</date>
  <message>OK</message>
  <code>1100</code>
  <request_id>[ID]</request_id>
  <reply>
    <person_valid>[true/false]</person_valid>
    <passport_valid>[true/false]</passport_valid>
    <snils_valid>[true/false]</snils_valid>
  </reply>
</response>

В случае ошибки код возврата отличается от 1100; в элементе message содержится текстовое сообщение об ошибке.

Код подтверждения из полученного пользователем сообщения проверяется на корректность и по результатам выдается подтверждение идентификации или отказ в ней.

Данный опкод требует жесткого указания источника данных, при помощи которого производится идентификация. В текущей реализации это подразумевает source_group_id = 3 и source = 205.

Элемент person_valid будет иметь значение True при успешной идентификации физического лица. Элементы passport_valid и snils_valid в этом случае также будут равны True.

При отказе в идентификации физического лица (person_valid равен False) эти элементы используются для уточнения причины ошибки (несовпадение паспорта и/или СНИЛС, соответственно).

CMS Plugins

В солучае, если необходимый вам плагин отсутствует в списке, обратитесь в Службу поддержки, и мы подумаем, что можно сделать.

Diafan CMS

Новая версия

Старая версия

Joomla

Joomla3.4 VirtueMart3

joomla2.5 JoomShopping3

joomla3 JoomShopping4

Старая версия VirtueMart

CS-CART

Скачать плагин

Bitrix

Скачать плагин

Drupal Ubercart

Скачать плагин

Magento

Скачать плагин

ModX

ModX Revo

ModX Evo

Старая версия

Opencart

Opencart 1

Opencart 2

PHP Shop

Скачать плагин

Prestashop

Скачать плагин

Старая версия

Simpla

Скачать плагин

UMI.CMS

Скачать плагин

Webasyst

Скачать плагин

Wordpress

Скачать плагин

Старая версия

Insales

Необходимо зарегистрировать клиента у нас в системе на сайте https://mandarinpay.com.

Далее в Insales вам необходимо добавить новый способ оплаты - внешний способ оплаты. В появившемся меню необходимости ввести:

  1. merchantid в качестве идентификатора магазина,
  2. значение secret в качестве пароля,
  3. http://insales.mandarinpay.com/mandarin_proxy.php в качестве внешней ссылки

Далее необходимо в настройках нашего ЛК прописать ссылку из “URL для перехода при успешной оплате” в качестве callbackurl

Статья в базе знаний на тему merchantid, secret и callbackurl