# Платежные продукты

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

Вы можете загрузить коллекцию для Postman, в которую уже введены все запросы из данного раздела.

Параметр Тип Описание и возможные значения Где используется (action)
payment object Объект, содержащий данные о транзакции. pay, preauth, reversal, payout
payment.action string Тип транзакции.
Возможные значения:
pay - Платеж;
preauth - Авторизация;
reversal - Отмена транзакции;
payout - Выплата.
pay, preauth, reversal, payout
payment.orderId string Номер заказа в вашей системе. Должен быть уникальным среди успешных операций! pay, preauth, reversal, payout
payment.price string Сумма платежа. Разделитель - точка. pay, preauth, reversal, payout
payment. orderActualTill string Срок резервирования товара/услуги. После указанной даты платеж будет невозможен. Формат: 2020-02-20 12:34:56+00:00. pay, preauth
customerInfo object Объект, содержащий данные о пользователе. pay, preauth, reversal, payout, card-binding
customerInfo. email string Email пользователя. Формат: user@example.com. pay, preauth, reversal, payout, card-binding
customerInfo. phone string Телефон пользователя в формате РФ: +79001234567.
customerInfo. fullName string Владелец карты. Используется и обязателен тогда и только тогда, когда транзакция является выплатой на иностранную карту. payout
senderInfo object Объект, содержащий данные об отправителе выплаты на карту. Используется и обязателен тогда и только тогда, когда транзакция является выплатой на иностранную карту. payout
senderInfo. fullName string Имя отправителя латиницей. Используется и обязательно тогда и только тогда, когда транзакция является выплатой на иностранную карту. payout
senderInfo. birthDate string Дата рождения отправителя. Используется и обязательна тогда и только тогда, когда транзакция является выплатой на иностранную карту. payout
target object Объект, содержащий ссылку на существующую транзакцию/токен карты. pay, reversal, payout, card-binding
target.transaction string Идентификатор существующей транзакции, на которую ссылается новая. pay, reversal
target.card string Токен карты (например, для реккурентных платежей). pay, payout
target. knownCardNumber string Номер карты, на которую осуществляется выплата. payout, card-binding
allowinteractive boolean Индикатор интерактивного (с участием плательщика) платежа, если оплата без участия плательщика невозможна. Поддерживается только в Mandarin Custom Pay. При использовании всегда равен true: "allowinteractive": true pay
interactive boolean Индикатор интерактивного (с участием плательщика) платежа. Поддерживается только в Mandarin Custom Pay. При использовании всегда равен true: "interactive": true pay
customValues[] array Массив, содержащая дополнительную информацию о платеже. Может содержать до 8 пар параметров. Каждый параметр отображается плательщику в правом блоке платежной страницы. pay, preauth, reversal, payout
customValues[]. name string Заголовок параметра (отображаемый в правом блоке платежной страницы). pay, preauth, reversal, payout
customValues[]. value string Значение параметра (отображаемое в правом блоке платежной страницы). pay, preauth, reversal, payout
metadata object Объект, содержащий список ваших параметров с любыми названиями и любыми значениями, которые будут отправлены в callback-уведомлении. Параметры не отображаются в пользовательском интерфейсе плательщика. Названия параметров не могут содержать пробелы! pay, preauth, reversal, payout
urls object Объект, содержащий url. Если отсутствует, то используются url из настроек. pay, preauth, reversal, payout, card-binding
urls.return string Url для редиректа пользователя после платежа. pay, preauth, reversal, payout, card-binding
urls.callback string Url для отправки callback-уведомления о статусе трaнзакции. pay, preauth, reversal, payout, card-binding
fiscalInformation object Объект, содержащий фискальную информацию для создания чеков клиентам ЕКАМ и ЧекОнлайн. pay
fiscalInformation. taxationSystem string Система налогообложения.
Возможные значения:
Common - Общая (ОСН);
Simplified - Упрощенная (УСН) "Доходы";
SimplifiedMinusOutlay - Упрощенная (УСН) "Доходы минус расходы";
UnifiedImputedIncome - Единый налог на вмененный доход (ЕНВД);
UnifiedAgricultural - Единый сельскохозяйственный налог (ЕСХН);
Patent - Патентная (ПСН).
pay
fiscalInformation. items[] array Массив строк в чеке. pay
fiscalInformation. items[].description string Наименование товара. pay
fiscalInformation. items[].quantity string Количество или вес. Разделитель - точка. pay
fiscalInformation. items[].totalPrice string Сумма (цена * количество). Разделитель - точка. pay
fiscalInformation. items[].vat string Ставка НДС.
Возможные значения:
None - Без НДС;
Vat0 - НДС по ставке 0%;
Vat10 - НДС по ставке 10%;
Vat18 - НДС по ставке 18%;
Vat20 - НДС по ставке 20%.
pay

