.. meta:: :description: /api/v4/status API endpoint Payneteasy: опрашивает текущий статус транзакции v4 по идентификатору заказа, с кодами ответа и примерами вызовов. .. _/api/v4/status/: /api/v4/status ############################## .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ Получение статуса транзакции осуществляется через запрос методом :code:`HTTPS POST` на указанный ниже :ref:`URL` с использованием указанных :ref:`параметров`. Для аутентификации запроса используется :ref:`RSA-SHA256`. См. :ref:`Статусы транзакций`. .. _status_request_v4_url: API URL ^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/status/ENDPOINTID` - :ex:`https://gate.payneteasy.ru/paynet/api/v4/status/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/status/group/ENDPOINTGROUPID` - :ex:`https://gate.payneteasy.ru/paynet/api/v4/status/group/ENDPOINTGROUPID` .. _status_v4_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. .. list-table:: :widths: 30, 45, 25 :header-rows: 1 :class: longtable * - Название параметра - Описание - Необходимость * - :code:`login` - Логин Присоединяющейся Стороны в Платёжном Шлюзе. - Обязательно * - :code:`client_orderid` - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. - Обязательно * - :code:`orderid` - Идентификатор заказа, присвоенный Payneteasy. - С условием * - :code:`by-request-sn` - Серийный номер, присвоенный Payneteasy конкретному API-запросу. Если параметр присутствует в запросе статуса, ответ на запрос будет возвращён только для той стадии транзакции, на которой она находилась в момент совершения запроса с таким серийным номером. Параметр может быть включён в запрос для получения такой стадии в специальных случаях. Для получения наиболее актуального статуса транзакции, не следует включать этот параметр в запрос. - Опционально | | В большинстве случаев наилучшим вариантом является включение обоих параметров :code:`client_orderid` и :code:`orderid` в запрос статуса. Статус заказа можно запросить только с :code:`client_orderid`, если он уникален для Присоединившейся Стороны и :code:`orderid` не получен. Если :code:`orderid` не получен в ответе, но ответ содержит ошибку, см. полученное сообщение об ошибке, чтобы получить информацию о том, почему транзакция не была создана в системе. .. _status_v4_response_parameters: Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | API команда запроса статуса участвует во множестве сценариев использования API, поэтому некоторые из указанных параметров могут не встречаться в определенных сценариях. Ниже предоставлен полный список возможных параметров ответа. .. note:: | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра. | * - эти параметры не возвращаются в ответе по умолчанию. Для их получения необходимо связаться со службой поддержки. .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Параметры ответа на запрос статуса - Описание * - :code:`type` - Тип ответа. Может быть :ex:`status-response`. * - :code:`status` - Подробности см. в :ref:`status_list`. * - :code:`amount` - Фактическая сумма транзакции. Данное значение может быть изменено в ходе транзакции. * - :code:`currency` - Валюта, в которой взимается транзакция (трехбуквенный код валюты). Примеры допустимых значений параметров: :ex:`USD` для доллара США :ex:`EUR` для евро. * - :code:`paynet-order-id` - Идентификатор заказа, присвоенный заказу gate.payneteasy.ru. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. * - :code:`html` - HTML-код формы авторизации 3DS, закодированный в формате MIME application/x-www-form-urlencoded. Присоединяющейся Сторона должен декодировать этот параметр перед показом формы Плательщику. Система gate.payneteasy.ru возвращает следующие параметры ответа, когда получает форму авторизации 3DS от Банка-эмитента. Он содержит HTML-код формы авторизации, который должен быть передан без каких-либо изменений в браузер клиента. Этот параметр существует и имеет значение только тогда, когда HTML перенаправления уже доступен. Для не-3DS этого никогда не происходит. Для 3DS HTML имеет значение через некоторое короткое время после начала обработки. * - :code:`redirect-to` - Для 3DS-авторизации Присоединившейся Сторона может перенаправить плательщика по URL , указанному в этом параметре, вместо отображения страницы, предоставленной в параметре :code:`html`. Параметр :code:`redirect-to` возвращается только в том случае, если возвращается параметр :code:`html`Присоединившейся Сторона должен использовать HTTP-метод :ex:`GET` для перенаправления. Этот параметр необходимо использовать для работы с 3DS 2.0. * - :code:`serial-number` - Уникальный номер, присваиваемый сервером gate.payneteasy.ru конкретному запросу от присоединяющейся стороны. * - :code:`last-four-digits` - Последние четыре цифры номера банковской карты Плательщика. * - :code:`dest-last-four-digits` - Последние четыре цифры номера кредитной карты клиента. Относится только к транзакциям перевода. * - :code:`bin` - BIN банка или номер банковской карты плательщика. * - :code:`card-type` - Тип банковской карты Плательщика (:ex:`VISA`, :ex:`MASTERCARD` и т.д.). * - :code:`gate-partial-reversal` - Возможность проведения частичного возврата (enabled - возможно, disabled - невозможно). * - :code:`gate-partial-capture` - Возможность проведения частичного списания захолдированной суммы (enabled - возможно, disabled - невозможно). * - :code:`transaction-type` - Тип тпанзакции (:ex:`продажа`, :ex:`возврат`, :ex:`списание`, :ex:`преавторизация`). * - :code:`processor-rrn` - Регистрационный номер банка-получателя. * - :code:`processor-tx-id` - Идентификатор транзакции, присвоенный Эквайером. * - :code:`receipt-id` - Электронная ссылка на квитанцию: :code:`https://gate.payneteasy.ru/paynet/view-receipt/ENDPOINTID/receipt-id/`. * - :code:`name` - Имя плательщика * - :code:`card-ref-id` - Ссылочный идентификатор, используемый в последующих повторяющихся платежах. Имеет значение только в том случае, если card-ref-id был создан для первоначальной транзакции. * - :code:`cardholder-name` - Имя владельца карты. * - :code:`card-exp-month` - Месяц окончания срока действия банковской карты. * - :code:`card-exp-year` - Год окончания срока действия банковской карты. * - :code:`card-hash-id` - Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество. * - :code:`card-country-alpha-three-code` - Трехбуквенный код страны эмитента карты отправителя. Подробности см. в :ref:`country-state-codes`. * - :code:`destination-card-country-alpha-three-code` - Трехбуквенный код страны эмитента карты получателя. Подробности см. в :ref:`country-state-codes`. * - :code:`dest-bin` - Банковский BIN кредитной карты клиента. * - :code:`dest-card-type` - Тип кредитной карты клиента (:ex:`VISA`, :ex:`MASTERCARD` и т.д.). * - :code:`dest-bank-name` - Наименование банка по BIN карты клиента. * - :code:`destination-hash-id` - Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество. Актуально только для транзакций переводов. * - :code:`destination-card-hash-id` - Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество. * - :code:`first-name` - Имя плательщика. * - :code:`last-name` - Фамилия Плательщика. * - :code:`email` - Электронная почта плательщика. * - Параметр :code:`country` * - Страна плательщика (двухбуквенный код страны). Список допустимых кодов стран см. в :ref:`country-state-codes`. * - Параметр :code:`state` * - Штат плательщика. Список допустимых кодов штатов см. в:ref:`country-state-codes`. Обязательно для США, Канады и Австралии. * - Параметр :code:`city` * - Город Плательщика. * - Параметр :code:`zip_code` * - Почтовый индекс Плательщика. * - Параметр :code:`address1` * - Адрес Плательщика, строка 1. * - :code:`purpose` - Место назначения платежа. Это полезно для Присоединяющейся Стороны, которые позволяют своим плательщикам пополнять свои счета с помощью банковских карт (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: :ex:`+9999999999`; :ex:`mail@example.com` и т. д. Данное значение может использоваться системой мониторинга мошенничества. * - :code:`bank-name` - Наименование банка по BIN карты плательщика. * - :code:`terminal-id` - Идентификатор терминала эквайера, который будет указан в чеке. * - :code:`paynet-processing-date` - Дата обработки транзакции эквайером. * - :code:`approval-code` - Код одобрения банка. * - :code:`order-stage` - Текущая стадия обработки транзакции. Подробности см. в:ref:`order_stage`. * - :code:`total-reversal-amount` - Сумма последнего обработанного возврата. Актуально только для транзакций возврата. * - :code:`reversal-amount` - Сумма последнего обработанного возврата. Актуально только для транзакций возврата. * - :code:`auth-response-code` - Код ответа, используемый в протоколе Iso8583. Возвращается только в определенных случаях. * - :code:`acquirer-processing-date` - Дата обработки транзакции эквайером. * - :code:`processor-auth-credit-code` - Код одобрения кредита. Возвращается только в определенных случаях. * - :code:`processor-credit-rrn` - Номер ссылки извлечения для кредитной транзакции. * - :code:`processor-credit-arn` - Ссылочный номер карты-эквайера для кредитной транзакции. * - :code:`processor-debit-arn` - Ссылочный номер карты-эквайера для дебитной транзакции. * - :code:`loyalty-balance` - Текущий баланс бонусов программы лояльности для текущей операции. :ex:`если доступно`. * - :code:`loyalty-message` - Сообщение от программы лояльности. :ex:`если доступно`. * - :code:`loyalty-bonus` - Бонусная стоимость программы лояльности для текущей операции :ex:`если доступно`. * - :code:`loyalty-program` - Название программы лояльности для текущей операции :ex:`если доступно`. * - :code:`descriptor` - Банковский идентификатор получателя платежа. * - :code:`original-gate-descriptor` - Дескриптор, который устанавливается на уровне шлюза в системе. * - :code:`error-message` - Если статус:ex:`declined`,:ex:`error` или:ex:`filtered`, этот параметр содержит причину отклонения. * - :code:`error-code` - Код ошибки для транзакций в статусе:ex:`declined`,:ex:`error`,:ex:`filtered`. * - :code:`by-request-sn` - Серийный номер, назначенный конкретному запросу gate.payneteasy.ru. Если это поле существует в запросе статуса, ответ статуса возвращается для этого конкретного запроса. * - :code:`verified-3d-status` - Подробную информацию см. :ref:`3d_secure_status_list`. * - :code:`verified-rsc-status` - Возвращается, если была выполнена проверка случайной суммы. См. :ref:`alternative_cardholder_authentication` * - :code:`eci` - Индикатор электронной коммерции (Visa). * - :code:`ips-src-payment-product-code` - Код карты, установленный международной финансовой службой (Visa/Mastercard). * - :code:`ips-src-payment-product-name` - Расшифрованный код для карты, установленный международной финансовой службой (Visa/Mastercard). * - :code:`ips-src-payment-type-code` - Код типа карты, установленный международной финансовой службой (Visa/Mastercard). * - :code:`ips-src-payment-type-name` - Расшифрованный код типа карты, установленный международной финансовой службой (Visa/Mastercard). * - :code:`merchantdata` - Если параметр merchant_data и его значение указаны в первоначальном запросе, они будут включены в ответ о статусе. * - :code:`initial-amount` - Сумма, установленная при инициировании транзакции, без каких-либо сборов или комиссий. Это значение не может измениться в ходе транзакции. * - :code:`seller-commission` - Общая комиссия за обработанную транзакцию. Это необязательный параметр. Пожалуйста, свяжитесь с вашим менеджером в Payneteasy, если вы хотите его получить. * - :code:`acquirer-commission` - Комиссия эквайера за обработанную транзакцию. Это необязательный параметр. Обратитесь к своему менеджеру в Payneteasy, если хотите его получить. * - :code:`motivational-message` - Опциональный параметр, содержаний сообщение с расширенной информацией по причине отклонения транзакции. * - :code:`transaction-date` - Дата присвоения окончательного статуса транзакции. * - :code:`orig-amount` - Содержит исходную сумму запроса, если она была преобразована на вспомогательном терминале в интеграции с параллельной формой. Актуально только для транзакций Payment Cashier. * - :code:`orig-currency` - Содержит исходную валюту запроса, если она была преобразована на вспомогательном терминале в интеграции с параллельной формой. Актуально только для транзакций Payment Cashier. .. only:: sbp_parameters_enabled | Параметры ответа статуса QR-кода: .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Параметры ответа на запрос статуса - Описание * - :code:`qr-code` - QR-код в формате base64. * - :code:`qr-code-payload-type` - Тип QR-кода = SBP. * - :code:`qr-code-payload-value` - Ссылка на QR-код =https://qr.nspk.ru/BS***** (только для интеграции H2H). Параметры ответа на запрос статуса PaReqForm ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 40, 60 :header-rows: 1 :class: longtable * - Название - Описание * - :code:`tds-pareq-form-pareq` - Данные ACS 3DS PaReq, полученные Присоединяющейся Стороной. * - :code:`tds-pareq-form-acs-url` - ACS URL для перенаправления Плательщика в рамках сценария аутентификации 3DS 1.0.2. Параметры ответа на запрос статуса CReqForm ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 30, 70 :header-rows: 1 :class: longtable * - Название - Описание * - :code:`tds-creq-form-creq` - Сообщение CReq инициирует взаимодействие держателя карты в полной проверке 3DS (Challenge) и используется для передачи аутентификационных данных. Формируется сервером 3DS Присоединяющейся Стороной через браузер держателя карты в адрес ACS URL. * - :code:`tds-creq-form-acs-url` - ACS URL для перенаправления Плательщика для полной проверки 3DS (Challenge). Параметры ответа на запрос статуса MethodUrlFrame ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 35, 65 :header-rows: 1 :class: longtable * - Название - Описание * - :code:`tds-method-url-frame-3ds-server-trans-id` - Универсальный уникальный идентификатор транзакции, присвоенный 3DS-сервером для идентификации отдельной транзакции. * - :code:`tds-method-url-frame-3ds-method-url` - URL 3DS Метода используется в форме iframe, передающейся от Присоединяющейся Стороны к Плательщику. Правила создания HTML формы. | Данные метода 3DS: :code:`threeDSMethodData` (:code:`threeDSMethodNotificationURL` + :code:`threeDSServerTransID`). Пример запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none POST /paynet/api/v4/status/46750 HTTP/1.1 User-Agent: curl/7.88.1 Accept: */* Authorization: OAuth oauth_consumer_key="Test_Merchant", oauth_nonce="BKOz6eHOs6sDJlLPAJhbDHAaXCy9xxNv", oauth_signature="eQXkV%2BJdiqJlyRqNaEzIKmYa3FZzUjdcMR6lXSfRn9tOYKUNPxI3UKU%2F%2FGsPpofXL%2B2RBjGh3Gqv%2BZBoKaVKOgNKwNNwpA4IOaskV71uuMbZCp0gPEbS%2BVaWLD8vzqpcgZ%2Bd5DRNMfimyXkWVWbsMUYj8N%2BSpXl4YnGIo0nXz9Q0Ppxetie3EG9NrN7CNu7NdovVjmstfYqpDRv9OhLo4tSQTD9C6bWvW2kmEvZsb2d1KANsGUW6rXyjkIoPxJ2XigIXBOUfwSWj9cV7SsZ%2FNk%2FVjNWgav2uw9J9I%2FiTqLLcKZ1pTWj1WOMwXhfoMCP10XOAOe72CQHX0DJL%2BFt01jmOXLvLdEkUZTFzsC6DGfHSDdcsjXquc9gxFKVr3d8e15by3566UI4pXKef%2Fe%2B3Ytvlrj7IUhIcNyA%2BVXp%2FwivxgwYu2xpQJMs6wlvw6Lz3N2wcFRqLs5ZEbdZ1%2F29pox8XW0ae8yZ2z2PClPzmJIoDcOr0GEtwyz5ByyeW0m33XA67UbPN6rwbdlVL2gwMqWwkn7KDYp7%2BifP%2B2BdbyXnw2LeJcuYDYAIDHa%2Bi0P09ZVToBpeLOx%2FobSF2y%2FsheVgo0O%2FRWtUEEXONvd0n7hEdnJ7mMYNivNitbfQ4SryQ2o8CdUDk9RgEaR7pn7ybTi4rQEhDqWF8sFMtaKhFn9o%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1734327207", oauth_version="1.0" Content-Length: 58 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=1&login=Test_Merchant&order_id=7364742 Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 Server: server Date: Mon, 16 Dec 2024 05:38:33 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: 1469 type=status-response &serial-number=00000000-0000-0000-0000-000002f38234 &merchant-order-id=123456 &processor-tx-id=PNTEST-7364748 &paynet-order-id=7364748 &status=approved &amount=10.42 ¤cy=USD &descriptor=Test &original-gate-descriptor=Test &transaction-type=transfer &receipt-id=2f885ae0-5220-3549-8eb5-622f4201f882 &name=John+Doe &cardholder-name=John+Doe &card-exp-month=12 &card-exp-year=2099 &processor-rrn=0435171505391 &approval-code=466875 &order-stage=transfer_approved &last-four-digits=5721 &bin=421070 &card-type=VISA &bank-name=DEMIRBANK+OJSC &dest-bank-name=JPMORGAN+CHASE+BANK+N.A. &dest-bin=423261 &dest-last-four-digits=1636 &dest-card-type=VISA &auth-response-code=00 &paynet-processing-date=2024-12-16+08%3A37%3A25+MSK &acquirer-processing-date=2024-12-16+08%3A37%3A25+MSK &processor-auth-credit-code=311830 &card-hash-id=2511341 &destination-card-hash-id=2511340 &card-country-alpha-three-code=AZE &destination-card-country-alpha-three-code=USA &verified-3d-status=NOT_AUTHENTICATED &processor-credit-rrn=0435147814453 &processor-credit-arn=899834666 &processor-debit-arn=668539305 &ips-src-payment-product-code=UNK &ips-src-payment-product-name=Unknown &ips-src-payment-type-code=Credit &ips-src-payment-type-name=VISA+Credit &ips-dst-payment-product-code=UNK &ips-dst-payment-product-name=Unknown &ips-dst-payment-type-code=Prepaid &ips-dst-payment-type-name=VISA+Prepaid &initial-amount=10.42 &transaction-date=2024-12-16+08%3A37%3A34+MSK Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none HTTP/1.1 200 Server: server Date: Mon, 16 Dec 2024 05:33: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: 164 type=status-response &serial-number=00000000-0000-0000-0000-000002f38231 &merchant-order-id=1 &status=error &error-message=AMBIGUOUS_CLIENT_ORDER_ID &error-code=124 Коллекция Postman ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_status.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Введите приватный ключ, содержащийся в PKCS#1. См. :ref:`RSA-SHA256`. .. raw:: html :file: ../_static/examples/v4Transfer_order_status_debug.html