Checkout API
Checkout Process
Chart summarising transaction flow using humm
Step 1: Customer places an order and selects humm as payment option.
Step 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).
Step 3: Customer completes their purchase on humm. Customers that cancel are redirected back to the x_url_cancel URL.
Step 4: humm either Approves or Declines the order and then POSTs (Server to Server) to the x_url_callback URL (See Response POST content).
Step 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.
Step 6: The transaction is now complete on both humm and the shopping cart.
Step 7: Shopping cart sends a final POST (acknowledgment) to confirm order completion.
Humm Endpoints
| Humm Environment | URL |
|---|---|
| Production Endpoint | https://cart.shophumm.co.nz/Checkout?platform=Default |
| Sandbox Endpoint | https://integration-cart.shophumm.co.nz/Checkout?platform=Default |
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.
Request values
| Key | Description | Type | Example | Length |
|---|---|---|---|---|
| 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_currency Required | Currency | ISO-4217 | NZD | 3 |
| 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_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 | AUK | 200 |
| x_customer_billing_postcode | Billing postcode | unicode string | 1023 | 200 |
| x_customer_email | Billing email address | unicode string | user@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 | AUK | 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_transaction_timeout | Transaction timeout in minutes. Maximum is 1440. | int | 60 | |
| x_test Required | Set to False, needed for backwards compatibility | False | False | |
| 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_signature Required | Request payload that is signed using HMAC-SHA256 | hex string, case-insensitive | See Signature Generation | 64 |
Even though there's not states in New Zealand, you’d still need to populate x_customer_shipping_state and x_customer_billing_state with a value. Three letter abbreviations for NZ regions as per ISO 3166-2:NZ would be sufficient.
Example: "AUK" for Auckland or "STL" for Southland.
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=NZD&x_url_callback=sample_callback_url&x_url_complete=sample_complete_url&x_shop_country=NZ&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=NZ&x_customer_billing_city=Auckland&x_customer_billing_address1=97+Pirie&x_customer_billing_address2=St&x_customer_billing_state=AUK&x_customer_billing_zip=1023&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 and 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
x_url_callbackshould 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.
| Key | Description | Type | Example |
|---|---|---|---|
| x_account_id | humm Merchant ID | Unicode string | 123456 |
| x_reference | Reference no. assigned by the shopping cart | ASCII string | 19783 |
| x_currency | Currency | ISO-4217 | NZD |
| 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_test | Indicates whether this is a production or test transaction | True/False | True |
| x_signature | Response payload that is signed using HMAC-SHA256 | hex string, case-insensitive | See Signature Generation |
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 mistmatch, the response should be disregarded.
For more information on how to calcualte 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.
| Key | Description | Type | Example |
|---|---|---|---|
| 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 |