Subscriptions with the Hosted Payment Page

Learn how to use the Hosted Payment Page in conjunction with the Payment API to take advantage of BlueSnap's award-winning Subscription Engine. You use the Payment API to set up subscription billing plans and the Hosted Payment Page to enable the shopper to purchase a plan in order to create a subscription.

Step 1: Set up subscription billing plans

First, use the Payment API to send Create Plan requests in order to set up each of your subscription billing plans, which includes defining the billing frequency, amount, currency, and more.

Step 2: Generate the payment page

Generate the payment page by passing the applicable Hosted Payment Page Parameters. At a minimum, pass merchantid and plan[plan ID] so the payment page can be generated based on the plan's details (such as the price and billing frequency). For example, the following payment page URL has the Gold Plan's ID specified in the query string.

https://sandbox.bluesnap.com/buynow/checkout?plan12152782&merchantid=500801

Optionally, set plan[plan ID] to the default purchase quantity to be displayed on the payment page (if not set, the default quantity is 1). For example, if the shopper wants to purchase 3 Gold Plans, passing plan12152782=3 tells the payment page to display the details of the Gold Plan and set the default quantity to 3.

https://sandbox.bluesnap.com/buynow/checkout?plan12152782=3&merchantid=500801

Step 3: Get the subscription ID

Once the initial payment has been processed, BlueSnap assigns a subscription ID to the new subscription. Use this ID to manage the subscription in the future (more details on this in Step 4). Get the subscription ID via the Charge IPN (webhook), which is sent after the payment has been processed.

Step 4: Manage the subscription

The subscription ID enables you to manage the details associated with the subscription. For example, you can change the payment method or plan, cancel the subscription, and so on. To manage the subscription, use the Payment API to send an Update Subscription request.

Overriding plan details (initial charge amount, etc.)

The following parameters allow you to override various plan details for the subscription:

• amount — Overrides the initial charge amount of the plan.
• recurringamount — Overrides the recurring charge amount of the plan.
• trialperioddays — Overrides the trial period days of the plan.

The HTTP method used to generate the payment page determines how the parameters should be passed:

• GET — You get the encrypted token for the parameter(s) and pass the token within the query string of the payment page URL.
• POST — You can either pass the encrypted token for the parameter(s) or pass each parameter as plaintext when generating the payment page.

📘

Notes

• To encrypt parameters, make sure you've created API Credentials and a Data Protection Key.

• The currency of the plan cannot be overridden. If amount or recurringamount is passed, the parameter value is based on the currency of the plan.

Encrypting the parameters into a single token prevents the shopper from tampering with the values during checkout. To obtain the token, send an Encrypt Parameters request with the parameters and the values that you want to encrypt.

curl -v -X POST https://sandbox.bluesnap.com/services/2/tools/param-encryption \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<param-encryption xmlns="http://ws.plimus.com">
  <parameters>
    <parameter>
      <param-key>amount</param-key>
      <param-value>25</param-value>
    </parameter>
    <parameter>
      <param-key>recurringamount</param-key>
      <param-value>100</param-value>
    </parameter>
    <parameter>
      <param-key>trialperioddays</param-key>
      <param-value>14</param-value>
    </parameter>
  </parameters>
</param-encryption>'

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<param-encryption xmlns="http://ws.plimus.com">
    <encrypted-token>k9BV%2BCYFQv%2B3k077gfZj2uqEy1%2BYe0YdewFL%2B6NZ0F9%2Bi2OHfooGY%2FSJ8VVFPvvUsryjGRF5OUYtrlZf%2BXu5xA%3D%3D</encrypted-token>
</param-encryption>

Grab the encrypted token from the response and include it within enc when generating the payment page.

https://sandbox.bluesnap.com/buynow/checkout?enc=k9BV%2BCYFQv%2B3k077gfZj2uqEy1%2BYe0YdewFL%2B6NZ0F9%2Bi2OHfooGY%2FSJ8VVFPvvUsryjGRF5OUYtrlZf%2BXu5xA%3D%3D&plan12152782=3&merchantid=500801

Back to Top