Mandarin

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

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

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

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

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

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

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

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

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

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

Запрос

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

{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	},
	"urls": {
		"callback": "http://...",
		"return": "http://..."
	}
}

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

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

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

{
	"error": "Invalid request"  
}

# Статус "payout-only"

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

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

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

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

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

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

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

# Токенизация с нулевым балансом

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

  • новый: с использованием параметра checkCard (для платежей и выплат);

  • прежний: с присвоением статуса payout-only (для выплат).

# Токенизация с нулевым балансом при помощи "checkCard"

При использовании терминала ecom none3ds, служба поддержки может включить использование параметра checkCard.

В этом сценарии процедура 3-D Secure не проводится, но возвращается токен полных карточных данных. Таким образом, наличие на карте клиента 1 рубля не обязательно.

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

СЛУЖБА ПОДДЕРЖКИ

Использование параметра checkCard возможно только после настроек со стороны службы поддержки!
Кроме того, поддержка может настроить, чтобы все привязки выполнялись по сценарию без "3-D Secure", даже если параметр checkCard не передан (исключая только те случаи, где в запросе явно указан checkCard: false).

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

Запрос

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

{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
	"checkCard": true,
	"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/CardBindings/New?id=4c9932c6-5e57-4807-9103-8c4083a06d23",
	"jsOperationId": "binding_4c9932c6-5e57-4807-9103-8c4083a06d23"
}

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

{
	"error": "Invalid request"  
}

# Токенизация с нулевым балансом со статусом "payout-only"

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

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

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

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

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

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

Запрос

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

{
	"customerInfo": {
		"email": "user@example.com",
		"phone": "+79001234567"
	},
  	"target": {
		"knownCardNumber": "4012888888881881"
    },
	"metadata": {
		"first_parameter_to_callback_and_not_to_show": "p1",
		"second_parameter_to_callback_and_not_to_show": "p2"
	}
}

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

{
	"id": "43913ddc000c4d3990fddbd3980c1725"
}

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

{
	"error": "Invalid request"  
}

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

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

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

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

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

Авторизация - XAuth (opens new window).

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

GET https://secure.mandarinpay.com/api/operations/{operationId}

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

{
    "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 тип карты (дебетовая/кредитная)

← Выплаты →