Оплата в две стадии

В рамках платёжной платформы оплаты в две стадии проводятся в соответствии с моделью проведения платежей (Разовая оплата в две стадии): с инициированием первой стадии такой оплаты по запросу со стороны веб-сервиса мерчанта, а второй стадии — по запросу или автоматически по истечении заданного срока. Информация о двухстадийных оплатах с прямым использованием платёжных карт содержится в данном разделе, а информация о таких оплатах с использованием альтернативных платёжных методов — в разделе Методы.

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

Для настройки автоматического инициирования второй стадии оплаты, то есть автоматического списания средств или отмены их блокировки, следует обращаться к специалистам технической поддержки (support@ecommpay.com). При этом срок блокировки и тип операции, которую необходимо выполнить по истечении этого срока, указываются со стороны мерчанта.

Информацию о возможности проведения таких оплат необходимо уточнять у службы технической поддержки support@ecommpay.com.

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

• Реквизиты (в явном виде). Это базовая форма, при использовании которой необходимо обеспечить предоставление реквизитов пользователем, а затем передать эти реквизиты в платёжную платформу в запросе на проведение платежа. Это касается и так называемых оплат Mail Order/Telephone Order (MO/TO), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе Проведение оплат MO/TO.
• Идентификатор реквизитов. В этом случае со стороны веб-сервиса передаётся идентификатор, однозначно ассоциированный с реквизитами платёжного инструмента на стороне платёжной платформы (подробнее — в разделе Сохранение платёжных данных).
• Токен реквизитов. В отличие от базового способа, вместо полных реквизитов передаётся токен. Для использования этого способа необходимо провести первоначальный платёж. Подробная информация об использовании токена представлена в разделе Использование токенов.

Ограничение максимальных сроков блокировки

При проведении оплат в две стадии необходимо учитывать, что в соответствии с требованиями международных платёжных систем Visa, Mastercard и American Express срок, на который можно заблокировать средства пользователя, ограничивается. И для различных типов карт этот срок определяется с учётом разных условий:

• Для карт платёжной системы Visa:
  1. если блокировка средств выполняется в рамках повторяемой оплаты — 5 дней;
  2. если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code (MCC) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 30 дней;
  3. в других случаях — 10 дней.
• Для карт Maestro и Cirrus — 6 дней.
• Для других карт платёжной системы Mastercard — 28 дней.
• Для карт платёжной системы American Express:
  1. если в соответствии с присвоенным мерчанту кодом Merchant Category Code (MCC) его деятельность относится к гостиничному бизнесу, аренде автомобилей или организации круизов — на весь срок проживания, аренды или круиза соответственно;
  2. в других случаях — 7 дней.

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

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

Ограничение возможности изменения суммы

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

• После уменьшения суммы заблокированных средств оставшаяся сумма должна составлять не менее 0,01 USD или эквивалента в другой валюте с учётом курса для этой валюты. Если оставшаяся сумма меньше требуемой, запрос на уменьшение суммы отклоняется с кодом ошибки 3117.
• Для оплат с использованием карт платёжной системы Visa изменение суммы более чем на 15 % поддерживается только при соответствии присвоенного мерчанту MCC одному из следующих: 3351–3500, 3501–3999, 4111, 4112, 4121, 4131, 4411, 4457, 5411, 5552, 5812, 5813, 7011, 7033, 7394, 7512, 7513, 7519, 7523, 7996, 7999. При любых других MCC мерчанта допускается изменение суммы в пределах 15 % от первоначально заблокированной.

Для оплат с использованием карт платёжной системы American Express эта возможность не поддерживается.

Для проведения оплаты в две стадии через Gate со стороны веб-сервиса необходимо:

1. Отправить запрос на предварительную блокировку к конечной точке /v2/payment/card/auth[/форма указания реквизитов платёжного инструмента].
2. При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже.
   • Аутентификация 3‑D Secure. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием платёжных карт через интернет. Подробная информация об этой процедуре представлена в разделе Аутентификация 3‑D Secure.
   • Аутентификация по инициативе мерчанта. Такая аутентификация предназначена для обеспечения дополнительной безопасности оплаты с использованием платёжных карт. Подробная информация об этой процедуре представлена в разделе Аутентификация по инициативе мерчанта.
   • Дополнение информации о платеже. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе Дополнение информации о платеже.
3. Принять от платёжной платформы оповещение о результате предварительной блокировки.
4. При необходимости изменить сумму предварительно заблокированных средств без одновременного подтверждения их списания — отправить запрос, содержащий требуемые параметры и подпись, к одной из следующих конечных точек:
   • /v2/payment/card/incremental — для увеличения суммы заблокированных средств;
   • /v2/payment/card/cancel — для уменьшения суммы предварительно заблокированных средств.

   После чего принять оповещение о результате изменения суммы средств.

