Hyper

Overview

Using the Hyper service allows a merchant (such as yourself) to accept cash payments easily. Whenever an end-user wants to purchase an item from your website, your website's backend issues an API call to Hyper to create an order. An order amounts to a cash collection of a particular amount from a particular end-user (identified by the combination of an email address and a phone number). Hyper then organizes a pickup time with the end-user, and picks up the requested amount. As the status of your order changes, your backend is informed through the Asynchronous Notifications Interface (ANI).

The following figure depicts the life-cycle of an order from the moment the end-user purchases an item on your website, to the moment you fulfill the purchase.

The steps depicted in the figure are as follows:

1. The end-user browses the merchant's website and places a purchase.
2. The merchant uses the Hyper API to create an order.
3. The cash collection is performed (including scheduling a pickup time and address).
4. Hyper informs the merchant of the success of the order through the ANI.
5. The merchant fulfills the end-users purchase (for example, delivers a virtual good to his account).

Statuses of an Order

The previous section mentions that the merchant is updated through the ANI when an order is successfully completed. In fact, the merchant is updated on every status change of an order (not only when it turns successful). An order can be in one of four statuses:

• unscheduled: This is the status of a new order. The end-user has not been contacted yet to schedule a pickup time and location. The only possible status change from this status is scheduled or failed.
• scheduled: The end-user has been contacted, and a pickup time and location has been scheduled. The only possible status change from this status is successful or failed.
• successful: The amount has been picked up and cleared. The merchant should fulfill the purchase. No changes to the order can happen once it has reached this status.
• failed: The amount could not be picked up. This can be due to a number of reasons such as the end-user could not be contacted after multiple trials, or declined paying. No changes to the order can happen once it has reached this status.

Live Mode and Sandbox Mode

The fact that calls to the API initiate real-life processes (such as contacting the end-user) creates a hassle when a developer would like to test the API and play around with it. For this purpose, Hyper includes a sandbox mode in which no real-life processes are initiate for any action.

The sandbox mode is a complete separate system from live mode. This includes both the web interface and the API. Any changes done in the sandbox mode are never reflected to the live mode, and it is therefore safe to perform any action in the sandbox.

You are currently in the live mode. To switch between the sandbox mode and the live mode:

• In the web interface: Use the toggle switch in the navigation bar at the top.
• In API calls: Connect to https://api.payhyper.com/v1 for the live mode, or https://sandbox-api.payhyper.com/v1 for the sandbox mode, and use the correct corresponding Access Key. The use of your Access Key is explained in more detail in the API Documentation.

When in the sandbox, the cash-collection step (step 3 from the figure above) is not performed. To allow the testing of the ANI, a bot simulates the changes that would happen to the system if step 3 was to be performed. You can control this bot by including some information in the email field when creating the order. In particular, any email of the form <anything>-<delay>-s@<anything> would turn the order successful after <delay> seconds. Any email of the form <anything>-<delay>-f@<anything> would turn the order into failed after <delay> seconds. For example, using [email protected] turns the order successful after 30 seconds. In both cases, the order turns scheduled at half the specified <delay>. Notice <delay> has to be a positive integer.