Общая информация (API Reference)

Введение (intro)

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

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

Точка входа для создания привязок

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

API Mandarinpay базируется на технологии REST API. В системе используются ресурсо-ориентированные точки входа (endpoints), а все ответы, возвращаемые системой имеют формат JSON.

API Mandarinpay является асинхронным (незначительная часть запросов работает синхронно) - на ваш запрос вы синхронно получите id платежа (запроса), а затем в асинхронном режиме получите callback уведомление, включающее полученный ранее id платежа (запроса), а также статус операции и прочие данные по ней.

Для того, чтобы вы могли максимально протестировать API, проекты в системе имеют тестовый (sandbox) и боевой режим. Авторизационные данные (merchant id, secret) находятся в настройках проекта в вашем Личном кабинете на сайте mandarinpay.com (Подробная инструкция). Запросы, создаваемые в рамках sandbox-режима не никогда передаются в банковские информационные системы и, как следствие, не приводят к возникновению затрат.

Тестовые карты (test cards)

Данные тестовых карт для проверки работоспособности в sandbox-режиме (срок действия любой, позднее текущего месяца в формате ММ/ГГ)

Параметр	Значение	Комментарий
Номер карты	4929509947106878	Для имитации успешных транзакций без 3DSecure
Номер карты	4692065455989192	Для имитации успешных транзакций с 3DSecure
Номер карты	4485913187374384	Для имитации неуспешных транзакций без 3DSecure
Номер карты	4556058936309366	Для имитации неуспешных транзакций с 3DSecure
Номер карты	5192618384533242	Для имитации интерактивной оплаты с принудительным переводом карты в payout-only
Имя держателя карты	CARD HOLDER
CVV	123

Мониторинг во время отладки (heartbeat)

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

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

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

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

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

Авторизация (Authentication)

Авторизация запросов к API Mandarinpay осуществляется двумя способами:

HTTP Basic Auth - см. здесь
Авторизация через хэш - см. здесь

Все запросы к API должны осуществляться через HTTPS. Запросы с HTTP будут отклоняться без создания транзакции.

HTTP Basic Auth

Подробнее о Basic Auth можно прочитать в Wikipedia.

В случае Mandarinpay в качестве логина используется merchantId, а в качестве пароля значение secret.

Авторизация через хэш (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}";
}

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

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

API запросы без заголовка или с некорректным заголовком, в том числе некорректным X-Auth будут отклонены без создания транзакций.

Для проверки корректности расчета X-Auth можете воспользоваться данной утилитой.

Синхронные ответы (Response codes)

Примеры ответов

200-OK - Запрос обработан корректно, транзакция создана

Для транзакции

{
  "id": "43913ddc000c4d3990fddbd3980c1725",
  "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
  "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Для привязки

{
    "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"

}

Mandarinpay использует стандартные HTTP коды для индикации успешности или неуспешности API запросов. В общем случае коды формата 2хх означают успешность, коды формата 4xx говорят о неуспешности запроса в связи с предоставленной информацией (отсутствие нужного формата, неверно сформированный заголовок и т.д.), коды в формате 5хх говорят о неисправности на стороне сервера Mandarinpay (довольно редкий случай).

Перечень полей и их описание

Поле	Описание
id	id созданной операции
userWebLink	Ссылка для перенаправления пользователя при работе с платежной страницей
jsOperationId	Идентификатор операции для использования с CustomPay
error	Текстовое описание ошибки

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

Для использования платежной страницы - Перенаправить пользователя по ссылке, полученной в качестве userWebLink - см. здесь
Для использования встроенной формы CustomPay - Использовать значение из jsOperationId в качестве OperationId в соответствии с описанием - см. здесь
В отдельных ситуациях дальнейшие действия не требуются. В этом случае в синхронном ответе будет получен только id.

Асинхронные ответы (Callback)

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

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

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

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

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

screen

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

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

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

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

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

Поле	Пример	Описание
`merchantId`	`1`	Id мерчанта
`orderId`	`1234OR`	Уникальный номер заказа в системе Продавца.
`price`	`12.34`	Сумма платежа. Обязательна к передаче в текущей версии системы.
`action`	`pay`, `payout`	Действие (покупка или выплата на карту) - актуально только для транзакций
`transaction`	`05991602ed7c47d996ca7ab119b07f66`	ID транзакции в системе - актуально только для транзакций
`card_binding`	`38467cb0-da73-4755-84da-2acb7f638a59`	ID привязки в системе - актуально только для привязок
`status`	`success`, `failed`, `payout-only`	Статус операции
`customer_email`	`[email protected]`	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 - уникальный идентифкатор транзакции в системе Банка-эмитента банковской карты

ID Платежа (PaymentID)

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

ID платежа также доступен в таблице транзакций в вашем личном кабинете на сайте mandarinpay.com (см. скриншот) и в интерфейсе Heartbeat.

При обращении в Службу поддержки касаемо конкретного платежа наличие данного идентификатора существенно ускорит получение ответа

Пользовательский интерфейс (User Interfaces)

Платежная страница (Payment Page)

Платежная страница Mandarinpay имеет адаптивный дизайн, содержит ваш логотип, а также информацию о платеже, переданную вами в API запросе.

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

Встроенная форма оплаты (CustomPay)

Пример формы

<form id="form-hosted-pay">
  <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", {
  operationId: "9874694yr87y73e7ey39ed80",
  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;
}

