Recurring Billing


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 PartDescriptionPossible Values
{number of charges}A number of charges in this stage of the recurring seriesA positive integer number between 1 and 99
{gap unit}A unit to specify a gap between the dates of subsequent chargesD (day), W (week), M (month), Q (quarter), Y (year)
{gap length}A number of gap units1 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.

Samples


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.

Submitting Data


https://process.gr8pay.com/member/recurring_modify.aspx


Using this interface you can:

  • suspend active series
  • resume suspended series
  • modify dates and/or amounts of future charges
  • delete series

The request must be sent from your server to the following URL:https://process.gr8pay.com/member/recurring_modify.aspx

Sample Requests

https://process.gr8pay.com/member/recurring_modify.aspx?MerchantNumber=5722306&SeriesID=123&Action=SUSPEND
https://process.gr8pay.com/member/recurring_modify.aspx?MerchantNumber=5722306&TransID=987654&Action=RESUME
https://process.gr8pay.com/member/recurring_modify.aspx?MerchantNumber=5722306&SeriesID=123&Action=MODIFY&StartDD=15&StartMM=07&StartYYYY=2009&Recurring1=1W2A5.99&Recurring2=11M1A9.99

Request Fields

FieldRequiredDescription
MerchantNumberYesYour merchant number - 5722306
SeriesIDYes1ID number of the recurring series. This field is required only if TransID is omitted.
TransIDYes1ID number of the initial transaction that started the recurring series. This field is required only if SeriesID is omitted.
ActionYesAction 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
UnchargedNoWhen 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.
SignatureNoSignature for verifying the authenticity of the request parameters. Field values to use: MerchantNumber + SeriesID + TransID + Action + PersonalHashKey Refer to for detailed explanation.

Optional Fields – Start Date

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!

FieldLengthDescriptionDetails
StartDD2DayDay to start the future charges. Between 1 and 31, depending on month specified in StartMM.
StartMM2MonthMonth to start the future charges. Between 1 and 12.
StartYYYY4YearYear to start the future charges. Cannot be less than the current year.

Optional Fields – Recurring Strings

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.

FieldDescriptionMaxLengthRequired 2
Recurring1Parameter for first stage in the recurring series12Yes
Recurring2Parameter for second stage in the recurring series12No
Recurring3Parameter for third stage in the recurring series12No
Recurring4Parameter for fourth stage in the recurring series12No
Recurring5Parameter for fifth stage in the recurring series12No
Recurring6Parameter for sixth stage in the recurring series12No

(1) Either SeriesID or TransID must be provided
(2) When the action is MODIFY

Manage Recurring Series – Checking Reply


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.

Example of How and What is Replied

FieldDescription
ReplyTwo digits reply code (possible codes are listed below).
DescriptionThe textual representation of the reply code (from the list below)
DetailsAdditional information, that may be useful for debugging purposes.
Usually contains a list of fields with invalid values.

Reply in case of success:

REPLY=00&DESCRIPTION=SUCCESS

Reply in case of failure:

REPLY=09&DESCRIPTION=INVALID RECURRING STRING&DETAILS=Recurring2 5N1A7.01

Reply Codes

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

Transaction Status


https://process.gr8pay.com/member/getStatus.aspx


Request Fields

FieldRequiredDescription
CompanyNumYesYour merchant number - 5722306
TransIDYesID number of transaction
RequestTypeNoFor a non-pending transaction send "1"
https://process.gr8pay.com/member/getStatus.asp?CompanyNum=XXXXXXX&TransID=XXXX

Response Fields

FieldDescription
ReplyReply code (see list of possible reply codes of Silent Post)
ReplyDescReply description
TransIDID number of transaction

Response Format

Reply=XXX&ReplyDesc=Some Reply Description&TransID=XXXX

Transaction Status by Order


https://process.gr8pay.com/member/getStatus.aspx


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.

Request Fields

FieldRequiredDescription
CompanyNumYesYour merchant number - 5722306
OrderYesID number of transaction
SignatureYesSignature creation algorithm is: base64(Hash("SHA256",CompanyNum + Order + MerchantHashKey))
signature output example: ZaezsN+9xHWkLorQgtNW5M+fB6/lVP4SgtlUDwgBl+0=
https://process.gr8pay.com/member/getStatus.asp?Order=XXXXXXX&CompanyNum=XXXXXXX&signature=ZaezsN+9xHWkLorQgtNW5M+fB6/lVP4SgtlUDwgBl+0=

Response Fields

FieldDescription
ReplyReply code (see list of possible reply codes of Silent Post)
ReplyDescReply description
TransIDID number of transaction
trans_dateDate and time of the transaction
merchantIDCompany Number
trans_amountTransaction amount
trans_currencyTransaction currency
trans_typeTransaction type: 0 = Debit Transaction 1 = Authorization only 2 = Capture 3 = Charge stored credit card (pass the stored card ID in CcStorageID field)
trans_installmentsThe number of installments for the transaction.
client_fullNameCard holder full name
client_emailCard holder email
client_phoneNumCard holder phone number

Response Format

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”:[] }