Knowledge Base

Get help for payment solutions. Search our articles or browse by category below.

7.2.3 Subscription Creation Request

Each subscription should be created based on some stored subscription. When new subscription is created it name, description, set-up price, recurring price, length, period type and type are copied from the corresponding stored subscription, most subscription fields can be changed by Subscription Updating request.

To create new subscription based on an existing Stored Subscription following XML Gateway request should be sent:

<?xml version="1.0" encoding="UTF-8"?>
<ADDSUBSCRIPTION>
	<MERCHANTREF>MR01-02</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<STOREDSUBSCRIPTIONREF>MR01</STOREDSUBSCRIPTIONREF>
	<SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF>
	<DATETIME>30-07-2009:15:34:23:671</DATETIME>
	<STARTDATE>01-08-2009</STARTDATE>
	<ENDDATE>31-07-2010</ENDDATE>
	<EDCCDECISION>Y</EDCCDECISION>
	<CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD>
</ADDSUBSCRIPTION>


If Stored Subscription doesn't yet exist it can be created putting all it details into the nested NEWSTOREDSUBSCRIPTIONINFO tag, STOREDSUBSCRIPTIONREF in such case should be omitted. There is example of such request:

<?xml version="1.0" encoding="UTF-8"?>
<ADDSUBSCRIPTION>
	<MERCHANTREF>MR02-02</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF>
	<DATETIME>30-07-2009:15:34:23:671</DATETIME>
	<STARTDATE>01-08-2009</STARTDATE>
	<ENDDATE>31-07-2010</ENDDATE>
	<EDCCDECISION>Y</EDCCDECISION>
	<NEWSTOREDSUBSCRIPTIONINFO>
		<MERCHANTREF>MR001</MERCHANTREF>
		<NAME>Animal Life</NAME>
		<DESCRIPTION>Magazine membership</DESCRIPTION>
		<PERIODTYPE>MONTHLY</PERIODTYPE>
		<LENGTH>12</LENGTH>
		<CURRENCY>EUR</CURRENCY>
		<RECURRINGAMOUNT>15.87</RECURRINGAMOUNT>
		<INITIALAMOUNT>10.99</INITIALAMOUNT>
		<TYPE>AUTOMATIC</TYPE>
		<ONUPDATE>CONTINUE</ONUPDATE>
		<ONDELETE>CANCEL</ONDELETE>
	</NEWSTOREDSUBSCRIPTIONINFO>
	<HASH>8515ccc5605651c12ab0645f79eb0271</HASH>
	<CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD>
</ADDSUBSCRIPTION>


Fields Description:

Filter:

Field Name Required description
MERCHANTREF Y Unique merchant identifier per terminal. Length is limited to 48 chars.
TERMINALID Y A Terminal ID provided by Worldnet.
STOREDSUBSCRIPTIONREF N Stored Subscription Merchant Reference, it is allowed only if NEWSTOREDSUBSCRIPTIONINFO do not present.
SECURECARDMERCHANTREF N Merchant Reference of a Secure Card which will be used to do set-up and recurring payments.
CARDREFERENCE N System-Genrated Secure Card reference (Only one of SECURECARDMERCHANTREF or CARDREFERENCE must be present)
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
RECURRINGAMOUNT N Cost of each payment. Should only be sent if stored subscription type is “Automatic (without amounts)” and new stored subscription is not being created.
INTIALAMOUNT 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 type is “Automatic (without amounts)” and new subscription is not being created.
STARTDATE Y Subscription Start Date. Format: DD-MM-YYYY.
ENDDATE N Subscription End Date, if it is not set subscription will continue until manually canceled or length reached (if it is set). Format: DD-MM-YYYY.
EDCCDECISION N This field is supported by a eDCC-enabled terminals only and will be ignored if terminal doesn't support eDCC. Can be “Y” or “N”.
NEWSTOREDSUBSCRIPTIONINFO N It is allowed only if STOREDSUBSCRIPTIONREF is not set. This tag and all it's children should be set if Stored Subscription on which new subscription being added should be based doesn't exist yet and should be created. Please check NEWSTOREDSUBSCRIPTIONINFO fields description table for details.
HASH Y An MD5 HASH. See note 1 below.


Notes:

1. If “SECURECARDMERCHANTREF” is used, the MD5 HASH is generated using the following as an input string:

TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+SECURECARDMERCHANTREF+DATETIME+STARTDATE+secret


2. If “CARDREFERENCE” is used, the MD5 HASH is generated using the following s an input string:

TERMINALID+MERCHANTREF+STOREDSUBSCRIPTIONREF+CARDREFERENCE+DATETIME+STARTDATE+secret


3. STOREDSUBSCRIPTIONREF should be omitted if it is not set.

NEWSTOREDSUBSCRIPTIONINFO fields description:

Filter:

Field Name Required Description
MERCHANTREF Y Unique merchant identifier per terminal. Length is limited to 48 chars.
NAME Y Display name for subscription.
DESCRIPTION Y Description explaining subscription.
PERIODTYPE Y Period Type, can be: WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY, YEARLY.
LENGTH Y 0 for non ending / multiplier of period. This does not take effect if (Subscription length *Period Type)> (End Date - Current Date).
CURRENCY Y Currency of subscription, this must either be the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT N Cost of each payment (should not be sent if TYPE is “MANUAL”).
INITIALAMOUNT Y Initial (set- up ) payment to be taken off card. Payment will not be taken if it is 0.
TYPE Y MANUAL / AUTOMATIC.
ONUPDATE Y UPDATE / CONTINUE (Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/Let them finish their subscription prior to update)
ONDELETE Y CANCEL/CONTINUE (Cancel all subscriptions/Continue subscriptions until cancelled manually or reach end date or length).


Example of a successful subscription creation response:

<ADDSUBSCRIPTIONRESPONSE>
	<MERCHANTREF>MR02-02</MERCHANTREF>
	<DATETIME>30-07-2009:15:34:24:305</DATETIME>
	<HASH>8bb39be67a1f05bf73fe334e12037257</HASH>
</ADDSUBSCRIPTIONRESPONSE>


The following fields will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Reference sent in registration request.
DATETIME Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH An MD5 HASH. See note 1 below.


Notes:

1. The MD5 HASH is generated using the following as an input string:

TERMINALID+MERCHANTREF+DATETIME+secret


Error handling
If new subscription was not registered, error code and error message will be returned:

<ERROR>
	<ERRORCODE>E08</ERRORCODE>
	<ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING>
</ERROR>


Subscription creation and updating error codes:

Filter:

Error Code Description
E01 SYSTEM ERROR - TRY AGAIN
E03 OPERATION NOT ALLOWED
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E09 INVALID DATETIME
E13 INVALID HASH
E20 INVALID LENGTH
E21 INVALID PERIOD TYPE
E22 INVALID NAME
E23 INVALID DESCRIPTION
E24 INVALID RECURRINGAMOUNT
E25 INVALID INITIALAMOUNT
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 CARDS MERCHANT REF
E33 INVALID STARTDATE
E34 INVALID ENDDATE
E35 INVALID EDCCDCECISION
E36 SETUP PAYMENT PROCESSING ERROR
E37 INVALID SUBSCRIPTIONRECURRINGAMOUNT
E38 INVALID SUBSCRIPTIONINITIALAMOUNT
E39 SECURE CARD NOT VALIDATED
E41 PASS ONLY ONE OF CARDREFERENCE OR SECURECARDMERCHANTREF OR SECURECARDACHACCOUNTMERCHANTREF
E48 INVALID SECURE CARD REFERENCE
E49 SECURECARDMERCHANTREF AND CARDREFERENCE ARE ABSENT (ONLY ONE OF THEM IS REQUIRED)
E50 SECURECARDMERCHANTREF AND CARDREFERENCE ARE BOTH PRESENT (ONLY ONE OF THEM IS REQUIRED)

Copyright © 2017 Worldnet Knowledge Base | Powered by DokuWiki
developer/integrator_guide/7._subscriptions/7.2._xml_subscriptions/7.2.3._subscription_creation.txt · Last modified: 2016/07/26 13:04 (external edit)