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

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

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

ТЕСТИРОВАНИЕ

Данные для тестирования находятся в разделе Платежные сервисы.

Аутентификация

Все запросы к API приема платежей аутентифицируются заголовком x-auth. Формирование значения — в разделе Аутентификация запросов.

Платежная страница

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

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

Платежная страница локализована на русском и английском языках. Язык выбирается автоматически в зависимости от настроек браузера пользователя.

Платежная страница на русском языке

Платежная страница на английском языке

Мобильная верстка платежной страницы

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

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

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

*Для МСС 4814 и МСС 6050 параметр customerInfo.phone является обязательным. Уточнить МСС для ваших банковских терминалов можно у вашего менеджера или обратившись в службу технической поддержки (opens new window).

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

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"  
}

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

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

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

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

Для холдирования доступны два типа операций:

• Авторизация — "action": "auth";
• Предавторизация — "action": "preauth".

Отличия типов холдирования

Тип операции	Значение action	Когда использовать	Особенности
Авторизация	auth	Когда итоговая сумма известна заранее и в большинстве случаев списывается полностью в короткий срок (до 7 дней)	Холд действует до 7 дней. Для частичного списания сначала выполните частичный reversal на разницу, затем pay
Предавторизация	preauth	Когда итоговая сумма может быть меньше захолдированной и нужны частичные списания без отдельного шага разблокировки	Допускается полное или частичное списание; при частичном списании оставшаяся сумма разблокируется автоматически

Авторизация

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

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

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

ВАЖНО

Характеристики авторизации (auth):

• срок холдирования — до 7 дней;
• рекомендуется использовать, если более 50% операций холдирования завершаются списанием на полную сумму;
• если требуется частичное списание, сначала нужно выполнить частичную разблокировку (reversal) на разницу, затем выполнить 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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "auth",
		"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" 
}

Предавторизация

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

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

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"  
}

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

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

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

Для preauth:

• допускается полное или частичное списание;
• при частичном списании оставшаяся сумма разблокируется автоматически.

Для auth:

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

Отмена (reversal) при двухстадийной оплате выполняется через target.transaction.

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

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"
}

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

{
	"error": "Invalid request"  
}

Частичное списание для auth: последовательность reversal -> pay

Если по auth захолдировано 1000.00, а списать нужно 900.00:

1. Выполните reversal на 100.00;
2. Выполните pay на 900.00.

Шаг 1. Частичный reversal

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "reversal",
		"orderId": "your_unique_order_id_reversal",
		"price": "100.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://..."
	}
}'

Шаг 2. Частичный pay на оставшуюся сумму

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "pay",
		"orderId": "your_unique_order_id_pay",
		"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://..."
	}
}'

Сохранение карты на платежной странице

Данный функционал позволяет отображать пользователю ранее сохраненные банковские карты при оплате. Это упрощает повторные платежи и повышает конверсию.

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

Для активации функционала необходимо передать параметр defaultSaveCardData = true.

Параметры

В объект customerInfo добавляются следующие поля:

Параметр	Тип	Обязательность	Описание
clientCustomerId	string	Да	Уникальный идентификатор плательщика (GUID), используется для поиска ранее сохраненных карт.
defaultSaveCardData	boolean	Да	Флаг включения отображения и сохранения карт.

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

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"payment": {
		"action": "pay",
		"orderId": "12345",
		"price": "1000.00"
	},
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79999999999",
		"clientCustomerId": "550e8400-e29b-41d4-a716-446655440000",
		"defaultSaveCardData": true
	}
}'

Поведение системы

• Если у пользователя есть карты, сохраненные ранее на платежной странице, они отображаются в форме; плательщик может выбрать одну из них и ввести только CVV/CVC для оплаты.
• Если сохраненных карт нет, отображается стандартная форма ввода реквизитов; при defaultSaveCardData = true данные карты могут быть сохранены на странице после успешной оплаты.

Особенности

• Параметр clientCustomerId должен быть уникальным и постоянным для каждого плательщика. При его изменении пользователь считается новым, и ранее сохраненные на странице карты не подтягиваются.
• Отображение и сохранение карт работают только при передаче defaultSaveCardData = true.

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

В этом случае плательщик совершает платеж или авторизацию, выбрав сохраненную карту и вводя только 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 платежа

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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

Платеж осуществляется по ранее сохраненной (привязанной) карте без необходимости повторного ввода следующих данных:

• CVV/CVC-код — трехзначный защитный код с обратной стороны карты
• Подтверждение через 3-D Secure — двухфакторную аутентификацию

Особенности:

• Платеж инициируется непосредственно плательщиком;
• Используется ранее сохраненная (привязанная) карта плательщика;
• Отсутствие дополнительных верификационных шагов для плательщика.

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

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

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

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

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"
}

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

{
	"error": "Invalid request"  
}

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

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

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

Mandarin должен получить от вас значения jsOperationId, который получен в ответе на запрос и CVV (через Mandarin Custom Form (opens new window)).

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

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

В Mandarin поддерживаются два основных типа автоматических платежей:

• Платежи, инициированные плательщиком — оплата в один клик (opens new window) по сохраненной карте (без ввода CVV/CVC и прохождения 3-D Secure);

