Hosted Page Subscription Feature


This feature enables you to create a Subscription using the Hosted Page method.

Use the Request URL and the Request Body Fields to perform a request for this feature, then put in place your Secure Token URL so the Gateway can use the Response Body Fields to send the creation's response.

Subscription Registration

  • REQUEST URL: https://testpayments.worldnettps.com/merchant/subscriptionpage/register

Request Body Fields

To create a new subscription based on an existing one:

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A TerminalID provided by Worldnet.
MERCHANTREF Y Unique reference assigned by the Merchant site/ solution to identify the subscription details. The length is limited to 48 characters.
STOREDSUBSCRIPTIONREF Y Reference of a previously created stored subscription, at SelfCare System. This field is required if the new Subscription being created is going to be based on an already existing Stored Subscription.
SECURECARDMERCHANTREF Y Merchant reference of a previously created Secure Token, which will be used to do set-up and recurring payments.
You should either use the SECURECARDMERCHANTREF, or CARDREFERENCE fields on your request.
CARDREFERENCE Y Payment Gateway Reference of a previously created Secure Token.
You should either use the SECURECARDMERCHANTREF, or CARDREFERENCE fields on your request.
SUBSCRIPTIONRECURRINGAMOUNT N Cost of each payment to be processed for the subscription.
This field should only be informed if the Stored Subscription (STOREDSUBSCRIPTIONREF) type is Automatic (without amounts).
SUBSCRIPTIONINITIALAMOUNT N Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Should only be sent if Stored Subscription (STOREDSUBSCRIPTIONREF) type is Automatic (without amount).
DATETIME Y Date and time of the request. Format: DD-MM-YYYY:HH:MM:SS:SSS.
STARTDATE Y Subscription start date.
ENDDATE N Subscription End Date, if it is not set subscription will continue until manually canceled or length reached (if it is set).
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


To create a new subscription, and at the same time, create a new stored subscription:

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A TerminalID provided by Worldnet.
MERCHANTREF Y Unique reference assigned by the Merchant site/ solution to identify the subscription details. The length is limited to 48 characters.
SECURECARDMERCHANTREF Y Merchant reference of a previously created Secure Token, which will be used to do set-up and recurring payments.
You should either use the SECURECARDMERCHANTREF, or CARDREFERENCE fields on your request.
CARDREFERENCE Y Payment Gateway Reference of a previously created Secure Token.
You should either use the SECURECARDMERCHANTREF, or CARDREFERENCE fields on your request.
DATETIME Y Date and time of the request. Format: DD-MM-YYYY:HH:MM:SS:SSS.
STARTDATE Y Subscription start date.
ENDDATE N Subscription End Date, if it is not set subscription will continue until manually canceled or length reached (if it is set).
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
NEWSTOREDSUBSCRIPTIONREF N Merchant Ref to be assigned for a new Stored Subscription being created.
NAME Y Display name for subscription.
DESCRIPTION Y Description explaining subscription.
PERIODTYPE Y Value can can be:
2 - for WEEKLY
3 - For FORTNIGHTLY
4 - For MONTHLY
5 - for QUARTERLY
6 - for YEARLY.
LENGTH Y 0 for non ending/ multipler of period. This does not take effect if (Subscription length*Period Type)>(End Date-Current Date).
RECURRINGAMOUNT Y Cost of each payment (will be ignored if manual).
INITIALAMOUNT Y 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 Integer code of subscription type:
1 - AUTOMATIC.
2 - MANUAL
3 - AUTOMATIC (WITHOUT AMOUNTS).
ONUPDATE Y Integer code of onupdate:
1 - CONTINUE.
2 - UPDATE (Let all depending subscriptions finish their subscription prior to update/ Update name, description, recurring price, setup price, subscription length, period type, type for all subscriptions).
ONDELETE Y Integer code of ondelete:
1 - CONTINUE.
2 - CANCEL (Continue subscriptions untill cancelled manually or reach end date or length/ Cancel all subscriptions).
OTHERFIELD N If Any other fields sent in the request will be treated as a custom field. They are not going to be stored, but they are going to be used by the Payment Gateway for the request sent 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.


Finally, if you want to add Enhanced Data to your subscription, add the following fields to your request:

Filter:

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N Text type field with max length of 48 characteres. This number is defined by the cardmember. It is entered by the merchant at the point of sale. See ND002 for more details.
TAX_AMOUNT N Value type field, with max length of 13 algarisms. A value of zero is required in order to indicate tax exempt transactions. See ND002 for more details.
SHIPPING_FULL_NAME N Text type field with max length of 50 characteres. See ND002 for more details.
SHIPPING_ADDRESS1 N Text type field with max length of 50 characteres. See ND002 for more details.
SHIPPING_ADDRESS2 N Text type field with max length of 50 characteres. Always optional regardless compulsory setting. See ND002 for more details.
SHIPPING_CITY N Text type field, between 1 and 128 characteres. See ND002 for more details.
SHIPPING_REGION N Text type field, between 1 and 128 characteres. See ND002 for more details.
SHIPPING_POSTCODE N Text type field, between 1 and 50 characteres. See ND002 for more details.
SHIPPING_COUNTRY N Text type field, with 2 characteres. ISO ALPHA-2 Country Code. See ND002 for more details.
TOTAL_DISCOUNT_AMOUNT N Total discount amount provided to the sale. Max of 13 characteres and 3 decimal points, depending on your terminal's currency. See ND003 for more details.
TOTAL_FREIGHT_AMOUNT N Total freight amount applied to the sale. Max of 13 characteres and 3 decimal points, depending on your terminal's currency. See ND003 for more details.
TOTAL_DUTY_AMOUNT N Total discount amount applied to the sale. Max of 13 characteres and 3 decimal points, depending on your terminal's currency. See ND003 for more details.
LINE_ITEM_’N’_PRODUCT_CODE N This is the merchant’s identifier for the product, also known as Universal Product code (UPC). Subfield of a line item. You can add as much items as see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 chars. See ND003 for more details.
LINE_ITEM_’N’_COMMODITY_CODE N Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial aggrements level. Consult your Acquirer for more details. Subfield of a line item. You can add as much items as see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 chars. See ND003 - Level 3 Data Validation.
LINE_ITEM_’N’_DESCRIPTION N This is the merchant’s description for the product. Subfield of a line item. You can add as much items as see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 250 chars. See ND003 for more details.
LINE_ITEM_’N’_QUANTITY N Quantity of the specific item for the sale. See ND003 for more details.
LINE_ITEM_’N’_UNIT_OF_MEASURE N Measure unit used for this specific item type to sell it in parts, units or sets. Subfield of a line item. You can add as much items as see fit, using a sequential instead of 'N' to identify its fields. Its value can be up to 45 chars. See ND003 for more details.
LINE_ITEM_’N’_UNIT_PRICE N Unit price applied for that specific type of item and measure unit, within the sale. Max of 13 characteres and 3 decimal points, depending on your terminal's currency. See ND003 for more details.
LINE_ITEM_’N’_DISCOUNT_RATE N A % of discount applied to the item total (quantity x unit price) before taxes. Max of 100%. See ND003 for more details.
LINE_ITEM_’N’_TAX_RATE N A % of tax applied to the item total (quantity x unit price) after discounts. Max of 100%. See ND003 for more details.
LINE_ITEM_’N’_TOTAL_AMOUNT N Final item value based on total (quantity x unit price), after discount and tax applied. Max of 13 characteres and 3 decimal points, depending on your terminal's currency. See ND003 for more details.



Notes and Details About the Request

ND001 - Hash Formation

The gerenal rule to build HASH field is given at the Special Fields and Parameters page. For this specific feature, you should use the following formats:

If your request uses SECURECARDMERCHANTREF:

TERMINALID:MERCHANTREF:SECURECARDMERCHANTREF:DATETIME:STARTDATE:SECRET

If your request uses CARDREFERENCE:

TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:STARTDATE:SECRET


ND002 - Level 2 Data Validation

These fields are associate with of the Transaction`s Level 2 Enhanced Data. To be used, it's necessary that your terminal has the enhanced data enabled and set to LEVEL 2 or LEVEL 3. All of its fields, except for SHIPPING_ADDRESS2, are necessary if you want to have a better chance to qualify for Level 2 with your acquirer, but no field is actually mandatory.

This feature is only available for specific acquirers (contact our support team for more details).


ND003 - Level 3 Data Validation

These fields are associate with of the Transaction`s Level 3 Enhanced Data. To be used, it's necessary that your terminal has the enhanced data enabled and set to LEVEL 3. To be valid, these fields need to be added to the transaction together with the Level II fields. Also, consider that the enhanced data fields are not mandatory, but if you send any Level 3 data fields, your application must send at least one item, and this item must contain at least the unit price, quantity and final amount. This feature is only available for specific acquirers (contact our support team for more details).

Examples for a Request

  • Scenario: Minimum request, with only mandatory data, based on an existing Stored Subscription.
  • Stored Subscription Ref: 6523423.
  • Secure Token Reference: 237498.
  • Terminal Secret: x4n35c32RT.
<html>
  <body>
    <form action="https://testpayments.worldnettps.com/merchant/paymentpage" 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-2009:17:32:18:329">
      <input type="hidden" name="STARTDATE" value="04-08-2009">
      <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 Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


Response Body Fields

Assuming valid details were sent, the Subscription Registration Hosted page will be displayed, clicking on “Accept & Subscribe” button will create the subscription only if the setup amount authorises successfully, and the resulting GET parameters will be forwarded to the Subscription Receipt URL that is configured on the Terminal Setup page. If the Subscription Secure Token currency is different from the Stored Subscription currency, then an eDCC Decision Page will be displayed, and the customer will have to decide if eDCC should be used for the initial and all subsequent payments for the subscription. The response body field will be:

Filter:

FIELD DESCRIPTION
RESPONSECODE A: Approval.
C: Cancelled.
Error Code: Verify the ND002 for more Details on possible values.
RESPONSETEXT The text of the response.
MERCHANTREF Original MERCHANTREF provided by the Merchant on request.
DATETIME The time of the registration. Format: YYYY-MM-DDTHH:MM:SS.
HASH A HASH code formed by part of the response fields. The formation rule is given at the ND001 - Hash Formation, in the next section.



Notes and Details on the Response

ND001 - Hash Formation

The gerenal rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section.

For this specific feature, you should consider the following formats:

TERMINALID:MERCHANTREF:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET


ND002 - 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
E48 INVALID Secure Token REFERENCE


Filter:

CONSTRAINT DESCRIPTION
C001 To created a subscription, you need to inform a valid, existing Secure Token. You may either used the SECURECARDMERCHANTREF or the CARDREFERENCE field for that, but only one of those.
C002 When requesting the creation of a new Subscription, you may also created your Stored Subscription, or use an existing one, but you can only use the fields of one of these options.
C003 When requesting the creation of a new Subscription based on an existing Stored Subscription, you need to provide a valid Stored Subscription.



Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International