# Прием платежей

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

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

# Одностадийная оплата

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
payment.orderActualTill Нет urls Нет
customerInfo Да urls.return Нет
customerInfo.email Да urls.callback Нет
customerInfo.phone Нет
allowinteractive Нет
interactive Нет

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request"  
}

# Двухстадийная оплата

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

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

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

# - Авторизация

Для авторизации денежных средств с карты в рамках двухстадийной схемы оплаты необходимо создать транзакцию, где "action": "preauth".

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

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

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
payment.orderActualTill Нет urls Нет
customerInfo Да urls.return Нет
customerInfo.email Да urls.callback Нет
customerInfo.phone Нет

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "preauth",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request" 
}

# - Авторизация с использованием токена карты

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

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

Для активации этого особого вида авторизации нужно обязательно обговорить технические детали с вашим менеджером!

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

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

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

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
payment.orderActualTill Нет urls Нет
customerInfo Да urls.return Нет
customerInfo.email Да urls.callback Нет
customerInfo.phone Нет
target Да
target.card Да

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "preauth",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если автосписание невозможно (200 ОК)

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

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

{
	"error": "Invalid request"  
}

# - Завершение расчетов

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

Для полного или частичного списания используйте "action": "pay" и полученный в уведомлении об успешной авторизации id в качестве значения для target.transaction. Активного участия плательщика при этом не требуется.

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
customerInfo Да urls Нет
customerInfo.email Да urls.return Нет
customerInfo.phone Нет urls.callback Нет
target Да
target.transaction Да

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "900.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request"  
}

# Платеж по сохраненной карте в интерактивном режиме

В этом случае плательщик совершает платеж или авторизацию, выбрав сохраненную карту и вводя только CVV/CVC-код. Следующее действие зависит от настроек вашего терминала: если он позволяет совершить платеж без прохождения процедуры 3-D Secure, то дополнительных действий не требуется. Иначе произойдет переадресация браузера плательщика на ввод СМС-кода для прохождения 3-D Secure.

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

Если на платеж без использования 3-D Secure поступит опротестование от плательщика, то платежная система автоматически удержит с вас сумму этого платежа.

Кроме того, возможен сценарий, при котором плательщик выбирает сохраненную карту, а затем проходит процедуру 3-D Secure. CVV/CVC-код при этом плательщик не вводит.

При любом сценарии, процесс занимает два этапа:

  1. Инициация.

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

Для инициации платежа/авторизации необходимо передать в Mandarin токен полных карточных данных и индикатор интерактивного платежа "interactive": true.

Синхронный ответ на запрос инициации содержит id платежа, и jsOperationId для создания транзакции через Mandarin Custom Pay.

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
target Да urls Нет
target.card Да urls.return Нет
interactive Да urls.callback Нет

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

Запрос interactive платежа

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"interactive": true,
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"parameter to callback and not to show 0": "0",
		"parameter to callback and not to show 1": "1"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

Ответ в случае успешной инициации (200 ОК)

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

Ответ в случае, если инициация не произошла (400 Bad request)

{
	"error": "Invalid request"  
}

На втором этапе (создание транзакции), Mandarin должен получить от вас значения jsOperationId из предыдущего запроса и CVV (которое передается через Mandarin Custom Pay).

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

# Платеж по сохраненной карте без ввода CVV/CVC-кода и без прохождения 3-D Secure

