3.11. /api/v2/status

Введение

Получение статуса транзакции осуществляется через запрос методом HTTPS POST на указанный ниже URL с использованием указанных параметров. Для аутентификации запроса используется SHA-1. См. Статусы транзакций.

API URL

Интеграционная среда	Производственная среда
https://sandbox.sbctech.ru/paynet/api/v2/status/ENDPOINTID	https://gate.sbctech.ru/paynet/api/v2/status/ENDPOINTID
https://sandbox.sbctech.ru/paynet/api/v2/status/group/ENDPOINTGROUPID	https://gate.sbctech.ru/paynet/api/v2/status/group/ENDPOINTGROUPID

Параметры запроса

Note

Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded.

Название параметра	Описание параметра	Необходимость
login	Логин Присоединяющейся Стороны в Платёжном Шлюзе.	Обязательно
client_orderid	Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.	Обязательно
orderid	Идентификатор заказа на стороне Платёжного Шлюза.	Условно
by-request-sn	Серийный номер, присвоенный SBC конкретному API-запросу. Если параметр присутствует в запросе статуса, ответ на запрос будет возвращён только для той стадии транзакции, на которой она находилась в момент совершения запроса с таким серийным номером. Параметр может быть включён в запрос для получения такой стадии в специальных случаях. Для получения наиболее актуального статуса транзакции, не следует включать этот параметр в запрос.	Опционально
control	Контрольная сумма, сгенерированная SHA-1. Строка для подписи представляет собой объединение следующих параметров: 1. Параметр запроса: login, 2. Параметр запроса: client_orderid, 3. Параметр запроса: orderid, 4. merchant_control (Контрольный ключ Присоединяющейся Стороны в Платёжном Шлюзе SBC).	Обязательно

В большинстве случаев наилучшим вариантом является включение обоих параметров client_orderid и orderid в запрос статуса. Статус заказа можно запросить только с client_orderid, если он уникален для Торговца и orderid не получен. Если orderid не получен в ответе, но ответ содержитошибку, см. полученное сообщение об ошибке, чтобы получить информацию о том, почему транзакция не была создана в системе.

Параметры ответа

API команда запроса статуса участвует во множестве сценариев использования API, поэтому некоторые из указанных параметров могут не встречаться в определенных сценариях. Ниже предоставлен полный список возможных параметров ответа.

Note

Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencode, с символом (0xA) в конце значения каждого параметра.

* - эти параметры не возвращаются в ответе по умолчанию. Для их получения необходимо связаться со службой поддержки.

