Integration Guidelines

Here we provide some guidelines regarding how to change your front-end to accommodate Hyper. These guidelines are divided into two parts: requirements (that must be met), and recommendations (that only form suggestions).

This section also includes a set of artwork that you may use in your integration. Please do not hot-link the artwork as its location might change, instead, download the artwork that you will be using and host it yourself.


Requirements

Include a Cash Payment Method

The list of payment options at checkout on your website should include a "Cash" option. If you include artwork for different payment methods, we provide four options for such artwork that you may (but are not required to) use.

Include the Hyper Logo

The Hyper logo should be included somewhere in the checkout process, and should be linked to http://payhyper.com/. We provide two possible logos to use.


Collect the Email and Phone Number of End-Users

You have to collect the email and phone number of your end-users to place an order. We require you to allow both fields to be edited by the user, but the fields can be pre-filled with any information already on file.

Regarding the phone number field, we recommend having a separate field to select the country code, and instructions on examples of field values to avoid validation errors.


Recommendations

Explain the Process to Your End-User

We recommend you explain to your end-user how the process of cash collection will occur. Since Hyper is providing an entirely new method of payment it is important that your users know what to expect between the online and offline steps. This does not entail a full explanation of the entire transaction cycle, as the flow of Hyper's service introduces itself as it happens.

At the point of checkout, the main points to highlight to the user are:

  • After your order is placed, you will be contacted by one of our representatives within 24 hours to arrange for a cash collection.
  • Once the amount is successfully collected, your order will immediately be cleared and fulfilled to you.
You may use the literal text from the previous two points, or rephrase them or translate them as you see suitable.

We are also providing the following artwork to illustrate each of the points above:

Limit to Participating Countries

Currently, the Hyper service is only available in Jordan. We recommend, if possible, that you limit this visibility of this payment options to countries where it applies only.

Pre-Validate and Report Errors

It is possible for validation errors to occur when creating an order. This could occur, for example, if the phone number provided by the end user does not match the requirements (as documented in the endpoints).

Putting instructions next to the fields the user has to fill helps lower validation errors, however, validation errors are still possible. It is important to let the end-user know when such a validation error happens. It is possible to catch such an error in one of three places:

  1. On the client-side, using Javascript.
  2. At your server, prior to doing the API call.
  3. After doing the API call and receiving a 422 status code.

We recommend you perform pre-validation (that is, validation the client-side or your server prior to making the API call). To understand what criteria is required for validation, please check the endpoints. Should your validations miss any conditions, you could also report back errors that are delivered with 422 responses. These errors are user-friendly, but are provided in English only. Once you catch an error in validation, make sure to report it to your user in a prominent manner.

Using the bindings make the task of pre-validation and catching the 422 status code easier.

Send Email on Fulfillment

Once you receive a notification on your ANI reporting the success of an order, and after you fulfill that order, we recommend you send an email to the end-user informing him that his purchase has been fulfilled.