Вы можете передать в запросе токен полных карточных данных и "allowinteractive": true вместо "interactive": true. Тогда Mandarin проведет обычный реккурентный платеж (автосписание), не спрашивая никакой дополнительной информации у плательщика.

Если токен полных карточных данных находится в статусе payout-only (а значит, автосписание по нему невозможно), то Mandarin попытается спасти положение, переключившись на сценарий интерактивного платежа с "interactive": true, и вместо ошибки Card binding is payout-only вернет значение jsOperationId (тогда вам все-таки нужно будет передать CVV-код для такого токена карты).

Для проверки на тестовом (sandbox) окружении используйте номер карты 5192618384533242 для токенизации. Эта карта токенизируется с принудительным переводом в статус payout-only. Затем используйте ее токен в примере ниже.

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
target Да urls Нет
target.card Да urls.return Нет
allowinteractive Да urls.callback Нет

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

Запрос allowinteractive платежа

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"allowinteractive": true,
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

Ответ в случае успешного автосписания (200 ОК)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

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

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

{
	"error": "Invalid request"  
}

На втором этапе (создание транзакции), Mandarin должен получить от вас значения jsOperationId из предыдущего запроса и CVV (которое передается через Mandarin Custom Pay).

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

# Рекуррентный платеж (автосписание)

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

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

Проведение реккурентных платежей имеет определенные ограничения. В частности, они могут быть недоступны для карт Visa Electron, Maestro, Momentum и т.д.

# - Платеж с использованием токена карты

Для создания повторного списания средств с карты используйте "action": "pay" и id ранее проведённой успешной токенизации полных карточных данных в качестве target.card.

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

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

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
target Да urls Нет
target.card Да urls.return Нет
urls.callback Нет

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

Запрос реккурентного платежа с использованием токена карты

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае, если автосписание невозможно (200 ОК)

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

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

{
	"error": "Invalid request"  
}

# - Платеж с использованием ранее совершенной транзакции

Помимо использования токена полных карточных данных, создание реккурентного платежа возможно на основании любого ранее совершенного успешного платежа ("action": "pay") или авторизации ("action": "preauth") денежных средств.

Используйте "action": "pay" и id ранее проведённой успешной транзакции (pay или preauth) в качестве target.rebill.

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
target Да urls Нет
target.rebill Да urls.return Нет
urls.callback Нет

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

Запрос реккурентного платежа на основании успешного платежа/авторизации

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"target": {
		"rebill": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

# Отмена и возврат

# - Отмена авторизации

Для разблокировки авторизованной суммы используйте "action": "reversal" и полученный в уведомлении об успешной авторизации id в качестве значения для target.transaction. Активного участия плательщика при этом не требуется. Отмена производится для всей авторизованной суммы.

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
customerInfo Да metadata Нет
customerInfo.email Да urls Нет
customerInfo.phone Нет urls.return Нет
target Да urls.callback Нет
target.transaction Да

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "reversal",
		"orderId": "your_unique_order_id"
	},
	"customerInfo":
	{
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request" 
}

# - Отмена платежа

Для отмены успешной транзакции на списание средств с карты ("action": "pay") используйте "action": "reversal" и id ранее проведённой транзакции в качестве target.transaction.

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

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
target Да urls Нет
target.transaction Да urls.return Нет
urls.callback Нет

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "reversal",
		"orderId": "your_unique_order_id",
    	"price": "1000.00"
	},
	"target": {
		"transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"
}

# Сохранение дополнительной информации

Вы можете передавать в запросе дополнительную информацию о платеже.

Массив customValues может содержать до 8 пар параметров, которые отображаются плательщику в правом блоке платежной страницы. Объект metadata может содержать json с любыми названиями полей и их значениями, при этом плательщику они не отображаются.

Например, кредитная организация принимает ежемесячные платежи от своих клиентов. Массив customValues может содержать номер договора и сумму комиссии с плательщика. Объект metadata пусть содержит источник (source), из которого плательщик открыл платежную страницу, и дату отправки уведомления (sent_at).

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1030.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "Номер договора", "value": "К-12345-789"},
		{"name": "Комиссия", "value": "30.00"}
	],
	"metadata": {
		"source": "email",
		"sent_at": "2020-01-31"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request"  
}