5. Отправить запрос на списание средств, содержащий требуемые параметры и подпись, к конечной точке /v2/payment/card/capture или на отмену блокировки — к конечной точке /v2/payment/card/cancel.

   При необходимости списать сумму, отличную от суммы заблокированных средств, в запросе к конечной точке /v2/payment/card/capture необходимо указать сумму для списания и код валюты.

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

Схема проведения оплаты в две стадии в базовом случае — без выполнения дополнительных процедур — со списанием заблокированных средств представлена далее.

Информация о формате запросов и параметрах инициирования операций оплаты в две стадии с прямым использованием платёжных карт через Gate, а также о формате оповещений о результатах операций приведена далее; общая информация о работе с API — в разделе Организация взаимодействия. Информацию о возможных статусах такой оплаты можно найти в соответствующей статье.

Запрос на предварительную блокировку

При формировании запросов необходимо учитывать следующее:

1. POST-запрос должен отправляться к одной из следующих конечных точек:
   • при передаче реквизитов карты в явном виде — /v2/payment/card/auth,
   • при передаче идентификатора вместо реквизитов карты— /v2/payment/card/auth/saved,
   • при передаче токена вместо реквизитов карты — /v2/payment/card/auth/token.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью);
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя;
     • id — идентификатор пользователя в рамках проекта мерчанта;
     • screen_res — разрешение экрана устройства пользователя, в пикселях и с символом x в качестве разделителя (например, 360x640);
     • email — адрес электронной почты пользователя;
     • phone — номер телефона пользователя;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;
     • currency — валюта платежа в формате ISO-4217 alpha-3.
3. В запросе должны содержаться сведения о платёжной карте пользователя:
   • при передаче реквизитов карты в явном виде — следующие данные в объекте card:
     • pan — номер карты,
     • year — год окончания срока действия карты,
     • month — месяц окончания срока действия карты,
     • card_holder — имя держателя карты (в соответствии с указанным на карте),
     • cvv — код проверки подлинности карты (в соответствии с указанным на карте); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе Проведение оплат MO/TO;
   • при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платёжной платформе, и код проверки подлинности карты в параметрах saved_account_id и cvv;
   • при передаче токена — токен и код проверки подлинности карты в параметрах token и cvv.
4. В запросе должен содержаться объект return_url с адресами для перенаправления пользователя к веб-сервису:
   • success — URL для перенаправления после завершения платежа;
   • decline — URL для перенаправления после отклонения платежа.
5. Если необходимо зачислить средства на электронный кошелёк мерчанта, в объекте customer дополнительно должны использоваться следующие параметры:
   • first_name — имя пользователя,
   • last_name — фамилия,
   • address — адрес проживания (улица, номер дома),
   • email — адрес электронной почты,
   • city — город проживания (или иной населенный пункт),
   • state — регион проживания (штат, графство, кантон и т.д.).
6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12",
      "screen_res": "360x640",
      "phone": "44991234567",
      "email": "john_smith@email.com"
  },
    "payment": {
      "amount": 15000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },

//при передаче реквизитов карты в явном виде:
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//при передаче идентификатора ранее сохранённой платёжной карты:
    "saved_account_id": 2345678,
    "cvv": "123"

//при передаче токена ранее сохранённой платёжной карты:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}

Запрос на увеличение суммы заблокированных средств

Запрос отправляется методом POST к конечной точке /v2/payment/card/incremental и должен содержать следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
• customer — объект, содержащий сведения о пользователе:
  • id — идентификатор пользователя в рамках проекта мерчанта;
• payment — объект, содержащий сведения о платеже:
  • amount — сумма, на которую необходимо увеличить сумму заблокированных средств, в дробных единицах валюты;
  • currency — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку.
• Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "customer": {
      "id": "customer_12"
  },
    "payment": {
      "amount": 1000,
      "currency": "USD"
  }
  }

Запрос на списание заблокированных средств

Запрос отправляется методом POST к конечной точке /v2/payment/card/capture и должен содержать следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
• Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Перечисленных параметров достаточно для списания всей суммы заблокированных средств. Чтобы списать часть суммы или сумму больше заблокированной, в объекте payment дополнительно необходимо использовать следующие параметры:

• amount — итоговая сумма списания в дробных единицах валюты;
• currency — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку.

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

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}

Запрос на уменьшение суммы или отмену блокировки средств

Запрос отправляется методом POST к конечной точке /v2/payment/card/cancel и должен содержать следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью).
• Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Перечисленных параметров достаточно для отмены блокировки всей суммы средств. Чтобы уменьшить сумму заблокированных средств, в объекте payment дополнительно необходимо использовать следующие параметры:

• amount — сумма, на которую необходимо уменьшить сумму заблокированных средств, в дробных единицах валюты;
• currency — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку.

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

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}