SubscriptionBridge: recurring billing and subscription management system - Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Shopping Cart Integration:  Magento - Specifications ======

===== Overview =====

This document includes the specifications that were used in the Magento Extension for SubscriptionBridge.

===== Store Administration =====

==== Activation ====

  * The Magento store manager will have access to a page where he/she can enter their **SubscriptionBridge API Credentials**. The page provide a link to the [[:cartintegration:productcart:pc_api_credentials|instructions on how to obtain their API credentials]]. This will provide a way for the store to be authorized to communicate with SubscriptionBridge.
  * The activation process is accomplished using the [[:developer_guide:call_reference:ActivationRequest|ActivationRequest]] call in the SubscriptionBridge API.
  * Once the //ActivationRequest// has been executed successfully, the system will capture the response and parse it, looking for the "Ack" element. If "Ack" has a value of "Success", then the activation was a success. If the activation was not a success then check for a "Error" element in the XML. If the error element exists you can parse out the "ErrorCode" and "ErrorDetail" so you can display a message to the user.  

----

Here is an example of the "SubscriptionBridge Activation" page in the [[cartintegration:productcart:productcart|ProductCart]] integration:

{{:developer_guide:developer_guide:sb_integration_activation.png|SubscriptionBridge activation in ProductCart}}

----
==== Linking Products and Packages ====