ОБРАБОТКА ДАННЫХ

Значения value из массива customValues сохраняются в параметрах cs2, cs3, cs4, cs5, cs6, cs7, cs8, cs9 в том порядке, в которым они были переданы (если не переданы, то значения - пустые). Они являются частью платежной транзакции и доступны из личного кабинета, в callback-уведомлении и т.д.

Блок metadata может иметь сложную структуру. Он возвращается только в callback-уведомлении точно в таком же виде, в котором был передан. В дальнейшем эта информация не сохраняется.

# Фискализация (чеки)

Mandarin поддерживает передачу фискальной информации в онлайн-кассы ЕКАМ (opens new window) и ЧекОнлайн (opens new window). Если вы являетесь клиентом этих сервисов, то вы можете воспользоваться готовой интеграцией от Mandarin.

В запрос платежа добавляется объект fiscalInformation, который содержит массив строк в чеке и выбранную систему налогообложения. Каждая строка включает в себя наименование, количество, сумму строки и ставку НДС.

Параметр Обязателен Параметр Обязателен
payment Да metadata Нет
payment.action Да urls Нет
payment.orderId Да urls.return Нет
payment.price Да urls.callback Нет
payment.orderActualTill Нет fiscalInformation При необходимости
customerInfo Да fiscalInformation.taxationSystem Да
customerInfo.email Да fiscalInformation.items[] Да
customerInfo.phone Нет fiscalInformation.items[].description Да
customValues[] Нет fiscalInformation.items[].quantity Да
customValues[].name Нет fiscalInformation.items[].totalPrice Да
customValues[].value Нет fiscalInformation.items[].vat Да

Поле taxationSystem указывается один раз и содержит систему налогообложения, общую для всего чека. Возможные значения:

  • Common - Общая (ОСН);
  • Simplified - Упрощенная (УСН) "Доходы";
  • SimplifiedMinusOutlay - Упрощенная (УСН) "Доходы минус расходы";
  • UnifiedImputedIncome - Единый налог на вмененный доход (ЕНВД);
  • UnifiedAgricultural - Единый сельскохозяйственный налог (ЕСХН);
  • Patent - Патентная (ПСН).

Поле vat указывается в каждой строке и содержит ставку НДС. Возможные значения:

  • None - Без НДС;
  • Vat0 - НДС по ставке 0%;
  • Vat10 - НДС по ставке 10%;
  • Vat18 - НДС по ставке 18%;
  • Vat20 - НДС по ставке 20%.

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	},
	"fiscalInformation": {
		"taxationSystem": "Common",
		"items": [{
			"quantity": 10,
			"vat": "Vat20",
			"description": "Товар",
			"totalPrice": "800.00"
		}, {
			"quantity": 1,
			"vat": "Vat20",
			"description": "Доставка",
			"totalPrice": "200.00"
		}]
	}
}

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

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

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

{
	"error": "Invalid request"  
}

Для подключения необходимо выполнить следующие действия (на примере ЕКАМ):

  1. Войти в личный кабинет ЕКАМ, созданный вашим менеджером Mandarin. Перейти в верхнем меню в раздел "Сайты", а затем нажать кнопку "Добавить".
  2. Выбрать источник чеков "Закрытое приложение" (внизу списка).
  3. Ввести в поле Client ID значение 4744f46f93a20923f465, в поле Client Secret Key - значение 9c03385c1c149422f960a420b39bdb185c0d54e7b6c843757ae33842cf18. Затем вы получите токен доступа.
  4. Сообщите токен доступа вашему менеджеру или в заявке для Cлужбы поддержки (opens new window) Mandarin.

Интерфейс ЕКАМ

Более подробная инструкция по настройке интеграции между Mandarin и ЕКАМ находится на сайте ЕКАМ (opens new window).

Кроме того, ЕКАМ предоставляет специальный тариф для клиентов Mandarin (opens new window).

# Токенизация

Токенизация используется для целей списания/зачисления на карту без участия пользователя, а также для проверки того, что пользователь имеет доступ к данной карте (списание контрольной суммы, проверка через 3-D Secure).

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

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

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

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

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

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

