SitelokTM Stripe Plugin V1.5
Sitelok Stripe Plugin Manual Copyright 2015-2018 Vibralogix. All rights reserved. This document is provided by Vibralogix for informational purposes only to licensed users of the Sitelok product and is provided on an as is basis without any warranties expressed or implied. Information in this document is subject to change without notice and does not represent a commitment on the part of Vibralogix. The software described in this document is provided under a license agreement. The software may be used only in accordance with the terms of that license agreement. It is against the law to copy or use the software except as specifically allowed in the license. It is the users responsibility to ensure the suitability of Sitelok Stripe Plugin before using it. In no circumstances will Vibralogix be responsible for any loss or damage of data or programs as a result of using Sitelok. Your use of Sitelok implies acceptance of these terms.
Contents Chapter 1 Introduction!... 4 What is the Sitelok Stripe Plugin?!... 4 Using Stripe buttons for new members!... 5 Using Stripe buttons for existing members!... 5 Chapter 2 Installation!... 7 Installing the Sitelok Stripe Plugin!... 7 Installing for the first time or upgrading!... 7 Setting up your Stripe account!... 8 Setting up the Stripe plugin!... 10 Chapter 3 Creating Products!... 14 Single payment membership products!... 14 Subscription membership products!... 18 Chapter 4 Creating buttons!... 20 Choose the button type!... 20 Choose the button function!... 21 Chapter 5 Accessing transactions!... 22 Chapter 6 Canceling subscriptions!... 23 Chapter 7 Updating card details!... 24 Chapter 8 Coupon Codes!... 25 Creating a coupon code!... 25 Chapter 9 Using a quantity field!... 27 Chapter 10 API functions!... 28 Chapter 11 Support!... 30
Chapter 1 Introduction Chapter 1 Introduction What is the Sitelok Stripe Plugin? The Sitelok Stripe Plugin allows you to sell membership access to your Sitelok protected areas processing the payments via Stripe. Both one off and recurring payments (subscriptions) are supported and a built in button generator creates the button code ready to paste into your pages. We use Stripes checkout box to collect credit card details from the user. This secure system pops up neatly over your page, is mobile friendly and constantly being improved by Stripe. It also avoids having to add credit card fields to your own forms. The Stripe plugin supports discount coupon codes (for subscription and single payment buttons) and also trial periods for subscriptions. The Stripe plugin also works with our Credits plugin allowing you to sell credits for access to downloads or other features on your site. Although no credit card data touches your server Stripe require that you use SSL (https) on your site. Page 4
Chapter 1 Introduction Using Stripe buttons for new members There are a number of ways to use Stripe buttons on your site for new members. Register for free and then upgrade to paid access The most common method is to have users register for free access to your site and then offer them the Stripe button(s) which updates their account to paid access. The initial free access can provide them with limited access or simply access to the payment button page. Its up to you. Auto register on checkout This option will collect the users details (name, email and address) from the Stripe checkout and create an account automatically for the user. Pay and register With this option you can have users click a Stripe button, enter their card details and then register for access. Sitelok V4.5 and above has a Stripe option when designing the registration form. Using Stripe buttons for existing members Once a user is a member of your site they can use Stripe buttons to pay for further access or to upgrade or downgrade subscriptions. They can also pay for non membership products such as credits. If a user clicks a subscription button (once logged in) they will be able to change from one type of membership to another. Stripe will automatically pro-rate the payment amount due. Users can only have one active subscription at a time. Subscription payments use the users last entered card details for payment. We have a change payment details button that allows users to update their payment details at any time. For security the actual details are not stored in Sitelok but in Stripe. Single payment membership buttons allow logged in users to add extra membership access to their account with a single payment. This can be with or without an expiry date. Page 5
Chapter 1 Introduction Non membership buttons allow you to charge for other features such as credits. Page 6
Chapter 2 - Installation Chapter 2 Installation Installing the Sitelok Stripe Plugin Before installing the Sitelok Stripe Plugin make sure that you have installed Sitelok and that it is working correctly. Ideally you should use the latest version but at the very least V3.0 should be installed. If you are using an older version of Sitelok prior to V5 the screenshots in this manual will differ. Important Although no credit card data touches your server Stripe require that you use SSL (https) on your site, at least on the pages that handle payment. You should also use a separate Stripe account for each site where you use the Sitelok Stripe plugin. This is because Stripe make use of custom email addresses and also the numeric user id of Sitelok users. These of course can't be guaranteed to be unique on separate sites. You should only create and edit products in the plugin and not directly in the Stripe account. Installing for the first time or upgrading 1) Extract the contents of the zip file to your PC. 2) Upload the pay_stripe folder to your existing Sitelok slpw folder using FTP. There are no special permissions required on most servers. If you have a previous version then overwrite the files. 3) Login to the Sitelok control panel. 4) Open the following URL in the browser http://www.yoursite.com/slpw/pay_stripe/install.php which will start the installation process. If all is well you will be taken to the plugin preferences page where you will see the plugin listed. If you have any problems with installation please let us know so that we can help you. Page 7
Chapter 2 - Installation Setting up your Stripe account If you just upgraded you can ignore this section which is only required the first time you install the Stripe Plugin. Before using the Sitelok Stripe Plugin for the first time we need to setup your Stripe account. Please note that in general you should not manually edit transactions in your stripe account so that Sitelok has control. 1) Login to Stripe, click Your Account and the click on the API menu option. 2) Copy the Secret Key and Publishable Key as we need to set these in the plugin later. You can use the test keys for test transactions and the live keys for live transactions. 3) Click on the Webhooks tab and then the Add Endpoint button. In the URL field enter the following (with your domain of course) https://www.yoursite.com/slpw/pay_stripe/slstripe.php You can if you require use http instead of https as no credit card details are ever sent by Stripe to webhooks. Set 'Send all event types'. Page 8
Chapter 2 - Installation 4) Click Business Settings in the main menu and then Emails Receipts. Here you can set whether to send email receipts to customers You can customize the emails as needed. 5) Click on the Subscriptions menu option and then the Settings tab to set how you would like Stripe to handle subscription payment failures. Page 9
Chapter 2 - Installation Setting up the Stripe plugin If you just upgraded you can ignore this section which is only required the first time you install the Stripe Plugin. In the Sitelok control panel select Stripe from the Plugins menu. Now click Stripe configuration at the bottom. Stripe settings Set your keys in the Stripe settings section Page 10
Chapter 2 - Installation Default checkbox settings This section allows you to set default labels and image for the Stripe checkout box that appears when a Stripe payment button is clicked. You can also set these for each product instead / as well if your prefer. Click the Preview Checkout link to see how the checkout will appear. The product description line is set for each product. If you wish to use an image in the checkout box just enter the absolute path to the image file excluding the https://www.yoursite.com part. The path should start with /. For example /images/logo.png. If you wish to allow the user the option to have the checkbox remember card details you can enable the Remember card option. Stripe uses a secure method to handle this which includes sending an SMS message to the user to confirm identity. Default product return pages After a user clicks a Stripe payment button and enter there credit card details they will be taken to a payment success or failure page page. You can setup default and / or product specific pages. If you want default pages enter the full absolute paths to the pages here. Do not include the https://www.yoursite.com part. For example /folder/success.php Page 11
Chapter 2 - Installation When using a default page you can get the product id purchased using $_GET['pid'] Default product buy buttons You can set a default buy button style which will be used if you don't set product specific buttons. There are a number of options to make buttons look how you want. The plugin also allows you to use any object on your page (images etc) as buttons as well if you prefer. Page 12
Chapter 2 - Installation Update card box settings The stripe plugin allows a user to update their card details at any time. This is only really needed if you use subscriptions though as single payments request card details at payment time. Click the Preview update card link to see how the box will appear. In the next chapter we will look at how to create products. Page 13
Chapter 3 - Creating Products Chapter 3 Creating Products Single payment membership products Enter the Sitelok control panel and select Stripe from the Plugins menu. Click the Add new Stripe single payment product button add a single payment product. Product Details In this section you should enter a product id, short description, price and currency. Note that Stripe only allows each customer to use one currency. Set the Product Type to Single payment membership if the product is to add the user to usergroups. If you are just taking payment for something else such as credits select Other single payment. Page 14
Chapter 3 - Creating Products Checkout box Set the labels and optional image for the products checkout box. If you prefer you can leave the fields blank and use the default checkout box you set earlier. You should still set the Checkout description though which is product specific. Click the Preview Checkout link to preview the box. Return Pages If you have not set default return pages you can set product specific pages here. Use a full path without the http://www.yoursite.com part. For example /folder/success.php Page 15
Chapter 3 - Creating Products Emails Set the email templates to be sent to the user and admin when this product is purchased. Inside the email templates you can use these email variables in additional to the standard variables.!!!stripeproductid!!!!!!stripeproductdescription!!!!!!stripetotal!!! Usergroups Set the usergroup(s) and expiry days for this product. Set the expiry to 0 for no expiry and -1 to remove a group (if needed) when the product is purchased. Page 16
Chapter 3 - Creating Products Product buy button Define the style and label for the button you want to use for this product. If you want to use the same style as the default that you set just click the Use default button style checkbox. In this case you just need to set the button label. Now you have create a product click Save Changes to store it. Page 17
Chapter 3 - Creating Products Subscription membership products Setting up a subscription product is mostly the same as for a single payment product described above. Here we will just cover the settings that are specific to subscription products. Product details Unlike a single payment product which has just one price, subscriptions allow you to have a setup fee on the first payment and also a trial period. The setup fee will be added to the normal subscription amount on the first payment. You must enter a description for the setup fee if you use one. This is used in Stripe receipts. Enter the payment period required. So for example you could set 1 Month for a monthly fee. There must be no more than 1 year between payments. Page 18
Chapter 3 - Creating Products If you want to have a trial period enter the number of days or enter 0 for no trial period. If set then the first payment will not be taken until that time. Emails For subscription products there are some extra email events that you can set templates for. Usergroups Usergroups are setup for subscriptions in the same way as for single payment products. However we recommend setting the expiry days to 0 for subscriptions. This ensures the user has access while payments are made. If a user cancels their subscription or Stripe cancels it after payments fail more than the set number of times then access to the product related groups will be expired automatically. Now you have created a subscription product click Save Changes to store it. Page 19
Chapter 4 - Creating Buttons Chapter 4 Creating buttons When you have added some products to the Stripe Plugin you can easily create the html code required for the button by clicking the icon next to the product. Choose the button type Select Use Styled button to create a button using the style you defined. If instead you want to use a page object as a button select Use a page object. In this case you need to replace OBJECTID in the button code with the id of the html object. Page 20
Chapter 4 - Creating Buttons Choose the button function Used on members page Select Used on members page if the button is to be placed on a secured page where the user is already logged in. This must be selected if the product is an Other single payment type product. With this selection when the user clicks the button they will see the Stripe checkout box, enter their card details and get sent to the product return page. Auto register on checkout Select Auto register on checkout to have a Sitelok account created automatically after payment. The Stripe checkout box will collect the users name, email and address which are used to create the Sitelok account. You can store the address details in custom fields if you wish. This type of button should be place on a Sitelok page secured using the PUBLIC usergroup. This allows non members to access the button. Connects to registration page Select Connects to registration page if you want non members to use the button before they register for your site. In this case you should first make a registration page on your site that will be used. Use Sitelok's registration form designer selecting Pay via Stripe and register as the Registration type to create the form and add it to your page. Sitelok V4.5 is required for this option. In the button code generated replace /folder/register.php with the path to your registration page. Don't include the http:// www.yoursite.com in the path. This type of button should be place on a Sitelok page secured using the PUBLIC usergroup. This allows non members to access the button. Once setup the user will click the button, enter their card details in the checkout box and then register for your site. Page 21
Chapter 5 - Accessing transactions Chapter 5 Accessing transactions Of course you can view almost everything that happens using the Stripe dashboard. We do recommend that you are careful about making changes to transactions though so that Sitelok retains control. It is safe to cancel subscriptions or refund payments through Stripe if you wish. The Sitelok control panel has options to view recent user transactions, cancel subscriptions or refund payments. To do this click the Stripe icon in the users More Options drop down in the main table.there are two sections on the page. The first section shows the users stripe id, last used payment details (that are used for subscription payments), the current subscription product (if relevant) and the subscription status. There are also links to cancel the subscription with immediate effect or at the end of the currently paid period. The second section of the page shows the most recent transactions and allows you to refund them if required. Page 22
Chapter 6 - Canceling subscriptions Chapter 6 Canceling subscriptions When a user starts a subscription it will continue indefinitely until either it is cancelled or payments fail after the set number of retries. If you wish to manually want to cancel a users subscription you can do so as described in the previous chapter 'Accessing transactions'. You may also want to allow users to cancel the subscription from inside the members area as well. To create a page that cancels a subscription follow these steps. 1) Create the page as usual and secure it with Sitelok as usual. 2) On the page place the following code <?php $res=sl_stripecancelsubscr(false); if ($res>0) print "Subscription canceled"; else print "Could not cancel subscription";?> When this page is visited the subscription will be cancelled with access until the end of the currently paid period. Of course you should not send the user directly to this page without warning but instead we recommend using three pages like this. Page 1 has link on it which say something like 'Cancel my subscription' linking to page 2. Page 2 has a link on it saying something like 'Are you sure you want to cancel' linking to page 3 which has the above code on it. Page 23
Chapter 7 - Updating card details Chapter 7 Updating card details If you offer subscription products its a good idea to allow users to update their card details that used to fund each payment. This can be achieved easily using a link on a secured page. You can also display the details of the currently stored card. Only a partial card number is displayed for security. To display the current card details use the following snippet. <?php echo sl_stripegetcard();?> To create a change card link create a link like this <a href="#" id="updatecard">change</a> and then add this line <?php echo sl_updatecardlink(array("objid"=>"updatecard"));?> setting the id of the link element to be used. Here is complete example an example Current Card: <?php echo sl_stripegetcard();?>  <a href="#" id="updatecard">change</a> <?php echo sl_updatecardlink(array("objid"=>"updatecard"));?> which looks like this on the page Current Card: Visa credit ****4242 01/2017 change Page 24
Chapter 8 - Coupon Codes Chapter 8 Coupon Codes The Stripe plugins supports Stripe's coupon system allowing you to create discount codes that can be entered by the user before payment to get a percentage or fixed amount discount. Coupons can be setup to provide a subscription discounts for the first payment only, multiple payments or every payment. Stripe doesn't currently officially support coupons with single payment products but we have found a way to implement that anyway. Creating a coupon code Login to the Stripe dashboard and click the Subscriptions menu option. Click the Coupons tab and then the New link at the top to display the following dialog. Page 25
Chapter 8 - Coupon Codes You can either enter a percentage discount (e.g. 10) or a fixed amount off (e.g. 2.50). Set the duration of the discount. This determines if its a one off (for the first payment of subscriptions or for single payment products) or whether it applies to multiple payments. Enter a unique coupon code which identifies the coupon and is what the user types in. You can also set a maximum number of redemptions and an expiry date for use as well. Click Create Coupon to create it. Now that you have created a coupon we need a way for the user to enter that before they make a payment. To do this 1) Add an input text field to your page using html like this <input type="text" id="coupon" value=""><br> <span id="couponmsg" style="display: none;"> This coupon code is not valid </span> You can of course style the input field as needed. 2) Tell the Stripe button(s) on the page that you want the coupon to apply to the id of the input field and the coupon not valid message like this <?php echo sl_get_stripe_button(array( "pid"=>"id1", "couponid"=>"coupon", "couponmsgid"=>"couponmsg" ));?> Page 26
Chapter 9 - Using a quantity field Chapter 9 Using a quantity field When charging a user for joining a single payment or subscription product there is usually no reason to have a quantity field. Sitelok would just create one account anyway. However when selling a product such as credits there maybe times when a quantity field is useful. This can be setup in a similar way to the coupon field (they can be used together too). 1) Add an input text field to your page using html like this <input type="text" id="qty" value="1"> You can of course style the input field as needed. 2) Tell the related Stripe button(s) on the page that you want the quantity to apply to the id of the input field like this <?php echo sl_get_stripe_button(array( "pid"=>"id1", "quantityid"=>"qty" ));?> Page 27
Chapter 10 - API functions Chapter 10 API functions There are several PHP functions that you can use on members pages to retrieve information about a users current subscription. Although not usually needed they may be useful in some cases. $res=sl_stripesubscrdescription(); This function gets the description of the current subscription or blank if the user doesn't have a subscription. Example usage <?php echo sl_stripesubscrdescription();?> $res=sl_stripesubscrpid(); This function gets the product id of the current subscription or blank if the user doesn't have a subscription. Example usage <?php echo sl_stripesubscrpid();?> $res=sl_stripegetcancelts(); This function returns the time that a cancelled subscription will actually finish. This is useful if you or a user cancels a subscription which remains valid for the rest of the paid period. The function returns 0 if the subscription has not been cancelled, -1 if the user has no subscription or if >0 the timestamp when the subscription will actually terminate. Example usage. <?php $res=sl_stripegetcancelts(); if ($res>0) { Page 28
Chapter 10 - API functions echo "Subscription has been cancelled and will terminate on ".date("d/m/y",$res); } if ($res==0) echo "Subscription has not been terminated"; if ($res<0) echo "You have no subscription setup";?> $res=sl_stripegetperiodendts(); This function returns the timestamp for the next payment (renewal). Example usage <?php echo date('d/m/y',sl_stripesubscrpid());?> Page 29
Chapter 11 - Support Chapter 11 Support Hopefully if you have followed this manual carefully everything will be working fine. However sometimes things don t go quite so smoothly so if you have any questions or problems then please check the FAQ on the support page or email us. Support area: http://www.vibralogix.com/support/ Email: support@vibralogix.com Page 30