Встроенная форма оплаты CustomPay позволяет осуществить полноценную интеграцию в ваш интерфейс, при этом отсутствует требование к Вам по соответствию стандарту безопасности банковских карт PCI DSS.

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

Логически такая форма состоит из 2 частей:

набор div-ов с классами mandarinpay-field-card-number, mandarinpay-field-card-holder, mandarinpay-field-card-expiration и mandarinpay-field-card-cvv, внутрь этих div-ов будут помещены iframe-ы
Javascript-а, запускающего процесс установки iframe-ов и обрабатывающего нажатие на кнопку

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

В качестве operationId необходимо передать значение, полученное в прямом ответе Mandarinpay в поле jsOperationid - см. здесь

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

Пример:

screen

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

Стилизация осуществляется посредством добавления соответствующего поля в объект, передаваемый 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"  
                },
            }
        }
    }
});

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

color в формате #000000
font-size с единицами px и pt
font-family (можно использовать запятые и кавычки)
font-style

Прием платежей (Payin)

Типы операций (Transaction types)

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

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

Тип транзакции	Описание
Purchase	Списание денег с банковской карты
Rebill	Рекуррентный платеж, повторное списание денежных средств на основании ранее совершенной успешной транзакции оплаты/блокировки
Refund	Отмена операции списания денежных средств с карты
Preauth	Блокировка (предавторизация) суммы денежных средств на карте - нефинансовая операция
ConfirmAuth	Подтверждение списания заблокированной (предавторизованной) суммы денежных средств на карте
Reversal	Возврат заблокированной (предавторизованной) суммы денежных средств на карте

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

Списание денежных средств с карты можно осуществить в рамках одностадийной схемы оплаты или двухстадийной схемы оплаты.

Одностадийная оплата (Purchase)

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

- Purchase

Создание транзакции типа Purchase

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

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "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",
   "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

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

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

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `purchase` передается значение `pay`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента.
orderActualTill	Нет	Срок резервирования товара/услуги. После указанной даты оплата будет невозможна

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Нет	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Данный блок является НЕОБЯЗАТЕЛЬНЫМ и позволяет передать любую дополнительную информацию вместе с платежом. Вы можете передать до 8 пар параметров.

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

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

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

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

Полученные в синхронном ответе userWebLink используйте для работы с платежной страницей (см. здесь), а jsOperationId для работы через CustomPay (см. здесь)

Двухстадийная оплата (Preauth, ConfirmAuth, Reversal)

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

- Preauth

Создание транзакции типа Preauth

{
  "payment":
  {
    "orderId": "123321",
    "action": "preauth",
    "price": "10.00",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "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",
   "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request" 
}

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

В случае отсутствия операции подтверждения списания денежных средств сумма будет автоматически разблокирована через определенное время (от 7 до 30 дней).

Также возможна операция принудительной разблокировки ВСЕЙ заблокированной суммы (Reversal)

Для блокировки денежных средств с карты в рамках двухстадийной схемы оплаты необходимо создать транзакцию с типом Preauth

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `preauth` передается значение `preauth`, для ее подтверждения - `pay`, а разблокировки - `reversal`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента.
orderActualTill	Нет	Срок резервирования товара/услуги. После указанной даты оплата будет невозможна

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Нет	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

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

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

- ConfirmAuth

Создание транзакции на списание заблокированной суммы ConfirmAuth

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "transaction": "43913ddc000c4d3990fddbd3980c1725"
  }
}

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

