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:
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: 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: 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.
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:
https://api.payhyper.com/v1for the live mode, or
https://sandbox-api.payhyper.com/v1for 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
<anything>-<delay>-s@<anything> would turn the order
<delay> seconds. Any email of the form
<anything>-<delay>-f@<anything> would turn the order into
<delay> seconds. For example, using
firstname.lastname@example.org turns the order
successful after 30 seconds. In both cases,
the order turns
scheduled at half the specified
<delay> has to be a positive integer.