.. meta:: :description: /api/v2/sale-form API endpoint Payneteasy: инициирует продажу через размещённую платёжную форму, с параметрами запроса и обработкой redirect URL. .. _/api/v2/sale-form/: /api/v2/sale-form ################# .. role:: ex .. role:: code Введение ^^^^^^^^^^^^ Оплата по форме инициируется через запрос методом :code:`HTTPS POST` на указанный ниже :ref:`URL` с использованием указанных :ref:`параметров`. Для аутентификации запроса используется :ref:`SHA-1`. См. :ref:`Статусы транзакций`. .. _api_v2_sale-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/sale-form/ENDPOINTID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/sale-form/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/sale-form/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/sale-form/group/ENDPOINTGROUPID` .. _api_v2_sale-form_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded. | Банк может переопределить необходимость некоторых полей, сделав их обязательными. | Пробелы в начале и в конце значений параметров будут отсечены. .. warning:: В значениях параметров необходимо экранировать следующие символы: :code:`&` :code:`+` :code:`"`. .. list-table:: :widths: 25, 44, 26 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`client_orderid` - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`order_desc` - Описание заказа. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 64k * - :code:`first_name` - Имя Плательщика. Необходимость параметра зависит от канала эквайринга и необходимость параметра, необходимо уточнять у техподдержки. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`last_name` - Фамилия Плательщика. Необходимость параметра зависит от канала эквайринга и необходимость параметра, необходимо уточнять у техподдержки. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`ssn` - Последние четыре цифры номера социального страхования Плательщика. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 32 * - :code:`birthday` - Дата рождения Плательщика в формате :ex:`YYYYMMDD`. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 8 * - :code:`address1` - Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.) - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 256 * - :code:`city` - Город Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`state` - Штат Плательщика. Для списка действительных кодов штатов см. :ref:`Обязательные коды штатов`. Требуется для США, Канады и Австралии. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 2-3 * - :code:`zip_code` - Почтовый индекс Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 10 * - :code:`country` - Страна Плательщика. Для списка действительных кодов см. :ref:`Коды стран`. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2 * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 15 * - :code:`cell_phone` - Полный международный мобильный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`email` - Адрес электронной почты Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`purpose` - Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений::ex:`+9999999999`;:ex:`mail@example.com` и т. д. Это значение может проверяться системой защиты от мошенничества. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`amount` - Сумма к оплате. Сумма должна быть указана в наибольших единицах с разделителем :ex:`.`. Например, :ex:`10.5` для USD означает 10 долларов США и 50 центов. - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`currency` - Валюта, в которой проводится операция (см. :ref:`Коды валют`). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для европейского евро, RUB для российского рубля. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 3 * - :code:`ipaddress` - IP-адрес Плательщика, передаётся для целей мониторинга мошенничества. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 20 * - :code:`site_url` - URL-адрес сайта электронной коммерции, откуда происходит платеж. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :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:`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:`server_callback_url` - | URL-адрес :ex:`server_callback_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`notify_url`. При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`notify_url` - | URL-адрес :ex:`notify_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`server_callback_url`. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`preferred_language` - Двухбуквенный код языка Плательщика для многоязычных платежных форм. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`order_desc` - | Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на:ref:`запрос статуса`,:ref:`обратном вызове Присоединяющейся Стороны` или:ex:`server_callback_url`. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например:ex:`VIP клиент`,:ex:`телевизионная промо-кампания`. | Информация возвращается в ответе на запрос статуса и в обратном вызове Присоединяющейся Стороны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 64k * - :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:`card_recurring_payment_id` - Токенизированная платёжная информация держателя карты, также упоминающаяся как Идентификатор Повторного Платежа или Recurring Payment ID (RPI). Может быть создан с помощью запроса :ref:`токенизации v4`. - | ``Необходимость``: Условно | ``Тип``: Long * - :code:`cardrefid` - Ссылочный Идентификатор Платежа для последующих списаний. Может быть создан с помощью запроса :ref:`токенизации v4` или запроса :ref:`токенизации v2`. - | ``Необходимость``: Условно | ``Тип``: Long .. only:: sbp_parameters_enabled | Для интеграции Системы Быстрых Платежей (СБП) используйте ячейку :code:`purpose` для параметра :ex:`fpsRequestId` .. include:: empty.txt .. _api_v2_sale-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-form-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:`declined` или :ex:`error`, этот параметр будет содержать причину отклонения или сведения об ошибке. * - :code:`error-code` - Код ошибки для транзакций в статусе :ex:`declined` или :ex:`error`. * - :code:`redirect-url` - URL-адрес страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента методом:ex:`HTTP 302`. Подробнее см.:ref:`General Payment-form Process Flow`. Пример запроса ^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/sale-form/39519 HTTP/1.1 User-Agent: curl/7.83.0 Accept: */* Content-Length: 314 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=inv1409911 &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=156 &email=john.smith@gmail.com ¤cy=USD &ipaddress=65.153.12.232 &site_url=https://doc.payneteasy.ru &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=185aea68b751221b78fa9138e9d44a6aa4c2c446 .. include:: empty.txt Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Tue, 11 Oct 2022 14:25: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: 280 type=async-form-response &serial-number=00000000-0000-0000-0000-000002ddb0b9 &merchant-order-id=Test &paynet-order-id=6863099 &redirect-url=https%3A%2F%2Fsandbox.payneteasy.ru%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A68633370432F786752582F6154674965594A696F4D41306C50596E334F5453553D Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 OK Server: server Date: Tue, 11 Oct 2022 14:16:06 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-000002ddb0b7 &error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD &error-code=16 Коллекция Postman ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_sale_form.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^ .. only:: insurance_enabled .. raw:: html :file: ../_static/examples/d2_insurance_Request_Debug_sale.html .. only:: insurance_disabled .. raw:: html :file: ../_static/examples/payment_form_integrations_Request_Debug_sale.html