Значение price может быть любым в пределах значения, переданного в изначальной транзакции preauth

- Reversal

Создание транзакции на разблокировку заблокированной суммы Reversal

{
  "payment":
  {
    "orderId": "123321",
    "action": "reversal"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "transaction": "43913ddc000c4d3990fddbd3980c1725"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
    "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
    "error": "Invalid request" 
}

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

Отмена успешной оплаты (Refund)

Создание транзакции Refund

{
  "payment":
  {
    "orderId": "123321",
    "action": "reversal",
    "price": "10.00"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "transaction": "43913ddc000c4d3990fddbd3980c1725"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
    "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
    "error": "Invalid request"
}

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

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

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для отмены успешной транзакции оплаты и возврата денежных средств передается значение `reversal`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента.

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Рекуррентные платежи (Recurring payments)

Рекуррентный платеж (Rebill) - это операция списания денежных средств, совершаемая без ввода реквизитов банковской карты, на основании ранее совершенной привязки карты или операции оплаты/блокировки (pay/preauth/rebill/confirmauth)

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

- Привязанная карта (Binded rebill)

Создание транзакции Rebill с использованием привязанной карты (для случаев, когда ваш софт НЕ УМЕЕТ работать с интерактивным режимом)

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Ответ в случае, если автосписание невозможно:

{
   "error": "Card binding is payout-only"  
}

Создание транзакции Rebill с использованием привязанной карты (для случаев, когда ваш софт УМЕЕТ работать с интерактивным режимом)

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  },
  "allowinteractive": true
}

Ответ в случае успешного создания транзакции автосписания (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае успешного создания транзакции в интерактивном режиме (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725",
   "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `rebill` передается значение `pay`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента.

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

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

Такая привязка может быть использована для переводов на нее (см. здесь) или для оплаты в интерактивном режиме (см. здесь)

В этом случае вы получите callback с ошибкой, а также флагом о том, что дальнейшее проведение рекуррентных платежей невозможно. Дополнительно вам будет направлен callback для транзакции привязки карты с новым статусом payout-only. Дальнейшие попытки автосписаний будут проходить без создания транзакции, в результате запроса вам будет возвращаться ответ Card binding is payout-only.

В случае, если ваш софт умеет работать в “интерактивном режиме”, рекомендуем добавить в запрос флаг allowinteractive : true. Суть данного флага заключается в том, что в случае, если карта была переведена в режим payout-only, то в ответ на запрос вы получите jsOperationId для проведения транзакции в “интерактивном режиме”, вместо ошибки Card binding is payout-only.

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

- Ранее совершенная оплата (Success pay rebill)

Создание транзакции повторного списания Rebill на основании успешной оплаты/блокировки

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00"
  },
   "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "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

Помимо использования привязанной карты, создание rebill возможно на основании любой ранее совершенной успешной операции оплаты (pay/rebill/confirmauth), а также блокировки (preauth) денежных средств.

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

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для отмены успешной транзакции оплаты и возврата денежных средств передается значение `reversal`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента.

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Интерактивная оплата (Interactive payments)

“Интерактивная оплата” подразумевает под собой оплату с использованием ранее привязанной карты, при которой осуществляется взаимодействие с пользователем, а именно: ввод пользователем CVV (защитный код). Для совершения такой оплаты используется технология CustomPay

Таким образом, вы можете использовать карту, привязанную в режиме payout-only, а также полноценные привязки для создания операций типа purchase и preauth.

Существует два варианта вызова данного метода:

Передать в запросе флаг interactive : true - в этом случае, независимо от статуса привязки карты будет применен режим “интерактивной оплаты”
Передать в запросе флаг allowinteractive : true - в этом случае в зависимости от статуса привязки, оплата будет произведена через автосписание, либо с применением “интерактивного режима”, если автосписание невозможно.

Транзакции создаются в 2 этапа:

Инициация транзакции в интерактивном режиме через REST API - см. здесь
Создание транзакции с применением CustomPay - см. здесь

- Инициация транзакции (Init interactive request)

Инициация транзакции Purchase/Preauth

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay/preauth",
    "price": "10.00"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  },
  "interactive": true
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725",
   "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request" 
}

В данном случае к стандартному набору полей, используемому для оплаты с привязанной карты добавляется параметр interactive: true, а в ответе будет содержаться id транзакции и jsOperationId для создания транзакции через CustomPay.

