3.13. /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

Note

The path in API URL should not be hardcoded, as it may be changed in future.

Integration	Production
https://sandbox.goldenapple.com.cy/paynet/api/v2/return/ENDPOINTID	https://gate.goldenapple.com.cy/paynet/api/v2/return/ENDPOINTID
https://sandbox.goldenapple.com.cy/paynet/api/v2/return/group/ENDPOINTGROUPID	https://gate.goldenapple.com.cy/paynet/api/v2/return/group/ENDPOINTGROUPID

Request Parameters

Note

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

Warning

The following characters must be escaped in the parameter values: & + “.

Parameter Name	Description	Value
login	Connecting Party login name.	`Necessity`: Mandatory `Type`: String `Length`: 20
orderid	Unique order identifier assigned by GoldenApple system.	`Necessity`: Mandatory `Type`: String `Length`: 20
client_orderid	Unique Connecting Party identifier.	`Necessity`: Mandatory `Type`: String `Length`: 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 GoldenApple gateway system).	`Necessity`: Conditional `Type`: String `Length`: 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`: Mandatory `Type`: Numeric `Length`: 10
currency	Currency in which amount is specified. Provided in three-letter currency code format. Example: USD for US Dollar. Reference: Currency Codes.	`Necessity`: Mandatory `Type`: String `Length`: 50
comment	A brief description of reason.	`Necessity`: Mandatory `Type`: String `Length`: 50

Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.

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 GoldenApple.
merchant-order-id	Connecting Party order id.
serial-number	Unique number assigned by GoldenApple 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.goldenapple.com.cy
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

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

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