3.6. /api/v2/return

Введение

Возврат может быть проведён только для транзакций с успешным конечным статусом. См. Статусы транзакций. После успешного Возврата Преавторизированная Продажа принимает статус Отменённой транзакции, Продажа и Подтверждение - статус Возврата. Транзакции возврата инициируется через HTTPS POST запрос, используя URL и параметры, указанные ниже. Запрос подписывается SHA-1 для аутентификации.

API URL

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

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

https://sandbox.connpay.com/paynet/api/v2/return/ENDPOINTID

https://gate.connpay.com/paynet/api/v2/return/ENDPOINTID

https://sandbox.connpay.com/paynet/api/v2/return/group/ENDPOINTGROUPID

https://gate.connpay.com/paynet/api/v2/return/group/ENDPOINTGROUPID

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

Note

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

Warning

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

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

Описание

Значение

login

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

orderid

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

client_orderid

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

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

amount

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

currency

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

comment

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

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

Note

Ответ имеет заголовок 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

Номер заказа в системе ConnPay.

merchant-order-id

Номер заказа в системе Присоединяющейся Стороны.

serial-number

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

end-point-id

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

error-message

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

error-code

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

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

POST /paynet/api/v2/return/39914 HTTP/1.1
Host: sandbox.connpay.com
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