====== Hosted Page Subscription Feature ======

~~TOC~~

\\
This feature enables you to create a Subscription using the Hosted Page method. For more details on Subscriptions, please visit the **[[merchant:new_merchant:products#suscription|Products]]** page.

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.nuvei.com/merchant/subscriptionpage/register**

==== Request Body Fields ====

To create a new subscription based on an existing one:

<searchtable>
^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| TERMINALID |	Y	| A TerminalID provided by Nuvei. |
| 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 %Slafcare 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. |
</searchtable>
\\

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

<searchtable>
^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| TERMINALID |	Y	| A TerminalID provided by Nuvei. |
| 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/ multiplier 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. |
</searchtable>
\\
\\

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

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

If your request uses SECURECARDMERCHANTREF:

<WRAP center box 100%>
TERMINALID:MERCHANTREF:SECURECARDMERCHANTREF:DATETIME:STARTDATE:SECRET
</WRAP>

If your request uses CARDREFERENCE:

<WRAP center box 100%>
TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:STARTDATE:SECRET
</WRAP>
\\

==== 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.

<code html>
<html>
  <body>
    <form action="https://testpayments.nuvei.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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
Verify the **[[developer:integration_docs|Integration Docs]]** for viable examples or contact our support team.
</WRAP>

\\

==== 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:

<searchtable>
^ **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.  |
</searchtable>
\\
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The gerenal rule to build HASH field is given at the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section.

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

<WRAP center box 100%>
TERMINALID:MERCHANTREF:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
</WRAP>

\\

**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 |
\\

==== General Constraints and Rules Related to the Feature ====

<searchtable>
^ **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. |
</searchtable>
\\
\\