Введение

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

Что дальше:

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

URL для запросов - https://acq.bisys.kz

Так же необходимо, чтоб вы прислали свои IP, с которых будут идти запрос, чтобы мы добавили их в список разрешённых адресов.

Алгоритм

Создайте платёж, используя метод payment/do (Выполнить платеж).
В ответе вы получите данные для прохождения 3ds v1/3ds v2.
Пройдите процедуру аутентификации 3ds (подробнее в разделе ЧаВо).
Если вы использовали параметр для предавторизации средств (stage: PREAUTH), необходимо подтвердить платёж, используя метод /payment/confirm (Подтвердить выполнение платежа) или отменить платёж методом /payment/cancel (Отменить платёж).
Статус платежа можно проверить вызвав метод /payment/status
Если необходимо вернуть успешный платёж, используйте метод /payment/refund (Вернуть средства)

Методы

Описание методов (см. по ссылке)

ЧаВо

В данном разделе мы отвечаем на часто задаваемые вопросы, которые могут возникнуть при подключении.

В: Какие параметры необходимо передавать в browserInfo?

О: Желательно передать все параметры, которые начинаются на browser, но достаточно будет передать данные параметры:
{ "browserLanguage":"en", "browserColorDepth":"32", "browserScreenHeight":"1920", "browserScreenWidth":"1080", "browserTZ":"0", "browserUserAgent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)Gecko/20100101 Firefox/47.0" }

В: Какая механика прохождения 3DSv2.0?

О: Ниже приведены и описаны 2 случая прохождения 3DSv2.0

При отправке запроса на создание платежа /payment/do в ответе Вы получите resultCode со значением 3, данный код указывает на необходимость пройти аутентификацию 3DSv2.0

Также в ответе приходит группа параметров threeDSDataV2:

gatewaySessionId* - Идентификатор платежной сессии шлюза, приходит всегда

url - Адрес, на который нужно перенаправить клиента для проведения 3DS method и аутентификации 3DSv2, могут быть ситуации, когда параметр отсутствует в ответе на создание платежа, в таком случае необходимо следовать инструкции ниже

threeDSMethodData - Данные для выполнения 3DS method, приходит если карта подписана на 3dsMethod

threeDSMethodURLServer - Адрес для выполнения post-запроса в отдельном скрытом iframe без параметров при выполнении 3DS method, если значение передано (специфичен для РБС)

threeDSSessionData - Идентификатор сессии 3DSv2

creq - Тело запроса к ACS серверу эмитента 3DSv2

Разберем оба случая прохождения 3DS v2.0:

1. Банковская карта не подписана на 3ds method. Необходимое условие "resultCode": 3

Присутствуют параметры:

threeDSDataV2.gatewaySessionId

threeDSDataV2.url

threeDSDataV2.threeDSSessionData

threeDSDataV2.creq

В таком случае действуем по аналогии с 3DSv1.0:

Cоздается форма action = threeDSDataV2.url, c двумя параметрами threeDSSessionData, creq

Автоматический сабмит формы, пользователь проходит аутентификацию, после ввода кода пользователь вернется на URL, указанный в параметре merchantTermUrl при запросе /payment/do, с двумя параметрами threeDSSessionData и cres. После этого необходимо вызвать метод /payment/authenticate/v2 (Результат выполнения аутентификации 3DSv2.0)

В ответе Вы получите результат оплаты

2. Банковская карта подписана на 3ds method. Необходимое условие "resultCode": 3

Присутствуют параметры:

threeDSDataV2.gatewaySessionId

threeDSDataV2.url

threeDSDataV2.threeDSMethodData

threeDSDataV2.threeDSMethodURLServer

ВАЖНО! Могут прийти оба адреса - threeDSDataV2.url и threeDSDataV2.threeDSMethodURLServer, а может прийти только один из них, оба будут заполнены, либо какой то из них

Если присутствуют оба параметра, то необходимо 2 скрытых iframe post и сабмит при загрузке страницы.
Если присутствует только параметр threeDSDataV2.url, то необходимо выполнить 1 скрытый iframe post с передачей параметра threeDSMethodData
Если присутствует только параметр threeDSDataV2.threeDSMethodURLServer, то необходимо выполнить 1 скрытый iframe post без передачи параметра threeDSMethodData

Отсюда также следует, что:

Если отсутствует threeDSDataV2.threeDSMethodURLServer, то обязательно должен быть передан threeDSDataV2.url
Если присутствует threeDSDataV2.threeDSMethodURLServer, то threeDSDataV2.url может не присутствовать

Если в ответе есть значение у параметра threeDSDataV2.threeDSMethodURLServer, то необходимо выполнить запрос POST в скрытом iframe

Сабмит автоматически при загрузке страницы

Если в ответе есть значение у параметра threeDSDataV2.url, то необходимо выполнить запрос POST в скрытом iframe на данный адрес с параметром threeDSMethodData - url, закодированный в BASE64, внутри строки json, пример:

{"threeDSMethodNotificationURL":"https://ecomtest.akbars.ru:9999/cgi-bin/cgi_link","threeDSServerTransID":"41fae092-b99a-413d-8279-e0112cabf996"}

Сабмит автоматически при загрузке страницы.

Тут варианты:

Чтобы получить уведомление о прохождении клиентом 3DS method можно установить в параметре threeDSMethodNotificationURL - свой url, после получения ответа и возврата клиента на этот url, необходимо выполнить запрос POST на адрес первоначально указанный в threeDSMethodNotificationURL (в ответе от acs передается один параметр threeDSMethodData) Если клиент вернулся в течении 10 секунд выполняем запрос /payment/tdsmethod/complete - Результат выполнения 3ds method, указав "threeDSMethodState": "Y", если нет "threeDSMethodState": "N"
Или же не подменять threeDSMethodNotificationURL, после автосабмита форм выполнить /payment/tdsmethod/complete c передачей параметра threeDSMethodData, полученного при вызове метода payment/do. Результат выполнения 3dsMethod "threeDSMethodState": "N"

Если аутентификация прошла на основе 3DS method - в ответе Вы получите результат платежа, если банк отправит данные для прохождения аутентификации с участием клиента (challenge flow) будет передан "resultCode": 3

Присутствуют параметры:

threeDSDataV2.gatewaySessionId

threeDSDataV2.url

threeDSDataV2.threeDSSessionData

threeDSDataV2.creq

Действия при таком случае аналогичны пункту 1

Правило формировании подписи для Callback'a

Параметры для формирования подписи платежа


{
  return List.of(terminalId,
      regPayNum,
      orderId,
            payType,
      state,
      amountAction,
      amountAuthorization,
      currency,
      lastOperResult.getCode(),
      updated
  );
    }

Параметры для формирования подписи регистрации карты


{
  return List.of(terminalId,
      regPayNum,
      orderId,
      cardId,
      created);
    }

Пример расчета подписи для java


{
fun calcSign(param: List(Any?), key: String): Pair(Boolean, String?) {
        return try {

            val str = param.filterNotNull()
                .plus(key)
                .joinToString("|")

            val md = MessageDigest.getInstance("SHA-256")
            Pair(true, Base64.getEncoder().encodeToString(md.digest(str.toByteArray(Charsets.UTF_8))))
        } catch (ex: Exception) {
            Pair(false, ex.message)
        }
    }

Для формирования подписи callback соблюдаются следующие правила:

Дата используется в формате DD-MM-YYYY HH:MM:SS в UTC time.
Значения null игнорируются
Для разделения значений используется символ "|"
В конце строки добавляется параметр secKey
Результат в формате base64 преобразуется в праметр sign
Для хэширования используется алгоритм SHA-256