3.14. /api/v4/status

Введение

To make an order status request one have to send an HTTPS POST request to the URLs and the parameters specified below. Use RSA-SHA256 for authentication. See Статусы.

API URL

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

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

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.

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

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

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

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

Note

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

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

Параметры ответа на запрос статуса	Описание параметра
type	Тип ответа. Может быть status-response.
status	Для подпробностей см. Список статусов.
amount	Фактическая сумма транзакции. Данное значение может быть изменено в ходе транзакции.
currency	Валюта, в которой взимается транзакция (трехбуквенный код валюты). Примеры допустимых значений параметров: USD для доллара США EUR для евро.
paynet-order-id	Идентификатор заказа, присвоенный заказу gate.sbctech.ru.
merchant-order-id	Идентификатор заказа Присоединяющейся Стороны.
phone	Полный международный номер телефона плательщика, включая код страны.
html	HTML-код формы авторизации 3DS, закодированный в формате MIME application/x-www-form-urlencoded. Торговец должен декодировать этот параметр перед показом формы Плательщику. Система gate.sbctech.ru возвращает следующие параметры ответа, когда получает форму авторизации 3DS от Банка-эмитента. Он содержит HTML-код формы авторизации, который должен быть передан без каких-либо изменений в браузер клиента. Этот параметр существует и имеет значение только тогда, когда HTML перенаправления уже доступен. Для не-3DS этого никогда не происходит. Для 3DS HTML имеет значение через некоторое короткое время после начала обработки.
redirect-to	For 3DS authorization the merchant can redirect the Payer to URL provided in this parameter instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. Merchant should use GET HTTP method to redirect. This parameter must be used to work with 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 *	Payer’s state . Please see Коды стран и штатов for a list of valid state codes. Обязательно for USA, Canada and Australia.
city *	Город плательщика.
zip_code *	Почтовый индекс плательщика.
address1 *	Адрес Плательщика 1.
purpose	Место назначения платежа. Это полезно для продавцов, которые позволяют своим плательщикам пополнять свои счета с помощью банковских карт (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: +7123456789; gamer0001@ereality.com и т. д. Данное значение может использоваться системой мониторинга мошенничества.
bank-name	Наименование банка по BIN карты плательщика.
terminal-id	Идентификатор терминала эквайера, который будет указан в чеке.
paynet-processing-date	Дата обработки транзакции эквайером.
approval-code	Код одобрения банка.
order-stage	The current stage of the transaction processing. See Стадии транзакции for details.
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	Название программы лояльности для текущей операции если доступно.
descriptor	Банковский идентификатор получателя платежа.
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-кода:

Параметры ответа на запрос статуса	Описание параметра
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/v4/status/46750 HTTP/1.1
User-Agent: curl/7.88.1
Accept: */*
Authorization: OAuth oauth_consumer_key="Test_Fuad_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_Fuad_Merchant&order_id=7364742

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

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
&currency=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

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

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

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

Введите приватный ключ, содержащийся в PKCS#1. См. RSA-SHA256.

Order status form

URL
login	login should be used as Consumer Public for OAuth
client_orderid	input Invoice Number
orderid
by-request-sn

Normalized parameters string to sign, according to OAuth 1.0a rules

POST body parameters to submit

OAuth 1.0a headers to submit.

HEX Encoded Signature

^{* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.}

Base64 Encoded Signature

^{* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.}