Блокировка средств
Помимо этой статьи для работы с разовыми оплатами в две стадии могут быть полезны:
- статья Разовая оплата в две стадии модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в две стадии в платёжной платформе ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций;
- статьи раздела Платёжные методы с описанием того, как выполнять первую стадию оплат в две стадии (блокировку средств) через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом.
Общая информация
Оплата в две стадии, или разовая двухстадийная оплата — это вариант проведения разовой оплаты, в рамках которого для перевода денежных средств от пользователя к мерчанту сначала, на основании исходного запроса, осуществляется предварительная блокировка, а затем, на основании подтверждающего запроса или по истечении заданного периода, — списание заблокированных средств или отмена блокировки. В настоящее время оплаты в две стадии поддерживаются только при работе с платёжными картами.
С использованием Payment Page можно выполнять первую стадию оплат в две стадии — блокировку средств пользователя, в том числе с использованием возможности Mail Order/Telephone Order (MO/TO). Для этого используется режим работы платёжной формы Purchase.
Базовыми действиями пользователя при выполнении первой стадии разовой двухстадийной оплаты с использованием Payment Page могут быть: выбор платёжного инструмента, указание его реквизитов и ожидание уведомления о результате платежа.
Для выполнения второй стадии — списания заблокированных средств или отмены блокировки — следует использовать Gate или Dashboard, либо настроить автоматическое выполнение этой стадии по истечении заданного срока. По вопросам настройки данной функциональности следует обращаться к специалистам технической поддержки — support@ecommpay.com.
При выполнении блокировки средств платёжные данные могут быть указаны одним из следующих способов:
- Через ввод на форме. В этом случае пользователь обязательно заполняет на форме все требуемые поля.
- Через выбор или ввод на форме. В этом варианте, когда при вызове Payment Page был указан идентификатор пользователя, пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем.
В дополнение к выбранным реквизитам для некоторых инструментов требуется подтверждение, такое как ввод проверочного кода (CVC, CVV, CID) при работе с платёжными картами.
- Через выбор до вызова формы. В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты, и платёжная форма открывается с указанием всех реквизитов кроме проверочного кода (CVC, CVV, CID), который необходимо указать непосредственно на форме.
Payment Page при разных способах указания платёжных данных: при заполнении через ввод на форме, выборе из уже сохранённых данных и выборе конкретной карты до вызова формы соответственно.
Ограничения
При выполнении блокировки средств необходимо учитывать, что в соответствии с требованиями платёжных систем Visa, Mastercard и American Express срок, на который можно заблокировать средства пользователя, ограничивается. И для различных типов карт этот срок определяется с учётом разных условий:
- Для карт платёжной системы Visa:
- если блокировка средств выполняется в рамках повторяемой оплаты или с её регистрацией — 5 дней;
- если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code (MCC) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 30 дней;
- в других случаях — 10 дней.
- Для карт Maestro и Cirrus — 6 дней.
- Для других карт платёжной системы Mastercard — 28 дней.
- Для карт платёжной системы American Express:
- если в соответствии с присвоенным мерчанту кодом Merchant Category Code (MCC) его деятельность относится к гостиничному бизнесу, аренде автомобилей или организации круизов — на весь срок проживания, аренды или круиза соответственно;
- в других случаях — 7 дней.
Максимально допустимый срок блокировки средств отсчитывается от момента формирования в платёжной платформе ecommpay операции блокировки (auth). За полчаса до истечения этого срока в зависимости от параметров, указанных сотрудниками ecommpay, автоматически выполняется одна из следующих операций: списание заблокированных средств пользователя (capture) или отмена блокировки средств (cancel). После этого к веб-сервису направляется оповещение о списании средств. Для уточнения информации и изменения типа операции следует обратиться к курирующему менеджеру ecommpay. Исключением являются блокировки с использованием карт платёжной системы American Express, максимально допустимый срок для которых соответствует сроку проживания, аренды или круиза: для таких блокировок автоматическое списание не выполняется.
В случаях, когда в платёжной платформе настроено автоматическое списание или отмена блокировки средств в указанный со стороны мерчанта срок, но этот срок превышает максимально допустимый, списание или отмена выполняются в соответствии с максимально допустимым сроком. Допустим, в соответствии с пожеланиями мерчанта настроена автоматическая отмена блокировки по истечении десяти дней. Тогда для блокировки средств, выполненной с использованием карты Maestro (с максимально допустимым сроком в шесть дней), по истечении шести дней выполняется автоматическая отмена.
Схема работы
Для выполнения блокировки средств с помощью Payment Page со стороны веб-сервиса необходимо:
- Сформировать и отправить в платёжную платформу запрос на открытие Payment Page.
- Принять оповещение о результате выполнения запроса со стороны платёжной платформы.
При выполнении блокировки средств со стороны платёжной платформы может быть инициировано выполнение вспомогательных процедур, требующих участия пользователя:
- Аутентификация 3‑D Secure, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания (в то время, пока эмитент подтверждает подлинность без участия пользователя).
- Аутентификация по инициативе мерчанта, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения.
- Дополнение информации о платеже, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме.
Информация о форматах запросов и оповещений при выполнении блокировки средств с прямым использованием платёжных карт представлена далее, а о форматах запросов и оповещений при выполнении блокировки средств с использованием других платёжных методов, представлена в разделе Методы.
Формат запросов
Формат запроса на открытие Payment Page для выполнения блокировки соответствует описанному в разделе Описание Payment Page API. При формировании такого запроса необходимо учитывать следующее:
- В запросе должны использоваться следующие обязательные параметры:
card_operation_type— тип операции для проведения оплаты с использованием платёжной карты; если по запросу мерчанта в рамках проекта по умолчанию настроена оплата, в параметре необходимо указывать значениеauth;project_id— идентификатор проекта, полученный от ecommpay при интеграции;customer_id— идентификатор пользователя, уникальный в рамках проекта;payment_id— идентификатор платежа, уникальный в рамках проекта;payment_amount— сумма платежа в дробных единицах валюты;payment_currency— код валюты платежа в формате ISO 4217 alpha-3;signature— подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
- Для указания обязательных сведений о пользователе в случае, если не используется возможность указания таких сведений самим пользователем (подробнее), в запросе дополнительно необходимо использовать по крайней мере один из следующих параметров:
customer_emailиcustomer_phone. - Для предварительного выбора платёжной карты в запросе дополнительно необходимо использовать параметр
account_token, в котором необходимо передать токен платёжной карты. - Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр
language_code— код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее). - Для добавления описания платежа в запросе дополнительно необходимо использовать параметр
payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа. - Для проведения оплаты Mail Order (MO) в запросе дополнительно необходимо использовать параметр
moto_typeсо значением1, а для проведения оплаты Telephone Order (TO) — со значением2. - Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Purchase. Полный список параметров вызова Payment Page представлен в разделе Параметры вызова платёжной формы.
Таким образом, корректный запрос на проведение оплаты в две стадии должен содержать идентификаторы проекта, пользователя и платежа, тип платёжной операции auth, код валюты платежа, сумму платежа и подпись. Остальные параметры также могут использоваться в запросах, но не являются обязательными.
{
"card_operation_type": "auth",
"project_id": 42,
"payment_id": "456789",
"customer_id": "customer_12",
"payment_currency": "USD",
"payment_amount": "2000",
"customer_phone": "44991234567",
"signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF...",
// при проведении оплаты по предварительно выбранной карте:
"account_token":"959c664ad64b8caa54bb7836ddc737fd1a679242a039..."
}
https://https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&project_id=42&payment_amount=2000&payment_id=456789&card_operation_type=auth&customer_id=customer_12&customer_phone=44991234567&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhZLxEzkgcoZr...
Формат оповещений
Формат оповещения о результатах выполнения блокировок соответствует описанному в разделе Оповещения.
В следующем примере содержится информация о том, что в рамках проекта 42 для пользователя customer_12 заблокированы средства в размере 2 000,00 USD с использованием платёжной карты 541333******0019.
{
"project_id": 42,
"customer": {
"id": "customer_12",
"phone": "44991234567"
},
"payment": {
"id": "456789",
"type": "purchase",
"status": "awaiting capture",
"date": "2019-01-11T13:00:40+0000",
"method": "card",
"sum": {
"amount": 200000,
"currency": "USD"
},
"description": ""
},
"account": {
"number": "541333****0019",
"type": "mastercard",
"card_holder": "JOHN SMITH",
"expiry_month": "08",
"expiry_year": "2025"
},
"operation": {
"id": 2777000002350,
"type": "auth",
"status": "success",
"date": "2020-01-11T13:00:40+0000",
"created_date": "2020-01-11T13:00:37+0000",
"request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
"sum_initial": {
"amount": 200000,
"currency": "USD"
},
"sum_converted": {
"amount": 200000,
"currency": "USD"
},
"provider": {
"id": 120,
"payment_id": "224750650",
"date": "2020-01-11T13:00:39+0000",
"result_code": "000",
"result_message": "Approved",
"auth_code": "505050",
"endpoint_id": 120
},
"code": "0",
"message": "Success",
"description": "SUCCESS",
"eci": "00"
},
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
В следующем примере блокировка средств была отклонена из-за ввода некорректной даты окончания срока действия карты.
{
"project_id": 42,
"customer": {
"id": "customer_12",
"phone": "44991234567"
},
"payment": {
"id": "456789",
"type": "purchase",
"status": "decline",
"date": "2020-01-11T13:00:40+0000",
"method": "card",
"sum": {
"amount": 200000,
"currency": "USD"
},
"description": ""
},
"account": {
"number": "541333****0019",
"type": "mastercard",
"card_holder": "JOHN SMITH",
"expiry_month": "08",
"expiry_year": "2025"
},
"operation": {
"id": 6304000002973,
"type": "auth",
"status": "decline",
"date": "2020-01-11T13:00:40+0000",
"created_date": "2019-01-11T13:00:34+0000",
"request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c",
"sum_initial": {
"amount": 200000,
"currency": "USD"
},
"sum_converted": {
"amount": 200000,
"currency": "USD"
},
"provider": {
"id": 120,
"payment_id": "239689120",
"date": "2020-01-11T13:00:36+0000",
"result_code": "101",
"result_message": "Decline, expired card",
"auth_code": "",
"endpoint_id": 120
},
"code": "10106",
"message": "Card expired",
"description": "Bank cards. Operation was declined due to incorrect card expiry date entry",
"eci": "00"
},
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
В следующем примере содержится информация о том, что в рамках проекта 42 с платёжной карты №555555******4445 пользователя customer_12 списаны заблокированные ранее средства в размере 2 000,00 USD.
{
"project_id": 42,
"payment": {
"id": "456789",
"type": "purchase",
"status": "success",
"date": "2020-01-11T15:54:40+0000",
"method": "card",
"sum": {
"amount": 200000,
"currency": "USD"
},
"description": ""
},
"account": {
"number": "541333****0019",
"type": "mastercard",
"card_holder": "JOHN SMITH",
"expiry_month": "08",
"expiry_year": "2025"
},
"customer": {
"id": "customer_12",
"phone": "44991234567"
},
"operation": {
"id": 7178000006597,
"type": "capture",
"status": "success",
"date": "2020-01-11T15:54:40+0000",
"created_date": "2019-01-11T15:54:39+0000",
"request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
"sum_initial": {
"amount": 200000,
"currency": "USD"
},
"sum_converted": {
"amount": 200000,
"currency": "USD"
},
"provider": {
"id": 120,
"payment_id": "227307324",
"date": "2020-01-11T15:54:40+0000",
"auth_code": "919372",
"endpoint_id": 120
},
"code": "0",
"message": "Success"
},
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
В следующем примере содержится информация о том, что в рамках проекта 42 для пользователя customer_12 отменена блокировка средств в размере 2 000,00 USD на платёжной карте №555555******4445.
{
"project_id": 42,
"payment": {
"id": "456789",
"type": "purchase",
"status": "canceled",
"date": "2020-01-11T15:54:40+0000",
"method": "card",
"sum": {
"amount": 200000,
"currency": "USD"
},
"description": ""
},
"account": {
"number": "541333****0019",
"type": "mastercard",
"card_holder": "JOHN SMITH",
"expiry_month": "08",
"expiry_year": "2025"
},
"customer": {
"id": "customer_12",
"phone": "44991234567"
},
"operation": {
"id": 18289000007021,
"type": "cancel",
"status": "success",
"date": "2020-01-11T15:54:40+0000",
"created_date": "2020-01-11T15:54:40+0000",
"request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c",
"sum_initial": {
"amount": 200000,
"currency": "USD"
},
"sum_converted": {
"amount": 200000,
"currency": "USD"
},
"provider": {
"id": 120,
"payment_id": "239672146",
"auth_code": "",
"endpoint_id": 120
},
"code": "0",
"message": "Success"
},
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}
В следующем примере отмена блокировки средств была отклонена из-за ввода некорректных данных карты.
{
"account": {
"number": "541333****0019",
"type": "mastercard",
"card_holder": "JOHN SMITH",
"expiry_month": "08",
"expiry_year": "2025"
},
"customer": {
"id": "customer_12",
"phone": "44991234567"
},
"payment": {
"date": "2020-01-11T15:54:40+0000",
"id": "456789",
"method": "card",
"status": "decline",
"sum": {
"amount": 10000,
"currency": "USD"
},
"type": "purchase",
"description": ""
},
"project_id": 42,
"operation": {
"id": 18397000002376,
"type": "cancel",
"status": "decline",
"date": "2020-01-11T15:54:40+0000",
"created_date": "2020-01-11T15:54:35+0000",
"request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3",
"sum_initial": {
"amount": 10000,
"currency": "USD"
},
"sum_converted": {
"amount": 10000,
"currency": "USD"
},
"provider": {
"id": 120,
"payment_id": "248013808",
"date": "2020-01-10T22:37:10+0000",
"auth_code": "876856",
"endpoint_id": 120
},
"code": "10102",
"message": "Incorrect data entered"
},
"signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
}