.. meta:: :description: Конечная точка API /api/v2/status SBC: опрос текущего статуса ранее инициированной транзакции по идентификатору заказа с кодами ответов и примерами. .. _/api/v2/status/: /api/v2/status ############################## .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ Получение статуса транзакции осуществляется через запрос методом :code:`HTTPS POST` на указанный ниже :ref:`URL` с использованием указанных :ref:`параметров`. Для аутентификации запроса используется :ref:`SHA-1`. См. :ref:`Статусы транзакций`. .. _status_request_url: API URL ^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.sbctech.ru/paynet/api/v2/status/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/status/ENDPOINTID` * - :ex:`https://sandbox.sbctech.ru/paynet/api/v2/status/group/ENDPOINTGROUPID` - :ex:`https://gate.sbctech.ru/paynet/api/v2/status/group/ENDPOINTGROUPID` .. _status_request_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded. .. list-table:: :widths: 30, 45, 25 :header-rows: 1 :class: longtable * - Название параметра - Описание - Необходимость * - :code:`login` - Логин Присоединяющейся Стороны в Платёжном Шлюзе. - Обязательно * - :code:`client_orderid` - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. - Обязательно * - :code:`orderid` - Идентификатор заказа, присвоенный SBC. - С условием * - :code:`by-request-sn` - Серийный номер, присвоенный SBC конкретному API-запросу. Если параметр присутствует в запросе статуса, ответ на запрос будет возвращён только для той стадии транзакции, на которой она находилась в момент совершения запроса с таким серийным номером. Параметр может быть включён в запрос для получения такой стадии в специальных случаях. Для получения наиболее актуального статуса транзакции, не следует включать этот параметр в запрос. - Опционально * - :code:`control` - | Контрольная сумма, сгенерированная :ref:`SHA-1`. Строка для подписи представляет собой объединение следующих параметров: | 1. Параметр запроса::ex:`login`. | 2. Параметр запроса::ex:`client_orderid`. | 3. Параметр запроса::ex:`orderid`. | 4. :ex:`merchant_control` (Контрольный ключ, назначенный для аккаунта Присоединяющейся стороны в системе SBC). - Обязательно | | В большинстве случаев наилучшим вариантом является включение обоих параметров :code:`client_orderid` и :code:`orderid` в запрос статуса. Статус заказа можно запросить только с :code:`client_orderid`, если он уникален для Торговца и :code:`orderid` не получен. Если :code:`orderid` не получен в ответе, но ответ содержитошибку, см. полученное сообщение об ошибке, чтобы получить информацию о том, почему транзакция не была создана в системе. .. _status_v2_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.sbctech.ru. * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны. * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. * - :code:`html` - HTML-код формы авторизации 3DS, закодированный в формате MIME application/x-www-form-urlencoded. Торговец должен декодировать этот параметр перед показом формы Плательщику. Система gate.sbctech.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.sbctech.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.sbctech.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.sbctech.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` - Общая комиссия за обработанную транзакцию. Это необязательный параметр. Пожалуйста, свяжитесь с вашим менеджером в SBC, если вы хотите его получить. * - :code:`acquirer-commission` - Комиссия эквайера за обработанную транзакцию. Это необязательный параметр. Обратитесь к своему менеджеру в SBC, если хотите его получить. * - :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:: http POST /paynet/api/v2/status/37211 HTTP/1.1 Host: sandbox.sbctech.ru User-Agent: curl/7.77.0 Accept: */* Content-Length: 99 Content-Type: application/x-www-form-urlencoded Connection: close login=TestYujik &client_orderid=123 &orderid=6863082 &control=647f0581bbceb804a73e98d9ea7e78640a75bf1c Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: sbp_parameters_enabled .. code-block:: none type=status-response &serial-number=00000000-0000-0000-0000-0000037704d3 &merchant-order-id=902B4FF5 &paynet-order-id=6863082 &status=processing &amount=10.42 ¤cy=RUB &original-gate-descriptor=PAYMENT-RUB &transaction-type=sale &receipt-id=7d59a029-2316-36e5-b29b-96139fc7af38 &card-exp-month=0 &card-exp-year=0 &email=john.smith@gmail.com &order-stage=sale_3d_validating &merchantdata=VIP customer &card-type=SBP &phone=12063582043 &paynet-processing-date=2023-03-29 13:47:40 MSK &first-name=John &last-name=Smith &initial-amount=10.42 &qr-code=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAIAAADTED8xAAAFIklEQVR42u3dSXLjQAwEQP7/0/IbHFI... &qr-code-payload-type=SBP &qr-code-payload-value=https://qr.nspk.ru/BS100069IM4ESCN090DP55N859KG1AAD .. only:: sbp_parameters_disabled .. code-block:: http HTTP/1.1 200 OK Server: server Date: Mon, 12 Sep 2022 09:02:42 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 X-Cached: EXPIRED Content-Length: 1275 type=status-response &serial-number=00000000-0000-0000-0000-000002ddb056 &merchant-order-id=123 &processor-tx-id=PNTEST-6863082 &paynet-order-id=6863082 &status=approved &amount=555.00 ¤cy=USD &descriptor=XXXX &original-gate-descriptor=XXXX &gate-partial-reversal=enabled &gate-partial-capture=enabled &transaction-type=sale &receipt-id=081c0c0b-0dd1-3083-b251-e624ac8e57b4 &name=CARD+HOLDER &cardholder-name=CARD+HOLDER &card-exp-month=12 &card-exp-year=2099 &email=john.smith%40gmail.com &last-name=Smith &first-name=John &processor-rrn=0225083062885 &approval-code=979249 &order-stage=sale_approved &merchantdata=VIP+customer &last-four-digits=2063 &bin=410002 &card-type=VISA &phone=12063582043 &bank-name=BANCO+ITAUCARD+S.A. &auth-response-code=00 &terminal-id=12345678 &paynet-processing-date=2022-09-07+13%3A22%3A39+MSK &acquirer-processing-date=2022-09-07+13%3A22%3A39+MSK &processor-auth-credit-code=206551 &card-hash-id=2639503 &card-country-alpha-three-code=BRA &verified-3d-status=NOT_AUTHENTICATED &processor-credit-rrn=0225060914211 &processor-credit-arn=809124106 &processor-debit-arn=601904020 &purpose=user_account1 &ips-src-payment-product-code=F &ips-src-payment-product-name=Visa+Classic &ips-src-payment-type-code=Credit &ips-src-payment-type-name=VISA+Credit &initial-amount=555.00 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http HTTP/1.1 200 OK Server: server Date: Mon, 12 Sep 2022 09:08:02 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 X-Cached: MISS Content-Length: 137 type=validation-error &serial-number=00000000-0000-0000-0000-000002ddb057 &error-message=End+point+with+id+372118+not+found &error-code=3 .. 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_status.html Конструктор запросов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/sale_transaction_Order_Status_Debug.html