Параметр Обязателен Параметр Обязателен
customerInfo Да metadata Нет
customerInfo.email Да urls Нет
customerInfo.phone Нет urls.return Нет
urls.callback Нет

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

Запрос

POST https://secure.mandarinpay.com/api/card-bindings
{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

Ответ в случае успешной токенизации (200 ОК)

{
	"id": "43913ddc000c4d3990fddbd3980c1725",
	"userWebLink": "https://secure.psp.io/CardBindings/New?id=4c9932c6-5e57-4807-9103-8c4083a06d23",
	"jsOperationId": "binding_4c9932c6-5e57-4807-9103-8c4083a06d23"
}
}

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

{
	"error": "Invalid request"  
}

Токенизация с нулевым балансом (для выплат)

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

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

Рассмотрим эту ситуацию подробнее. В соответствии с требованиями международных платежных систем, введено ограничение на проведение рекуррентных платежей в случае получения следующих отказов многократно (более 4 раз за 16 календарных дней - для карт Visa, более 3 раз за 30 календарных дней - для карт MasterCard, более 2 раз за 14 календарных дней - для карт МИР):

  • с кодом "05" (отказать без указания причины).
  • с кодом "51" (отказать, на счете недостаточно средств).
  • с кодом "61" (отказать, превышение максимальной суммы операции для данной карты).
  • с кодом "65" (отказать, превышение максимального количества операций для данной карты).

В случае превышения лимитов, операция завершается с кодом "66" (отказать, обратиться в службу безопасности). Повторное проведение рекуррентного платежа становится возможным по истечении некоторого срока (16 календарных дней - для карт Visa, 30 календарных дней - для карт MasterCard, 14 календарных дней - для карт МИР) с момента последней неуспешной попытки запроса на проведение рекуррентного платежа.

Если количество отказов не превышает допустимое количество раз, то одна успешная операция по карте сразу же приводит к обнулению счетчика отказов с кодами "05", "51", "61", "65".

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

  • с кодом "14" (неверный номер карты).
  • с кодом "54" (срок действия карты истек).
  • с кодом "57" (недопустимый тип операции для данной карты).
  • с кодами "04", "07", "33", "35", "36", "37", "38", "41", "43", "67" (изъять карту, различные причины).

# Токенизация номера карты

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

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

Параметр Обязателен Параметр Обязателен
customerInfo Да target Да
customerInfo.email Да target.knownCardNumber Да
customerInfo.phone Нет metadata Нет

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

Запрос

POST https://secure.mandarinpay.com/api/card-bindings
{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
  	"target": {
		"knownCardNumber": "4012888888881881"
    },
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	}
}

Ответ в случае успешной токенизации (200 ОК)

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

# Использование токенов

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

  1. Рекуррентных платежей (автосписаний) с использованием токена карты.
  2. Платежей по сохраненной карте в интерактивном режиме. В этом случае пользователю необходимо заполнить только поле CVV.
  3. Платежей по сохраненной карте без ввода CVV/CVC-кода и без прохождения 3-D Secure. В этом случае произойдет автосписание. Если оно невозможно, то пользователю необходимо будет заполнить только поле CVV.
  4. Авторизации с использованием токена карты (активируется по запросу клиента).
  5. Автоматических выплат на карту.

# Выплаты на карту

В настоящий момент Mandarin поддерживает выплаты только на банковские карты.

# Выплата с использованием токена карты

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

Значение orderId должно быть уникальным в пределах успешных операций вывода средств. Если Вы не получили успешный callback и хотите повторно запросить ту же самую выплату, рекомендуем использовать тот же самый номер orderId. Это предотвратит дублирование выплаты, если первоначальная выплата была произведена, но успешный callback не дошел.

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

