После оплаты

После совершения платежа вы можете управлять им в личном кабинете портала продавца или через API. Прочтите разделы ниже, чтобы узнать больше.

Отмена и возврат платежа

Если вы хотите отменить платеж, вы можете выполнить одну из двух операций, в зависимости от статуса заказа: отмена или возврат. Эти операции описаны ниже.

Отмена

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

Доступны следующие способы отмены:

• Отмена платежа на портале продавца. Осуществляется нажатием кнопки Возврат на странице деталей операции. Эта кнопка работает как для отмены платежа, так и для возврата средств – в зависимости от статуса транзакции. Если это возможно, происходит отмена платежа, а если нет, то осуществляется возврат средств. Подробнее читайте здесь.

• Отмена платежа через API путем отправки запроса reverse.do.

• Отмена всех двухстадийных платежей автоматически по истечении определенного времени. Если вам нужен этот функционал, обратитесь в службу поддержки банка.

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

Возврат средств

Возврат означает возврат клиенту уже списанных средств. Эта операция может применяться к одностадийным и двухстадийным транзакциям, когда средства уже списаны (статус Завершён). Система позволяет возвращать средства более одного раза, но в общей сложности не более первоначальной суммы завершения.

Возможны следующие способы оформления возврата:

• Возврат средств в личном кабинете путем нажатия кнопки Возврат в деталях транзакции. Эта кнопка работает как для отмены платежа, так и для возврата средств – в зависимости от статуса транзакции. Если это возможно, происходит отмена платежа, а если нет, то осуществляется возврат средств. Подробнее читайте здесь.
• Возврат средств через API путем отправки запроса refund.do.

Как отмена, так и возврат средств могут быть назначены триггерами callback-уведомлений. Подробнее читайте здесь.

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

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

Выяснение статуса заказа на портале продавца

Статус заказа можно посмотреть на странице Сведения о транзакции соответствующей транзакции. Статус Deposited означает успешный платеж.

Выяснение статуса заказа через API

Для получения статуса заказа Интернет-магазин отправляет в платежный шлюз запрос getOrderStatusExtended.do. Запрос содержит либо orderId (уникальный номер заказа в платежном шлюзе), либо orderNumber (уникальный номер заказа в системе интернет-магазина). Если в запросе передаются оба параметра, приоритет orderId выше.

Платежный шлюз возвращает статус заказа в параметре orderStatus. Статус 2 означает успешный платеж.

Дополнительные возможности

Двухстадийные платежи

Виды платежей

В зависимости от специфики бизнеса компания может использовать два вида платежей:

• Одностадийные - операции по оплате товаров/услуг, совершаемые через Интернет с использованием банковских карт, не требующие дополнительного подтверждения, т.е. холдирование и списание денежных средств происходит в один этап. Этот вид оплаты предпочтителен, если товар или услуга предоставляется сразу после оплаты.
• Двухстадийные - операции по оплате товаров/услуг, совершаемые через Интернет с использованием банковских карт, требующие дополнительного подтверждения, т.е. оплата производится в два этапа. На первом этапе происходит проверка наличия и холдирование (резевирование) средств плательщика (предавторизация); затем на втором этапе компания либо подтверждает списание средств, либо отменяет холдирование средств.

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

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

Чтобы платеж был двухстадийным, заказ должен быть зарегистрирован с помощью запроса registerPreAuth.do, а не register.do.

Двухстадийная оплата возможна при любом способе интеграции:

• Оплата по ссылке
• Интеграция через редирект
• Платежи напрямую
• CMS
• SDK

Для вариантов прямой интеграции, интеграции через редирект, CMS, SDK возможна регистрация и оформление заказа через API.

Завершения

Завершение происходит на втором этапе двухэтапного платежа, когда предварительно зарезервированные средства списываются со счета держателя карты. Как только происходит списание, заказ становится завершенным и переходит в статус DEPOSITED. Сумма завершения может быть больше или меньше суммы предварительной авторизации. Также доступно поэтапное частичное завершение. Если вы не передадите сумму, то будет списана вся сумма.

Есть три способа сделать завершение:

• Завершение платежа на портале продавца
• Завершение платежа через API
• Автоматическое завершение всех двухстадийных платежей через некоторое время

Также есть возможность сделать частичное завершение. В этом случае заказ будет завершен на меньшую сумму (чем сумма авторизации).

Завершение и отмена заказов автоматически

Если наша служба поддержки включила для вас эту функцию, вы можете настроить свою интеграцию так, чтобы все предварительно авторизованные (в статусе Подтвержден) двухстадийные заказы завершались или отменялись автоматически по истечении определенного периода времени. В этом случае вам не нужно обрабатывать каждый заказ вручную в личном кабинете. Также нет необходимости вызывать API-методы deposit.do и/или reverse.do).

Чтобы включить автозавершение заказа в личном кабинете:

1. Выполните вход в личный кабинет
2. В панели управления слева перейдите в раздел Настройки. .
3. Перейдите на вкладку Общие.
4. В разделе Автозавершение, отметьте Автозавершение включено.
5. В поле Время завершения (в часах) введите количество часов после регистрации, через которое двухстадийный заказ должен быть завершен автоматически.

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

Вы также можете задать дату и время автозавершения и автоомены по API с помощью параметров autocompletionDate и autoReverseDate в API-запросе registerPreAuth.do. Используемый часовой пояс: UTC+3.

Ниже приводится описание логики работы автозавершения и автоотмены.

Когда заказ зарегистрирован и для него установлено автозавершение:

• Если статус заказа остается Создан на момент наступления времени автозавершения, с заказом ничего не произойдет: в конечном итоге срок его действия истечет, и он будет закрыт. Если заказ будет завершен по истечении заданного периода, автозавершение не сработает.
• Если заказ предварительно авторизован и не завершен до истечения заранее определенного периода завершения, заказ будет полностью выполнен, т.е. предварительно авторизованная сумма будет автоматически зачислена в полном объеме.
• Если заказ предварительно авторизован и завершен до истечения заданного периода завершения, статус заказа изменится в соответствии с его обычным жизненным циклом.
• Если до истечения заданного периода завершения к заказу применяется возврат/отмена, автозавершение не сработает.

Когда заказ зарегистрирован и для него установлена автоотмена:

• Если статус заказа остается Создан на момент наступления времени автоотмены, с заказом ничего не произойдет: в конечном итоге срок его действия истечет, и он будет закрыт. Если заказ будет завершен по истечении заданного периода, автоотмена не сработает.
• Если заказ предварительно авторизован и не завершен до истечения заранее определенного периода отмены, заказ будет полностью отменен, т.е. предварительно авторизованная сумма будет автоматически аннулирована в полном объеме.
• Если заказ предварительно авторизован и завершен до истечения заданного периода отмены, статус заказа изменится в соответствии с его обычным жизненным циклом.
• Если до истечения заданного периода отмены к заказу применяется возврат/отмена, автоотмена не сработает.

Операции по связкам

Транзакция по связке используется, когда держатель карты разрешает продавцу хранить платежные данные для дальнейших платежей. Например, плательщик может выбрать сохранение своей карты при оформлении заказа. В этом случае создается связка (CoF, credential on file), уникальный защищенный токен, генерируемый платежным шлюзом, который связывает номер карты плательщика (PAN) с его идентификатором в системе магазина (например, с логином плательщика).

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

Создание связки

Вы можете создать связку через API или через личный кабинет (независимо от типа интеграции). Подробнее см. ниже.

Создание связки через API

Чтобы сохранить карту (создать связку) в платежном шлюзе через API, вам необходимо передать параметр clientId в запросе регистрации заказа или инициации платежа. clientId - это идентификатор вашего клиента (владельца карты), к этому номеру будут привязаны все карты клиента. В целях тестирования вы можете использовать любой номер в качестве clientId. Этот параметр можно передавать в следующих запросах:

• register.do

• registerPreauth.do

• motoPayment.do

• /applepay/payment.do

• /applepay/paymentDirect.do

• /google/payment.do

• /google/paymentDirect.do

Связка будут создана только после успешной оплаты. После оплаты вы сможете получить идентификатор связки через запрос getOrderStatusExtended.do в параметре bindingId.

