Table of Contents

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 - WEEKLY
3 - FORTNIGHTLY
4 - MONTHLY
5 - QUARTERLY
6 - 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.