Installing the Jamroom Payment Pack

Installing the Jamroom Payments Pack is a straightforward process - simply follow the steps as outlined, and you should be configured and running quickly.

Tip: Configuration instructions for the new Jamroom Vault can be found in the Jamroom Vault Installation section.

• First, make sure you have download the latest version of the Jamroom Payments Pack from the Jamroom Downloads Page.
  

• Next, uncompress the downloaded archive (it will be named something like "jamroom-payment-3.0.20.zip" - note that the version number may be different) into a folder on your local hard drive. You will see that a sub-folder is created that is named the same as the download - i.e. “jamroom-payment-3.0.20”.

• Next, upload the entire contents (including sub directories) of this folder directly in to your Jamroom directory, using an FTP client like FileZilla. If uploaded correctly, you will see the scripts from the Payment Pack are now inside your jamroom directory - i.e. “jamroom/payment.php”. You do not need to worry about overwriting any files already installed in your Jamroom, since all of the new files in the Jamroom Payment Pack do not exist in your Jamroom install.

All of the files required by the Payment Pack have now been installed.

Configuring the Jamroom Payment Pack

Now that the Jamroom Payment Pack files have been installed, the next step is to configure the Payment Pack system to work how you want it to work.

• First, click on the "Jamroom Config" link from the Master Admin Menu, and select the "Payment Settings" link from the config menu, located in the "Module Settings" section:

• After clicking on the Payment Settings link, you will be see the Jamroom Payment Pack main config screen.  From this screen you can enable and disable the entire Payments sub system, as well as configure the individual Payment Processor plugins that are available on your system:

• First, click on the "Test Connection" button to the right of the selected Payment Processor - this will ensure your server has the necessary bi-directional communication necessary for automated transactions.

• Next, click on the "Configure" button to the right of the PayPal module, and this will take you into the PayPal (or other Payment Processor specific) settings section.  Within this section you can configure and set the options that are required for the configured payment processor.  Note that if you have more then 1 payment processor installed, you can select different Payment Processors to use on a per Jamroom Quota basis.   Make sure and configure the options as you would like them to be, and save your settings.

Configuring the Jamroom Quotas to support subscriptions

Now that you have enabled and configured the Jamroom Payment Pack, your next step is to setup your "subscription" Jamroom Quota(s).

• First, select the Jamroom Quota that you want your artists/members subscribing to.  Click on the "Browse Quotas" link from the Admin Menu, and click on the "Modify" button next to the Jamroom Quota.  This will take you into the Jamroom Quota Config.

• Now that the Jamroom Payments Pack has been installed, you will now see a new "page" option at the top of the Jamroom Quota Config window:

• Click on the new Payments tab, and you will see many options that are now available for your configuration.  This allows you to set up to three (3) different Subscription lengths on a per Jamroom Quota Basis.  The following options are available:
  • Allow Subscriptions - If this is set to "yes", then Artist and Member profiles can be subscribed to this Jamroom Quota.
  • Subscription Name - This is the "Name" of the subscription as it will be seen on the Browse Subscriptions page.
  • Subscription Processor - This is the Payment Processor that will be used to handle the subscriptions for this Jamroom Quota.
  • Subscription Currency - This is the currency that will be used in the subscription
  • Trial Length - If you want to offer a "free trial" period for subscribers to this quota, select the free trial length from this drop down menu.
  • Subscription Price #1 - This is the price for the first subscription option.
  • Subscription Length #1 - This is the length of time in the first subscription option.
  • Subscription Price #2 - This is the price for the second subscription option.
  • Subscription Length #2 - This is the length of time in the second subscription option.
  • Subscription Price #3 - This is the price for the third subscription option.
  • Subscription Length #3 - This is the length of time in the third subscription option.
  • End of Term Action - When a profile's subscription is canceled or runs out, what action should Jamroom take with the profile?
  • End of Term Reminder - Jamroom can send out a courtesy notification email letting the subscriber know their subscription is going to automatically renew.
  • End of Term Reminder Days - How many days before the subscription is set to renew, should the reminder be sent?
  • Payment Return Template - By default, Jamroom will automatically handle the "return" of the user after successful payment, however you can enter an alternate URL or template name (which is process by index.php) if you would like to manually override the return page.
  • Description - This is the main description of the subscription, which is shown to the user in the subscription browser.