Параметр Обязателен Параметр Обязателен
payment Да target Да
payment.action Да target.card Да
payment.orderId Да customValues[] Нет
payment.price Да customValues[].name Нет
customerInfo Для зарубежных карт customValues[].value Нет
customerInfo.fullName Для зарубежных карт metadata Нет
senderInfo Для зарубежных карт urls Нет
senderInfo.fullName Для зарубежных карт urls.callback Нет
senderInfo.birthDate Для зарубежных карт urls.return Нет

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"fullName": "Peter Petrov"
	},
	"senderInfo": {
		"fullName": "Ivan Petrov",
		"birthDate": "1970.01.01"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

# Выплата с использованием номера карты

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

Значение orderId должно быть уникальным в пределах успешных операций вывода средств. Если Вы не получили успешный callback и хотите повторно запросить ту же самую выплату, рекомендуем использовать тот же самый номер orderId. Это предотвратит дублирование выплаты, если первоначальная выплата была произведена, но успешный callback не дошел.

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

Параметр Обязателен Параметр Обязателен
payment Да target Да
payment.action Да target.knownCardNumber Да
payment.orderId Да customValues[] Нет
payment.price Да customValues[].name Нет
customerInfo Да customValues[].value Нет
customerInfo.email Да metadata Нет
customerInfo.phone Да urls Нет
customerInfo.fullName Для зарубежных карт urls.callback Нет
senderInfo Для зарубежных карт urls.return Нет
senderInfo.fullName Для зарубежных карт
senderInfo.birthDate Для зарубежных карт

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567",
		"fullName": "Peter Petrov"
	},
	"senderInfo": {
		"fullName": "Ivan Petrov",
		"birthDate": "1970.01.01"
	},
	"target": {
		"knownCardNumber": "4012888888881881"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

# Выплата со вводом карты на платежной странице

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

Параметр Обязателен Параметр Обязателен
payment Да customValues[] Нет
payment.action Да customValues[].name Нет
payment.orderId Да customValues[].value Нет
payment.price Да metadata Нет
customerInfo Да urls Нет
customerInfo.email Да urls.callback Нет
customerInfo.phone Да urls.return Нет
customerInfo.fullName Для зарубежных карт
senderInfo Для зарубежных карт
senderInfo.fullName Для зарубежных карт
senderInfo.birthDate Для зарубежных карт

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

Запрос

POST https://secure.mandarinpay.com/api/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567",
		"fullName": "Peter Petrov"
	},
	"senderInfo": {
		"fullName": "Ivan Petrov",
		"birthDate": "1970.01.01"
	},
	"customValues": [
		{"name": "first parameter to save and show", "value": "p1"},
		{"name": "second parameter to save and show", "value": "p2"}
	],
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request"  
}

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

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

Запрос

GET https://secure.mandarinpay.com/api/account/channels/{name}/balance

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

Параметр Описание параметра
openbank_direct Для запроса баланса расчетного счета, открытого в ПАО Банк «ФК Открытие» (Открытие)
psb_direct Для запроса баланса расчетного счета, открытого в ПАО Промсвязьбанк (ПСБ)

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

<?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/openbank_direct/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);
?>

# New! Роутинг

# Создание аккаунта (Роутинг)

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

Существуют аккаунт физлица ("accountType": "individual") и аккаунт юрлица ("accountType": "business").

# - Создание аккаунта физлица (Роутинг)

Для создания аккаунта физлица, обязателен один из параметров: номер его телефона или адрес email. Остальные параметры опциональны.

Параметр Тип Обязателен Описание
accountType string Да Тип аккаунта, для физлица принимает значение individual.
phone string Да, если не указан email Мобильный номер, в формате +79001234567.
email string Да, если не указан phone Email пользователя в формате user@example.com.
name string Нет ФИО пользователя.

Синхронный ответ содержит id (идентификатор) аккаунта.

Запрос

POST https://api.mandarin.io/secure/account/connect
{
	"accountType": "individual",
	"phone": "+79001234567",
	"email": "user@example.com",
	"name": "Иванов Иван Иванович"
}

Ответ в случае успешного создания аккаунта (200 ОК)

{
	"account": {
		"id": "e4276415-029f-4c58-b193-8ad1417e0851",
		"type": "individual"
	}
}

Ответ в случае, если запрос не создан (400 Bad request)

{
	"error": "Invalid request"  
}

# - Создание аккаунта юрлица (Роутинг)

