Menu
The following examples are an overview on how to send recurring data.
The code shown is intended to give you a start point on how to implement recurring information in our services.
Pay attention: recurring series is limited in time. The maximum duration is 10 years.
Each recurring field has the following format:
{number of charges}{gap unit}{gap length}A{amount}
| Recurring Field Part | Description | Possible Values |
|---|---|---|
| {number of charges} | A number of charges in this stage of the recurring series | A positive integer number between 1 and 99 |
| {gap unit} | A unit to specify a gap between the dates of subsequent charges | D (day), W (week), M (month), Q (quarter), Y (year) |
| {gap length} | A number of gap units | 1 or more |
| A{amount} | Amount to charge every time (optional) with decimal point (if needed) | Use only if the amount to charge at this stage is different from the initial transaction amount. If the amount is omitted, letter A must be omitted, too. |
Here are some useful samples of recurring series (having a transaction amount £10):
Recurring1=12M1
Annual subscription with monthly charges, £10 each charge
Total amount is £120 for a year
Recurring1=4Q1
Annual subscription with quarterly charges, £10 each charge
Total amount is £40 for a year
Recurring1=1D5&Recurring2=12M1A30
5 days trial, then annual subscription with monthly charges, £30 each charge
Total amount is £370 for a year and five days
Recurring1=1D5&Recurring2=1D25A20&Recurring3=11M1A30
5 days trial, then a “remainder” charge (£20 for 25 days), then 11 months subscription with monthly charges, £30 each payment
Total amount is £360 for a year
Recurring1=3M1&Recurring2=3M1A20&Recurring3=6M1A30
Annual subscription: first three months for £10 a month, then three months for £20 a month, then 6 months for £30 a month
Total amount is £270 for a year
Recurring1=1M1&Recurring2=2M1A10&Recurring3=3M1A20&Recurring4=6M1A30&RecurringTransType=0
Annual subscription: first month for free, then two months for £10 a month, then three months for £20 a month, then 6 months for £30 a month Total amount is £260 for a year.
Important for this sample
– TransType must be 1, this ensures first month for free.
– Amount should be 1, in order to affect the payment ability of the credit card as less as possible.
Using this interface you can:
| Field | Required | Description |
|---|---|---|
| MerchantNumber | Yes | Your merchant number – 5722306 |
| SeriesID | Yes1 | ID number of the recurring series. This field is required only if TransID is omitted. |
| TransID | Yes1 | ID number of the initial transaction that started the recurring series. This field is required only if SeriesID is omitted. |
| Action | Yes | Action to take on the series. Accepts one of the following values: SUSPEND – Suspend the specified series, if active RESUME – Resume the specified series, if suspended DELETE – Delete the specified series (this cannot be undone!) MODIFY – Drop all the future charges and create new charges based on the Recurring fields |
| Uncharged | No | When resuming the series (Action=RESUME), action to take on the past charges which are still unprocessed. Accepts one of the following values: CANCEL – Cancel all past charges which are still unprocessed. REINSTATE – Reinstate all past charges which are still unprocessed (also charges that were manually cancelled in the past). Empty (or omitted) – No changes are made to charges’ state. |
| Signature | No | Signature for verifying the authenticity of the request parameters. Field values to use: MerchantNumber + SeriesID + TransID + Action + PersonalHashKey Refer to for detailed explanation. |
When the action is MODIFY, all the future charges in the specified recurring series are deleted. You can specify a date to start new charges’ schedule. If omitted, the first of the new charges will be scheduled for today. If the first of the new charges is scheduled for today, it will be processed immediately!
| Field | Length | Description | Details |
|---|---|---|---|
| StartDD | 2 | Day | Day to start the future charges. Between 1 and 31, depending on month specified in StartMM. |
| StartMM | 2 | Month | Month to start the future charges. Between 1 and 12. |
| StartYYYY | 4 | Year | Year to start the future charges. Cannot be less than the current year. |
When the action is MODIFY, new payment schedule must be set. See for the recurring string structure and examples. Pay attention: recurring series is limited in time. The maximum duration is 10 years.
| Field | Description | MaxLength | Required 2 |
|---|---|---|---|
| Recurring1 | Parameter for first stage in the recurring series | 12 | Yes |
| Recurring2 | Parameter for second stage in the recurring series | 12 | No |
| Recurring3 | Parameter for third stage in the recurring series | 12 | No |
| Recurring4 | Parameter for fourth stage in the recurring series | 12 | No |
| Recurring5 | Parameter for fifth stage in the recurring series | 12 | No |
| Recurring6 | Parameter for sixth stage in the recurring series | 12 | No |
(1) Either SeriesID or TransID must be provided
(2) When the action is MODIFY
After the recurring series management request is received and processed, the Gr8Pay system returns a reply code listed below. These reply codes apply ONLY to management of recurring transactions and not regular transactions.
| Field | Description |
|---|---|
| Reply | Two digits reply code (possible codes are listed below). |
| Description | The textual representation of the reply code (from the list below) |
| Details | Additional information, that may be useful for debugging purposes. Usually contains a list of fields with invalid values. |
REPLY=00&DESCRIPTION=SUCCESS
REPLY=09&DESCRIPTION=INVALID RECURRING STRING&DETAILS=Recurring2 5N1A7.01
00 = SUCCESS
01 = MISSING ACTION
02 = INVALID ACTION
03 = MISSING MERCHANT NUMBER
04 = SERIES ID CONFLICTS WITH TRANSACTION ID
05 = MISSING SERIES ID OR TRANSACTION ID
06 = MERCHANT NOT FOUND OR NOT AUTHORIZED
07 = SERIES NOT FOUND FOR THE MERCHANT
08 = MISSING RECURRING1
09 = INVALID RECURRING STRING
10 = INVALID START DATE
11 = START DATE IS IN THE PAST
12 = SERIES BLOCKED
13 = INVALID UNCHARGED
14 = INVALID SIGNATURE
| Field | Required | Description |
|---|---|---|
| CompanyNum | Yes | Your merchant number – 5722306 |
| TransID | Yes | ID number of transaction |
| RequestType | No | For a non-pending transaction send “1” |
| https://process.highisk.com/member/getStatus.asp?CompanyNum=XXXXXXX&TransID=XXXX | ||
| Field | Description |
|---|---|
| Reply | Reply code (see list of possible reply codes of Silent Post) |
| ReplyDesc | Reply description |
| TransID | ID number of transaction |
Reply=XXX&ReplyDesc=Some Reply Description&TransID=XXXX
Service to request the response for a specific order id as configured on the merchant CRM system – Since there are cases where the Merchant might be using the same Order ID for multiple transactions, some approved some declined the service will return a JSON response holding all the relevant transactions found with that Order ID for that Merchant.
| Field | Required | Description |
|---|---|---|
| CompanyNum | Yes | Your merchant number – 5722306 |
| Order | Yes | ID number of transaction |
| Signature | Yes | Signature creation algorithm is: base64(Hash(“SHA256”,CompanyNum + Order + MerchantHashKey)) signature output example: ZaezsN+9xHWkLorQgtNW5M+fB6/lVP4SgtlUDwgBl+0= |
| https://process.highisk.com/member/getStatus.asp?Order=XXXXXXX&CompanyNum=XXXXXXX&signature=ZaezsN+9xHWkLorQgtNW5M+fB6/lVP4SgtlUDwgBl+0= | ||
| Field | Description |
|---|---|
| Reply | Reply code (see list of possible reply codes of Silent Post) |
| ReplyDesc | Reply description |
| TransID | ID number of transaction |
| trans_date | Date and time of the transaction |
| merchantID | Company Number |
| trans_amount | Transaction amount |
| trans_currency | Transaction currency |
| trans_type | Transaction type: 0 = Debit Transaction 1 = Authorization only 2 = Capture 3 = Charge stored credit card (pass the stored card ID in CcStorageID field) |
| trans_installments | The number of installments for the transaction. |
| client_fullName | Card holder full name |
| client_email | Card holder email |
| client_phoneNum | Card holder phone number |
Response example in JSON format:
{ “error”:”0″, “message”:”SUCCESS”, “data”:[
{ “replyCode”:”004″, “replyDesc”:”Missing Customer Name Part”, “trans_id”:”19717″, “trans_date”:”28/01/2019 16:05:21″, “merchantID”:”XXXXXXX”, “trans_amount”:”1.23″, “trans_currency”:”USD”, “trans_type”:”0″, “trans_installments”:”1″, “client_fullName”:”test best”, “client_email”:”test@coriunder.com”, “client_phoneNum”:”1212121212″ }
,
{ “replyCode”:”546″, “replyDesc”:”Previous transaction with this card is still in process, please try again after response is sent”, “trans_id”:”20″, “trans_date”:”21/08/2017 15:52:57″, “merchantID”:”XXXXXXX”, “trans_amount”:”10″, “trans_currency”:”USD”, “trans_type”:”0″, “trans_installments”:”1″, “client_fullName”:”test best”, “client_email”:”test@coriunder.com”, “client_phoneNum”:”+0()1234567″ }
,
{ “replyCode”:”546″, “replyDesc”:”No details”, “trans_id”:”20″, “trans_date”:”21/08/2017 15:52:57″, “merchantID”:”XXXXXXX”, “trans_amount”:”10″, “trans_currency”:”USD”, “trans_type”:”0″, “trans_installments”:”1″, “client_fullName”:”bester tester”, “client_email”:”best@coriunder.com”, “client_phoneNum”:”+0()1234567″ }
,
{ “replyCode”:”000″, “replyDesc”:”SUCCESS”, “trans_id”:”4091″, “trans_date”:”24/12/2017 21:03:04″, “merchantID”:”XXXXXXX”, “trans_amount”:”1″, “trans_currency”:”EUR”, “trans_type”:”0″, “trans_installments”:”1″, “client_fullName”:”TEST HOST CARD”, “client_email”:”tester1@coriunder.com”, “client_phoneNum”:”” }
] }
Or failed response example:
{ “error”:”103″, “message”:”Failed On Authentication”, “data”:[] }