- Создание транзакции (Transaction interactive request)

Создание транзакции через CustomPay

<form id="form-hosted-pay">
  <div style="margin: 10px; padding: 10px; border: 1px solid gray">
    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", {
  operationId: "9874694yr87y73e7ey39ed80",
  onsuccess: function(data) {
    alert("Success, id: " + data.transaction.id);
  },
  onerror: function(data) {
    alert("Error: " + data.error);
  }
});
</script>

Полученный в синхронном ответе jsOperationId в рамках предыдущего запроса необходимо использовать для создания транзакции через CustomPay. В отличие от стандартного создания транзакции через CustomPay в этом случае необходимо передать только значение CVV.

Подробную информацию о создании транзакции через CustomPay смотрите в соответствующем разделе.

Кредитование MandarinPOS (MandarinPos merchant)

Тестирование (testing)

Для тестирования необходимо осуществить подачу заявки от имени покупателя и довести ее до подписания.

В общем виде процесс выглядит следующим образом:

Отправка запроса на займ
Заполнение анкеты в Личном кабинете
Ожидание решения кредитора на странице Покупки
Выбор подходящих условий
Привязка карты или оплата первоначального взноса
Подписание займа через смс

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

В рамках тестирования необходимо выбирать варианты с 0 предоплатой. В этом случае необходимо использовать реальную карту, на которой будет заблокирован 1 рубль и произведен его возврат после подписания.

Тестирование режима “первоначального взноса” возможно с использованием данных тестовых карт. Но для этого необходимо, чтобы ваш Проект был переведен в тестовый режим использования банковских карт - для этого необходимо обратиться в Службу поддержки

Для тестирования рекомендуется использовать следующие данные:

Параметр	Значение
ФИО	Шариков Полиграф Полиграфович
Пол	мужской
Дата рождени	19.05.1975
Серия и номер паспорта	7709 543987
Выпустивший орган	УПРАВЛЕНИЕ ФЕДЕРАЛЬНОЙ МИГРАЦИОННОЙ СЛУЖБЫ РОССИИ ПО ГОР.МОСКВЕ
Дата выпуска	01.01.2011
Код подразделения	770-001
Адрес проживания	Москва, пр. Мира 111, кв. 11
Данные о занятости	Любые

Подача заявки (Paybyloan)

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

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания запроса на кредит/рассрочку передается значение `pay`
price	Да	Сумма платежа. Обратите внимание, что если `type`=`installments`, стоимость товара/услуги должна быть уменьшена вами на размер `discount`
orderId	Да	Номер заказа в системе Клиента.
method	Да	Для создания запроса на кредит/рассрочку передается значение `credit`
orderActualTill	Да	Срок резервирования товара/услуги. После указанной даты оформление будет невозможно

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Блок METADATA

Блок является ОБЯЗАТЕЛЬНЫМ. Он позволяет передавать дополнительную информацию, которую увидит покупатель при оформлении кредита рассрочки, а также информацию, необходимую нам для корректной обработки запроса. На текущий момент доступны слудющие поля:

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

- Запрос на кредит (paybyloan credit)

Создание запроса на продажу в кредит

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "10.00",
    "method": "credit",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "metadata": 
  {
    "picture_url": "http://yourdomain.ru/bestgood.png",
    "description": "Это замечательный товар! <br> Лучше него ничего не бывает и мы его рекомендуем абсолютно всем!",
    "type": "credit"
  }
}

Ответ в случае успешного создания транзакции (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"  
}

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

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

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

- Запрос на рассрочку (paybyloan installments)

Создание запроса на продажу в рассрочку

{
  "payment":
  {
    "orderId": "123321",
    "action": "pay",
    "price": "9.1",
    "method": "credit",
    "orderActualTill": "2016-10-29 12:34:56+00:00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "metadata": 
  {
    "picture_url": "http://yourdomain.ru/bestgood.png",
    "description": "Это замечательный товар! <br> Лучше него ничего не бывает и мы его рекомендуем абсолютно всем!",
    "type": "installments",
    "discount": "0.10",
    "purchase_amount": "10.00"
  }
}

Ответ в случае успешного создания транзакции (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"  
}

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

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

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

Массовые выплаты (Payout)

Проверка баланса (check balance)

Пример кода для проверки баланса

<?php
$merchantId=0;

$secret='******';

$reqid = time() ."_". microtime(true) ."_". rand();
$hash = hash("sha256", $merchantId ."-". $reqid ."-". $secret);
$auth= $merchantId ."-".$hash ."-". $reqid;

$url_transaction = "https://secure.mandarinpay.com/api/account/channels/rib_account/balance";
$ch = curl_init($url_transaction);

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
 "Content-Type: application/json",
 "X-Auth:" . $auth
));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);

