3.18. /api/v2/return

Введение

Транзакции Return можно инициировать только после получения транзакцией окончательного успешного статуса. См. Статусы. Для Preauth создаётся транзакция Cancel, для Capture и Sale — Reversal. Транзакции Return инициируются запросом HTTPS POST с использованием указанных ниже URL-адресов и параметров. Для аутентификации используйте SHA-1.

API URL

Примечание

Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

Интеграционная среда

Производственная среда

https://sandbox.sbctech.ru/paynet/api/v2/return/ENDPOINTID

https://gate.sbctech.ru/paynet/api/v2/return/ENDPOINTID

https://sandbox.sbctech.ru/paynet/api/v2/return/group/ENDPOINTGROUPID

https://gate.sbctech.ru/paynet/api/v2/return/group/ENDPOINTGROUPID

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

Примечание

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

Предупреждение

В значениях параметров необходимо экранировать следующие символы: & + «.

Название параметра

Описание

Значение

login

Логин Присоединяющейся Стороны в Платёжном Шлюзе.
Необходимость: Обязательно
Тип: String
Длина: 20

orderid

Уникальный идентификационный номер транзакции, присвоенный системой SBC.
Необходимость: Обязательно
Тип: String
Длина: 20

client_orderid

Уникальный идентификационный номер Присоединяющейся Стороны.
Необходимость: Обязательно
Тип: String
Длина: 128

control
Контрольная сумма, сгенерированная SHA-1. Строка для подписи представляет собой объединение следующих параметров:
1. Параметр запроса:login.
2. Параметр запроса:client_orderid.
3. Параметр запроса:orderid.
4. Параметр запроса: amount (в минимальных единицах).
5. Параметр запроса: currency.
6.:ex:merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся Cтороны в SBC).
Необходимость: Условно
Тип: String
Длина: 128

amount

Сумма должна быть указана в минимальных единицах с . разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек. Если данный параметр пропущен, будет произведен возврат всей суммы. Данный параметр имеет смысл для возвратов, но не отмены. Сумма не может быть больше изначальной суммы транзакции. Важно! Если указана сумма, необходимо также указать валюту!
Необходимость: Обязательно
Тип: Numeric
Длина: 10

currency

Валюта, в которой проводится операция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.
Необходимость: Обязательно
Тип: String
Длина: 50

comment

Краткое описание.
Необходимость: Обязательно
Тип: String
Длина: 50

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

Примечание

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

Название параметра

Описание

type

Тип ответа. Может принимать такие значения как: async-response, validation-error, error и т.д. Если тип ответа validation-error или error, параметры error-message и error-code будут содержать детали ошибки.

paynet-order-id

Идентификатор заказа, присвоенный SBC.

merchant-order-id

Идентификатор заказа Присоединяющейся Стороны.

serial-number

Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны.

end-point-id

Идентификатор терминала, используемый для транзакции.

error-message

Для транзакций в статусе error этот параметр будет содержать причину отклонения или сведения об ошибке.

error-code

Код ошибки для транзакций в статусе error.

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

POST /paynet/api/v2/return/39914 HTTP/1.1
Host: sandbox.sbctech.ru
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 162
Content-Type: application/x-www-form-urlencoded
Connection: close

login=TestMerchant
&client_orderid=Test
&orderid=6862958
&amount=5.00
&currency=RUB
&comment=Service not provided
&control=2dfdb99c4eff5b31c978ecb8bc4b4d094e24c1d4

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

HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 07:50:08 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: 141

type=async-response
&serial-number=00000000-0000-0000-0000-000002ddad4a
&merchant-order-id=Test
&paynet-order-id=6862958
&end-point-id=39914

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

HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 10:45:32 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: 153

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddad5c
&error-message=Reversal+currency+does+not+match+project+currency
&error-code=16

Коллекция Postman

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

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

login
client_orderid

input Invoice Number

orderid
amount
currency
merchant_control

input Control Key

comment

String to sign
Signature