.. meta:: :description: /api/v2/preauth API endpoint Payneteasy: блокирует средства на счёте держателя карты для последующего capture, с параметрами запроса и кодами ответа. .. _/api/v2/preauth/: /api/v2/preauth ################################ .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ Preauth инициируется запросом :code:`HTTPS POST` с использованием указанных ниже :ref:`URL` и :ref:`параметров`. Для аутентификации используйте :ref:`SHA-1`. См. :ref:`статусы`. .. _api-v2-preauth-request-url: API URL ^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/preauth/ENDPOINTID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/preauth/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/preauth/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/preauth/group/ENDPOINTGROUPID` .. _api_v2_preauth_request_parameters_url: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. 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 | ``Длина``: 1525 * - :code:`amount` - Сумма к оплате. Сумма должна быть указана в наибольших единицах с разделителем :ex:`.`. Например, :ex:`10.5` для USD означает 10 долларов США и 50 центов. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`currency` - Валюта, в которой проводится операция (см. :ref:`Коды валют`). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для европейского евро, RUB для российского рубля. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 3 * - :code:`address1` - Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.) - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 256 * - :code:`city` - Город Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`zip_code` - Почтовый индекс Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 10 * - :code:`country` - Страна Плательщика. Для списка действительных кодов см. :ref:`Коды стран`. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2 * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 15 * - :code:`email` - Адрес электронной почты Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`ipaddress` - IP-адрес Плательщика, передаётся для целей мониторинга мошенничества. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 45 * - :code:`control` - | Контрольная сумма, сгенерированная :ref:`SHA-1`. Строка для подписи представляет собой объединение следующих параметров: | 1. :ex:`` (См.: :ref:`URL запроса`). | 2. Параметр запроса::ex:`client_orderid`. | 3. Параметр запроса: :ex:`amount` в минимальных денежных единицах, | 4. Параметр запроса: :ex:`email`, | 5. :ex:`merchant_control` (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в Payneteasy). - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 40 * - :code:`cvv2` - Код CVV2 плательщика. CVV2 (Card Verification Значение) — это трех - или четырехзначное число, напечатанное на обратной стороне карты в области подписи. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 3-4 * - :code:`credit_card_number` - Номер банковской карты плательщика (также известный как PAN — Primary Account Number). - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 20 * - :code:`card_recurring_payment_id` - Идентификатор токенизированных данных держателя карты Плательщика. Отправьте либо :code:`card_recurring_payment_id`, либо комбинацию :code:`credit_card_number`, :code:`card_printed_name`, :code:`expire_month` и :code:`expire_year`, но не все значения одновременно. Сведения о создании :code:`card_recurring_payment_id` см. в :ref:`api-v2-card-ref-id`. - | ``Необходимость``: Обязательно | ``Тип``: Long | ``Длина``: 20 * - :code:`card_printed_name` - Имя владельца карты, напечатанное на банковской карте. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 64k * - :code:`expire_month` - Месяц окончания срока действия банковской карты. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 2 * - :code:`expire_year` - Год окончания срока действия банковской карты. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 4 * - :code:`first_name` - Имя Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`last_name` - Фамилия Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`state` - Штат Плательщика. Для списка действительных кодов штатов см. :ref:`Обязательные коды штатов`. Требуется для США, Канады и Австралии. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 2-3 * - :code:`redirect_url` - | URL, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is :ex:`approved`, :ex:`declined` in any other final :ref:`status`. | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`https://doc.payneteasy.ru` if you have no need to return payer anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_success_url` - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`успешного` статуса транзакции (см. :ref:`Статусы транзакций`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Otherwise put :ex:`https://doc.payneteasy.ru` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url` or :ex:`redirect_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_fail_url` - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`неуспешного` статуса транзакции (см. :ref:`Статусы транзакций`). | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command`. Pass :ex:`https://doc.payneteasy.ru` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`ssn` - Последние четыре цифры номера социального страхования Плательщика. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 32 * - :code:`birthday` - Дата рождения Плательщика в формате :ex:`YYYYMMDD`. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 8 * - :code:`cell_phone` - Полный международный мобильный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`site_url` - URL-адрес сайта электронной коммерции, откуда происходит платеж. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`purpose` - Получатель платежа. Это полезно для Присоединяющихся сторон, позволяющих плательщикам пополнять свои счета банковской картой (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: :ex:`+9999999999`; :ex:`mail@example.com` и т. д. Это значение может использоваться системой мониторинга мошенничества. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`server_callback_url` - | URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. | Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters`. This parameter can be sent instead of :ex:`notify_url`. If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`notify_url` - | URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. | Connecting Party may use notify URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`notify_url` refer to :ref:`Connecting Party callback parameters`. This parameter can be sent instead of :ex:`server_callback_url`. If :ex:`notify_url` is sent, Payment Gateway sends callback notification once the original transaction receives final status, and about every future update for this original transaction (reversal, chargeback, etc). If :ex:`server_callback_url` is sent, Payment Gateway sends callback notification only when original transaction receives final status. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`order_desc` - | Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на:ref:`запрос статуса`,:ref:`обратном вызове Присоединяющейся Стороны` или:ex:`server_callback_url`. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например:ex:`VIP клиент`,:ex:`телевизионная промо-кампания`. | Информация возвращается в ответе на запрос статуса и в обратном вызове Присоединяющейся Стороны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 64k * - :code:`minimum_transaction_amount` - Этот параметр можно использовать для ограничения минимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре:ex:`amount`. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 10 * - :code:`maximum_transaction_amount` - Этот параметр можно использовать для ограничения максимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре:ex:`amount`. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 10 * - :code:`customer_level` - Уровень клиента в системе CMS. - | ``Необходимость``: Опционально | ``Тип``: Varchar | ``Длина``: 32 * - :code:`customer_id` - Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом. - | ``Необходимость``: Опционально | ``Тип``: Int | ``Длина``: 10 * - :code:`merchant_customer_identifier` - Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM. - | ``Необходимость``: Опционально | ``Тип``: Varchar | ``Длина``: 64 * - :code:`recurring-payment-id` - Recurring Payment ID может быть передан вместо данных держателя карты. Для нативных транзакций CVV не требуется. Обновление данных клиента возможно через:ref:`/api/v4/update-recurring-payment/`. Процесс создания Recurring Payment ID инициируется:code:`HTTPS POST` запросом с использованием указанных ниже:ref:`URLs`. и:ref:`параметров`, используйте:ref:`RSA-SHA256` для аутентификация - | ``Необходимость``: Условно | ``Тип``: Long .. _api_v2_preauth_additional_form: Дополнительные поля для транзакций Preauth ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Для Присоединяющейся Стороны """""""""""""""""""""""""""""""""""""""" .. note:: | Данные браузера для 3DS 2.X собираются системой Payneteasy на этапе 3DS-аутентификации. Однако для некоторых каналов обработки данные браузера и/или URL Присоединяющейся стороны для результатов 3DS challenge должны быть переданы в первоначальном запросе транзакции. Обратитесь к менеджеру поддержки, чтобы уточнить, следует ли включать эти параметры в параметры запроса. Сайт Присоединяющейся Стороны должен точно заполнять информацию о браузере по каждой транзакции. Эти данные могут быть получены серверами Присоединяющейся Стороны. Убедитесь, что данные не изменены и не жестко запрограммированы, и что они уникальны для каждой транзакции. .. list-table:: :widths: 30, 40, 20 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`ipaddress` - IP-адрес браузера, возвращаемый HTTP-заголовками инициатору запроса 3DS. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 45 * - :code:`customer_browser_accept_header` - Точное содержание заголовков HTTP Accept, отправленное инициатору запроса 3DS из браузера владельца карты. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2048 * - :code:`customer_browser_javascript_enabled` - Boolean, представляющий cпособность браузера владельца карты запускать JavaScript. - | ``Необходимость``: Обязательно | ``Тип``: Boolean | ``Длина``: - * - :code:`customer_browser_accept_language` - Значение, представляющее язык браузера, по определено IETF BCP47. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 8 * - :code:`customer_browser_user_agent` - Точное содержание заголовка HTTP user-agent. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2048 * - :code:`tds_areq_notification_url`, alias :code:`tds_cres_notification_url` - Полный URL-адрес системы Присоединяющейся Стороны, которая получит сообщение CRes или сообщение об ошибке. Это сообщение CRes должно быть отправлено Payneteasy. См. :ref:`Загрузка результата CRes`. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 256 * - :code:`customer_browser_info` - Если true, параметры, приведенные ниже, должны быть указаны. - | ``Необходимость``: Опционально | ``Тип``: Boolean | ``Длина``: - * - :code:`customer_browser_color_depth` - Значение, представляющее разрядность цветовой палитры для отображения изображений, в битах на пиксель. Становится обязательным, когда :code:`browser_javaScript_enabled` = true». - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`customer_browser_java_enabled` - Boolean, который представляет способность браузера владельца карты запускать Java. Становится обязательным, когда :code:`browser_javaScript_enabled` = true. - | ``Необходимость``: Опционально | ``Тип``: Boolean | ``Длина``: - * - :code:`customer_browser_screen_height` - Общая высота экрана владельца карты в пикселях. Требуется, когда :code:`browser_javaScript_enabled` = true. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 6 * - :code:`customer_browser_screen_width` - Общая ширина экрана владельца карты в пикселях. Требуется, когда :code:`browser_javaScript_enabled` = true. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 6 * - :code:`customer_browser_time_zone` - Смещение часового пояса в минутах между UTC и местным временем браузера держателя карты. Обратите внимание, что смещение является положительным, если местный часовой пояс отстает от UTC, и отрицательным, если он опережает UTC. Становится обязательным, когда :code:`browser_javaScript_enabled` = true. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 5 Для платежных учреждений """""""""""""""""""""""""""""""""""""""""""" PSP или эквайер могут заполнить результаты 3DS для каждой транзакции, если выполнение 3DS аутентификации происходит на их стороне. .. include:: ../rst_include/additional_fields_for_psp.txt .. _api_v2_preauth_response_parameters: Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. 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` - Идентификатор заказа, присвоенный Payneteasy. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Присоединяющейся стороны. * - :code:`error-message` - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`error`. * - :code:`end-point-id` - Идентификатор терминала, используемый для транзакции. Пример запроса с данными владельца карты ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/preauth/39549 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close credit_card_number=4538977399606732 &card_printed_name=CARD HOLDER &expire_month=12 &expire_year=2099 &cvv2=123 &client_orderid=902B4FF5 &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=%2B12063582043 &cell_phone=%2B19023384543 &email=john.smith@gmail.com ¤cy=USD &amount=10.42 &ipaddress=65.153.12.232 &site_url=https://doc.payneteasy.ru &purpose=user_account1 &redirect_url=https://doc.payneteasy.ru/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483 Пример запроса с идентификатором регулярного платежа по карте ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none POST /paynet/api/v2/preauth/39549 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close card_recurring_payment_id=1491927 &cvv2=123 &client_orderid=34T43R77N &order_desc=Test Order Описание &amount=777 ¤cy=USD &ipaddress=65.153.12.232 &redirect_url=https://doc.payneteasy.ru/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &control=218d377897ce25c2ac69d99de42bc6902eb5bcd8 Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 OK Server: server Date: Mon, 05 Sep 2022 10:43:57 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: 139 type=async-response &serial-number=00000000-0000-0000-0000-000002ddb018 &merchant-order-id=123 &paynet-order-id=6863073 &end-point-id=39914 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 OK Server: server Date: Mon, 05 Sep 2022 10:51:14 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: 208 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb019 &merchant-order-id=123 &error-message=Validate+card+number+failed.+Card+Number+length+must+be+between+16+and+19+digits.. &error-code=8 Коллекция Postman ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_preauth.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/preauth_transaction_Request_Debug.html