var_dump($result);
?>

Данный вызов позволяет проверить баланс счета, с которого осуществляются массовые выплаты.

Для совершения совершения вызова необходимо отправить GET запрос на https://secure.mandarinpay.com/api/account/channels/{name}/balance

В качестве значения {name} необходимо передать параметр в соответствии с таблицей, приведенной ниже:

Параметр	Описание параметра
rib_account	Для запроса баланса расчетного счета, открытого в ООО РНКО РИБ
psb_direct	Для запроса баланса расчетного счета, открытого в ПАО Промсвязьбанк (ПСБ)
dol	Для запроса баланса номинального счета 99948, открытого в ООО ДеньгиОнлайн
vrb	Для запроса баланса технического счета 30232, открытого в ООО КБ ВРБ

Переводы на карту (Card MoneySend)

Перевод на карту можно осуществить тремя способами:

Перевод на ранее привязанную карту
Номер карты передается в составе API вызова
Ввод карты осуществляется на платежной странице

- На привязанную карту (Binded-card payout)

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

Создание транзакции MoneySend с использованием привязанной карты

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "fullName": "Vasia Pupkin"
  },
  "senderInfo":
  {
    "fullName": "Ivan Petrov",
    "birthDate": "1970.01.01"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Элемент	Обяз-ть	Описание
fullName	Да/Нет	Владелец карты. Поле является обязательным для переводов на иностранные карты. Для переводов на карты российских банков НЕ ПОДДЕРЖИВАЕТСЯ.

Блок SENDERINFO

Элемент	Обяз-ть	Описание
fullName	Да	Имя отправителя латиницей
birthDate	Да	Дата рождения отправителя

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения card передается id ранее совершенной успешной привязки карты см. здесь. Обратите внимание на то, что значение orderid должно быть уникальным.

- По номеру карты (KnownCardNumber payout)

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

Создание транзакции MoneySend по известному номеру карты

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567",
    "fullName": "Vasia Pupkin"
  },
  "senderInfo":
  {
    "fullName": "Ivan Petrov",
    "birthDate": "1970.01.01"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "knownCardNumber": "4012888888881881"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца
fullName	Да/Нет	Владелец карты. Поле является обязательным для переводов на иностранные карты. Для переводов на карты российских банков НЕ ПОДДЕРЖИВАЕТСЯ.

Блок SENDERINFO

Элемент	Обяз-ть	Описание
fullName	Да	Имя отправителя латиницей
birthDate	Да	Дата рождения отправителя

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения knownCardNumber передается номер карты, на которую осуществляется перевод. Обратите внимание на то, что значение orderid должно быть уникальным.

- Платежная страница (payment page payout)

POST запрос на https://secure.mandarinpay.com/api/transactions

Создание транзакции MoneySend с вводом карты на стороне платежной страницы

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567",
    "fullName": "Vasia Pupkin"
  },
  "senderInfo":
  {
    "fullName": "Ivan Petrov",
    "birthDate": "1970.01.01"
  },
  "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"  
}

Ввод карты осуществляется на стороне платежной страницы. Для этого вам необходимо перенаправить пользователя на userWebLink, полученный в синхронном ответе. Обратите внимание на то, что значение orderid должно быть уникальным.

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца
fullName	Да/Нет	Владелец карты. Поле является обязательным для переводов на иностранные карты. Для переводов на карты российских банков не применяется.

Блок SENDERINFO

Элемент	Обяз-ть	Описание
fullName	Да	Имя отправителя латиницей
birthDate	Да	Дата рождения отправителя

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Прочие виды массовых выплат (other payouts)

- Мобильный телефон (phone MoneySend)

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

Создание транзакции MoneySend для пополнение мобильного телефона

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target": "phone"
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя, на котрой происходит пополнение, в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется поле target, где в качестве значения передается phone. Номер телефона для пополнения берется из блока customerInfo Обратите внимание на то, что значение orderid должно быть уникальным.

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

- Яндекс.Деньги (MoneySend yandexMoney)

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

