.. meta:: :description: /api/v2/account-verification API endpoint SBC: проверяет счёт держателя карты напрямую через API с проверкой 3DS перед сохранением recurring ID. .. _api_v2_account-verification: /api/v2/account-verification ######################################################## .. role:: ex .. role:: code Введение ======================== Верификация аккаунта инициируется через :code:`HTTPS POST` запрос, используя :ref:`URL` и :ref:`параметры`, указанные ниже. Используйте :ref:`SHA-1` шифрование для аутентификации. См. :ref:`Статусы транзакций`. .. _api_url_account_verification_url: 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/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/account-verification/ENDPOINTID` * - :ex:`https://sandbox.sbctech.ru/paynet/api/v2/account-verification/group/ENDPOINTGROUPID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/account-verification/group/ENDPOINTGROUPID` .. _api_url_account_verification_request_parameters: Параметры запроса ============================== .. note:: | Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded. | Банк может переопределить необходимость некоторых полей, сделав их обязательными. | Пробелы в начале и в конце значений параметров будут отсечены. .. warning:: В значениях параметров необходимо экранировать следующие символы: :code:`&` :code:`+` :code:`"`. .. 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:`cvv2` - CVV2-код Плательщика. CVV2 (Card Verification Значение) — это трех- или четырех-значное число ПОСЛЕ номера кредитной карты в области подписи карты. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 3-4 * - :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:`cardrefid` - ИД ссылки на карту, полученный на шаге :ref:`Регистрации Карты`. - | ``Необходимость``: Опционально | ``Тип``: 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:`credit_card_number` - Номер банковской карты Плательщика. Нужно отправлять или комбинацию из :code:`credit_card_number`, :code:`card_printed_name`, :code:`expire_month` и :code:`expire_year`, или параметр :code:`card_recurring_payment_id`, но не все в одном запросе. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 20 * - :code:`card_printed_name` - Имя владельца карты, напечатанное на банковской карте. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`expire_month` - Месяц окончания срока действия банковской карты. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 2 * - :code:`expire_year` - Год окончания срока действия банковской карты. - | ``Необходимость``: Условно | ``Тип``: Numeric | ``Длина``: 4 * - :code:`site_url` - URL-адрес сайта электронной коммерции, откуда происходит платеж. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`purpose` - Назначение платежа. Полезно для Присоединяющихся сторон, которые позволяют своим Плательщикам пополнять счета банковской картой (счета мобильных телефонов, игровые счета и т. п.). Примеры значений: :ex:`+9999999999`; :ex:`mail@example.com` и т. п. Это значение может использоваться системой мониторинга мошенничества. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :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 .. include:: spb_request_parameters_api_v2_sale.rst Параметры ответа =============================== .. 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:`paynet-order-id` - Идентификатор заказа, присвоенный SBC. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны. * - :code:`error-message` - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`error`. Пример запроса ======================================= .. code-block:: http POST /paynet/api/v2/account-verification/39915 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 527 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=34T43R77N &order_desc=Test Order Описание &first_name=John &last_name=Smith &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 &credit_card_number=4666034752545240 &card_printed_name=CARD HOLDER &expire_month=12 &expire_year=2099 &cvv2=123 &purpose=user_account1 &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &control=5112b51084be33fa331d995d17b9d82af3bfbbc9 Пример успешного ответа ================================================ .. code-block:: http HTTP/1.1 200 Server: server Date: Thu, 27 Apr 2023 14:03:58 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: 145 type=async-response &serial-number=00000000-0000-0000-0000-000002e34518 &merchant-order-id=34T43R77N &paynet-order-id=6994016 &end-point-id=39915 Пример неуспешного ответа ============================================= .. code-block:: http HTTP/1.1 200 Server: server Date: Mon, 22 May 2023 11:14:25 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-000002e5c583 &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.html Конструктор запросов ======================================= .. raw:: html :file: ../_static/examples/sync_account_verification_Request_Debug.html