3.9. /api/v2/make-rebill-preauth

Introduction

Preauth recurring transactions are initiated through HTTPS POST request to the URLs and the parameters specified below. Use SHA-1 for authentication. See Statuses.

API URLs

Integration

Production

https://sandbox.goldenapple.com.cy/paynet/api/v2/make-rebill-preauth/ENDPOINTID

https://gate.goldenapple.com.cy/paynet/api/v2/make-rebill-preauth/ENDPOINTID

https://sandbox.goldenapple.com.cy/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID

https://gate.goldenapple.com.cy/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID

Request Parameters

Note

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

Parameter Name

Description

Value

login

Connecting Party’s login name.
Necessity: Required
Type: String
Length: 20

client_orderid

Connecting Party’s order identifier of the transaction.
Necessity: Required
Type: String
Length: 128

cardrefid

Card reference ID obtained at Card Registration Stage /api/v2/create-card-ref/.
Necessity: Required
Type: String
Length: 20

amount

Amount to be charged. 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.
Necessity: Required
Type: Numeric
Length: 10

currency

Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro.
Necessity: Required
Type: String
Length: 3

enumerate_amounts

This parameter may comprise multiple amounts, separated with ,. GoldenApple will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved.
Necessity: Optional
Type: String
Length: 128

recurrent_scenario

Type of the rebill transaction. Possible values: REGULAR or IRREGULAR. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers.
Necessity: Optional
Type: String
Length: 50

recurrent_initiator

Initiator of the rebill transaction. Possible values: CARDHOLDER or MERCHANT. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers.
Necessity: Optional
Type: String
Length: 50

cvv2

Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2.
Necessity: Optional
Type: Numeric
Length: 3-4

ipaddress

Customer’s IP address, included for fraud screening purposes.
Necessity: Required
Type: String
Length: 45

comment

A short comment.
Necessity: Optional
Type: String
Length: 50

order_desc

Order description.
Necessity: Required
Type: String
Length: 64k

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: cardrefid
4. Request parameter: amount in minor units (if sent).
5. request parameter: currency
6. merchant_control (Control key assigned to Connecting Party account in the GoldenApple gateway system).
Necessity: Required
Type: String
Length: 40

purpose

Destination to where the payment goes. It is useful for the Connecting Party who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system.
Necessity: Optional
Type: String
Length: 128

redirect_url

URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. This parameter should not be used to retrieve results from GoldenApple gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. Parameter is required for 3DS flow and optional for non-3DS. https://doc.goldenapple.com.cy/ can be used for testing purposes if it’s unknown whether 3DS is used or not. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
Necessity: Optional
Type: String
Length: 1024

redirect_success_url

URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. This parameter should not be used to retrieve results from GoldenApple gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. Parameter is required for 3DS flow and optional for non-3DS. https://doc.goldenapple.com.cy/ can be used for testing purposes if it’s unknown whether 3DS is used or not. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
Necessity: Optional
Type: String
Length: 1024

redirect_fail_url

URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. This parameter should not be used to retrieve results from GoldenApple gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to the backend server_callback_url must be used instead. Parameter is required for 3DS flow and optional for non-3DS. https://doc.goldenapple.com.cy/ can be used for testing purposes if it’s unknown whether 3DS is used or not. Use either redirect_url or combination of redirect_success_url and redirect_fail_url, not both.
Necessity: Optional
Type: String
Length: 1024

server_callback_url

URL the transaction result will be sent to. Connecting Party may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Connecting Party’s database. See more details at Connecting Party Callbacks.
Necessity: Optional
Type: String
Length: 1024

merchant_data

Any additional information for this transaction which may be useful in Connecting Party’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Connecting Party Callback.
Necessity: Optional
Type: String
Length: 64

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.

Sale Response Parameters

Description

type
The type of response. May be async-response, validation-error, error etc.
If type equals validation-error or error, error-message and error-code parameters contain error details.

serial-number

Unique number assigned by GoldenApple server to particular request from the Connecting Party.

merchant-order-id

Connecting Party’s order id.

paynet-order-id

Order id assigned to the order by GoldenApple.

end-point-id

ID of the used End Point.

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/make-rebill-preauth/46750 HTTP/1.1
Host: https://sandbox.goldenapple.com.cy
User-Agent: curl/7.85.0
Accept: */
Content-Length: 229
Content-Type: application/x-www-form-urlencoded
Connection: close

&login=login
&client_orderid=902B4FF5
&cardrefid=1461665
&amount=5.00
&currency=USD
&cvv2=321
&ipaddress=34.129.65.12
&comment=Information abount Rebill
&order_desc=Rebill order description
&control=a37f4972233b4a5dbfb4dcaae149ce7feed01ef9

Success Response Example

HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:10:44 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: 144

&type=async-response
&serial-number=00000000-0000-0000-0000-000002e0d498
&merchant-order-id=902B4FF5
&paynet-order-id=6937030
&end-point-id=46750

Fail Response Example

HTTP/1.1 200
Server: server
Date: Thu, 02 Feb 2023 13:18:50 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=validation-error
&serial-number=00000000-0000-0000-0000-000002e0d614
&merchant-order-id=902B4FF5
&error-message=End+point+with+id+99999+not+found
&error-code=3

Postman Collection

Request Builder

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

login
client_orderid

make it or use internal invoice ID

cardrefid
amount
currency
enumerate_amounts
recurrent_scenario
recurrent_initiator
cvv2
ipaddress
comment
order_desc
merchant_control

input Control Key

String to sign
Signature