3.1. /api/v2/auth-cash

Introduction

Auth-cash is initiated through HTTPS POST request by using 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/auth-cash/ENDPOINTID	https://gate.goldenapple.com.cy/paynet/api/v2/auth-cash/ENDPOINTID

Request Parameters

Note

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

Parameter Name	Description	Value
client_orderid	Unique order identifier assigned by Connecting Party.	`Necessity`: Required `Type`: String `Length`: 128
order_desc	Brief order description.	`Necessity`: Required `Type`: String `Length`: 64k
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 (See: Currency codes). Sample values are: USD for US Dollar EUR for European Euro.	`Necessity`: Required `Type`: String `Length`: 3
address1	Payer’s address line 1.	`Necessity`: Required `Type`: String `Length`: 50
city	Payer’s city.	`Necessity`: Required `Type`: String `Length`: 50
zip_code	Payer’s ZIP code.	`Necessity`: Required `Type`: String `Length`: 10
country	Payer’s country. Please see Country codes for a list of valid country codes.	`Necessity`: Required `Type`: String `Length`: 2
phone	Payer’s full international phone number, including country code.	`Necessity`: Required `Type`: String `Length`: 15
email	Payer’s e-mail address.	`Necessity`: Required `Type`: String `Length`: 50
ipaddress	Payer’s IP address, included for fraud screening purposes.	`Necessity`: Required `Type`: String `Length`: 45
control	Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters: 1. <ENDPOINTID \| ENDPOINTGROUPID> (See: Request URL). 2. Request parameter: client_orderid. 3. Request parameter: amount (in minor units). 4. Request parameter: email. 5. merchant_control (Control key assigned to Connecting Party account in the GoldenApple gateway system).	`Necessity`: Required `Type`: String `Length`: 40
first_name	Payer’s first name.	`Necessity`: Required `Type`: String `Length`: 50
last_name	Payer’s last name.	`Necessity`: Required `Type`: String `Length`: 50
state	Payer’s state. (two-letter state code). Please see Mandatory State codes for a list of valid state codes. Required for USA, Canada and Australia.	`Necessity`: Conditional `Type`: String `Length`: 2
redirect_url	URL, where the Payer is redirected to upon completion of the transaction. Please note that redirection is performed in any case, no matter whether transaction is approved, declined or in any other final status. Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass https://doc.goldenapple.com.cy/ if you have no need to return payer anywhere. 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, where the Payer is redirected to when transaction status is approved (See status list). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Otherwise put https://doc.goldenapple.com.cy/ if there is no need to redirect Payer anywhere. Use either combination of redirect_success_url and redirect_fail_url or redirect_url, not both.	`Necessity`: Optional `Type`: String `Length`: 1024
redirect_fail_url	URL, where the Payer is redirected to when transaction status is not approved (See status list). Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction. Instead Connecting Party can utilize server_callback_url or status API command. Pass https://doc2.codetime.net if there is no need to redirect Payer anywhere. Use either combination of redirect_fail_url and redirect_success_url or redirect_url, not both.	`Necessity`: Optional `Type`: String `Length`: 1024
ssn	Last four digits of the Payer’s social security number.	`Necessity`: Optional `Type`: Numeric `Length`: 32
birthday	Payer’s date of birth, in the format YYYYMMDD.	`Necessity`: Optional `Type`: Numeric `Length`: 8
cell_phone	Payer’s full international cell phone number, including country code.	`Necessity`: Optional `Type`: String `Length`: 15
site_url	The URL of the E-commerce entity, where the payment is originated from.	`Necessity`: Optional `Type`: String `Length`: 128
server_callback_url	URL, where the transaction status is sent to. Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to server_callback_url refer to Connecting Party callback parameters.	`Necessity`: Optional `Type`: String `Length`: 1024
preferred_language	Payer’s two-letter language code for multi-language invoices.	`Necessity`: Optional `Type`: String `Length`: 2

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.

Response Parameters	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	Endpoint id used for the 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/auth-cash/46760 HTTP/1.1
Host: sandbox.goldenapple.com.cy
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 592
Content-Type: application/x-www-form-urlencoded
Connection: close

client_orderid=inv3982750
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=55
&email=[email protected]
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://doc2.codetime.net
&purpose=user_account1
&redirect_url=http://sandbox.goldenapple.com.cy/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=ce2dcc2b307c123242b9867cb0ce15617b8ee7f9
&preferred_language=en

Success Response Example

HTTP/1.1 200
Server: server
Date: Wed, 14 Jun 2023 08:43:52 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: 146

type=async-response
&serial-number=00000000-0000-0000-0000-000002eb1adf
&merchant-order-id=inv3982750
&paynet-order-id=7174243
&end-point-id=46760

Fail Response Example

HTTP/1.1 200
Server: server
Date: Wed, 14 Jun 2023 08:43:52 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: 146

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb0d4
&error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
&error-code=16

Postman Collection

Request Builder

endpointid	input ENDPOINTID
client_orderid	make it or use internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
ipaddress
site_url
purpose
merchant_control	input Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
preferred_language

String to sign

Signature