3.19. /api/v2/return
Introduction
Return transactions may only be initiated when the transaction have final successful status. See Statuses. For Preauth it makes Cancel transaction, for Capture and Sale – Reversal. Return transactions are initiated through HTTPS POST request by using URLs and the parameters specified below. Use SHA-1 for authentication.
API URLs
Integration |
Production |
---|---|
https://sandbox.payneteasy.eu/paynet/api/v2/return/ENDPOINTID |
https://gate.payneteasy.eu/paynet/api/v2/return/ENDPOINTID |
https://sandbox.payneteasy.eu/paynet/api/v2/return/group/ENDPOINTGROUPID |
https://gate.payneteasy.eu/paynet/api/v2/return/group/ENDPOINTGROUPID |
Request Parameters
Note
Warning
The following characters must be escaped in the parameter values: & + “.
Parameter Name |
Description |
Value |
---|---|---|
login |
Connecting Party login name. |
Necessity : MandatoryType : StringLength : 20 |
orderid |
Unique order identifier assigned by Payneteasy system. |
Necessity : MandatoryType : StringLength : 20 |
client_orderid |
Unique Connecting Party identifier. |
Necessity : MandatoryType : StringLength : 128 |
control |
Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. Request parameter: login.
2. Request parameter: client_orderid.
3. Request parameter: orderid.
4. Request parameter: amount (in minor units, if sent).
5. Request parameter: currency (if sent).
6. merchant_control (Control key assigned to Connecting Party account in the Payneteasy gateway system).
|
Necessity : ConditionalType : StringLength : 128 |
amount |
The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that Currency MUST be specified if amount is specified! |
Necessity : MandatoryType : NumericLength : 10 |
currency |
Currency in which amount is specified. Provided in three-letter currency code format. Example: USD for US Dollar. Reference: Currency Codes. |
Necessity : MandatoryType : StringLength : 50 |
comment |
A brief description of reason. |
Necessity : MandatoryType : StringLength : 50 |
Response Parameters
Note
Parameter Name |
Description |
---|---|
type |
The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
paynet-order-id |
Order id assigned to the order by Payneteasy. |
merchant-order-id |
Connecting Party order id. |
serial-number |
Unique number assigned by Payneteasy server to particular request from the Connecting Party. |
end-point-id |
Entry point used for processing this transaction. |
error-message |
If status is error this parameter contains the reason for decline or error details. |
error-code |
The error code is case of error status. |
Request Example
POST /paynet/api/v2/return/39914 HTTP/1.1
Host: sandbox.payneteasy.eu
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
¤cy=RUB
&comment=Service not provided
&control=2dfdb99c4eff5b31c978ecb8bc4b4d094e24c1d4
Success Response Example
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
Fail Response Example
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 Collection
Request Builder
String to sign |
---|
Signature |
---|
|