Developer Area

The Hosted Pages are a set of interconnected pages that can operate as a standalone application, but in some cases you want to open the hosted pages on a specific page or to start a specific customer workflow.

Here are a few examples:

• After a sign-up, you need to start the subscription workflow to a given plan.
• You need your customer to upgrade one of their subscription to a custom-made one.
• You need to send your leads a link to subscribe to a private plan.

Note that most actions are already available and optimized in the hosted pages in the customer portal, so you don’t need to manage all the cases. Use this only if you really need dedicated customer workflows in your web application.

How it works

Pages are opened client-side. To avoid exposing sensitive information, the opening parameters are encrypted. We call the encrypted parameters a query.

The queries are generated in the Links array by the API Live when creating or retrieving some of the objects.

Example: GET /v1/Customer

{
  "Id": 1066136,
  "ReferenceCustomer": "cust-19847",
  ...
  "Links": [
    {
      "rel": "hosted-home",
      "href": "https://my-service.com/billing"
    },
    {
      "rel": "hosted-collection-offers",
      "query": "bvio5ZTZJOBmj2AvkFGZfrsD60tPJWoICRuc9nCUhMRpRqI0JU8Y0jLsRTEGncmoRshJx3GzVp8NRUuKnDsauqCU5DkAkeJmGAqI"
    },
    {
      "rel": "hosted-register",
      "query": "vkFGZfrsD60tPJWoICRuc9nCUhMRpRqI0JU8Y0jLsRTEGncmoRshJx3GzVp8NRUuEXfI9UF6VZ3w-lbfeC84f2DpMVPIuZnKOl6KA"
    }
  ]
}

Available queries

Object	Rel	Opened page	Use cases
Customer	hosted-collection-offers	Opens the catalog workflow, allowing the customer to subscribe.	You just created a customer, and you send them to the subscription workflow. You want a customer to subscribe to an extra subscription.
Customer	hosted-register	Opens a workflow allowing the customer to fill-in their contact information and payment method.	You need all the contact and payment information registered and verified to bill the customer later on.
Customer	hosted-collection-upgrade	Opens the catalog workflow, allowing the customer to change its current plan.	The customer wants to upgrade a given subscription.
Customer	hosted-subscribe	Opens the subscription workflow on the specified plan.	You just created a customer and you want them to subscribe to a specific plan.
Subscription	hosted-related-subscription	Opens the customer portal on the given subscription.	The customer has many subscriptions, one of those requiring their immediate attention.
Subscription	hosted-subscribe	Opens the workflow to subscribe to the given draft subscription.	You want the customer to subscribe to a custom subscription you created.
Subscription	hosted-register	Opens a workflow allowing the customer to fill-in their contact information and payment method. Only if the subscription has a delayed start.	You need all the contact and payment information registered and verified to bill the customer when the subscription starts.
Subscription	hosted-upgrade (1)	Opens the catalog workflow allowing the customer to change its current plan. Only if the subscription is active.	You need the customer to change the plan of the given subscription.
Subscription	hosted-upgrade (2)	You provided a plan. Opens the change plan workflow, allowing the customer to change the plan of one of its current subscription to the given plan.	You need the customer to change the plan of the given subscription to given plan.
Subscription	hosted-upgrade (3)	You provided a previous subscription. Opens the change plan workflow, allowing the customer to change the plan of one of its current subscription to the given one.	You need the customer to change the plan of the given subscription to a custom subscription you just created.
Subscription	hosted-restart	Opens a workflow allowing the customer to restart a suspended subscription.	The subscription had been interrupted and you want the customer to resume it.
Invoice	hosted-charge	Opens a workflow allowing the customer to pay a due invoice.	You need the customer to pay a given invoice.
Offer	hosted-subscribe (1)	Opens a workflow allowing an anonymous user to subscribe. Anonymous subscription (not recommended) must be enabled.	You want a non-declared user to subscribe.
Offer	hosted-subscribe (2)	You provided a customer. Opens the workflow to subscribe to the given plan.	You want a customer to subscribe to a given plan.
Offer	hosted-upgrade	You provided a subscription. Opens the workflow to change the plan of the given subscription to the given plan.	You want a customer to change its subscription to a given plan.

Methods

There are 2 methods you can use to send a customer to a specific page.

Those methods are not exclusive: advanced integration may use both to support a wide range of use cases.

Method 1) Use the installation page

This solution is the easiest, but it works only :

• if your customer is authenticated
• if you have configured an installation URL (check it here)

The biggest advantage of this solution is that you can generate secured links to send in an email to the customer in case you have a very specific need that is not covered by the customer emails already sent by ProAbono.

Step 1 – Fetch the object

Use the API Live to create or retrieve the related object.

Don’t forget any additional parameters required by the query you need.

Example: GET /v1/Customer

{
  "Id": 1066136,
  "ReferenceCustomer": "cust-19847",
  ...
  "Links": [
    {
      "rel": "hosted-home",
      "href": "https://my-service.com/billing"
    },
    {
      "rel": "hosted-subscribe",
      "query": "bvio5ZTZJOBmj2AvkFGZfrsD60tPJWoICRuc9nCUhMRpRqI0JU8Y0jLsRTEGncmoRshJx3GzVp8NRUuKnDsauqCU5DkAkeJmGAqI"
    }
    ...
  ]
}

Step 2 – Build the link

The link rel=hosted-home contains the Installation URL.

Append a pa_query parameter to that link using the query you need.

Example:

https://my-service.com/billing?pa_query=bvio5ZTZJOBmj2AvkFGZfrsD60tPJWoICRuc9nCUhMRpRqI0JU8Y0jLsRTEGncmoRshJx3GzVp8NRUuKnDsauqCU5DkAkeJmGAqI

That’s all. That link will open the required hosted page. You can redirect your customer to that page or send it as a link in an e-mail.

Method 2) Dynamic hosted page

With this method you can open the required hosted page on any page of your web application.

Step 1 – Fetch the object

It’s the exact same step as the Method 1.

Step 2 – Open the portal with the query

The method is very similar to the In-site installation.

In the head of the page, append the ProAbono library.

<script type="text/javascript"> src="https://portal.proabono.com/Get/portal.js"></script>

Where you want the page to open, append a <div>

<div> id="proabono_portal"></div>

Anywhere in the page, open the hosted pages

<script type="text/javascript">
  ProAbonoPortal.open({
    business_id: XX,
    segment_ref: 'XXX',
    customer_ref: 'XXX',
    query: 'OBmj2AvkFGZfrsD60tPJWoICRuc9nCUhMRpRqI0JU8Y',
    hash: '29d8b6e5edab22dccac0d60bd3377a2349331e314e752d6bf0731e7c3c22bc29'
  });
</script>

Check In-site installation for more information about this method.