Блокировка средств

Совет: Эта статья посвящена тому, как выполнять первую стадию оплат в две стадии (блокировку средств) через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт.

Помимо этой статьи для работы с разовыми оплатами в две стадии могут быть полезны:

  • статья Разовая оплата в две стадии модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в две стадии в платёжной платформе 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 Electron:
    1. если блокировка средств выполняется в рамках повторяемой оплаты или с её регистрацией — 4 дня;
    2. если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code (MCC) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 35 дней;
    3. в других случаях — 11 дней.
  • Для других карт платёжной системы Visa:
    1. если блокировка средств выполняется в рамках повторяемой оплаты или с её регистрацией — 7 дней;
    2. если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code (MCC) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 38 дней;
    3. в других случаях — 14 дней.
  • Для карт Maestro и Cirrus — 6 дней.
  • Для других карт платёжной системы Mastercard — 28 дней.
  • Для карт платёжной системы American Express:
    1. если в соответствии с присвоенным мерчанту кодом Merchant Category Code (MCC) его деятельность относится к гостиничному бизнесу, аренде автомобилей или организации круизов — на весь срок проживания, аренды или круиза соответственно;
    2. в других случаях — 7 дней.

Максимально допустимый срок блокировки средств отсчитывается от момента формирования в платёжной платформе ecommpay операции блокировки (auth). За полчаса до истечения этого срока в зависимости от параметров, указанных сотрудниками ecommpay, автоматически выполняется одна из следующих операций: списание заблокированных средств пользователя (capture) или отмена блокировки средств (cancel). После этого к веб-сервису направляется оповещение о списании средств. Для уточнения информации и изменения типа операции следует обратиться к курирующему менеджеру ecommpay. Исключением являются блокировки с использованием карт платёжной системы American Express, максимально допустимый срок для которых соответствует сроку проживания, аренды или круиза: для таких блокировок автоматическое списание не выполняется.

В случаях, когда в платёжной платформе настроено автоматическое списание или отмена блокировки средств в указанный со стороны мерчанта срок, но этот срок превышает максимально допустимый, списание или отмена выполняются в соответствии с максимально допустимым сроком. Допустим, в соответствии с пожеланиями мерчанта настроена автоматическая отмена блокировки по истечении десяти дней. Тогда для блокировки средств, выполненной с использованием карты Maestro (с максимально допустимым сроком в шесть дней), по истечении шести дней выполняется автоматическая отмена.

Схема работы

Для выполнения блокировки средств с помощью Payment Page со стороны веб-сервиса необходимо:

  1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page.
  2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы.

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

  • Аутентификация 3‑D Secure, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания (в то время, пока эмитент подтверждает подлинность без участия пользователя).
  • Аутентификация по инициативе мерчанта, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения.
  • Дополнение информации о платеже, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме.

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

Формат запросов

Формат запроса на открытие Payment Page для выполнения блокировки соответствует описанному в разделе Описание Payment Page API. При формировании такого запроса необходимо учитывать следующее:

  1. В запросе должны использоваться следующие обязательные параметры:
    • card_operation_type — тип операции для проведения оплаты с использованием платёжной карты; если по запросу мерчанта в рамках проекта по умолчанию настроена оплата, в параметре необходимо указывать значение auth;
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • customer_id — идентификатор пользователя, уникальный в рамках проекта;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_amount — сумма платежа в дробных единицах валюты;
    • payment_currency — код валюты платежа в формате ISO 4217 alpha-3;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
    Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. К параметрам, которые становятся обязательными для таких случаев, относятся customer_email и customer_phone (подробнее). Эти параметры можно включать в состав запроса на открытие Payment Page или запрашивать у пользователей (подробнее).
  2. Для предварительного выбора платёжной карты в запросе дополнительно необходимо использовать параметр account_token, в котором необходимо передать токен платёжной карты.
  3. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр language_code — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически (по языку браузера, языку региона или по умолчанию; подробнее).
  4. Для добавления описания платежа в запросе дополнительно необходимо использовать параметр payment_description, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа.
  5. Для проведения оплаты Mail Order (MO) в запросе дополнительно необходимо использовать параметр moto_type со значением 1, а для проведения оплаты Telephone Order (TO) — со значением 2.
  6. Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Purchase. Полный список параметров вызова Payment Page представлен в разделе Параметры вызова платёжной формы.

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

{
   "card_operation_type": "auth",
   "project_id": 42,
   "payment_id": "456789",
   "customer_id": "customer_12",
   "payment_currency": "USD",
   "payment_amount": "2000",
   "signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF...",

// при проведении оплаты по предварительно выбранной карте:
    "account_token":"959c664ad64b8caa54bb7836ddc737fd1a679242a039..."

}

Рис.: Пример запроса на открытие Payment Page

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&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhZLxEzkgcoZr...

Формат оповещений

Формат оповещения о результатах выполнения блокировок соответствует описанному в разделе Оповещения.

В следующем примере содержится информация о том, что в рамках проекта 42 для пользователя customer_12 заблокированы средства в размере 2 000,00 USD с использованием платёжной карты 541333******0019.

Рис.: Пример данных из оповещения о выполненной блокировке средств

{
    "project_id": 42,
    "customer": {
        "id": "customer_12"
    },
    "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"
    },
    "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"
    },
    "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"
    },
    "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..."
}