Создание аккаунта юрлица - более долгий процесс, для которого необходимо зарегистрировать личный кабинет для этого юрлица (opens new window), пройдя шаги от (1) подачи заявки до (4) завершения обработки анкеты. В заключение, нужно обратиться в Cлужбу поддержки (opens new window) для получения токена аккаунта юрлица, и использовать его в запросе ниже.

Параметр Тип Обязателен Описание
accountType string Да Тип аккаунта,
для юрлица принимает значение business.
token string Да Токен аккаунта юрлица.

Синхронный ответ содержит id (идентификатор) аккаунта.

Запрос

POST https://api.mandarin.io/secure/account/connect
{
	"accountType": "business",
	"token": "43913ddc000c4d3990fddbd3980c1725"
}

Ответ в случае успешного создания аккаунта (200 ОК)

{
	"account": {
		"id": "f4287be8-1772-45c5-ae2e-5806f4ee71d5",
		"type": "business"
	}
}

Ответ в случае, если запрос не создан (400 Bad request)

{
	"error": "Invalid request"  
}

# Прием платежей (Роутинг)

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

При этом в любой из запросов добавляется объект routing, содержащий схему распределения платежа. Для приема платежей: сумма значений amount из объекта routing должна быть равна верхнеуровневому amount!

Плательщик может вводить данные карты на платежной странице или встраиваемой форме оплаты Mandarin Custom Pay.

Параметр Тип Обязателен Описание
routing string Да Объект, содержащий параметры роутинга.
routing.destination string Да Массив, содержащий получателей платежа.
routing.destination. accountId string Да Идентификатор аккаунта получателя.
routing.destination. amount.value string Да Сумма, перечисляемая на аккаунт получателя. Для приема платежей: от этой суммы будет удержана комиссия платформы. Разделитель - точка.
routing.destination. amount.currency string Да Валюта суммы, перечисляемой на аккаунт получателя. Сейчас всегда RUB.
routing.destination. platformFeeAmount. value string Да Комиссия платформы, от суммы, перечисляемой на аккаунт получателя. Разделитель - точка.
routing.destination. platformFeeAmount. currency string Да Валюта комиссии платформы. Сейчас всегда RUB.
routing.destination. description string Нет Описание.

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

  • 3950 рублей на аккаунт 16f90c5e-6bc3-11eb-9439-0242ac130002 (который может принадлежать физлицу или юрлицу).
  • 50 рублей на аккаунт платформы.
  • 950 рублей на аккаунт 8ba85f01-8cc8-4161-b45d-ce6442e678ae (который также может принадлежать физлицу или юрлицу).
  • еще 50 рублей на аккаунт платформы. Итого 100 рублей на аккаунт платформы.

Кроме того, Mandarin спишет с аккаунта платформы сумму своей комиссии за платеж (по тарифу, указанному в договоре).

Запрос одностадийной оплаты

POST https://api.mandarin.io/secure/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"amount": {
			"value": "5000.00",
			"currency": "RUB"
		},
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"routing": {
		"destination": [{
				"accountId": "16f90c5e-6bc3-11eb-9439-0242ac130002",
				"amount": {
					"value": "4000.00",
					"currency": "RUB"
				},
				"platformFeeAmount": {
					"value": "50.00",
					"currency": "RUB"
				},
				"description": ""
			},
			{
				"accountId": "8ba85f01-8cc8-4161-b45d-ce6442e678ae",
				"amount": {
					"value": "1000.00",
					"currency": "RUB"
				},
				"platformFeeAmount": {
					"value": "50.00",
					"currency": "RUB"
				},
				"description": ""
			}
		]
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	}
}

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

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

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

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

{
	"error": "Invalid request"  
}

# Выплаты на карту (Роутинг)

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

В запрос добавляется объект routing, содержащий схему распределения платежа. Объект target содержит токен карты, полученный, например, в результате запроса токенизации полных карточных данных.

