.. meta:: :description: /api/v2/preauth-form API endpoint Payneteasy: инициирует preauth через размещённую платёжную форму, с параметрами запроса и обработкой redirect URL. .. _/api/v2/preauth-form/: /api/v2/preauth-form ########################################## .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ Предавторизация по форме инициируется через запрос методом :code:`HTTPS POST` на указанный ниже :ref:`URL` с использованием указанных :ref:`параметров`. Для аутентификации запроса используется :ref:`SHA-1`. См. :ref:`Статусы транзакций`. .. _api_v2_preauth-form_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-form/ENDPOINTID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/preauth-form/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID` .. _api_v2_preauth-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:`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`. | 4. Параметр запроса::ex:`amount` в минимальных денежных единицах (если отправлен). | 4. Параметр запроса: :ex:`email`, | 5. :ex:`merchant_control` (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в Payneteasy). - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 40 * - :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:`http://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:`http://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:`http://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:`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:`preferred_language` - Двухбуквенный код языка Плательщика для многоязычных платежных форм. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`merchant_form_data` - Ключи и значения, отправленные в параметре :ex:`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 * - :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:`preferred_language` - Двухбуквенный код языка Плательщика для многоязычных платежных форм. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`card_recurring_payment_id` - Токенизированная платёжная информация держателя карты, также упоминающаяся как Идентификатор Повторного Платежа или Recurring Payment ID (RPI). Может быть создан с помощью запроса :ref:`токенизации v4`. - | ``Необходимость``: Условно | ``Тип``: Long * - :code:`cardrefid` - Ссылочный Идентификатор Платежа для последующих списаний. Может быть создан с помощью запроса :ref:`токенизации v4` или запроса :ref:`токенизации v2`. - | ``Необходимость``: Условно | ``Тип``: Long .. include:: empty.txt .. _api_v2_preauth-form_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:`redirect-url` - URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом:ex:`HTTP 302`. Подробнее см.:ref:`General Payment-form Process Flow`. Пример запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/preauth-form/39539 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close 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=+12063582043 &cell_phone=+19023384543 &amount=69 &email=john.smith@gmail.com ¤cy=USD &ipaddress=65.153.12.232 &site_url=https://doc.payneteasy.ru &credit_card_number=4538977399606732 &card_printed_name=CARD HOLDER &expire_month=12 &expire_year=2099 &cvv2=123 &purpose=user_account1 &redirect_url=http://sandbox.payneteasy.ru/doc/dummy.htm &server_callback_url=https://httpstat.us/200 &merchant_data=VIP customer &merchant_form_data=testparam%3Dtest1%26mynewparam%3Dtest2 &control=b7ba0b0ce36fda192c3772e045520c7a9cb5e442 &preferred_language=en .. include:: empty.txt Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Thu, 13 Oct 2022 09:54:53 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: 280 type=async-form-response &serial-number=00000000-0000-0000-0000-000002ddb0d3 &merchant-order-id=Test &paynet-order-id=6863103 &redirect-url=https%3A%2F%2Fsandbox.payneteasy.ru%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F78675258396E6F78367975715973596936522B594B4F646168553D Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Thu, 13 Oct 2022 09:58:28 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: 170 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb0d4 &error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD &error-code=16 .. 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_preauth_form.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: insurance_enabled .. raw:: html :file: ../_static/examples/d2_insurance_Request_Debug_preauth.html .. only:: insurance_disabled .. raw:: html :file: ../_static/examples/payment_form_integrations_Request_Debug_preauth.html