Guides

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.

KeyDescriptionTypeExampleLength
x_account_id Requiredhumm Merchant IDunicode string12345610
x_amount RequiredTotal amount including any taxes and shipping costsdecimal99.9012
x_currency RequiredCurrencyISO-4217AUD3
x_reference RequiredReference no. assigned by the shopping cartascii string (max length 250 bytes)19783250
x_shop_country RequiredMerchant's store countryiso-3166-1alpha-2AU3
x_shop_name RequiredShopping cart store nameShop Inc200
x_customer_billing_address1Billing address line 1unicode string97 Pirie St200
x_customer_billing_address2Billing address line 2unicode stringLevel 6200
x_customer_billing_cityBilling cityunicode stringAdelaide200
x_customer_billing_countryBilling countryiso-3166-1 alpha-2AU3
x_customer_billing_stateBilling stateunicode stringSA200
x_customer_billing_postcodeBilling postcodeunicode string5000200
x_customer_emailBilling email addressunicode string[email protected]65
x_customer_first_nameCustomer's first nameunicode stringJohn50
x_customer_last_nameCustomer's last nameunicode stringAppleseed50
x_customer_phoneCustomer's phone numberunicode string0400 000 00012
x_customer_shipping_address1Shipping address line 1unicode string97 Pirie St200
x_customer_shipping_address2Shipping address line 2unicode stringLevel 6200
x_customer_shipping_cityShipping cityunicode stringAdelaide200
x_customer_shipping_countryShipping countryunicode stringAU3
x_customer_shipping_first_nameCustomer's first name (Shipping)unicode stringJohn50
x_customer_shipping_last_nameCustomer's last name (Shipping)unicode stringAppleseed50
x_customer_shipping_phoneCustomer's phone number (Shipping)unicode string0400 000 00012
x_customer_shipping_stateShipping stateunicode stringSA200
x_customer_shipping_postcodeShipping postcodeunicode string5000200
x_descriptionItem's description as setup in the shopping cartunicode stringOrder #767200
x_transaction_timeoutTransaction timeout in minutes. Maximum is 1440.int60
x_test RequiredSet to False, needed for backwards compatibilityFalseFalse
x_url_callback RequiredAsync-callback sent to this URL. must be HTTPSURLhttps://shop.com.au/callback200
x_url_cancel RequiredCancelled orders redirected to this URLURLhttps://shop.com.au/cancel200
x_url_complete RequiredApproved orders redirected to this URLURLhttps://shop.com.au/compete200
x_signature RequiredRequest payload that is signed using HMAC-SHA256hex string, case-insensitiveSee Signature Generation64

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.

KeyDescriptionTypeExample
x_account_idhumm Merchant IDunicode string123456
x_referenceReference no. assigned by the shopping cartASCII string19783
x_currencyCurrencyISO-4217AUD
x_amountTotal amount including any taxes and shipping costsdecimal99.90
x_gateway_referencehumm reference numberunique string123
x_purchase_numberhumm reference number (Same as x_gateway_reference)unique string123
x_timestampTime at which transaction is completediso-8601 in UTC
YYYY-MM-DDTHH:MM:SSZ
2017-06-24T12:11:43Z
x_resultTransaction outcomeValid values are completed or failedcompleted
x_testIndicates whether this is a production or test transactionTrue/FalseTrue
x_signatureResponse payload that is signed using HMAC-SHA256hex string, case-insensitiveSee 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.

KeyDescriptionTypeExample
x_referenceThe shopping cart reference for the orderASCII string19783
x_resultThe status of the order from your shopping cart's perspective, NOT a copy of the status from the initial async-callbackASCII stringApproved, Declined