Создание связки через личный кабинет

Для создания связки при оплате через пользовательский интерфейс перейдите в личный кабинет, выставьте счет на электронную почту с указанием параметра Идентификатор клиента. Если указать этот параметр, клиент увидит флажок Сохранить мою карту на странице оплаты. Если клиент установит этот флажок, после завершения платежа будет создана связка, и клиенту не нужно будет вводить данные карты в следующий раз. Подробнее читайте здесь.

Создание связки без оплаты

При наличии соответствующих прав пользователя, вы можете создать связку через API без проведения платежа.

Для этого передайте значение VERIFY в блоке features любого платежного запроса вместе с параметром clientId. В этом случае с держателя карты не будет взиматься никакая сумма. Ответ будет содержать идентификатор созданной связки в параметре bindingId. Этот идентификатор связки можно использовать в последующих запросах вместо сохраненных реквизитов карты.

Узнайте больше о функции VERIFY здесь.

Принудительное создание связки

Если вы передадите значение FORCE_CREATE_BINDING в блоке features платежного запроса, связка будет создана принудительно, даже если клиент решил не сохранять данные карты на платежной странице.

Значение FORCE_CREATE_BINDING нельзя передать в запросе с существующим bindingId или же при bindingNotNeeded = true (вызовет ошибку проверки). Для передачи этого значения также требуется передать параметр clientId.

Если в блоке features переданы оба значения FORCE_CREATE_BINDING и VERIFY, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).

Проведение оплаты по связке

Работа со связками через API

После создания связки вы можете работать с ней через API (при наличии разрешения на уровне продавца). Доступны следующие методы:

• paymentOrderBinding.do – проведение оплаты по связке
• getBindings.do – получить список связок клиента
• getBindingsByCardOrId.do – получить список всех связок банковской карты
• unBindCard.do – деакетивировать существующую связку
• bindCard.do – повторно активировать ранее деактивированную связку
• extendBinding.do — продлить срок действия связки.

Использование связок в рекуррентных платежах

Вы можете использовать связки для рекуррентных платежей. В этом случае параметр bindingId используется в обычном запросе на регистрацию заказа. Подробнее читайте здесь.

Использование связок при оплате кошельками

Вы также можете создавать связки при оплатах через кошельки Apple Pay и Google Pay. Для этого необходимо передать параметр clientId в платежном запросе или в запросе на оформление заказа (см. описание API-запросов для кошельков).

В этом случае связка соединит номер токенизированной карты плательщика (DPAN) с его ID в системе магазина (например, с логином плательщика). Такую связку нельзя использовать для отображения номера карты на платежной странице (поскольку номер карты токенизирован). Однако эту связку можно использовать в рекуррентных платежах.

Верификация держателя карты

Держателя карты можно верифицировать без взимания какой-либо оплаты. Для этого передайте значение VERIFY в блоке features любого платежного запроса.

Когда используется функция VERIFY, платежная карта будет проверена, чтобы убедиться, что она используется ее законным владельцем. Если для карты доступен 3-D Secure, то будет выполнена верификация 3-D Secure. При этом параметр amount верифицирующего запроса может быть равен только 0. Даже если некоторая сумма платежа будет передана в запросе, она не будет списана со счета клиента. После успешной регистрации заказ сразу переводится в статус REVERSED (отменен).

Если функция VERIFY передается вместе с параметром clientId, ее можно использовать для создания связки без оплаты. Подробнее читайте в разделе Связки.

Токен Open ID

Вы можете сгенерировать токен Open ID. Этот токен можно использовать вместо учетных данных для идентификации продавца в платежном шлюзе.

Токен Open ID не является приватным, его можно опубликовать или встроить в веб-страницу. Например, его можно использовать, когда заказ оформляется прямо из браузера. В этом случае отсутствует риск раскрытия персональных данных, поскольку расшифровать токен может только платежный шлюз.

Вы можете использовать токен Open ID для аутентификации продавца при отправке запросов API к платежному шлюзу. Для этого передайте токен Open ID в параметре token вместо передачи userName и password. Вы можете использовать параметр token в следующих запросах:

• register.do
• registerPreAuth.do

• getOrderStatusExtended.do