• Платежи, инициированные компанией — рекуррентные платежи, например, автоматическое списание задолженности, на основании ранее полученного токена полных карточных данных или транзакции оплаты, или авторизации без повторного ввода реквизитов карты. В отличие от платежа в один клик (opens new window), совершается без участия плательщика.

Для корректной работы каждого типа платежей требуется:

• Отдельная настройка параметров в системе Mandarin;
• Создание и использование разных Проектов для каждого типа платежей.

Для активации и настройки рекуррентных платежей необходимо обратиться в Службу поддержки (opens new window) или к вашему курирующему менеджеру (opens new window).

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

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

• По безусловно негативных кодам ответов (opens new window) необходимо прекращать попытки списания навсегда.
• По остальным кодам ошибок необходимо ограничить попытки списания - по одной карте можно выполнить только одну повторную попытку в течение дня. Третья и последующие попытки не должны направляться.
• Необходимо разносить платежи равномерно по времени в течение дня и до 1 запроса в секунду на операции.
• Рекуррентные платежи могут быть недоступны для карт 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	Нет

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

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

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"  
}

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

Для активации данного способа оплаты требуется выполнить дополнительные настройки в системе Mandarin Чтобы настроить функционал, пожалуйста, обратитесь в Службу поддержки (opens new window).

Помимо использования токена полных карточных данных, создание рекуррентного платежа возможно на основании любого ранее совершенного успешного платежа ("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	Нет

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

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

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"  
}

Платеж с использованием ранее совершенной оплаты по СБП

Для активации данного способа оплаты требуется выполнить дополнительные настройки в системе Mandarin Чтобы настроить функционал, пожалуйста, обратитесь в Службу поддержки (opens new window).

Рекуррентные списания через СБП выполняются путем вызова API метода с указанием в rebill id ранее проведенной успешной транзакции pay по СБП.

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

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

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

Запрос рекуррентного платежа на основании успешного платежа по СБП

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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": "pay" и id ранее проведенных успешных токенизаций полных карточных данных или id ранее проведенных успешных транзакций (opens new window) в качестве target.rebill.

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

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

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

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions/bulk-force \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '[
    {
        "payment": {
            "orderId": "00000281",
            "action": "pay",
            "price": "200.00"
        },
        "urls": {
            "callback": "https://test.com"
        },
        "target": {
            "rebill": "86257b9c-05cb-4608-b79c-0fd62ad6fc15"
        }
    },
        {
        "payment": {
            "orderId": "00000282",
            "action": "pay",
            "price": "400.00"
        },
        "urls": {
            "callback": "https://test.com"
        },
        "target": {
            "rebill": "86257b9c-05cb-4608-b79c-0fd62ad6fc15"
        }
    },
        {
        "payment": {
            "orderId": "00000283",
            "action": "pay",
            "price": "500.00"
        },
        "urls": {
            "callback": "https://test.com"
        },
        "target": {
            "rebill": "86257b9c-05cb-4608-b79c-0fd62ad6fc15"
        }
    }
]'

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

[
    {
        "id": "58592b2520304d20800d993fe6a2b26a"
    },
    {
        "id": "ec2c99fbd72c401fbd11cd098354aa53"
    },
    {
        "id": "9362c8bf0bdd4edd906bf48934a9917f"
    }
]

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

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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-уведомление могут содержать более широкий набор параметров по сравнению с примером.

Запрос

curl --request POST \
  --url https://secure.mandarinpay.com/api/transactions \
--header 'Content-Type: application/json' \
--header 'x-auth: {{x_auth}}' \
--data-raw '{
	"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"
}

Прием платежей через СБП

Для стандартной платежной страницы подключение СБП для приема платежей производится через техническую поддержку, методы используются полностью идентичные стандартному приему платежей. Подробнее по ссылке.
При оплате у клиента появится кнопка Оплата СБП, при нажатии откроется QR-код для оплаты.

Получение статуса транзакции

Метод API дает возможность по идентификатору операции получить ее статус, а также информацию о карте.

Запрос: operationId - id платежа (opens new window).

curl --request GET \
  --url https://secure.mandarinpay.com/api/operations/{operationId} \
--header 'x-auth: {{x_auth}}'

Пример ответа:

{
    "operationType": "Transaction",
    "state": "Success",
    "card": {
        "cardNumber": "519261XXXXXX3242",
        "cardHolder": "CARD HOLDER",
        "expireDate": "25/01",
        "cardId": "a3a5c49e1385e5096d05075d636f7baf",
        "country": "TUR",
        "productName": "Standard Mastercard Card",
        "productCode": "MCS",
        "brand": "mastercard",
        "bank": "ODEA BANK A.S.",
        "cardType": "Credit"
    }
}

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

Параметр	Описание
operationType	тип операции, транзакция/привязка
state	Статус операции: success, failed, payout-only, pendingExecution/none/unknown - операция не завершена и находится в обработке (может потребоваться сверка с банком-эквайером). Только статус success однозначно указывает на успешность операции!
cardNumber	маскированный номер карты
cardHolder	держатель карты
expireDate	срок действия карты
cardId	уникальный хэш полного номера карты
country	страна выпуска карты
productName	карточный продукт/категория карты
productCode	код карточного продукта/категории карт
brand	платежная система карты
bank	банк, выпустивший карту
cardType	тип карты (дебетовая/кредитная)