Checkout API
humm Checkout Process
![](https://files.readme.io/6713e37-image.png)
- Customer places an order and selects humm as payment option.
- 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).
- Customer completes their purchase on humm. Customers that cancel are redirected back to the
x_url_cancel
URL. - humm either Approves or Declines the order and then POSTs (Server to Server) to the
x_url_callback
URL (See Response POST content). - 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. - The transaction is now complete on both humm and the shopping cart.
- Shopping cart sends a final POST (acknowledgment) to confirm order completion.
humm Endpoints
humm Environment | URL |
---|---|
Production | https://cart.shophumm.com.au/Checkout?platform=Default |
Sandbox | https://integration-cart.shophumm.com.au/Checkout?platform=Default |
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.
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 | AUD | 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 | AU | 3 |
x_shop_name Required | Shopping cart store name | Shop Inc | 200 | |
x_customer_billing_address1 | Billing address line 1 | unicode string | 97 Pirie St | 200 |
x_customer_billing_address2 | Billing address line 2 | unicode string | Level 6 | 200 |
x_customer_billing_city | Billing city | unicode string | Adelaide | 200 |
x_customer_billing_country | Billing country | iso-3166-1 alpha-2 | AU | 3 |
x_customer_billing_state | Billing state | unicode string | SA | 200 |
x_customer_billing_postcode | Billing postcode | unicode string | 5000 | 200 |
x_customer_email | Billing email address | unicode string | [email protected] | 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 | 0400 000 000 | 12 |
x_customer_shipping_address1 | Shipping address line 1 | unicode string | 97 Pirie St | 200 |
x_customer_shipping_address2 | Shipping address line 2 | unicode string | Level 6 | 200 |
x_customer_shipping_city | Shipping city | unicode string | Adelaide | 200 |
x_customer_shipping_country | Shipping country | unicode string | AU | 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 | 0400 000 000 | 12 |
x_customer_shipping_state | Shipping state | unicode string | SA | 200 |
x_customer_shipping_postcode | Shipping postcode | unicode string | 5000 | 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.com.au/callback | 200 |
x_url_cancel Required | Cancelled orders redirected to this URL | URL | https://shop.com.au/cancel | 200 |
x_url_complete Required | Approved orders redirected to this URL | URL | https://shop.com.au/compete | 200 |
x_signature Required | Request payload that is signed using HMAC-SHA256 | hex string, case-insensitive | See Signature Generation | 64 |
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:
- The async-callback POST
- 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.
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 | AUD |
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 UTC YYYY-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 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.
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 |
Updated 10 days ago