Checkout API

humm Checkout Process

1. Customer places an order and selects humm as payment option.
2. Customer redirected to humm checkout page via a POST (See Request POST for details). This POST is signed to ensure it's security (See Signature Generation for details).
3. Customer completes their purchase on humm. Customers that cancel are redirected back to the x_url_cancel URL.
4. humm either Approves or Declines the order and then POSTs (Server to Server) to the x_url_callback URL (See Response POST content).
5. Customer is also presented with an 'Approved' or 'Declined' page and redirected (GET) to the x_url_complete URL with the same response content in Step 4.
6. The transaction is now complete on both humm and the shopping cart.
7. Shopping cart sends a final POST (acknowledgment) to confirm order completion.

humm Endpoints

📘

Info

All Humm API requests are required to be secured using TLS 1.2 or greater

Request POST

POST to humm in the format application/x-www-form-urlencoded and prefix all key names with x_

Below is an overview of the various key-value pairs that can be passed.

Sample POST

Here is a sample POST in application/x-www-form-urlencoded format.

x_reference=123&x_account_id=1&x_amount=100.00&x_currency=AUD&x_url_callback=sample_callback_url&x_url_complete=sample_complete_url&x_shop_country=AU&x_shop_name=Sample+Shop&x_customer_first_name=first&x_customer_last_name=last&x_customer_email=sample%40email.com&x_customer_billing_country=AU&x_customer_billing_city=Adelaide&x_customer_billing_address1=97+Pirie&x_customer_billing_address2=St&x_customer_billing_state=SA&x_customer_billing_zip=5000&x_description=Sample+Store+-+%123&x_url_cancel=sample_cancel_url&x_signature=dummy_signature

Response POST/GET

Once a transaction is processed, humm will fire off two responses at the same time:

1. The async-callback POST
2. The redirect GET and both will contain the same key-value pairs.

The POST is an asynchronous server-to-server call to the shopping cart on the x_url_callback URL in the application/x-www-form-urlencoded format. It is mainly there for scenarios where the GET redirect cannot take place due to user closing their browser on humm approved/declined screens

📘

Note

x_url_callback should specifiy a HTTPS URL as the POST response must be sent over HTTPS

The HTTP GET (HTTP) is a redirect from the browser to the cart on the x_url_complete URL.

Response POST/GET Values

Here is a list of the key-value pairs that humm returns.

Validating Response POST/GET

The x_signature in the POST and GET responses must validated by the shopping cart to ensure it's not tampered with by a third-party and in cases where there is a mismatch, the response should be disregarded.

For more information on how to calculate the signature, see Signature Generation.

Callback Acknowledgement

To confirm to humm that the async-callback POST was correctly received by your cart, you need to respond with an acknowledgement that is human-readable and does not exceed 1000 characters. Common errors include responding with a full HTML page.

A JSON with the following key-value pairs is sufficient.