.. meta:: :description: Конечная точка API SBC /api/v2/account-verification-form: проверка учётной записи держателя карты через размещённую форму перед последующими транзакциями с обработкой перенаправления. .. _api_v2_account-verification-form: /api/v2/account-verification-form ################################################################## .. role:: ex .. role:: code Введение ==================================== Верификация аккаунта с непрямой передачей карточных данных инициируется через :code:`HTTPS POST` запрос, используя :ref:`URL` и :ref:`параметры`, указанные ниже. Используйте :ref:`SHA-1` шифрование для аутентификации. См. :ref:`Статусы`. .. _api_url_account_verification_form: API URL ================================ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.sbctech.ru/paynet/api/v2/account-verification-form/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/account-verification-form/ENDPOINTID` * - :ex:`https://sandbox.sbctech.ru/paynet/api/v2/account-verification-form/group/ENDPOINTGROUPID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/account-verification-form/group/ENDPOINTGROUPID` .. _api_v2_account-verification-form_request_parameters: Параметры запроса ========================================== .. note:: | Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded. | Пробелы в начале и в конце значений параметров будут отсечены. | Банк может переопределить необходимость некоторых полей, сделав их обязательными. .. list-table:: :widths: 25, 45, 25 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`client_orderid` - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`order_desc` - Описание заказа. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 64k * - :code:`address1` - Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.) - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 256 * - :code:`city` - Город Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`zip_code` - Почтовый индекс Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 10 * - :code:`country` - Страна Плательщика. Для списка действительных кодов см. :ref:`Коды стран`. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2 * - :code:`email` - Адрес электронной почты Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`ipaddress` - IP-адрес Плательщика, передаётся для целей мониторинга мошенничества. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 45 * - :code:`control` - | Контрольная сумма, сгенерированная :ref:`SHA-1`. Строка для подписи представляет собой объединение следующих параметров: | 1. :ex:`` (См.: :ref:`Request URL`) | 2. Параметр запроса: :ex:`client_orderid` | 3. Параметр запроса: :ex:`email` | 4. :ex:`merchant_control` (Контрольный ключ, назначенный для аккаунта Присоединяющейся стороны в системе SBC). - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`first_name` - Имя плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 50 * - :code:`last_name` - Фамилия Плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 50 * - :code:`ssn` - Последние четыре цифры номера социального страхования Плательщика. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 32 * - :code:`birthday` - Дата рождения Плательщика в формате :ex:`YYYYMMDD`. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 8 * - :code:`state` - Штат Плательщика. Для списка действительных кодов штатов см. :ref:`Обязательные коды штатов`. Требуется для США, Канады и Австралии. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 2-3 * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`cell_phone` - Полный международный мобильный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`currency` - Валюта, в которой списывается транзакция (трёхбуквенный код валюты). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для евро. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 3 * - :code:`site_url` - URL-адрес сайта электронной коммерции, откуда происходит платеж. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`redirect_url` - | URL, на который плательщик перенаправляется после завершения транзакции. Обратите внимание: перенаправление выполняется в любом случае, независимо от того, имеет ли транзакция окончательный :ex:`одобренный`, :ex:`отклонённый` или любой другой :ref:`статус`. | Присоединяющаяся Сторона не должна использовать параметры, которые посылаются вместе с HTTP-запросом перенаправления на обработку статуса транзакции. Вместо этого Присоединяющаяся Сторона может использовать :ex:`server_callback_url` или :ref:`АПИ команду запроса статуса`. Если же нет необходимости перенаправлять Плательщика, вписать :ex:`https://doc.sbctech.ru`. Использовать или параметр :ex:`redirect_url`, или комбинацию параметров :ex:`redirect_success_url` и :ex:`redirect_fail_url`, не оба. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_success_url` - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`успешного` статуса транзакции (см. :ref:`Статусы транзакций`). | Присоединяющаяся Сторона не должна использовать параметры, которые посылаются вместе с HTTP-запросом перенаправления на обработку статуса транзакции. Вместо этого Присоединяющаяся Сторона может использовать :ex:`server_callback_url` или :ref:`АПИ команду запроса статуса`. Если же нет необходимости перенаправлять Плательщика, вписать :ex:`https://doc.sbctech.ru`. Использовать или параметр :ex:`redirect_url`, или комбинацию параметров :ex:`redirect_success_url` и :ex:`redirect_fail_url`, не оба. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_fail_url` - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`неуспешного` статуса транзакции (см. :ref:`Статусы транзакций`). | Присоединяющаяся Сторона не должна использовать параметры, которые посылаются вместе с HTTP-запросом перенаправления на обработку статуса транзакции. Вместо этого Присоединяющаяся Сторона может использовать :ex:`server_callback_url` или :ref:`АПИ команду запроса статуса`. Если же нет необходимости перенаправлять Плательщика, вписать :ex:`https://doc.sbctech.ru`. Использовать или параметр :ex:`redirect_url`, или комбинацию параметров :ex:`redirect_success_url` и :ex:`redirect_fail_url`, не оба. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`server_callback_url` - | URL-адрес :ex:`server_callback_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`notify_url`. При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`notify_url` - | URL-адрес :ex:`notify_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`server_callback_url`. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`preferred_language` - Двухбуквенный :ref:`код языка` плательщика для многоязычных платёжных форм. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`merchant_form_data` - Ключи и значения, отправленные в параметре MERCHANT_FORM_DATA, делятся на макросы с тем же именем. Параметр должен использовать URL кодировку (urlencode), например: :ex:`testparam%3Dtest1%26mynewparam%3Dtest2` делится на макросы :ex:`$MFD_testparam = test1` и :ex:`$MFD_mynewparam = test2` в форме. Символы ключей параметра [a-zA-Z0-9], символы значений параметра [a-zA-Z0-9], управляющие символы [=&], максимальный размер 2 МБ. Например, этот параметр можно использовать для отображения формы платежа в светлом/темном режиме в зависимости от переданного значения (для переданного параметра :code:`merchant_form_data=theme%3Ddark`, вместо макроса :ex:`$MFD_theme` в форме оплаты будет значение :ex:`dark`. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 Параметры ответа =========================================== .. note:: | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра. .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Параметры ответа - Описание * - :code:`type` - | Тип ответа. Может принимать такие значения как - :ex:`async-response`, :ex:`validation-error`, :ex:`error` и т.д. | Если тип равен :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` будут содержать сведения об ошибке. * - :code:`payet-order-id` - Идентификатор заказа, присвоенный SBC. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны. * - :code:`error-message` - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`error`. * - :code:`redirect-url` - URL, на который Присоединяющаяся Сторона должна перенаправить браузер Плательщика. Присоединяющаяся Сторона отправляет :ex:`HTTP 302` см. :ref:`Верификация аккаунта с непрямой передачей карточных данных`. Пример запроса ======================================= .. code-block:: http POST /paynet/api/v2/account-verification-form/39915 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 565 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=34T43R77N &order_desc=Test Order Описание &first_name=John &last_name=Smith &ssn=1267 &birthday=19820115 &address1=100 Main st &city=Seattle &state=WA &zip_code=98102 &country=US &phone=+12063582043 &cell_phone=+19023384543 &email=john.smith@gmail.com &ipaddress=65.153.12.232 &site_url=www.google.com ¤cy=USD &purpose=user_account1 &redirect_url=http://connectingparty.com/result &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2 &control=5112b51084be33fa331d995d17b9d82af3bfbbc9 Пример успешного ответа ================================================ .. code-block:: http HTTP/1.1 200 Server: server Date: Wed, 10 May 2023 09:07:27 GMT Content-Type: text/html;charset=utf-8 Connection: close Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 285 type=async-form-response &serial-number=00000000-0000-0000-0000-000002e378e8 &merchant-order-id=34T43R77N &paynet-order-id=6998044 &redirect-url=https%3A%2F%2Fsandbox.sbctech.ru%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5538374E4535734B44743364784335716A7979316B673D Пример неуспешного ответа ============================================= .. code-block:: http HTTP/1.1 200 Server: server Date: Mon, 22 May 2023 11:36:59 GMT Content-Type: text/html;charset=utf-8 Connection: close Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 152 type=validation-error &serial-number=00000000-0000-0000-0000-000002e5c587 &merchant-order-id=34T43R77N &error-message=INVALID_CONTROL_CODE &error-code=2 .. only:: openapi_doc_enabled Open API Collection ^^^^^^^^^^^^^^^^^^^ Open this method in the OpenAPI Reference .. raw:: html View in OpenAPI Коллекция Postman ========================================== .. raw:: html :file: ../_static/Postman/Postman_account_verification_form.html Конструктор запросов ====================================== .. raw:: html :file: ../_static/examples/account_verification_form_Request_Debug.html