# Платежные сервисы

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

Вы можете загрузить коллекцию для 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. merchantFee string Комиссия маркетплейса, взимаемая с плательщика. Если не взимается, то передать 0. Разделитель - точка. Только для Routes. pay, payout
payment. destinationWallet string id аккаунта получателя. Только для Routes. pay
payment. sourceWallet string id аккаунта плательщика. Только для Routes. 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-уведомлении. Блок может содержать json с любыми названиями полей и их значениями. Пробелы не должны использоваться в названиях полей. 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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если автосписание невозможно (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае успешного создания транзакции в интерактивном режиме (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если автосписание невозможно (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если транзакция не создана (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если транзакция не создана (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если транзакция не создана (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"metadata": {
		"parameter_to_callback_and_not_to_show_0": "0",
		"parameter_to_callback_and_not_to_show_1": "1"
	},
	"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": {
		"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",
	"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 раз для карт Visa.
  • до 3 раз для карт MasterCard.
  • до 2 раз для карт МИР.

Список ошибок:

  • код "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": {
		"parameter_to_callback_and_not_to_show_0": "0",
		"parameter_to_callback_and_not_to_show_1": "1"
	}
}

Ответ в случае успешной токенизации (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если транзакция не создана (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

Ответ в случае, если транзакция не создана (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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"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} необходимо передать параметр из таблицы ниже:

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

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

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

# New! Routes

# Уровни идентификации аккаунта (Routes)

Для получения средств, последующего вывода и другого использования электронных средств платежа (ЭСП), пользователь (ФЛ) должен иметь аккаунт.

После создания, аккаунт имеет уровень идентификации ЭСП 1 (владелец не идентифицирован).

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

Для увеличения лимитов, владелец может пройти полную идентификацию. Для этого необходимо посетить офис расчетного банка в Москве (opens new window). Аккаунт получает тип ЭСП 3 (владелец прошел полную идентификацию).

Уровень идентификации Максимальный остаток на балансе (руб.) Максимальный объем переводов, всего (руб.) Максимальный объем вывода на карту и аккаунт (руб.)
ЭСП 1 (ФЛ, владелец не идентифицирован) 0 0 Запрещен
ЭСП 2 (ФЛ, владелец упрощенно идентифицирован) 15 тыс. 15 тыс./операция и 40 тыс./месяц, на ЮЛ и ФЛ 15 тыс./операция и 40 тыс./месяц
ЭСП 3 (ФЛ, владелец прошел полную идентификацию) 600 тыс. 600 тыс./операция, месячного лимита нет, на ЮЛ и ФЛ 600 тыс./операция, месячного лимита нет

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

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

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

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

Параметр Тип Обязателен Описание
type string Да Тип аккаунта,
всегда принимает значение person.
phone string Да Мобильный номер,
в формате +79001234567.

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/wallets
{
    "type": "person",
    "person": {
        "phone": "+79001234567"
    }
}

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

{
	"id": "d1387389-b6c7-4a80-81a4-3960ed96cfd0"
}

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

{
	"error": "Invalid request" 
}

# Запрос баланса аккаунта (Routes)

Запрос баланса включает в себя id аккаунта (в адресе). Например, d1387389-b6c7-4a80-81a4-3960ed96cfd0.

Синхронный ответ содержит значение баланса аккаунта в рублях.

Запрос

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

GET https://api.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/balance

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

GET https://api-sandbox.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/balance

Ответ, содержащий баланс нового аккаунта (200 ОК)

{
    "RUB": 0
}

Ответ, содержащий баланс аккаунта после пополнения (200 ОК)

{
    "RUB": 5000.0
}

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

{
	"error": "Invalid request" 
}

# Инициализация процесса идентификации (Routes)

Процесс упрощенной идентификации для Routes не отличается от основного процесса упрощенной идентификации, который описан подробно на отдельной странице.

Simplified Identification Diagram

Запрос на инициализацию процесса идентификации может быть отправлен с двумя наборами параметров (вариант со СНИЛС или вариант с ИНН). В качестве серии и номера паспорта можно передать только данные паспорта гражданина РФ.

Запрос баланса включает в себя id аккаунта (в адресе). Например, d1387389-b6c7-4a80-81a4-3960ed96cfd0.

Параметр Тип Обязателен Описание
firstName string Да Имя.
patronymic string Да Отчество.
lastName string Да Фамилия.
passportSeries string Да Серия паспорта РФ.
passportNumber string Да Номер паспорта РФ.
snils string Нет Номер СНИЛС.
inn string Нет Номер ИНН.
phone string Да Мобильный номер,
в формате +79001234567.

В случае успешной регистрации запроса вы синхронно получите идентификатор сессии sessionId, который необходимо использовать в следующих запросах. На указанный в параметре phone мобильный номер будет отправлено СМС-сообщение с кодом для подтверждения номера телефона.

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

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

POST https://api.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification

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

POST https://api-sandbox.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification
{
	"firstName": "Иван",
	"patronymic": "Иванович",
	"lastName": "Иванов",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "19033603123",
	"phone": "+79001234567"
}

Запрос на идентификацию по ИНН

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

POST https://api.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification

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

POST https://api-sandbox.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification
{
	"firstName": "Иван",
	"patronymic": "Иванович",
	"lastName": "Иванов",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"inn": "501716749325",
	"phone": "+79001234567"
}

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

{
	"sessionId": "0dae98e5-8274-42fe-9e65-a884087d4e9b"
}

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

{
	"error": "Invalid request" 
}

# Передача СМС-кода (Routes)

В адресной строке запрос содержит два параметра. Первый из них - id аккаунта, полученный при его создании (например, d1387389-b6c7-4a80-81a4-3960ed96cfd0). Второй - sessionId, полученный при запросе на идентификацию аккаунта (например, 0dae98e5-8274-42fe-9e65-a884087d4e9b).

В теле запросе содержится СМС-код.

Параметр Тип Обязателен Описание
smsCode string Да СМС-код.

В случае успешной регистрации запроса вы синхронно получите тот же самый идентификатор сессии sessionId.

В случае, если пользователь неправильно ввел СМС-код, то на этапе проверки статуса вы получите "phoneVerified": false. Тогда вы можете повторять отправку данного запроса, передав те же параметры в адресной строке, и новый СМС-код, введенный пользователем, до тех пор, пока не получите "phoneVerified": true.

ВАЖНО!

Текущая версия протокола позволяет использовать до 5 (включительно) попыток передачи СМС-кода. Если лимит превышен, то необходимо инициализировать процесс идентификации заново.

Запрос

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

PUT https://api.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification/0dae98e5-8274-42fe-9e65-a884087d4e9b

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

PUT https://api-sandbox.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification/0dae98e5-8274-42fe-9e65-a884087d4e9b
{
	"code": "123456"
}

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

{
	"sessionId": "0dae98e5-8274-42fe-9e65-a884087d4e9b"
}

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

{
	"error": "Invalid request" 
}

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

В адресной строке запрос содержит два параметра. Первый из них - id аккаунта, полученный при его создании (например, d1387389-b6c7-4a80-81a4-3960ed96cfd0). Второй - sessionId, полученный при запросе на идентификацию аккаунта (например, 0dae98e5-8274-42fe-9e65-a884087d4e9b).

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

  1. Проверка имени, отчества, фамилии, серии и номера паспорта, СНИЛС/ИНН (один из двух) производится через СМЭВ.
  2. Проверка номера мобильного телефона выполняется с помощью отправки СМС-кода.

Ответ содержит индикаторы окончания обеих проверок и индикаторы правильности предоставленных данных.

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

Запрос

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

GET https://api.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification/0dae98e5-8274-42fe-9e65-a884087d4e9b

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

GET https://api-sandbox.mandarinpay.com/v1/wallets/d1387389-b6c7-4a80-81a4-3960ed96cfd0/identification/0dae98e5-8274-42fe-9e65-a884087d4e9b

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

{
	"phoneVerified": true,
	"phoneVerificationFinished": true,
	"personVerified": true,
	"personVerificationFinished": true,
	"personVerificationError": ""
}

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

{
	"error": "Invalid request" 
}

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

Синхронный ответ содержит следующую информацию:

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

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

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

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

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

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

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/card-bindings
{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"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",
	"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"  
}

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

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

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

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

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

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/card-bindings
{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
  	"target": {
		"knownCardNumber": "4012888888881881"
    },
	"metadata": {
		"parameter_to_callback_and_not_to_show_0": "0",
		"parameter_to_callback_and_not_to_show_1": "1"
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

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

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

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

# - Тарификация и комиссии для приема платежей

Комиссия Mandarin прописывается в договоре с маркетплейсом и не передается в запросах. Mandarin списывает ее автоматически с внутреннего счета маркетплейса.

Комиссия маркетплейса merchantFee именно для пополнения учитывается внутри суммы к списанию price.

# - Пример 1. Стандартное пополнение

В договоре с Mandarin указано, что комиссия Mandarin составляет 3% от суммы платежа (для операции пополнения аккаунта).

Маркетплейс передает запрос на пополнение, содержащий:

  • сумму платежа price, которая будет списана с карты (1000 рублей).
  • комиссию маркетплейса merchantFee (130 рублей).

С карты плательщика будет списано 1000 рублей.

На счет маркетплейса будет зачислено 130 рублей, и сразу списано 30 рублей (3% от 1000 руб.). В результате, баланс счета маркетплейса увеличится на 100 рублей.

На счет саб-мерчанта будут зачислены оставшиеся 870 рублей.

# - Пример 2. Пополнение за счет маркетплейса

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

Как в предыдущем примере, в договоре с Mandarin указано, что комиссия Mandarin составляет 3% от суммы платежа (для операции пополнения счета аккаунта).

Маркетплейс передает запрос на пополнение, содержащий:

  • сумму платежа price (1000 рублей).
  • комиссию маркетплейса merchantFee (0 рублей).

С карты плательщика будет списано 1000 рублей.

На счет маркетплейса будет зачислено 0 рублей, и сразу списано 30 рублей (3% от 1000 руб.). В результате, баланс счета маркетплейса уменьшится на 30 рублей. Мерчант должен следить, чтобы баланс счета оставался положительным, иначе операция не будет осуществлена.

На счет саб-мерчанта будут зачислены 1000 рублей (столько же, сколько было списано с карты плательщика).

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

Описание работы содержится в основной главе про одностадийную оплату. Вариант для Routes имеет такую же логику работы, поддерживаются платежи по сохраненной карте в интерактивном режиме и без ввода CVV/CVC-кода и без 3-D Secure.

Для Routes добавлены два обязательных параметра:

  • merchantFee - комиссия маркетплейса, взимаемая с плательщика. Не может быть больше значения price. Если не взимается, то нужно передать 0. Разделитель - точка.
  • destinationWallet - идентификатор аккаунта получателя.

Параметр price при этом хранит сумму платежа, списываемую с карты плательщика и включающую в себя все комиссии.

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

В примере ниже с карты плательщика будет списано 1000 рублей. Саб-мерчант получает 870 рублей. Маркетплейс получает 130 рублей в виде комиссии (комиссия учитывается внутри суммы к списанию), из которой 30 рублей будут списаны как комиссия Mandarin (согласно условиям договора).

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
        "merchantFee": "130.00",
        "destinationWallet": "d1387389-b6c7-4a80-81a4-3960ed96cfd0",
		"orderActualTill": "2020-02-20 12:34:56+00:00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
	"jsOperationId": "9874694yr87y73e7ey39ed80"
}

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

{
	"error": "Invalid request"  
}

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

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

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

В примере ниже с карты плательщика будет списано 1000 рублей. Саб-мерчант получает 870 рублей. Маркетплейс получает 130 рублей в виде комиссии (комиссия учитывается внутри суммы к списанию), из которой 30 рублей будут списаны как комиссия Mandarin (согласно условиям договора).

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"merchantFee": "130.00",
		"destinationWallet": "d1387389-b6c7-4a80-81a4-3960ed96cfd0"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

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

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

{
	"error": "Invalid request"  
}

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

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

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

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

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

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

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

Описание работы содержится в основной главе про авторизацию. Вариант для Routes имеет такую же логику работы, но при этом отличается адрес.

Параметр Обязателен Параметр Обязателен
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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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",
	"userWebLink": "https://secure.mandarinpay.com/Pay?transaction=0eb51e74-e704-4c36-b5cb-8f0227621518",
	"jsOperationId": "9874694yr87y73e7ey39ed80"
}

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

{
	"error": "Invalid request" 
}

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

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

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

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

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

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

Параметр Обязателен Параметр Обязателен
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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/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": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

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

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

{
	"error": "Invalid request"  
}

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

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

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

При этом:

  • price - сумма платежа, списываемая с карты плательщика и включающая в себя все комиссии. Значение price может быть любым в пределах значения, переданного в изначальной транзакции авторизации, где был указан "action": "preauth".
  • merchantFee - комиссия маркетплейса, взимаемая с плательщика. Не может быть больше значения price. Если не взимается, то нужно передать 0. Разделитель - точка.
  • destinationWallet - идентификатор аккаунта получателя.
Параметр Обязателен Параметр Обязателен
payment Да target Да
payment.action Да target.transaction Да
payment.orderId Да customValues[] Нет
payment.price Да customValues[].name Нет
payment.merchantFee Да customValues[].value Нет
payment.destinationWallet Да metadata Нет
customerInfo Да urls Нет
customerInfo.email Да urls.return Нет
customerInfo.phone Нет urls.callback Нет

Транзакция завершения расчетов в примере ниже ссылается на авторизацию суммы 1000 рублей. Так как price принимает значение 900 рублей, то оставшиеся 100 рублей будут возвращены на карту плательщика автоматически. Саб-мерчант получает 770 рублей. Маркетплейс получает 130 рублей в виде комиссии (комиссия учитывается внутри суммы к списанию), из которой 30 рублей будут списаны как комиссия Mandarin (согласно условиям договора).

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

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id",
		"price": "900.00",
		"merchantFee": "130.00",
		"destinationWallet": "d1387389-b6c7-4a80-81a4-3960ed96cfd0"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

{
	"error": "Invalid request"  
}

# Отмена авторизации (Routes)

Для разблокировки авторизованной суммы используйте "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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "reversal",
		"orderId": "your_unique_order_id"
	},
	"customerInfo":
	{
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"transaction": "43913ddc000c4d3990fddbd3980c1725"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

{
	"error": "Invalid request" 
}

# Отмена платежа (Routes)

Платеж в Routes включает в себя несколько комиссий:

  • комиссия от плательщика к маркетплейсу.
  • комиссия от маркетплейсу к Mandarin.

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

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

# Выплаты на карту (Routes)

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

# - Тарификация и комиссии для выплат

Комиссия Mandarin прописывается в договоре с маркетплейсом и не передается в запросах. Mandarin списывает ее автоматически с внутреннего счета маркетплейса.

Комиссия маркетплейса именно для списания учитывается сверху от суммы к списанию.

# - Пример

В договоре с Mandarin указано, что комиссия Mandarin составляет 2% + 30 рублей (для операции вывода на карту).

Маркетплейс передает запрос на вывод, содержащий:

  • сумму вывода, которая будет зачислена на карту (1000 рублей).
  • комиссию маркетплейса (150 рублей).

Со счета саб-мерчанта будет списано 1150 рублей.

На счет маркетплейса будет зачислено 150 рублей, и сразу списано 50 рублей (2% от 1000 руб. + 30 рублей). В результате, баланс счета маркетплейса увеличится на 100 рублей.

На карту получателя будут зачислены запрошенные 1000 рублей.

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

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

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

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

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

Транзакция выплаты на карту в примере ниже списывает со счета саб-мерчанта 1150 рублей. На карту будет зачислено 1000 рублей. Маркетплейс получает 150 рублей в виде комиссии (комиссия учитывается сверху от суммы к списанию), из которой 50 рублей будут списаны как комиссия Mandarin (согласно условиям договора).

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

Запрос (для российских карт)

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"merchantFee": "150.00",
		"sourceWallet": "d1387389-b6c7-4a80-81a4-3960ed96cfd0"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"card": "0eb51e74-e704-4c36-b5cb-8f0227621518"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

{
	"error": "Invalid request"  
}

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

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

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

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

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

Транзакция выплаты на карту в примере ниже списывает со счета саб-мерчанта 1150 рублей. На карту будет зачислено 1000 рублей. Маркетплейс получает 150 рублей в виде комиссии (комиссия учитывается сверху от суммы к списанию), из которой 50 рублей будут списаны как комиссия Mandarin (согласно условиям договора).

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

Запрос (для российских карт)

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

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

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

POST https://api-sandbox.mandarinpay.com/v1/transactions
{
	"payment": {
		"action": "payout",
		"orderId": "your_unique_order_id",
		"price": "1000.00",
		"merchantFee": "150.00",
		"sourceWallet": "d1387389-b6c7-4a80-81a4-3960ed96cfd0"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"target": {
		"knownCardNumber": "4012888888881881"
	},
	"customValues": [
		{"name": "parameter to save and show 0", "value": "0"},
		{"name": "parameter to save and show 1", "value": "1"}
	],
	"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"
}

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

{
	"error": "Invalid request"  
}