Creating Subscriptions
This feature enables you to set up subscription payments using a hosted page.
- Sandbox URL:
Request
To create a new subscription based on an existing payment plan (stored subscription):
Filter:
| FIELD | REQUIRED | DESCRIPTION |
|---|---|---|
| TERMINALID | Y | string [ 1 .. 50 ] characters The terminal number assigned by . |
| MERCHANTREF | Y | string [ 1 .. 48 ] characters Unique reference assigned by the merchant to identify the subscription. |
| STOREDSUBSCRIPTIONREF | Y | string [ 1 .. 48 ] characters Reference of an existing payment plan (stored subscription). You can also create a payment plan while creating the subscription, check out the next section. |
| SECURECARDMERCHANTREF | Y | string [ 1 .. 200 ] characters Merchant reference of an existing Secure Token which will be used in the initial and all subsequent payments. When using this field, please do not include the CARDREFERENCE. |
| CARDREFERENCE | Y | string [ 12 .. 19 ] characters Token reference of an existing Secure Token. When using this field, please do not include the SECURECARDMERCHANTREF. |
| SUBSCRIPTIONRECURRINGAMOUNT | N | number <double> >= 0 Cost of each payment to be processed for the subscription. |
| SUBSCRIPTIONINITIALAMOUNT | N | number <double> >= 0 Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. |
| DATETIME | Y | string <date-time> DD-MM-YYYY:HH:MM:SS:SSS Date and time of the request. |
| STARTDATE | Y | string <date> dd-MM-yyyy Subscription start date. |
| ENDDATE | N | string <date> dd-MM-yyyy Subscription end date. If not provided, subscription will continue until manually canceled or length reached (if it is set). |
| HASH See notes: ND001 | Y | string <SHA-512> [ 1 .. 128 ] characters A HASH code formed by part of the request fields. |
To create a new subscription, and at the same time, create a new payment plan (stored subscription):
Filter:
| FIELD | REQUIRED | DESCRIPTION |
|---|---|---|
| TERMINALID | Y | string [ 1 .. 50 ] characters The terminal number assigned by . |
| MERCHANTREF | Y | string [ 1 .. 48 ] characters Unique reference assigned by the merchant to identify the subscription. |
| SECURECARDMERCHANTREF | Y | string [ 1 .. 200 ] characters Merchant reference of an existing Secure Token which will be used in the initial and all subsequent payments. When using this field, please do not include the CARDREFERENCE. |
| CARDREFERENCE | Y | string [ 12 .. 19 ] characters Token reference of an existing Secure Token. When using this field, please do not include the SECURECARDMERCHANTREF. |
| DATETIME | Y | string <date-time> DD-MM-YYYY:HH:MM:SS:SSS Date and time of the request. |
| STARTDATE | Y | string <date> dd-MM-yyyy Subscription start date. |
| ENDDATE | N | string <date> dd-MM-yyyy Subscription end date. If not provided, subscription will continue until manually canceled or length reached (if it is set). |
| HASH See notes: ND001 | Y | string <SHA-512> [ 1 .. 128 ] characters A HASH code formed by part of the request fields. |
| NEWSTOREDSUBSCRIPTIONREF | N | string [ 1 .. 48 ] characters Merchant Ref to be assigned for the payment plan (stored subscription) being created. |
| NAME | Y | string [ 5 .. 128 ] characters Display name for subscription. |
| DESCRIPTION | Y | string [ 0 .. 128 ] characters A brief description of the subscription. |
| PERIODTYPE | Y | string <enum> The frequency of which payments are collected. 2 - WEEKLY3 - FORTNIGHTLY4 - MONTHLY5 - QUARTERLY6 - YEARLY. |
| LENGTH | Y | number <integer> >= 0 Total number of billing cycles. Send a value of 0 to set the subscription's billing cycle to never expire (Unlimited). |
| RECURRINGAMOUNT | Y | number <double> >= 0 Cost of each payment (will be ignored if manual). |
| INITIALAMOUNT | Y | number <double> >= 0 Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Setup fails if setup payment declines. |
| TYPE | Y | string <enum> The type by which payments are collected. 1 - AUTOMATIC 2 - MANUAL 3 - AUTOMATIC (WITHOUT AMOUNTS). |
| ONUPDATE | Y | string <enum> 1 - CONTINUE 2 - UPDATE |
| ONDELETE | Y | string <enum> 1 - CONTINUE 2 - CANCEL |
| CURRENCY | N | string 3-char ISO 4217 code The currency of the payment plan. |
| OTHERFIELD | N | Any other fields sent in the request will be treated as metadata. They are not going to be stored, but they'll be echoed back to the Receipt URL. Note that this is subject to the max length of a HTTP GET request which we would conservatively recommend considering to be 2000 characters. |
Request notes
ND001 - Hash generation
See how to generate a hash string at Special Fields and Parameters. For this specific feature, you should use one of the following formats:
/** * If your request contains the {@code CARDREFERENCE} field */ TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:STARTDATE:SECRET
/** * If your request contains the {@code SECURECARDMERCHANTREF} field */ TERMINALID:MERCHANTREF:SECURECARDMERCHANTREF:DATETIME:STARTDATE:SECRET
ND002 - Enhanced Data - Level 2
You can add Level 2 data to your subscriptions by including the following extra fields in the request.
Note that your terminal must support and be enabled to process enhanced data, otherwise these fields will just be ignored.
Make sure to send as much information as possible in order to have a better chance to qualify for the lower Level 2 fees with your bank.
| FIELD | REQUIRED | DESCRIPTION |
|---|---|---|
| CUSTOMER_REF_NUMBER | N | string [ 1 .. 48 ] characters Sometimes referred to as customer code, it must be sent if provided by the cardholder. |
| TAX_AMOUNT | N | number <double> >= 0 Sales tax amount. 0 - Indicates that the transactions is exempt of tax. |
| SHIPPING_FULL_NAME | N | string [ 1 .. 50 ] characters Shipping address - contact name. |
| SHIPPING_ADDRESS1 | N | string [ 1 .. 50 ] characters Shipping address - first line. |
| SHIPPING_ADDRESS2 | N | string [ 1 .. 50 ] characters Shipping address - second line. |
| SHIPPING_CITY | N | string [ 1 .. 128 ] characters Shipping address - city. |
| SHIPPING_REGION | N | string [ 1 .. 128 ] characters Shipping address - region. |
| SHIPPING_POSTCODE | N | string [ 1 .. 50 ] characters Shipping address - postal code. |
| SHIPPING_COUNTRY | N | string 2-char ISO 3166-1 code Shipping address - country. |
Request sample
- Scenario: Minimum request containing only mandatory data and using an existing payment plan (stored subscription).
- Stored Subscription Ref: 6523423
- Secure Tokens Reference: 237498
- Terminal Secret: x4n35c32RT
<html> <body> <form action="" method="post"> <input type="hidden" name="TERMINALID" value="6491002"> <input type="hidden" name="MERCHANTREF" value="26352"> <input type="hidden" name="STOREDSUBSCRIPTIONREF" value="6523423"> <input type="hidden" name="SECURECARDMERCHANTREF" value="237498"> <input type="hidden" name="DATETIME" value="03-08-2023:17:32:18:329"> <input type="hidden" name="STARTDATE" value="04-08-2023"> <input type="hidden" name="ENDDATE" value="03-08-2010"> <input type="hidden" name="HASH" value="d880c3e63d5acf0c23737c742ad63e7b"> <input type="submit" value="Register"> </form> </body> </html>
Remember to change the
TERMINALID and SECRET for valid values. Ready to try? Sign up for a sandbox account.
Response
Assuming valid details were sent, the subscription registration hosted page will be displayed, clicking on “Accept & Subscribe” button will create the subscription. Once the registration is complete, the following parameters will be forwarded to the Subscription Receipt URL configured in your terminal:
Filter:
| FIELD | DESCRIPTION |
|---|---|
| RESPONSECODE See notes: ND003 | string <enum> A: Approval. C: Cancelled. |
| RESPONSETEXT | string [ 1 .. 48 ] characters The text of the response. |
| MERCHANTREF | string [ 1 .. 48 ] characters The MERCHANTREF provided in the request. |
| DATETIME | string <date-time> DD-MM-YYYY:HH:MM:SS:SSS The time of the registration. |
| HASH See notes: ND001 | A HASH code formed by part of the response fields. |
Response notes
ND001 - Hash validation
A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by . See how to decode and validate a hash string at Special Fields and Parameters.
For this specific feature, you should expect the following format:
TERMINALID:MERCHANTREF:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
ND002 - International customers
If you want to be able to accept international payments, make sure your account has any type of multi-currency processing enabled.
The most common is DCC (Dynamic Currency Conversion), it is also the only form of multi-currency processing that adds extra steps to the cardholder experience.
When setting up a subscription for a foreign card, a decision page will be displayed where the customer has to decide whether he wants to pay in his home currency or in the terminal's base currency.
ND003 - Response Codes - Errors
| Error Code | Description |
|---|---|
| E01 | SYSTEM ERROR - TRY AGAIN |
| E03 | OPERATION NOT ALLOWED |
| E06 | INVALID TERMINALID |
| E07 | METHOD NOT SUPPORTED |
| E08 | INVALID MERCHANTREF |
| E09 | INVALIDE DATETIME |
| E13 | INVALID HASH |
| E20 | INVALID LENGTH |
| E21 | INVALID PERIOD TYPE |
| E22 | INVALID NAME |
| E23 | INVALID DESCRIPTION |
| E24 | INVALID RECURRINGAMOUNT |
| E25 | INVALID INTIALAMOUNT |
| E26 | INVALID TYPE |
| E27 | INVALID ONUPDATE |
| E28 | INVALID ONDELETE |
| E29 | INVALID TERMINAL CURRENCY |
| E30 | INVALID STORED SUBSCRIPTION REF |
| E31 | INVALID STORED SUBSCRIPTION MERCHANT REF |
| E32 | INVALID SECURE TOKEN MERCHANT REF |
| E33 | INVALID STARTDATE |
| E34 | INVALID ENDDATE |
| E35 | INVALID EDCCDESICION |
| E36 | SETUP PAYMENT PROCESSING ERROR |
| E37 | INVALID SUBSCRIPTIONRECURRINGAMOUNT |
| E38 | INVALID SUBSCRIPTIONINITIALAMOUNT |
| E39 | SECURE TOKEN NOT VALIDATED |
| E41 | PASS ONLY ONE OF CARDREFERENCE OR SECURECARDMERCHANTREF OR SECUREACHACCOUNTMERCHANTREF |
| E42 | INVALID SECURE ACH ACCOUNT MERCHANT REF |
| E43 | AMOUNT IS NOT VALID |
| E45 | MULTIPLE PAYMENTS FOR ONE PERIOD IS NOT ALLOWED |
| E46 | SUBSCRIPTION HAS SKIP PERIOD |
| E47 | INVALID BANK IDENTIFIER |
| E48 | INVALID SECURE TOKEN REFERENCE |
| E60 | INVALID SECURE ACH MERCHANT REF |
| E61 | INVALID SECURE ACH REFERENCE |
| E65 | INVALID RECEIPT SUBSCRIPTION URL |
| E67 | INVALID HOST |
| E68 | UNSUPPORTED PAYMENT NETWORK FOR BANK TRANSFERS |
| E69 | UNSUPPORTED CURRENCY FOR CARD PROCESSING |
| E70 | UNSUPPORTED CURRENCY FOR BANK TRANSFER PROCESSING |
General constraints and rules
Filter:
| CONSTRAINT | DESCRIPTION |
|---|---|
| C001 | To create a subscription, you need to provide a valid, existing Secure Token. You may either use the SECURECARDMERCHANTREF or the CARDREFERENCE field for that, but never both. |
| C002 | When requesting the creation of a new subscription, you may also create your payment plan (stored subscription), or use an existing one. |
| C003 | When requesting the creation of a new subscription based on an existing payment plan (stored subscription), you need to provide a valid STOREDSUBSCRIPTIONREF. |