• motoPayment.do

Чтобы сгенерировать токен Open ID, перейдите в личный кабинет, выберите Настройки в боковом меню, а затем выберите Общие настройки в блоке Продавец. Нажмите Создать рядом с полем Токен Open Id. Если вы уже знаете свой токен, вы можете ввести его вручную. Подробнее читайте здесь.

Редирект на ACS

Если требуется 3-D Secure, то после получения ответа на запрос оплаты, клиент должен быть перенаправлен на ACS. Существует два способа перенаправления: обычный и упрощенный.

Обычный редирект

Если оплата производится с помощью 3-D Secure, мерчанты должны перенаправлять своих клиентов в ACS по адресу, указанному в параметре acsUrl, полученном в ответе на запрос оплаты. Тело запроса должно включать MD=mdorder&PaReq=paReq&TermUrl=termUrl, где:

• MD - уникальный идентификатор заказа в платежном шлюзе;
• PaReq - параметр paReq, полученный в ответе на запрос оплаты. Это сообщение, которое должно быть отправлено в ACS вместе с редиректом и содержит данные, необходимые для аутентификации;
• TermUrl - параметр termUrl, полученный в ответе на запрос оплаты. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации.

Это должен быть запрос POST (не GET).

В зависимости от конфигурации, согласованной с банком, покупатель после аутентификации в ACS будет перенаправлен либо в магазин, либо на платежный шлюз.

Пример POST-запроса для обычного перенаправления:

<html>
<head><title>ACS Redirect</title></head>
<body onload="document.forms['acs'].submit()">
ACS Redirect
<form id="acs" method="post" action="[result.acsUrl]">
    <input type="hidden" id="MD" name="MD" value="[MD]"/>
    <input type="hidden" id="PaReq" name="PaReq" value="[result.PaReq]"/>
    <input type="hidden" id="TermUrl" name="TermUrl" value="[result.TermUrl]"/>
</form>
</body>
</html>

Обычный редирект (расширенная схема 3DS2)

Если оплата производится с помощью 3-D Secure, мерчанты должны перенаправлять своих клиентов в ACS по адресу, указанному в параметре acsUrl, полученном в ответе на запрос оплаты. Тело запроса должно включать creq=[packedCReq], где [packedCReq] - значение параметра packedCReq, полученного в ответ на запрос продолжения оплаты.

Это должен быть запрос POST (не GET).

В зависимости от конфигурации, согласованной с банком, покупатель после аутентификации в ACS будет перенаправлен либо в магазин, либо на платежный шлюз.

Пример POST-запроса для обычного перенаправления:

<html>
<head><title>ACS Redirect</title></head>
<body onload="document.forms['acs'].submit()">
ACS Redirect
<form id="acs" method="post" action="[acsUrl]">
    <input type="hidden" id="creq" name="creq" value="[packedCReq]"/></form>
</body>
</html>

Упрощенный редирект

Также Интернет-магазин может использовать метод шлюза acsRedirect, который выполнит такое же перенаправление держателя карты на ACS эмитента.

Оплата с помощью собственного MPI

Merchant Plugin Interface (MPI)/3DS Server — это компонент технологии 3D Secure, который может быть реализован в платежном шлюзе или на вашей стороне. Если у вас есть собственный MPI, вы можете использовать его для авторизации 3D Secure в API-запросах. Чтобы включить эту функциональность, обратитесь в службу технической поддержки.

Если вы используете собственный MPI, платежный шлюз ожидает, что каждый из платежных запросов – paymentOrder, paymentOrderBinding.do – будет включать дополнительные параметры в блокеjsonParams: eci, cavv, xid, threeDSProtocolVersion, и authenticationTypeIndicator. Эти параметры описаны ниже.

eci

eci — индикатор электронной коммерции (ECI), полученный от вашего сервера 3-D Secure. Ниже приводится расшифровка ECI-кодов.

• ECI=1 или ECI=6 - мерчант поддерживает 3-D Secure, платежная карта не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.
• ECI=2 или ECI=5 - и мерчант, и платежная карта поддерживают 3-D Secure;
• ECI=7 - мерчант не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.

cavv, xid