Параметр Тип Обязателен Описание
routing string Да Объект, содержащий параметры роутинга.
routing.source string Да Массив, содержащий получателей платежа.
routing.source. accountId string Да Идентификатор аккаунта отправителя.
routing.source. amount.value string Да Сумма, перечисляемая на карту получателя. Для выплат: комиссия платформы не входит в эту сумму, и будет удержана "сверху". Разделитель - точка.
routing.source. amount.currency string Да Валюта суммы, перечисляемой на карту получателя. Сейчас всегда RUB.
routing.source. platformFeeAmount. value string Да Комиссия платформы, сверх суммы, перечисляемой на карту получателя. Разделитель - точка.
routing.source. platformFeeAmount. currency string Да Валюта комиссии платформы. Сейчас всегда RUB.
routing.source. description string Нет Описание.

В примере ниже с аккаунта 16f9114a-6bc3-11eb-9439-0242ac130002 списывается 5050 рублей, которые будут зачислены следующим получателям:

  • 5000 рублей на карту с токеном 0eb51e74-e704-4c36-b5cb-8f0227621518.
  • 50 рублей на аккаунт платформы.

Кроме того, Mandarin спишет с аккаунта платформы сумму своей комиссии за выплату на карту (по тарифу, указанному в договоре).

Запрос выплаты с использованием токена российской карты

POST https://api.mandarin.io/secure/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"amount": {
			"value": "5000.00",
			"currency": "RUB"
		},
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"routing": {
		"source": [{
			"accountId": "16f9114a-6bc3-11eb-9439-0242ac130002",
			"amount": {
				"value": "5000.00",
				"currency": "RUB"
			},
			"platformFeeAmount": {
				"value": "50.00",
				"currency": "RUB"
			},
			"description": ""
		}]
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	}
}

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

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

# Выплаты на банковский счет (Роутинг)

В запрос добавляется объект routing, содержащий схему распределения платежа. Объект target содержит реквизиты счета в банке РФ, на который будут выплачены средства.

Параметр Тип Обязателен Описание
routing string Да Объект, содержащий параметры роутинга.
routing.source string Да Массив, содержащий получателей платежа.
routing.source.accountId string Да Идентификатор аккаунта отправителя.
routing.source.amount.value string Да Сумма, перечисляемая на карту получателя. Для выплат: комиссия платформы не входит в эту сумму, и будет удержана "сверху". Разделитель - точка.
routing.source. amount.currency string Да Валюта суммы, перечисляемой на карту получателя. Сейчас всегда RUB.
routing.source. platformFeeAmount.value string Да Комиссия платформы, сверх суммы, перечисляемой на карту получателя. Разделитель - точка.
routing.source. platformFeeAmount.currency string Да Валюта комиссии платформы. Сейчас всегда RUB.
routing.source.description string Нет Описание.
target string Да Объект, в данном запросе содержащий информацию о получателе платежа.
target.bankAccount string Да Объект, содержащий реквизиты счета в банке РФ.
target.bankAccount. accountNumber string Да Номер счета получателя платежа.
target.bankAccount.bic string Да БИК.
target.bankAccount. bankName string Да Наименование банка.
target.bankAccount. correspondentAccountNumber string Да Корреспондентский счет банка.
target.bankAccount.bankCity string Нет Местонахождение банка (город).

В примере ниже с аккаунта 16f9114a-6bc3-11eb-9439-0242ac130002 списывается 5050 рублей, которые будут зачислены следующим получателям:

  • 5000 рублей на банковский счет с реквизитами, указанными в объекте target.bankAccount.
  • 50 рублей на аккаунт платформы.

Кроме того, Mandarin спишет с аккаунта платформы сумму своей комиссии за выплату на российский банковский счет (по тарифу, указанному в договоре).

Запрос выплаты на российский банковский счет

POST https://api.mandarin.io/secure/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"amount": {
			"value": "5000.00",
			"currency": "RUB"
		},
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"routing": {
		"source": [{
			"accountId": "16f91046-6bc3-11eb-9439-0242ac130002",
			"amount": {
				"value": "5000.00",
				"currency": "RUB"
			},
			"platformFeeAmount": {
				"value": "50.00",
				"currency": "RUB"
			},
			"description": ""
		}]
	},
	"target": {
		"bankAccount": {
			"accountNumber": "40817810438068123456",
			"bic": "044525225",
			"bankName": "ПАО СБЕРБАНК",
			"correspondentAccountNumber": "30101810400000000225",
			"bankCity": "Москва"
		}
	}
}

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

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}