Configuring the Email Templates

The next step is to modify the Jamroom Payment Pack email templates.  There are quite a number of email templates related to the Jamroom Payment Pack, and you can tell which templates are part of the Payment Pack as the template filenames all begin with "jr_payment".  You should find the following email templates in your jamroom/templates/email directory after successfully installing the Jamroom Payment Pack:

jr_payment_subscr_cancel_message.tpl
jr_payment_subscr_cancel_subject.tpl
jr_payment_subscr_create_message.tpl
jr_payment_subscr_create_subject.tpl
jr_payment_subscr_eot_message.tpl
jr_payment_subscr_eot_subject.tpl
jr_payment_subscr_failed_message.tpl
jr_payment_subscr_failed_subject.tpl
jr_payment_subscr_pending_message.tpl
jr_payment_subscr_pending_subject.tpl
jr_payment_subscr_reminder_message.tpl
jr_payment_subscr_reminder_subject.tpl

Make sure and modify the templates if you would like so they appear and contain the information you wish to have.

Creating a link to the Subscription Browser

Now that you have configured the Jamroom Subscriptions, and have configured your Jamroom Quota(s) that you want to allow your users to subscribe to, the next step is to create a link to the Subscription Browser.  The Subscription Browser is the built in way for your users to "view" the available Jamroom Subscriptions that have been made available for them to subscribe to.  Note that this can also be completely customized via the use of a Jamroom template, but for now, set it up using the default to ensure everything is working.

• First, we want to create a Custom Button that will be displayed to the Jamroom Quota that we want users to subscribe FROM.  This would likely be your "free" Jamroom Quota.
• Log in to your Jamroom as the Master Admin
• Click on the "Jamroom Config" option from the Admin menu, then click on the "Custom Buttons" link to take you into the Custom Button section.
• Next, click on the "Create Button" button in the "Options" section of the Create Button/Menu screen, and enter the the following values:
  • Button Label - enter "subscriptions" (or whatever text you would like to appear on the button).
  • Button URL - enter "subscribe.php?mode=view" for the URL.

  Note: If you would like to make it so only specific Jamroom Quotas are shown to the user when they click on the Custom Button, the following parameters can be added to the Button URL to  limit the output:

  &type=member - will limit the Jamroom Quota subscriptions that are shown to ONLY Member Quota Subscriptions.

  &type=artist - will limit the Jamroom Quota subscriptions that are shown to ONLY Artist Quota Subscriptions.

  &quota_id=# - will limit the Jamroom Quota subscriptions that are shown to ONLY the specified Jamroom Quota Id (replace # with actual quota id).

  • Button Quota - select here the Jamroom Quota's that you want to see the button.
  • Save your new Custom Button by clicking on the "Create Button" submit button.
• Now, log in as an Artist/Member Profile user that is in a Jamroom Quota you just associated with the new Custom Button, and you should see the button in your Menu.  Clicking on this button will now show you the available subscription options.

Creating a Custom Subscription Browser template

If you decide that you want to create your own custom Subscription Browser, and not use the built in subscription browser, Jamroom can do that for you as well.

• The first step is to create a new template in the active skin directory called "subscriptions.tpl" (or whatever you would like to call it).
• Next, create the Custom Button (as outlined in the "Creating a link to the Subscription Browser" option above), and add the name of the template to the URL - i.e.

    subscribe.php?mode=view&template=subscribe.tpl

• Within the subscribe.tpl you can place whatever HTML code you would like, and design it to suit your needs.  Internally within the template Jamroom will create an array called $_SUBS that will contain the information about the subscriptions available to be browsed by the person viewing.  The following is an example template that can be further modified to suit your needs:

{* Our subscriptions quotas are stored in $_SUBS array *} {foreach from=$_SUBS key=key item="_sub"}   <b>{$_sub.QUOTA_SUBSCRIBE_NAME} Subscription Options</b><br>&raquo; {$_sub.QUOTA_SUBSCRIBE_DESC}<br>   <br><a href="{$_sub.QUOTA_SUBSCRIBE_URL1}">Subscribe to Option 1</a>:   {$_sub.QUOTA_SUBSCRIBE_CURRENCY_SYMBOL}{$_sub.QUOTA_SUBSCRIBE_PRICE1} / {$_sub.QUOTA_SUBSCRIBE_DAYS1}   <br><a href="{$_sub.QUOTA_SUBSCRIBE_URL2}">Subscribe to Option 2</a>:   {$_sub.QUOTA_SUBSCRIBE_CURRENCY_SYMBOL}{$_sub.QUOTA_SUBSCRIBE_PRICE2} / {$_sub.QUOTA_SUBSCRIBE_DAYS2}   <br><a href="{$_sub.QUOTA_SUBSCRIBE_URL3}">Subscribe to Option 3</a>:   {$_sub.QUOTA_SUBSCRIBE_CURRENCY_SYMBOL}{$_sub.QUOTA_SUBSCRIBE_PRICE3} / {$_sub.QUOTA_SUBSCRIBE_DAYS3}   <br><br> {/foreach}

• Now when you click on the subscription button from the Menu, you should see your custom template instead of the default Subscription Browser screen created by Jamroom. You can customize the page to fully fit your design needs, and make use of the following variables available to you within the subscription "loop" (the part between the {foreach} tags in your template):

Variable	Description
$_sub.QUOTA_ID	The Jamroom Quota ID
$_sub.QUOTA_SUBSCRIBE	This variable will be set to yes/no depending on whether or not the "Allow Subscriptions" option has been set to yes or no.
$_sub.QUOTA_SUBSCRIBE_NAME	This is the descriptive name given for the Subscription
$_sub.QUOTA_SUBSCRIBE_DESC	The Description of the Subscription
$_sub.QUOTA_SUBSCRIBE_PLUG	The Payment Processor plug in selected for the Jamroom Quota
$_sub.QUOTA_SUBSCRIBE_TRIAL	The length of the Free Trial period for this subscription. Will be set to "0" (zero) if no Free Trial period is offered.
$_sub.QUOTA_SUBSCRIBE_CURRENCY	The Currency selected for this Subscription
$_sub.QUOTA_SUBSCRIBE_CURRENCY_SYMBOL	The HTML Entity of the currency symbol selected
$_sub.QUOTA_SUBSCRIBE_DAYS1	The subscription length Subscription option 1.  Will be set to 0 (zero) if No Selection is chosen.
$_sub.QUOTA_SUBSCRIBE_PRICE1	The Price for Subscription option 1
$_sub.QUOTA_SUBSCRIBE_URL1	The URL to subscribe to the Subscription option 1
$_sub.QUOTA_SUBSCRIBE_DAYS2	The subscription length Subscription option 2.  Will be set to 0 (zero) if No Selection is chosen.
$_sub.QUOTA_SUBSCRIBE_PRICE2	The Price for Subscription option 2
$_sub.QUOTA_SUBSCRIBE_URL2	The URL to subscribe to the Subscription option 2
$_sub.QUOTA_SUBSCRIBE_DAYS3	The subscription length Subscription option 3.  Will be set to 0 (zero) if No Selection is chosen.
$_sub.QUOTA_SUBSCRIBE_PRICE3	The Price for Subscription option 1
$_sub.QUOTA_SUBSCRIBE_URL3	The URL to subscribe to the Subscription option 1

Troubleshooting

Here are solutions to to some common issues that you might run into when working with the Jamroom Payments Pack:

• I've added a second Jamroom Quota to my available subscriptions, but it's not showing up in the Subscription Browser - what's wrong?
• Go into the Jamroom Quota Config for the Jamroom Quota that is not showing, and make sure the "Allow Subscriptions" option is set to "yes"

• When doing my testing with the PayPal Sandbox, it is not working and I am receiving "error 3005" or "error 3006" warnings - what's wrong?
• When testing with the PayPal Sandbox, you must be logged in to the PayPal Sandbox (PayPal Developer Central) in another browser window at all times, otherwise the PayPal Sandbox does not see your account, and will give you an error.