Version 2 Published: 26 April 2018 2.1.21 (c)
Table of Contents 1 Introduction... 3 1.1 About Subscriptions... 3 1.2 Process Overview... 3 1.3 Pre-requisites... 3 2 Processing a Subscription through Payment Pages... 4 2.1 Required fields to perform the initial authorisation... 4 2.2 Required fields to schedule the subscription... 5 2.3 Sending the request... 8 3 Managing a Subscription... 9 3.1 Using MyST... 9 3.2 Sending XML Requests... 9 4 Subscription Notifications... 10 4.1 Subscription Reports... 10 4.2 Error Reports... 11 4.3 URL Notifications... 11 5 Skipping the first payment... 12 5.1 Pre-requisites... 12 5.2 Process overview... 13 6 Additional Notes... 14 6.1 End of month subscription payments... 14 6.2 Fraud checks... 14 6.3 Declined Authorisation... 14 6.4 Subscription active field... 14 6.5 3-D Secure and subscription payments... 14 6.6 Accepted payment types... 14 6.7 Expiry dates... 14 7 Further Information and Support... 15 7.1 Secure Trading Support... 15 7.2 Secure Trading Sales... 15 7.3 Useful Documents... 15 7.4 Frequently Asked Questions... 15 8 Appendix... 16 8.1 Acquirer advice code mapping... 16 8.2 Example report email for subscriptions... 16 Secure Trading Limited 2018 26 April 2018 Page 2 / 16
1 Introduction This document outlines how to schedule an automated subscription using Secure Trading Payment Pages. 1.1 About Subscriptions Subscriptions allow transactions to be automatically re-processed without the need for the customer to re-enter their payment details e.g. payments can be scheduled to be processed on the first of each month for 10.00. 1.2 Process Overview Your system is required to process a standard Authorisation using the Payment Pages, along with additional fields to schedule the subscription. The additional fields define how many Subscription payments are to be processed and the interval between the payments. Once the initial transaction is settled, the Subscription is made active and the Secure Trading Subscription Engine automatically processes payments at regular intervals. The Secure Trading Subscription Engine runs daily and processes all pending payments for that day. For more information on the Secure Trading Subscription Engine, please refer to the STPP Subscription Engine document. 1.3 Pre-requisites A Secure Trading account is required to process Subscription payments. For more information, contact Secure Trading Sales (see section 7.2). If you already have a Secure Trading account but do not have a Secure Trading Site Reference, please contact Secure Trading Support (see section 7.1). It is imperative that the Merchant ID is capable of processing Subscription payments. This is usually referred to by the acquirer as recurring or continuous authority payments. This document assumes the reader has an understanding of performing basic authorisations on their site using Payment Pages and also how Subscriptions are scheduled on Secure Trading s subscription engine. Please refer to the Payment Pages Setup Guide and the STPP Subscription Engine document respectively for further details. Please note Secure Trading strongly recommend that you test Subscriptions on your provided TEST account (The site-reference would begin with test_ ) to ensure that the Subscriptions are scheduled as expected. Secure Trading Limited 2018 26 April 2018 Page 3 / 16
2 Processing a Subscription through Payment Pages Your system will need to send a request to the Payment Pages that both processes a standard authorisation payment (this can include 3-D Secure) and also instructs the subscription engine to schedule future payments. This can be achieved in a single POST to the Payment Pages. 2.1 Required fields to perform the initial authorisation To process the initial standard Authorisation, the following fields must be included in the request to the Payment Pages (https://payments.securetrading.net/process/payments/choice). These are the same fields required in a stand-alone authorisation, as outlined in the Payment Pages Setup Guide. Field Name sitereference currencyiso3a mainamount Details The unique Secure Trading site reference received during sign-up. e.g. example32075 The currency of the transaction in iso3a format. A list of available currencies can be found at: http://www.securetrading.com/support/tools/currency-codes e.g. GBP The amount of the transaction should be in main units, with no commas, so 100 would be 100.00 Currencies such as Japanese Yen which do not require a decimal place can be submitted without. So 100 Yen would be 100. version This value will be set to 1 credentialsonfile Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use (e.g. by a Subscription or by processing a re-authorisation). Following this, you must appropriately identify credentials that are to be stored for later, by submitting credentialsonfile with value 1. Note: The CoF mandate only applies for new transactions processed after 30th April 2018. However, if you are storing credentials as part of your solution, we strongly recommend implementing the above ahead of the cut-off date, so you are ready when it comes into effect. Credentials stored before this date do not need to be updated. Secure Trading Limited 2018 26 April 2018 Page 4 / 16
2.2 Required fields to schedule the subscription To schedule the subscription in the subscription engine, you will need to consider including the following fields in the same request to the Payment Pages: Please note Secure Trading strongly recommend including all submitted Subscription fields within the Payment Pages Site Security. For more information please refer to the Payment Pages Setup Guide. 2.2.1 subscriptionunit (Mandatory) This field represents the unit of time between each subscription. This can be either DAY or MONTH. It is imperative that the field subscriptionunit is submitted to the gateway in CAPITALS e.g. DAY or MONTH. 2.2.2 subscriptionfrequency (Mandatory) Combined with the subscriptionunit field, this field defines how frequently payments are processed. e.g. For one payment every 7 days: subscriptionfrequency = 7 subscriptionunit = DAY e.g. For one payment every 2 months: subscriptionfrequency = 2 subscriptionunit = MONTH 2.2.3 subscriptionfinalnumber (Mandatory) This is the number of subscriptions to be processed in total over the course of the subscription (including the initial authorisation). e.g. if subscriptionfinalnumber = 12, there will be 12 monthly payments in total (the initial authorisation + 11 repeat payments). If the value is 0, the Subscription Engine will schedule payments indefinitely until the user manually sets the subscription to Inactive using MyST. Please note that if you submit a subscriptionfinalnumber of 1, only one payment will be taken from the customer in total (no subscription payments will be processed after the initial authorisation). Secure Trading Limited 2018 26 April 2018 Page 5 / 16
2.2.4 subscriptiontype (Mandatory) This field indicates the type of Subscription, as required by the acquiring bank. The value can either be INSTALLMENT or RECURRING. RECURRING is used when the Customer is making a recurring payment for a new product/service each time (for example, a magazine subscription). For most merchants, the subscriptiontype should be set to RECURRING. INSTALLMENT is only used in select cases with certain acquirers. It is designed for when a Customer is purchasing a single item over several installments (for example, paying 100 a month for an item until it has been paid in full). Installments are only accepted by certain acquirers. For further information, please contact your acquiring bank. Secure Trading Limited 2018 26 April 2018 Page 6 / 16
2.2.5 subscriptionbegindate (Optional) This field allows you to specify the starting date of payments processed automatically by the subscription engine. Before submitting requests with this field, please ensure you have read and understood the text below on its usage. 2.2.5.1 Subscription without begin date When processing a subscription, it is important to remember that the first payment will always be processed immediately. Following settlement, recurring payments are automatically processed at your specified interval. This is summarised in the following flow: Example of standard subscription flow Today s date is 5 th January. Your system submits a POST including unit of MONTH and frequency of 1 to schedule a monthly subscription. The first payment is processed immediately on 5 th January. The automated payments begin on a date determined by the unit and frequency fields, based on when the first payment was processed. 2.2.5.2 Specifying the begin date As an alternative to the flow above, you can submit the additional optional field subscriptionbegindate in the POST. This is used to specify a custom begin date for the automated payments, as described in the following flow. The begin date is submitted in the format YYYY-MM-DD and cannot be a date in the past: e.g. 2017-01-08 Example of subscription flow WITH custom begin date Today s date is 5 th January Your system submits a POST that schedules a monthly subscription and optional field subscriptionbegindate = 2017-01-08 The first payment is always processed immediately on 5 th January. On 8 th January, the subscription engine processes the first automated payment (using the date specified in the subscriptionbegindate field). Subsequent automated payments will be processed on dates calculated by using the subscriptionbegindate in conjunction with the unit and frequency fields. If the subscriptionbegindate included in the POST is the same as the date the first payment is processed, a second payment will be processed the next day. Secure Trading Limited 2018 26 April 2018 Page 7 / 16
2.3 Sending the request The following example demonstrates how to process a subscription payment by performing a POST to the Secure Trading Payment Pages. <html> <head> </head> <body> <form method="post" action="https://payments.securetrading.net/process/payments/choice"> <input type="hidden" name="sitereference" value="example32075"> <input type="hidden" name="currencyiso3a" value="gbp"> <input type="hidden" name="mainamount" value="10.00"> <input type="hidden" name="stprofile" value="default"> <input type="hidden" name="version" value="2"> <input type="hidden" name="subscriptionunit" value="month"> <input type="hidden" name="subscriptionfrequency" value="1"> <input type="hidden" name="subscriptionfinalnumber" value="12"> <input type="hidden" name="subscriptiontype" value="recurring"> <input type="hidden" name="credentialsonfile" value="1"> <input type="submit" value="pay"> </form> </body> </html> Secure Trading Limited 2018 26 April 2018 Page 8 / 16
3 Managing a Subscription 3.1 Using MyST MyST is a password protected online management area which allows all Secure Trading merchants to monitor their transactions and perform other management on their account(s). We recommend that you use the MyST system to view and update Subscriptions. This is explained in detail in the MyST User Guide. Figure 1 Single Transaction View of an active Subscription Transaction details tab 3.2 Sending XML Requests It is also possible to view and update Subscriptions by sending XML requests to Secure Trading, by using either the STAPI application or the Web Services interface. Subscriptions can be viewed by sending a Transaction Query XML request, and be updated by sending a Transaction Update XML request. This is explained in detail in the Subscriptions XML Specification. Secure Trading Limited 2018 26 April 2018 Page 9 / 16
4 Subscription Notifications Once your site has been set up to process Subscriptions, it is recommended that you opt-in to receiving notifications to keep you informed of payments processed on your account by the subscription engine. 4.1 Subscription Reports If you would like to receive email reports that show Subscription payments processed on your site, please contact our support team (see section 7.1). 4.1.1 Structure of email If you have the email report enabled on your account, you will receive an email from no-reply@securetrading.com, for each day that Subscription payments are processed. You will receive a maximum of one email per day. They are presented in the format of a table (see 8.2 in the Appendix), with the following fields: Field Name Details Subscription reference A unique Secure Trading reference for the Subscription transaction. Transaction reference A unique Secure Trading reference for the transaction. Account This will match the account type description supplied within the request. This should be RECUR. Request The type of request processed. Note: AUTH is an Authorisation request. Currency The currency that the transaction was processed in. Settle status The current status of the transaction at the end of request. Auth code The authorisation code provided by the Issuing Bank. This is generated by the Issuing Bank, and will differ, depending on which bank you use. Error code Whether or not the transaction was successful. 0 represents a successful transaction. Base amount The amount of the transaction in base units, with no commas or decimal points. For example, 10 would be shown as 1000. Sitereference The Site reference relates to your individual account which you received on setup. Subscription frequency This is the time between Authorisations. It represents the gap between each payment in a Subscription. Subscription number This represents the position of the transaction within a series of Subscription payments. E.g. 5/10 would represent the 5 th transaction out of 10. Subscription type This is the type of Subscription: RECURRING or INSTALLMENT (see section 2.2.4 for further details). (Optional) Acquirer advice code A numeric value returned, indicating if further payments can be processed. As this field is only supported by certain acquiring banks, you will need to ask our Support team to add this to your report. See section 8.1 for a full mapping. The email will be sent from no-reply@securetrading.com, with the subject Subscription Report for [date in YYYY-MM-DD]. Please add a rule or filter to your email client to prevent the emails from being classified as junk mail / spam. Secure Trading Limited 2018 26 April 2018 Page 10 / 16
4.2 Error Reports If you would like to receive an email if a Subscription transaction processed on your site returns an error, please contact our Support team (see section 7.1). 4.2.1 Structure of email If you have the email report enabled on your account, you will receive an email from no-reply@securetrading.com, whenever errors are encountered while processing Subscription payments. You will receive a maximum of one email per day. More than one Subscription can appear in one email, and are separated by spaces. Here is an example of a Subscription error email report (in this case, the customer s card has been declined): Problem with processing transaction 3-64-56 70000 Decline subscriptionnumber:2 The email will be sent from no-reply@securetrading.com with the subject Secure Trading transaction error. Please add a rule or filter to your email client to prevent the emails from being classified as junk mail / spam. 4.3 URL Notifications It is possible to configure URL Notifications to be submitted to your system, following each payment processed on your site by the subscription engine. (One notification per transaction) To configure this, sign in to MyST and navigate to the Rule Manager. If you are new to the Rule Manager, we recommend reading this information in conjunction with the Rule Manager document. 1. Choose the site Select the site through which you are processing subscriptions and the action type URL Notification, then click Change. 2. Create the condition Create a condition for completed requests, with the following properties: Account type is RECUR. Request type is AUTH. Select all payment types, currencies and settle statuses. Error code is 0. 3. Create the action If you haven t already, create a new action with the URL of your server and include the fields you would like to be included in the notification. 4. Create the rule Using the Rule Manager, assign the condition to the action, and click Save. Ensure the checkbox in the Active column in ticked, indicating the new rule is active. Please test the rule is working on your test site reference before applying it to your live site reference. Secure Trading Limited 2018 26 April 2018 Page 11 / 16
5 Skipping the first payment So far we have discussed the processing of subscriptions, where the first payment is processed immediately and subsequent payments are processed automatically at regular intervals defined in the POST. This section covers scheduling a subscription where the first payment is skipped, meaning no transactions are processed until after the first interval (e.g. 1 month) has passed. E.g. customer agrees to a monthly subscription, and the first month is free of charge. The first payment that is skipped is still counted against the final number value submitted in the POST (see section 2.2.3). e.g. When a subscription with final number of 12 is submitted, if the first payment is skipped, only 11 payments will be processed in total. 5.1 Pre-requisites Contact the Support team (see section 7.1) and enquire about the following: (Required) Check your acquiring bank can support 'Account checks'. If supported, request that the 'Enhanced post' functionality is enabled using request types ACCOUNTCHECK, THREEDQUERY (optional), AUTH, SUBSCRIPTION. (Optional) Configure rules that suspend subscriptions if details entered by the customer do not match those held on their bank's records. This can be used to provide an additional level of security. For further information, refer to the Payment Pages Setup Guide and read the section on Account checks. Please ensure you have read and understood the previous pages on subscriptions in this document before proceeding. Secure Trading Limited 2018 26 April 2018 Page 12 / 16
5.2 Process overview 1. Modify the POST You will need to update your POST used to request a subscription and add the field requesttypedescriptions, as shown in the following example: <html> <head> </head> <body> <form method="post" action="https://payments.securetrading.net/process/payments/choice"> <input type="hidden" name="sitereference" value="test_site12345"> <input type="hidden" name="stprofile" value="default"> <input type="hidden" name="currencyiso3a" value="usd"> <input type="hidden" name="mainamount" value="15.00"> <input type="hidden" name="version" value="2"> <input type="hidden" name="subscriptionunit" value="month"> <input type="hidden" name="subscriptionfrequency" value="1"> <input type="hidden" name="subscriptionfinalnumber" value="12"> <input type="hidden" name="subscriptiontype" value="recurring"> <input type="hidden" name="credentialsonfile" value="1"> <input type="hidden" name="subscriptionbegindate" value="2013-04-30"> <input type="hidden" name="requesttypedescriptions" value="accountcheck"> <input type="hidden" name="requesttypedescriptions" value="subscription"> <input type="submit" value="pay"> </form> </body> </html> 2. Customer enters their details Once they have reached the Payment Pages, the customer enters their payment and billing details, as with a normal payment. 3. Account check is processed The customer's bank checks the billing address and card security code details entered match those held on their records for the customer's card. 4. Subscription is scheduled Providing the checks are successful, the customer is shown a confirmation message and the subscription is scheduled in our subscription engine. 5. Scheduled payments are processed after the first interval Payments are automatically processed for the customer at the intervals defined in the POST. Because the first payment was skipped, the total number processed will be one less than the final number specified in the POST. Secure Trading Limited 2018 26 April 2018 Page 13 / 16
6 Additional Notes 6.1 End of month subscription payments Subscription payments can be processed monthly from the date of the initial payment. If the date of the initial payment is after the 28 th of the month, all following subscription payments are scheduled for the 28 th of each month. This is to prevent issues for subscription payments on months that have fewer days than others. 6.2 Fraud checks If enabled on your account, Secure Trading will run fraud checks on every Authorisation in a series of subscription payments processed on your account. However, if the first AUTH is sent with a settlestatus value of 1, fraud checks will not be performed on the first AUTH or any of the payments in the subscription. For further information on fraud checks, please contact Secure Trading Support (section 7.1). 6.3 Declined Authorisation It is not possible to schedule recurring payments in the Subscription Engine, if the first Authorisation request was declined by the acquirer. 6.4 Subscription active field A Subscription transaction is initially set as 2 - Pending and is only updated to 1 - Active once the initial payment has settled. This is to prevent Subscription payments being processed if the initial transaction has not completed and also to ensure fraud*, duplicate* and settlement checks are carried out. The subscription active field can be manually overridden using MyST (see the MyST User Guide). Please note that updating a Pending Subscription to be Active will ignore the results of any fraud*, duplicate* or settlement checks on the initial Authorisation. *Fraud and duplicate checks are not enabled by default on new Secure Trading accounts. Please contact Secure Trading Support for further information. 6.5 3-D Secure and subscription payments The initial Subscription payment can be processed using 3-D Secure, where the customer will be required to authenticate their transaction. All subsequent transactions will be processed as standard Authorisations (non 3-D Secure). For further information regarding 3-D Secure please refer to the 3D Secure XML Specification. 6.6 Accepted payment types Only Visa, Mastercard and AMEX branded cards can be used for processing subscription payments (excluding Maestro). 6.7 Expiry dates Please ensure that the expiry dates on your active subscriptions are valid and up-to-date as some issuers may decline cards with outdated card expiry dates. These can be updated by using MyST (see the MyST User Guide). Secure Trading Limited 2018 26 April 2018 Page 14 / 16
7 Further Information and Support 7.1 Secure Trading Support If you have any questions regarding integration or maintenance of the system, please contact our support team using one of the following methods. Method Details Telephone +44 (0) 1248 672 050 Fax +44 (0) 1248 672 099 Email support@securetrading.com Website http://www.securetrading.com/support/support.html 7.2 Secure Trading Sales If you do not have an account with Secure Trading, please contact our Sales team and they will inform you of the benefits of a Secure Trading account. Method Details Telephone 0800 028 9151 Telephone (Int l) +44 (0) 1248 672 070 Fax +44 (0) 1248 672 079 Email sales@securetrading.com Website http://www.securetrading.com 7.3 Useful Documents All documents regarding the STPP system can be found on Secure Trading s website (http://www.securetrading.com). Alternatively, please contact our support team as outlined above. 7.4 Frequently Asked Questions Please visit the FAQ section on our website (http://www.securetrading.com/support/faq). Secure Trading Limited 2018 26 April 2018 Page 15 / 16
8 Appendix 8.1 Acquirer advice code mapping Code Description Action 0 N/A (Mastercard only) No action required 1 New account information available (Mastercard only) The bank has reason to believe that the customer s card details are out-ofdate (e.g. the expiry date has passed). Please check with the customer that their card details are still correct. This field is advisory and we will allow you to re-process even if the card details are not updated, however the acquiring bank may not accept the payment. You may find it useful to contact your bank in such cases for clarification. 2 Cannot approve at this time Try again later. If you are continuing to have difficulties, please contact your acquiring bank 4 Do not try again 8 Payment blocked by card scheme Do not process further recurring transactions For information on how to test for different acquirer advice code values, please refer to the Testing document. 8.2 Example report email for subscriptions The following is the contents of an example email report for Subscriptions. For more information on report emails, see section 4. [ This is an automated email ] The following subscriptions were processed on 2013-03-07 All of these transactions were authorised: Subscription Transaction Settle Auth Error Base Site Subscription Subscription Subscription Account Request Currency reference reference status Code code amount Reference frequency number type 3-64-56 6-9-482453 RECUR AUTH GBP 1 - Manual settlement TEST 0 1200 test_site1 1 DAY 2/2 RECURRING 3-64-58 4-9-744247 RECUR AUTH GBP 1 - Manual settlement TEST 0 1000 test_site1 1 MONTH 2/9 RECURRING 3-64-59 2-9-482237 RECUR AUTH GBP 1 - Manual settlement TEST 0 1200 test_site1 1 DAY 2/2 RECURRING This e-mail was sent from a notification-only address that cannot accept incoming e-mail. Please do not reply to this message Secure Trading Limited 2018 26 April 2018 Page 16 / 16