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
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.
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/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.