3.3. /api/v2/create-card-ref
Introduction
Card reference ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use SHA-1 for authentication.
API URLs
Integration |
Production |
|---|---|
https://sandbox.goldenapple.com.cy/paynet/api/v2/create-card-ref/ENDPOINTID |
https://gate.goldenapple.com.cy/paynet/api/v2/create-card-ref/ENDPOINTID |
https://sandbox.goldenapple.com.cy/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID |
https://gate.goldenapple.com.cy/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID |
Request Parameters
Note
Get Card Ref Request Parameters |
Description |
|---|---|
login |
Connecting Party’s login name.
|
client_orderid |
Connecting Party’s order identifier of the transaction.
|
orderid |
Transaction order identifier assigned by Payment Gateway.
|
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. merchant_control (Control key assigned to Connecting Party account in the GoldenApple gateway system).
|
Connecting Party has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurring payments. To authorize the credit card the information about it must be sufficient and an initial payment must be in final status.
The returned Recurring Payment ID and/or Card Reference ID is a token that refers to cardholder data stored on Payment Gateway side. See the required API command to find which type of token is supported in request parameters. This ID has the following usage: 1. In direct API commands it can be passed instead of cardholder data to initiate new transaction. 2. In form API commands it can be passed to prefill the payment form with previously saved cardholder data.
Response Parameters
Note
Registration 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. |
card-ref-id |
Card reference ID to used in subsequent recurring payments. |
unq-card-ref-id |
Unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. |
status |
See Status List for details.
|
error-message |
If status is declined or error this parameter contains the reason for decline. |
error-code |
The error code is case of declined or error status. |
Request Example
POST /paynet/api/v2/create-card-ref/46750 HTTP/1.1
Host: https://sandbox.goldenapple.com.cy
User-Agent: curl/7.85.0
Accept: */*
Content-Length: 100
Content-Type: application/x-www-form-urlencoded
Connection: close
login=login
&client_orderid=902B4FF5
&orderid=6937242
&control=717349cab3fcab2c13c93ff5770ae07a7b8e0727
Success Response Example
HTTP/1.1 200
Server: server
Date: Tue, 07 Feb 2023 08:46:24 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=create-card-ref-response
&serial-number=00000000-0000-0000-0000-000002e110a2
&card-ref-id=1461670
&unq-card-ref-id=2463777
&status=approved
Fail Response Example
HTTP/1.1 200
Server: server
Date: Tue, 07 Feb 2023 08:55:26 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: 123
type=validation-error
&serial-number=00000000-0000-0000-0000-000002e110ad
&error-message=INVALID_CONTROL_CODE
&error-code=2
Postman Collection
Request Builder
| String to sign |
|---|
| Signature |
|---|
|