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

В рамках платежной платформы оплата в две стадии проводится, как описано в разделеСхема и статусы разовой оплаты в две стадии: с инициированием первой стадии такой оплаты по запросу со стороны веб-сервиса мерчанта и затем второй стадии — по запросу или автоматически по истечении заданного срока.

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

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

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

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

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

• Для карт 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 — 6 дней.

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

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

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

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

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

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

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

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

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

1. POST-запрос должен отправляться к одной из следующих конечных точек:
   • при передаче реквизитов карты в явном виде — /v2/payment/card/auth,
   • при передаче идентификатора вместо реквизитов карты— /v2/payment/card/auth/saved,
   • при передаче токена вместо реквизитов карты — /v2/payment/card/auth/token.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от Rocketpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи);
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя;
     • id — идентификатор пользователя в рамках проекта мерчанта;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма оплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют;
     • currency — валюта платежа в формате ISO-4217 alpha-3.
3. В запросе должны содержаться сведения о платежной карте пользователя:
   • при передаче реквизитов карты в явном виде — следующие данные в объекте card:
     • pan — номер карты,
     • year — год окончания срока действия карты,
     • month — месяц окончания срока действия карты,
     • card_holder — имя держателя карты (в соответствии с указанным на карте),
     • cvv — код проверки подлинности карты (в соответствии с указанным на карте);
   • при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платежной платформе, и код проверки подлинности карты в параметрах 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"
  },
  "payment": {
      "amount": 15000,
      "currency": "USD"
  },
  "return_url": {
        "success": "http://example.com/return",
        "decline": "http://example.com/decline"
  },
//при передаче реквизитов карты в явном виде:
  "card": {
      "pan": "4242424242424243",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

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

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

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

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

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

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

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

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

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

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

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

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