We have used this API to integrate humm into leading shopping cart platforms such as Shopify, WooCommerce and Magento.
Communicating with humm involves the buyers' browser performing a HTTP POST to humm - authorisation request. Details provided below on expected format of request as well as response.
This is not an HTTP API and cannot be used for server to server communication.
POST to humm in the format
application/x-www-form-urlencoded and prefix all key names with
Below is an overview of the various key-value pairs that can be passed.
|x_account_id Required||humm Merchant ID||unicode string||123456||10|
|x_amount Required||Total amount including any taxes and shipping costs||decimal||99.90||12|
|x_customer_billing_address1||Billing address line 1||unicode string||111 Carlton Gore Rd||200|
|x_customer_billing_address2||Billing address line 2||unicode string||Level 1||200|
|x_customer_billing_city||Billing city||unicode string||Auckland||200|
|x_customer_billing_country||Billing country||iso-3166-1 alpha-2||NZ||3|
|x_customer_billing_state||Billing state||unicode string||NZ||200|
|x_customer_billing_postcode||Billing postcode||unicode string||1023||200|
|x_customer_email||Billing email address||unicode email@example.com||65|
|x_customer_first_name||Customer's first name||unicode string||John||50|
|x_customer_last_name||Customer's last name||unicode string||Appleseed||50|
|x_customer_phone||Customer's phone number||unicode string||0200 000 000||12|
|x_customer_shipping_address1||Shipping address line 1||unicode string||111 Carlton Gore Rd||200|
|x_customer_shipping_address2||Shipping address line 2||unicode string||Level 1||200|
|x_customer_shipping_city||Shipping city||unicode string||Auckland||200|
|x_customer_shipping_country||Shipping country||unicode string||NZ||3|
|x_customer_shipping_first_name||Customer's first name (Shipping)||unicode string||John||50|
|x_customer_shipping_last_name||Customer's last name (Shipping)||unicode string||Appleseed||50|
|x_customer_shipping_phone||Customer's phone number (Shipping)||unicode string||0200 000 000||12|
|x_customer_shipping_state||Shipping state||unicode string||NZ||200|
|x_customer_shipping_postcode||Shipping postcode||unicode string||1023||200|
|x_description||Item's description as setup in the shopping cart||unicode string||Order #767||200|
|x_reference Required||Reference no. assigned by the shopping cart||ascii string (max length 250 bytes)||19783||250|
|x_shop_country Required||Merchant's store country||iso-3166-1alpha-2||NZ||3|
|x_shop_name Required||Shopping cart store name||Shop Inc||200|
|x_signature Required||Request payload that is signed using HMAC-SHA256||hex string, case-insensitive||See Signature Generation||64|
|x_url_callback Required||Async-callback sent to this URL. must be HTTPS||URL||https://shop.co.nz/callback||200|
|x_url_cancel Required||Cancelled orders redirected to this URL||URL||https://shop.co.nz/cancel||200|
|x_url_complete Required||Approved orders redirected to this URL||URL||https://shop.co.nz/compete||200|
|x_transaction_timeout||Transaction timeout in minutes. Maximum is 1440.||int||60|
Below is a sample POST request in
application/x-www-form-urlencoded format. This is a sample POST so ignore values for individual keys
POST and GET responses
Once a transaction is processed, humm will send two responses: 1) the async-callback POST and 2) the redirect GET.
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 includes key-values pairs specific to the transaction such as it's outcome.
x_url_callbackshould specifiy a HTTPS URL as the POST response must be sent over HTTPS
The HTTP GET (HTTP) is to the client on the
Both the POST and GET will contain the same set of key-value pairs as shown below.
Response POST/GET values
Below is an overview of the key-value pairs that humm returns.
Some of these key-value echo corresponding key-value pairs in the request, such as
|x_account_id||humm Merchant ID||Unicode string||123456|
|x_reference||Reference no. assigned by the shopping cart||ASCII string||19783|
|x_amount||Total amount including any taxes and shipping costs||decimal||99.90|
|x_gateway_reference||humm reference number||unique string||123|
|x_purchase_number||humm reference number Same as x_gateway_reference||unique string||123|
|x_timestamp||Time at which transaction is completed||iso-8601 in UTCYYYY-MM-DDTHH:MM:SSZ||2017-06-24T12:11:43Z|
|x_result||Transaction outcome||Valid values are completed or failed||completed|
|x_signature||Response payload that is signed using HMAC-SHA256||hex string, case-insensitive||See Signature Generation|
Validating humm Responses
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. If there is a mistmatch, then the response should be disregarded.
For more information on how to calcualte the signature, see Signature Generation.
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.
|x_reference||The shopping cart reference for the order||ASCII string||19783|
|x_result||The status of the order from your shopping cart's perspective, NOT a copy of the status from the initial async-callback||ASCII string||Approved, Declined|