The Magento store administration area will provide a way for the merchant to associate items that exist in the store catalog with the corresponding //package// in the merchant's SubscriptionBridge store. This will be accomplished as follows:

  - Search the store catalog.  Products already linked to a subscription package should not appear in the search results.
  - Select a product
  - Select a subscription package to link it to. \\ This can be done by showing a drop-down menu populated by the [[:developer_guide:call_reference:GetPackagesRequest|GetPackagesRequest]]. The drop-down is populated with all packages that exist in the merchant's SubscriptionBridge store, and that have not already been associated with other products in the store catalog. It is important to note that __the option value in the drop down must be the package "LinkID" that is returned by GetPackagesRequest__. 
  - Make sure that the relationship is unique: the same package should __only__ be associated __with one product__ in the store catalog
  - Prompt the merchant to specify whether:
    - There is a trial
    - What the trial price is \\ This is done so that when customers search or browse the store, the subscription price is shown (e.g. $49.95), but when they checkout, the actual price paid today is shown (e.g. $0). The [[:developer_guide:developer_guide:terms_widget|Terms Widget]] provides the details on exactly what the terms are (e.g. //FREE for the first month. $49.95 per month after the Trial//).
    - Whether there are Terms & Conditions that the customer must agree to before purchasing the subscription \\ This should be a texarea field where the merchant may enter T&C for the subscription. If T&C are entered:
      - Show the T&C during checkout (wherever it is easier to do so in Magento). For example, they could be shown on the payment page
      - Require that the customer agree to the T&C before purchasing the subscription 
  - Save the product - package association

Here is an example of how the product-package link screen looks in the [[cartintegration:productcart:productcart|ProductCart]] integration:

{{:developer_guide:developer_guide:sb_integration_packagelink.png|Creating and editing a package link}}

----

==== View / Modify Linked Packages ====

The Magento store administration area will provide a way for the merchant to review and edit the existing //product-package associations//.
==== Settings (text strings) ====

There are text strings that will be shown in the storefront that are specific to the SubscriptionBridge integration. The store manager should have control on what is shown. Specifically:

  * Message to show when: **Shopping cart in use for subscription** \\ For example: "//The shopping cart is currently in use for purchasing a subscription. At this time, you can not add additional products to the cart. If you would like to purchase additional items, please complete the current order and then place a new one (this can be done very quickly as your customer information will have already be entered). Alternatively, you can empty the shopping cart and add different products. <a href="">View shopping cart</a>.//"
  * Message to show when: **Shopping cart in use** \\ For example: "//The shopping cart is currently in use. At this time, you can not add a subscription product to the cart. If you would like to purchase subscription items, please first complete the current order and then place a new one (this can be done very quickly as your customer information will have already be entered). Alternatively, you can empty the shopping cart and add different products. <a href="">View shopping cart</a>//"
  * Tex strings related to Terms & Conditions \\ For example:
    * //Terms & Conditions//
    * //Please read and agree to the terms & conditions listed below//
    * //I agree to the Terms & Conditions//
  * Message to show on payment page to **inform customer of credit card authorization** \\ For example: "//$1 Authorization: We will validate your credit card by performing a $1 authorization. Once authorized, the transaction will immediately be voided. This authorization is performed because our billing system will charge the actual subscription amount at a different time (later today).//"

===== Storefront =====
==== Add to Cart ====

=== Limitation: one subscription, no other products ===

The //Add to Cart// mechanism will be modified so that:

  - only 1 subscription product can be added to the shopping cart
  - non-subscription products cannot be added if a subscription product exists already in the shopping cart

The customizable messages mentioned above under //Settings// are shown to the customer when these scenarios occur.

This limitation exists to avoid __complex scenarios__, such as:

  * separating the subscription's price from the other items when a discount is used
  * calculating which portion of the total tax should be added to the subscription (if taxable)
  * calculating which portion of the total shipping charges (if the subscription contains shippable products)

=== Preparing the data you will need ===

Also during the //Add to Cart// process you will need to consider the data you will need after payment is rendered.  If you use an array or database to store the cart contents, then this is a good time to get the data you need for checkout.  You will be creating a [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] that will generate the recurring billing in your SubscriptionBridge Merchant Center.  Please review the [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] and make sure you are saving all the required information.

For instance, you may want to save the following:

  * The LinkID of the product/package in the cart
  * A flag indicating if there is a trial
  * The trial price, if applicable

==== Displaying Subscription Payment Terms ====

SubscriptionBridge includes a **simple widget** that allows you to display subscription payment terms without having to store that information in the store database. You can place the widget in the HTML source code and pass into the widget the "LinkID" of the package. The widget will communicate with SubscriptionBridge to display the most up-to-date pricing information. Learn about the [[:developer_guide:developer_guide:terms_widget|Terms Widget]].

The Magento storefront will display the subscription payment terms, via the Terms Widget:

  - On the **product details page** \\ This ensures that the customer can visually, immediately recognize the product as a subscription product, and see what the subscription terms are.
  - On the **shopping cart page** \\ This ensures that the customer knows that a subscription product has been added to the shopping cart.
  - On the **payment page** \\ This ensures that the customer is reminded of exactly what the subscription terms are at the time the order is finalized.

Here is an example of the Terms Widget shown on the shopping cart page on a [[cartintegration:productcart:productcart|ProductCart-powered]] store.

{{:developer_guide:developer_guide:sb_cart_widget.png|SubscriptionBridge's subscription terms widget}}
==== Checkout and subscription creation ====

The checkout flow will be the standard Magento checkout flow until the payment page. The system will detect that the customer is checking out with a subscription and redirect to a special payment page that will communicate with SubscriptionBridge to setup the new subscription by executing a [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] call.

The Magento storefront will gather all the information needed for the  [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] call, which includes:

  * trial total
  * total
  * trial tax
  * tax
  * trial shipping
  * shipping

[[:developer_guide:developer_guide:recommended#an-example|See an example]] of what this information might look like.

=== Coupons, discounts, and trial price ===

Customers might be eligible for a discount or apply a coupon during checkout.

  - If a coupon or a discount is applied during checkout, it will affect the regular subscription amount (//total//)
  - Coupons and discounts do not affect the //trial total// (if a trial exists)

When a discount applies, the subscription terms shown by the Terms Widget will not match the subscription amount that the customer will be paying. This is not a problem. The discrepancy is explained to the customer by the merchant by using the [[:developer_guide:developer_guide:terms_widget#adding-and-editing-the-third-line|third line of the Terms Widget]].

=== Incompatible payment options ===

Incompatible payment options will be disabled in the storefront when a subscription is being purchased. The customer will be taken automatically to the only payment option supported, which is the payment form that you have created to pass information to the SubscriptionBridge API via the [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] call.

=== Payment terms ===

The payment screen is the final opportunity to be clear about the pricing terms for the subscription that the customer is signing up for. Therefore, it will display the subscription terms via the [[:developer_guide:developer_guide:terms_widget|Terms Widget]].

=== Terms and Conditions ===

As mentioned above when defining how a product is linked to a package, if Terms & Conditions have been entered, the customer should be required to agree to the T&C before being able to submit the payment form.

=== Creating the subscription ===

After the payment form is submitted, the Magento storefront will contact SubscriptionBridge to create the new subscription through the [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionRequest]] call.

The system will validate the [[:developer_guide:call_reference:subscriptionrequest#subscriptionresponse|SubscriptionResponse]] a confirmation is shown. If there are any errors you should redirect back to the payment page and display the error message to the customer.  

Once you get a "Ack" (Acknowledgment) of "Success", parse the "GUID" from the response and save it to your database.  The GUID is the only information you will need to save from the response. It uniquely identifies a specific subscription. With the GUID you can access all API Methods. We recommend that you save this information in the table where order information is saved, or in a separate table that references the order ID.

===== After the purchase =====
==== Administration area ====

The merchant will be able to see a report of orders that contained a subscription. This new page in the Magento store administration area will include:

  * Order ID
  * Order Date
  * Customer Name
  * Product Name
  * Link to the SubscriptionBridge Merchant Center so that the merchant may manage the subscription. The syntax for the link should be as follows, where <GUID> is the identifier for the subscription associated with the order:

<code>https://www.subscriptionbridge.com/MerchantCenter/SubscriptionslistDetails.asp?SubscriptionUID=<GUID></code>

=== Limitation: no changes to order details page ===

Due to restrictions in the ability to edit the standard order details page, the standard order details page in the Magento store administration area will not contain details on whether the order contains a subscription.

==== Customer account area ====

The customer account management area will include a way for the customer to "Manage by subscriptions"

  * Detect whether the customer has placed an order for a subscription
  * Link to a page that lists those orders
  * Provide a link to the SubscriptionBridge Customer Center. 

The syntax for the link to the SubscriptionBridge Customer Center should be as follows, where <GUID> is the identifier for the subscription associated with the order, <MODE> is the landing page (list of landing pages below), and <EMAIL> is the customer's e-mail address (which was passed to SubsriptionBridge via the SubscriptionRequest call):

<code>https://www.subscriptionbridge.com/CustomerCenter/AutoLogin.asp?ID=<GUID>&Email=<EMAIL>&mode=<MODE></code>

== Landing Pages <MODE> ==

  * **Detail** \\   Replace <MODE> with "details" to send the customer to the subscription details page.
  * **Transaction History** \\  Replace <MODE> with "history" to send the customer to the transaction page.
  * **Edit Billing** \\  Replace <MODE> with "billing" to send the customer to the billing details page.
  * **Edit Shipping** \\  Replace <MODE> with "shipping" to send the customer to the shipping details page.
  * **Cancel Subscription** \\   Replace <MODE> with "cancel" to send the customer to the subscription cancellation page.