Если значение ECI отличается от тех, которые используются для SSL-авторизации, также необходимо передать следующие параметры:

• cavv - значение аутентификации держателя карты;
• xid - индикатор электронной коммерции транзакции (значение ARes.dsTransID, полученное от ACS).

threeDSProtocolVersion

Кроме того, вы можете передать в платежном запросе параметр threeDSProtocolVersion (версия протокола 3DS). Он может принимать следующие значения:

• 2.1.0 - для 3DS 2
• 2.2.0 - для 3DS 2

Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2).

authenticationTypeIndicator

Параметр authenticationTypeIndicator (тип аутентификации платежа) необходим для оплаты через ваш MPI с 3DS 2.

Для платежей с SSL этот параметр является необязательным и определяется автоматически в зависимости от значения ECI.

Пример запроса

curl --request POST \\
  --url https://3dsec.berekebank.kz/payment/rest/paymentorder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data userName=test_user \\
  --data password=test_user_password \\
  --data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
  --data '$PAN=4000001111111118' \\
  --data '$CVC=123' \\
  --data YYYY=2030 \\
  --data MM=12 \\
  --data 'TEXT=TEST CARDHOLDER' \\
  --data language=en \\
  --data 'jsonParams={
  "eci": "02",
  "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=",
  "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110",
  "threeDSProtocolVersion": "2.2.0",
  "authenticationTypeIndicator": "5"
}'

Если вы используете собственный MPI, ответ на соответствующий API-запрос оплаты не содержит параметров, связанных с 3D Secure, таких как redirect, termUrl, acsUrl и paReq.

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

{
  "redirect": "https://3dsec.berekebank.kz/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

3-D Secure авторизация

Что такое 3-D Secure

3-D Secure (также называемый 3DS) - технический стандарт, созданный Visa и MasterCard, который позволяет выполнять дополнительную авторизацию владельца карты на стороне банка-эмитента. Для завершения транзакции владельцу карты предлагается подтвердить свою личность путем ввода уникального пароля, СМС кода или временного PIN-кода.

Термин 3DS означает 3 Domain Server. Такое название объясняется тем, что в каждой 3-D Secure транзакции принимают участие три стороны:

1. Домен эквайера. Выступает в роли 3DS requestor – инициатора процесса авторизации.
2. Домен эмитента. Включает в себя ACS (Access Control Server), который обеспечивает подтверждение личности плательщика банком-эмитентом.
3. Домен взаимодействия. Выступает в роли связующего звена между двумя первыми доменами. Как правило, это платежная система.

Версии протокола

Платежный шлюз поддерживает 3-D Secure авторизацию, чтобы защитить вас и ваших клиентов от угрозы платежного мошенничества.

Для транзакций в браузере мы используем 3-D Secure v2 (также называемый 3DS2) - обновленную версию протокола 3-D Secure, которая обеспечивает лучшее взаимодействие между тремя участниками транзакции. Протокол проверки подлинности 3DSv2 в зависимости от настроек ACS банка-эмитента позволяет выполнить проверку подлинности без участия клиента (схема Frictionless). В этом случае от клиента не потребуется совершать действия для аутентификации, такие как ввод одноразового пароля или другие действия.

Сценарии интеграции

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

Если платёжная страница расположена на стороне мерчанта, при использовании аутентификации клиента по протоколу 3DSv2 для каждой транзакции мерчанту необходимо отправить ряд дополнительных API запросов в платежный шлюз.

Схемы интеграции описаны здесь.

3RI авторизация

3RI – это тип авторизации 3DS 2, который инициируется продавцом без запроса подтверждения платежа от владельца карты. Фактически, 3RI оплата - это MIT оплата с tii=R или tii=I, т.е. рекуррентная оплата или оплата в рассрочку (см. Связки и типы транзакций) с 3DS 2 frictionless авторизацией.

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

Если выполняется какое-либо из условий:

• инициирующая транзакция выполнялась не через платежный шлюз,
• инициирующая транзакция выполнялась с вашим собственным MPI,
• инициирующая транзакция выполнялась без сохранения связки,

то необходимо в блоке jsonParams отправить следующие дополнительные параметры: