====== Creating Subscriptions ====== ~~TOC~~ This feature enables you to set up subscription payments using a hosted page. * Sandbox URL: ''%URLSubscriptionReg'' ===== Request ===== === To create a new subscription based on an existing payment plan (stored subscription): === ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | 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 ''>= 0''} \\ Cost of each payment to be processed for the subscription. | | SUBSCRIPTIONINITIALAMOUNT | N | ^{number ''>= 0''} \\ Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. | | DATETIME | Y | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Date and time of the request. | | STARTDATE | Y | ^{string ''dd-MM-yyyy''} \\ Subscription start date. | | ENDDATE | N | ^{string ''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: [[hpp_subscription_features#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 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): === ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | 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 ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Date and time of the request. | | STARTDATE | Y | ^{string ''dd-MM-yyyy''} \\ Subscription start date. | | ENDDATE | N | ^{string ''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: [[hpp_subscription_features#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 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 \\ The frequency of which payments are collected. \\ ''2'' - WEEKLY\\ ''3'' - FORTNIGHTLY\\ ''4'' - MONTHLY\\ ''5'' - QUARTERLY\\ ''6'' - YEARLY. | | LENGTH | Y | ^{number ''>= 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 ''>= 0''} \\ Cost of each payment (will be ignored if manual). | | INITIALAMOUNT | Y | ^{number ''>= 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 \\ The type by which payments are collected. \\ ''1'' - AUTOMATIC \\ ''2'' - MANUAL \\ ''3'' - AUTOMATIC (WITHOUT AMOUNTS). | | ONUPDATE | Y | ^string \\ ''1'' - CONTINUE \\ ''2'' - UPDATE | | ONDELETE | Y | ^string \\ ''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 **[[selfcare:api_specification:special_fields_and_parameters|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 ''>= 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. | {gateway=nuvei} \\ ==ND003 - Enhanced Data - Level 3== You can add Level 3 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 and at least one line item in order to have a better chance to qualify for the lower Level 3 fees with your bank. \\ \\ To include line items, you need to replace the ''N'' with a sequential count identifier, e.g., ''LINE_ITEM_1_PRODUCT_CODE'', ''LINE_ITEM_1_TOTAL_AMOUNT'' and so on. ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TOTAL_DISCOUNT_AMOUNT | N | ^{number ''>= 0''} \\ Total discount amount applied to the sale. | | TOTAL_FREIGHT_AMOUNT | N | ^{number ''>= 0''} \\ Total freight amount applied to the sale. | | TOTAL_DUTY_AMOUNT | N | ^{number ''>= 0''} \\ Total duty amount applied to the sale. | | LINE_ITEM_''N''_PRODUCT_CODE | N | ^{string ''[ 1 .. 45 ] characters''} \\ This is the merchant’s identifier for the product, also known as Universal Product code (UPC). | | LINE_ITEM_''N''_COMMODITY_CODE | N | ^{string ''[ 1 .. 45 ] characters''} \\ 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. | | LINE_ITEM_''N''_DESCRIPTION | N | ^{string ''[ 1 .. 250 ] characters''} \\ This is the merchant’s description for the product. | | LINE_ITEM_''N''_QUANTITY | N | ^{number ''> 0''} \\ Quantity of the specific item for the sale. | | LINE_ITEM_''N''_UNIT_OF_MEASURE| N | ^{string ''[ 1 .. 45 ] characters''} \\ Measure unit used for this specific item type to sell it in parts, units or sets.| | LINE_ITEM_''N''_UNIT_PRICE | N | ^{number ''> 0''} \\ Unit price applied for that specific type of item and measure unit, within the sale. | | LINE_ITEM_''N''_DISCOUNT_RATE | N | ^{number ''[ 0 .. 100 ]''} \\ A % of discount applied to the item's total amount **before** taxes. | | LINE_ITEM_''N''_TAX_RATE | N | ^{number ''[ 0 .. 100 ]''} \\ A % of tax applied to the item's total amount **after** discounts. | | LINE_ITEM_''N''_TOTAL_AMOUNT | N | ^{number ''> 0''} \\ The item's total amount ''quantity * unit price'' after discounts and taxes. | {/gateway} ==== 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

===== 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: ^ **FIELD** ^ **DESCRIPTION** ^ | RESPONSECODE \\ ^{See notes: [[hpp_subscription_features#ND003 - Response Codes - Errors|ND003]]} | ^string \\ ''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 ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ The time of the registration. | | HASH \\ ^{See notes: [[hpp_subscription_features#ND001 - Hash validation|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 %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|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 ==== ^ **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''. | \\ \\