Создание транзакции MoneySend для пополнения кошелька Яндекс.Деньги

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "yandexMoney": "123456789091"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения yandexMoney передается номер кошелька Яндекс.Денег. Обратите внимание на то, что значение orderid должно быть уникальным.

- Webmoney (MoneySend webmoney)

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

Создание транзакции MoneySend для пополнения кошелька Webmoney

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "webMoney": "R111222333444"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения webMoney передается номер кошелька Webmoney (WMR, WMZ, WME). Обратите внимание на то, что значение orderid должно быть уникальным.

- Qiwi (MoneySend qiwi)

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

Создание транзакции MoneySend для пополнения кошелька Qiwi

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567"
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target":
  {
    "qiwi": "+79001234567"
  }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В рамках данного API вызова к стандартному вызову добавляется блок target, где в качестве значения qiwi передается номер кошелька Qiwi. Обратите внимание на то, что значение orderid должно быть уникальным.

- Банковский счет (MoneySend bank-account)

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

Создание транзакции MoneySend для перевода на банковский счет

{
 "payment": {
  "action": "payout",
  "orderId": "123321",
  "price": "123",
  "reason": "Назначение"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "phone": "+79001234567",
    "firstName": "Иван",
    "middleName": "Иванович",
    "lastName": "Иванов",
    "bankAccount":
    {
       "number": "40101810800000010041",
       "bic": "044583001"
    },
    "address": {
       "rawString": "Адрес полностью"
    }
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
  "target": "bank-account"
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.
reason	Да	Назначение платежа

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца
firstName	Да	Имя получателя
middleName	Да	Отчество получателя
lastName	Да	Фамилия получателя
number	Да	Номер банковского счета получателя
bic	Да	БИК банка получателя
address	Да	Адрес получателя полностью

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

В качестве значения target необходимо передать bank-account.

- Unistream / ПС БЭСТ (MoneySend bestmt)

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

Создание транзакции MoneySend для перевода через систему денежных переводов (ПС БЭСТ / Unistream)

{
  "payment":
  {
    "orderId": "123321",
    "action": "payout",
    "price": "10.00"
  },
  "customerInfo":
  {
    "email": "[email protected]",
    "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
    }
  },
  "customValues":
  [
    {"name": "custom field 0", "value": "123321"},
    {"name": "custom field 1", "value": "123321"}
  ],
  "urls":
  {
    "callback": "http://...",
    "return": "http://..."
  },
    "target": "bestmt"
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Блок PAYMENT

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
action	да	Для создания транзакции `MoneySend` передается значение `payout`
price	Да	Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId	Да	Номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца
firstName	Да	Имя получателя
middleName	Да	Отчество получателя
lastName	Да	Фамилия получателя
rfnspDocId	Да	Тип документа получателя в соответствии с российским классификатором
docSeria	Да	Серия документа получателя
docNum	Да	Номер документа получателя
docIssuer	Да	Орган, выдавший документ получателя
docIssuerCode	Да	Код подразделения, выдавшего документ получателя
docIssuingDate	Да	Дата выдачи документа получателя
birthDate	Да	Дата рождения получателя
birthPlace	Да	Место рождения получателя
countryCode	Да	Код страны получателя
isRussianFederationTaxResident	Да	Информация о том, является ли получатель налоговым резидентом РФ. Возможные значения `true`/`false`

Блок CUSTOMVALUES

Элемент	Обяз-ть	Описание
name	Нет	Заголовок параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы.
value	Нет	Значение параметра, который используется для прикрепления дополнительной информации к данным Платежа. В случае использования платежной страницы отображается Плательщику в правом блоке платежной страницы

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Выплаты по реестрам (bulk payouts)

Данный способ интеграции позволяет вам без программирования и реализации сервиса выплат по API организовать массовую выплату по готовому реестру получателей.

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

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

Каждый перевод - отдельная строка, при этом при этом первая строка должна быть строкой заголовков

Пример реестра для выплат на банковские карты

orderId,action,price,customer_email,customer_phone,target_known_card_number
111,payout,150.00,[email protected],+71234567890,4271111111111111
222,payout,150.00,[email protected],+71234567891,4271111111111112
333,payout,150.00,[email protected],+71234567892,4271111111111113

Набор полей для выплаты по реестру на банковские карты

Элемент	Обяз-ть	Описание
action	да	тип операции (`payout`), остается неизменным для всех получателей
price	Да	сумма выплаты с копейками через “точку” (0.00)
orderId	Да	номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций.
customer_email	Да	адрес электронной почты получателя
customer_phone	Да	мобильный телефон получателя в формате +79999999999
target_known_card_number	Да	номер банковской карты получателя без пробелов (только номер, без дополнительных карточных параметров)

Пример реестра для выплат на банковские счета

target,orderId,email,price,action,reason,customer_fullName,customer_phone,customer_bankAccount_n
umber,customer_bankAccount_bic,customer_firstName,customer_lastName,customer_middleName,cus
tomer_address_rawString
bank_account,000001,[email protected],1000.00,payout,Назначение платежа,Иванов 
Иван Иванович,+79101234455,40811112334410000000,444222333,Иван,Иванов,Иванович,442222 г. Самара, Московское шоссе 311-101
bank_account,000002,[email protected],2468.00,payout,Акция "MandarinBank",Петров 
Александр Васильевич,+79253214455,41022223334445556666,666555444,Александр,Петров,Васильевич,443122 г. Москва, Шоссе энтузиастов 311-101

Набор полей для выплаты по реестру на банковские счета

Элемент	Обяз-ть	Описание
target	да	тип получателя
orderId	Да	номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций
email	Да	email получателя
price	Да	сумма выплаты с копейками через “точку” (0.00)
action	Да	тип операции (`payout`), остается неизменным для всех получателей
reason	Да	назначение платежа
customer_phone	Да	мобильный телефон получателя в формате +79999999999
customer_fullName	Да	ФИО получателя
customer_bankAccount_number	Да	номер банковского счета получателя
customer_bankAccount_bic	Да	БИК банка получателя
customer_firstName	Да	имя получателя
customer_lastName	Да	фамилия получателя
customer_middleName	Да	отчество получателя
customer_address_rawString	Да	адрес получателя

Пример реестра для выплат на банковские мобильные телефоны

target,orderId,action,price,customer_email,customer_phone
phone,00005,payout,50.00,[email protected],+71234567890
phone,00006,payout,250.00,[email protected],+71234567891
phone,00007,payout,100.00,[email protected],+71234567892

Набор полей для выплаты по реестру на мобильные телефоны

Элемент	Обяз-ть	Описание
target	да	тип получателя
orderId	Да	номер заказа в системе Клиента. Значение должно быть уникальным в пределах успешных операций
email	Да	email получателя
price	Да	сумма выплаты с копейками через “точку” (0.00)
action	Да	тип операции (`payout`), остается неизменным для всех получателей
customer_email	Да	адрес электронной почты получателя
customer_phone	Да	мобильный телефон получателя в формате +79999999999

Привязка банковских карт (Card Binding)

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

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

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

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

Привязка банковской карты (full binding)

POST запрос на https://secure.mandarinpay.com/api/card-bindings

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

{
    "customerInfo":
    {
        "email": "[email protected]",
        "phone": "+79001234567"
    },
    "urls":
    {
        "callback": "http://...",
        "return": "http://..."
    }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725",
   "userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
   "jsOperationId": "9874694yr87y73e7ey39ed80"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

Суть данной операции - блокировка (preauth) суммы на банковской карте в размере 1 рубля с последующей разблокировкой. Операция проводится с применением технологии 3DSecure.

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

Блок CUSTOMERINFO

Данный блок является ОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
email	Да	Email пользователя
phone	Да	Телефон пользователя в формате +79999999999 российского образца

Блок URLS

Блок является НЕОБЯЗАТЕЛЬНЫМ

Элемент	Обяз-ть	Описание
callback	Нет	Url для отправки `callback`-уведомления о статусе трназакции
return	Нет	Url для редиректа пользователя после оплаты

Возможна ситуация, при которой привязка принудительно переводится в режим payout-only. Это происходит в случаях, когда от платежной системы приходит ответ с кодом, при котором дальнейшее проведение “автосписаний” невозможно. Такая привязка может быть использована для переводов на нее (см. здесь) или для оплаты в интерактивном режиме (см. здесь)

Привязка с нулевым балансом (payout-only)

Возможна настройка, при которой, в случае, если у пользователя отсутствуют денежные средства на карте (после прохождения 3DSecure получена ошибка с кодом 51), карта привязывается в режим payout-only (status=payout-only в callback-уведомлении). Такая карта может быть использована для переводов на нее (см. здесь) или для оплаты в интерактивном режиме (см. здесь).

Сохранение номера карты (one-side binding)

Создание запроса на сохранение номера карты

{
    "customerInfo":
    {
        "email": "[email protected]",
        "phone": "+79001234567"
    },
    "target":
    {
      "knownCardNumber": "4012888888881881"
    }
}

Ответ в случае успешного создания транзакции (Standard HTTP 200 JSON response):

{
   "id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если транзакция не создана (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

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

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

Использование привязанных карт (binding usage)

Привязанная методом full binding карта может быть использована в дальнейшем для:

Рекуррентных платежей (Автоматических списаний с карты) - см. здесь
Списаний с карты в интерактивном режиме. В этом случае пользователю необходимо заполнить только поле CVV - см. здесь
Автоматических переводов на карту - см. здесь

Роутинг платежей (Routes API)

Документация по продукту MandarinPay Routes находится здесь.

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

Создание запроса на идентификацию (startPersonIdentification)

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

Создание запроса на идентификацию Аккаунта с СНИЛС

{
  "firstName": "Иван",
  "patronymic": "Иванович",
  "lastName": "Иванов",
  "passportNumber": "111111",
  "passportSeries": "1111",
  "phone": "+79999999999",
  "snils": "19033603123"  
}

Создание запроса на идентификацию Аккаунта с ИНН

{
  "firstName": "Иван",
  "patronymic": "Иванович",
  "lastName": "Иванов",
  "passportNumber": "111111",
  "passportSeries": "1111",
  "phone": "+79999999999",
  "snils": "",
  "inn": "501716749325"  
}

Ответ в случае успешного создания запроса (Standard HTTP 200 JSON response):

{
  "id" : "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

В случае успешного создания запроса вам вернется идентификатор сессии id, а на используемый номер телефона будет отправлено смс-сообщение с кодом для подтверждения номера телефона

Подтверждение номера телефона (setPersonConfirmCode)

PUT https://secure.mandarinpay.com/api/personidentification/{id}

Подтверждение номера телефона через смс

{
  "smsCode": "123456"
}

Ответ в случае успешного создания запроса (Standard HTTP 200 JSON response):

{
  "id" : "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Ответ в случае ошибки (Standard HTTP 400 Bad request):

{
   "error": "Invalid request"  
}

В качестве значения {id} используется полученный на предыдущем этапе {id}. В случае, если клиентом введена неверная смс, то есть на этапе проверки статуса вами получен "phoneVerified": false, вы можете повторять отправку данного запроса, передав тот же {id} и новый код, введенный пользователем до тех пор, пока не получите "phoneVerified": true. В текущей версии протокола количество попыток ограничено 5.

Проверка статуса идентификации (getPersonIdentificationResult)

GET https://secure.mandarinpay.com/api/personidentification/{id}

Ответ в случае успешного прохождения запроса (Standard HTTP 200 JSON response):

{
  "id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d",
  "phoneVerified": true,
  "phoneVerificationFinished": true,
  "personVerified": true,
  "personVerificationFinished": true,
  "personVerificationError": "string"
}

Описание структуры ответа

Элемент	Описание
phoneVerified	`null` - переданный код еще не проверен, `true` - переданный код верный, `false` - переданный код неверный
phoneVerificationFinished	`true` - проверка кода завершена, `false` - проверка кода не завершена
personVerified	`null` - идентификация не завершена, `true` - идентификация завершена, данные верны, `false` - идентификация завершена, данные неверны
personVerificationFinished	`true` - проверка данных завершена, `false` - проверка данных не завершена
personVerificationError	описание ошибки в случае ее наличия. При отсутствии ошибок имеет значение `null`

CMS Plugins

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

В случае, если вы хотите модифицировать модуль, документация по API форм доступна здесь

Diafan CMS

Новая версия

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

Joomla

Joomla3 Ksenmart

Joomla3.4 VirtueMart3

joomla2.5 JoomShopping3

joomla3 JoomShopping4

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

CS-CART

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

Bitrix

Скачать плагин для 1С-Битрикс

Скачать плагин для 1С-Битрикс Малый Бизнес

Drupal Ubercart

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

Magento

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

ModX

ModX Revo

ModX Evo

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

Opencart

PHP Shop

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

Prestashop

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

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

Simpla

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

UMI.CMS

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

Webasyst

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

Wordpress

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

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

Insales

Инструкции

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

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

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

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

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