Параметры ответа на запрос статуса CReqForm	Описание параметра
type	Тип ответа. Может быть status-response.
status	Для подпробностей см. Список статусов.
amount	Фактическая сумма транзакции. Данное значение может быть изменено в ходе транзакции.
currency	Валюта, в которой взимается транзакция (трехбуквенный код валюты). Примеры допустимых значений параметров: USD для доллара США EUR для евро.
paynet-order-id	Идентификатор заказа на стороне Платёжного Шлюза.
merchant-order-id	Идентификатор заказа Присоединяющейся Стороны.
phone	Полный международный номер телефона плательщика, включая код страны.
html	HTML-код формы авторизации 3DS, закодированный в формате MIME application/x-www-form-urlencoded. Торговец должен декодировать этот параметр перед показом формы Плательщику. Система gate.sbctech.ru возвращает следующие параметры ответа, когда получает форму авторизации 3DS от Банка-эмитента. Он содержит HTML-код формы авторизации, который должен быть передан без каких-либо изменений в браузер клиента. Этот параметр существует и имеет значение только тогда, когда HTML перенаправления уже доступен. Для не-3DS этого никогда не происходит. Для 3DS HTML имеет значение через некоторое короткое время после начала обработки.
redirect-to	Для авторизации 3DS Торговец может перенаправить плательщика на URL, указанный в данном параметре, вместо отображения страницы, указанной в параметре html. Параметр redirect-to возвращается только в том случае, если возвращается параметр html. Для перенаправления Торговец должен использовать метод HTTP GET. Данный параметр должен использоваться для работы с 3DS 2.0.
serial-number	Уникальный номер, присваиваемый сервером gate.sbctech.ru конкретному запросу от присоединяющейся стороны.
last-four-digits	Последние четыре цифры номера банковской карты Плательщика.
dest-last-four-digits	Последние четыре цифры номера кредитной карты клиента. Относится только к транзакциям перевода.
bin	BIN банка или номер банковской карты плательщика.
card-type	Тип банковской карты Плательщика (VISA, MASTERCARD и т.д.).
gate-partial-reversal	Шлюз обработки поддерживает частичный возврат (включено или выключено).
gate-partial-capture	Шлюз обработки поддерживает частичное списание (включено или выключено).
transaction-type	Тип тпанзакции (продажа, возврат, списание, преавторизация).
processor-rrn	Регистрационный номер банка-получателя.
processor-tx-id	Идентификатор транзакции эквайера.
receipt-id	Электронная ссылка на квитанцию https://gate.sbctech.ru/paynet/view-receipt/ENDPOINTID/receipt-id/.
name	Имя плательщика
card-ref-id	Ссылочный идентификатор, используемый в последующих повторяющихся платежах. Актуально только в том случае, если card-ref-id был создан для первоначальной транзакции.
cardholder-name	Имя владельца карты.
card-exp-month	Месяц истечения срока действия банковской карты.
card-exp-year	Год истечения срока действия банковской карты.
card-hash-id	Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество.
card-country-alpha-three-code	Трехбуквенный код страны эмитента карты отправителя. Подробности см. в Коды стран и штатов.
destination-card-country-alpha-three-code	Трехбуквенный код страны эмитента карты получателя. Подробности см. в Коды стран и штатов.
dest-bin	Банковский BIN кредитной карты клиента.
dest-card-type	Тип кредитной карты клиента (VISA, MASTERCARD и т.д.).
dest-bank-name	Наименование банка по BIN карты клиента.
destination-hash-id	Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество. Актуально только для транзакций переводов.
destination-card-hash-id	Уникальный идентификатор карты для использования в программах лояльности или проверках на мошенничество.
first-name	Имя плательщика.
last-name	Фамилия плательщика.
email	Электронная почта плательщика.
country *	Страна плательщика (двухбуквенный код страны). Список допустимых кодов стран см. в Коды стран и штатов.
state *	Штат плательщика. Список допустимых кодов штатов см. в Коды стран и штатов. Обязательно для США, Канады и Австралии.
city *	Город плательщика.
zip_code *	Почтовый индекс плательщика.
address1 *	Адрес Плательщика 1.
purpose	Место назначения платежа. Это полезно для продавцов, которые позволяют своим плательщикам пополнять свои счета с помощью банковских карт (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: +7123456789; gamer0001@ereality.com и т. д. Данное значение может использоваться системой мониторинга мошенничества.
bank-name	Наименование банка по BIN карты плательщика.
terminal-id	Идентификатор терминала эквайера, который будет указан в чеке.
paynet-processing-date	Дата обработки транзакции эквайером.
approval-code	Код одобрения банка.
order-stage	Текущая стадия обработки транзакции. Подробности см. в Стадии транзакции.
total-reversal-amount	Сумма последнего обработанного возврата. Актуально только для транзакций возврата.
reversal-amount	Сумма последнего обработанного возврата. Актуально только для транзакций возврата.
auth-response-code	Код ответа, используемый в протоколе Iso8583. Возвращается только в определенных случаях.
acquirer-processing-date	Дата обработки транзакции эквайером.
processor-auth-credit-code	Код одобрения кредита. Возвращается только в определенных случаях.
processor-credit-rrn	Номер ссылки извлечения для кредитной транзакции.
processor-credit-arn	Ссылочный номер карты-эквайера для кредитной транзакции.
processor-debit-arn	Ссылочный номер карты-эквайера для дебитной транзакции.
loyalty-balance	Текущий баланс бонусов программы лояльности для текущей операции. : ex:если доступно.
loyalty-message	Сообщение от программы лояльности. если доступно.
loyalty-bonus	Бонусная стоимость программы лояльности для текущей операции если доступно.
loyalty-program	Название программы лояльности для текущей операции если доступно.
Описание параметра	Банковский идентификатор получателя платежа.
original-gate-descriptor	Дескриптор, который устанавливается на уровне шлюза в системе.
error-message	Если статус declined, error, filtered этот параметр содержит причину отказа.
error-code	The error code is case status in declined, error, filtered.
by-request-sn	Серийный номер, назначенный конкретному запросу gate.sbctech.ru. Если это поле существует в запросе статуса, ответ статуса возвращается для этого конкретного запроса.
verified-3d-status	Подробную информацию см. Список статусов 3D Secure.
verified-rsc-status	Возвращается, если была выполнена проверка случайной суммы. См. Alternative cardholder authentication
eci	Индикатор электронной коммерции (Visa).
ips-src-payment-product-code	Код карты, установленный международной финансовой службой (Visa/Mastercard).
ips-src-payment-product-name	Расшифрованный код для карты, установленный международной финансовой службой (Visa/Mastercard).
ips-src-payment-type-code	Код типа карты, установленный международной финансовой службой (Visa/Mastercard).
ips-src-payment-type-name	Расшифрованный код типа карты, установленный международной финансовой службой (Visa/Mastercard).
merchantdata	Если параметр merchant_data и его значение указаны в первоначальном запросе, они будут включены в ответ о статусе.
initial-amount	Сумма, установленная при инициировании транзакции, без каких-либо сборов или комиссий. Это значение не может измениться в ходе транзакции.
seller-commission	Общая комиссия за обработанную транзакцию. Это необязательный параметр. Пожалуйста, свяжитесь с вашим менеджером в SBC, если вы хотите его получить.
acquirer-commission	Комиссия эквайера за обработанную транзакцию. Это необязательный параметр. Обратитесь к своему менеджеру в SBC, если хотите его получить.
motivational-message	Это необязательное сообщение, которое содержит расширенную информацию о причине отклонения транзакции.
transaction-date	Дата присвоения окончательного статуса транзакции.
orig-amount	Содержит исходную сумму запроса, если она была преобразована на вспомогательном терминале в интеграции с параллельной формой. Актуально только для транзакций Payment Cashier.
orig-currency	Содержит исходную валюту запроса, если она была преобразована на вспомогательном терминале в интеграции с параллельной формой. Актуально только для транзакций Payment Cashier.

Параметры ответа статуса QR-кода:

Параметры ответа на запрос статуса CReqForm	Описание параметра
qr-code	QR-код в формате base64.
qr-code-payload-type	Тип QR-кода = SBP
qr-code-payload-value	Ссылка на QR-код =https://qr.nspk.ru/BS***** (только для интеграции H2H).

Параметры ответа на запрос статуса PaReqForm

Название	Описание параметра
tds-pareq-form-pareq	Данные ACS 3DS PaReq, полученные Присоединяющейся Стороной.
tds-pareq-form-acs-url	ACS URL для перенаправления Плательщика в рамках сценария аутентификации 3DS 1.0.2.

Параметры ответа на запрос статуса CReqForm

Название	Описание параметра
tds-creq-form-creq	Сообщение CReq инициирует взаимодействие держателя карты в полной проверке 3DS (Challenge) и используется для передачи аутентификационных данных. Формируется сервером 3DS торговцем через браузер держателя карты в адрес ACS URL.
tds-creq-form-acs-url	ACS URL для перенаправления Плательщика для полной проверки 3DS (Challenge).

Параметры ответа на запрос статуса MethodUrlFrame

Название	Описание параметра
tds-method-url-frame-3ds-server-trans-id	Универсально уникальный идентификатор транзакции, присвоенный сервером 3DS для идентификации одной транзакции.
tds-method-url-frame-3ds-method-url	URL 3DS Метода используется в форме iframe, передающейся от торговца к Плательщику.

Правила создания HTML формы.

threeDSMethodData (threeDSMethodNotificationURL + threeDSServerTransID).

Пример запроса

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

Пример успешного ответа

type=status-response
&serial-number=00000000-0000-0000-0000-0000037704d3
&merchant-order-id=902B4FF5
&paynet-order-id=6863082
&status=processing
&amount=10.42
&currency=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

Пример неуспешного ответа

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

Коллекция Postman

Конструктор запросов

endpointid or groupid	input ENDPOINTID or ENDPOINTGROUPID
login	input Login
client_orderid	input Invoice Number
orderid
merchant_control	input Control Key
by-request-sn

String to sign

Signature