What is the Pre-Population API?

The Pre-Population API has been designed for merchants who obtain and store their customers information within their own CMS. When a customer would like to purchase with humm, the Merchant can easily populate data from their CMS into a humm Buyer Portal application automatically using this API.

How does it work?

The client’s browser performs a post to humm’s API. The POST endpoint returns a view. This view is essentially a UI to complete the final payment step (and resolve any validation errors from the posted data).

An approved, declined, error page may follow an authorisation. These pages do not redirect automatically. The page relies on the client to press the Redirect Now button. This action will redirect to the URLs you provided in the original POST.

Resource Information


HTTP Method	POST from a client side HTML page
Testing Resource URL	https://integration-seller.shophumm.com.au/
Production Resource URL	https://seller.shophumm.com.au/

Data Definitions

Key	Type	Required	Sample	Description
x_account_id	String	True	30199999	The merchant number provided to you by Humm.
x_signature	String	True		The signature for this request. See the section Signature Generation for further details
x_guid	Guid (200)	False		Your GUID reference for this transaction (required for resuming transactions) This is returned as part of the response
x_reference	String	False	ABC123	Your reference for this transaction This is returned as part of the response
x_test	Boolean	False	True	Perform process under test mode
x_staff_first_name	String	False	Harry	The first name of the staff member processing this transaction
x_staff_last_name	String	False	Tipper	The last name of the staff member processing this transaction
x_currency	String	False	AUD, NZD, etc.	Will default to AUD if not specified
x_amount	Decimal	False	1500.00	The total sales amount of the transaction
x_deposit_amount	Decimal	False	100.00	The deposit paid by the customer
product	String		Diamond Ring	Short description of the item or service purchased. NOTE: This is excluded from the API signature process
x_vip_number	Long (10)	False	1234567890	The customer’s VIP or Pre-Approval number
x_customer_title	String	False	Mr = 1 Mrs = 2 Ms = 3 Miss = 4	The customer's title
x_customer_first_name	String	False	John	The customer's first name
x_customer_middle_name	String	False	Andrew	The customer's middle name (not initial)
x_customer_last_name	String	False	Smith	The customer's surname
x_customer_email	String	False	[email protected]	The customer's email address
x_customer_mobile_phone	String	False	0400123123	The customer's mobile phone number
x_customer_home_phone	String	False	0881231234	The customer's full home phone number
x_customer_dob	Date	False	1980-12-01	The customer's date of birth in iso8601 standard date 2016-12-01 18 years and older
x_customer_address_unit	String	False	1	The customer's address (unit number)
x_customer_address_street_number	String	False	97	The customer's address (street number)
x_customer_address_street_name	String	False	Pirie	The customer's address (street name)
x_customer_address_street_type	String	False	Street	The customer's address (street type)
x_customer_suburb	String	False	Adelaide	The customer's address (suburb)
x_customer_state	String	False	ACT, NSW, QLD, SA, TAS, NT, VIC, WA	The customer's address (state)
x_customer_postcode	Integer	False	5000	The customer's address (postcode)
x_customer_country	String	False	AU, NZ, etc	Will default to AU if not specified
x_customer_postcode	Integer	False	FullTime = 1 PartTime = 2 Casual = 3 SelfEmployed = 4 AgedPensioner = 5 VeterenPensioner = 6 SelfFundedRetiree = 7 NotEmployed = 8	Employment type of the customer
x_customer_employment_hours_per_week	Decimal	False	38	Customer's total working hours in a week (Not required for APC, VPC, SFR)
x_customer_employer_name	String	False	BHP Billiton	Customer's employer (Not required for APC, VPC, SFR)
x_customer_employer_suburb	String	False	Adelaide	Customer's employer suburb (Not required for APC, VPC, SFR)
x_customer_work_phone	String	False	0882345678	Customer's work phone number
x_customer_abn	String	False	99 888 888 888	Customer's Australian Business Number (or ACN) Only if Self Employed
x_customer_last_pay_date	Date	False	2018-05-01	Customer's last pay date For all Employment Types
x_customer_id_type	Integer	False	1: Driver's License 3: Age Pension Card 4: Veteran Affairs Card	Identity type provided by the customer
x_customer_id_state	String	False	SA	State where the Customer's Identity issued (if applicable)
x_customer_id_expiry_date	Date	False	2020-01-01	Expiry date of Customer's Identity card (if applicable)
x_customer_id_number	String	False	abc255q	Identity card number
x_customer_id_reference	String	False	123	Additional identity card number/reference ie, NSW Drivers Licence Card Number
x_url_cancel	String (200)	False	https://example.com/Cancel	The location that the client is redirected to if the transaction is cancelled or an error occurs.
x_url_complete	String (200)	False	https://example.com/API	The location that our API will call as part of a background process for either outcome (Approved or Declined)

Return Result

Key	Type	Description
x_account_id	String	Your humm Merchant Number
x_purchase_number	String	Your purchase number for this transaction
x_reference	String	Your originating reference for this transaction
x_guid	Guid	Your originating GUID reference for this transaction
x_test	Boolean	Test mode enabled flag
x_amount	Decimal	The purchase amount of the transaction
x_deposit	Decimal	The deposit amount required for this transaction Note: This might be a higher amount than your initial deposit
x_timestamp	DateTime	System timestamp for the transaction
x_result	String	Response code from the transaction - Pending - Approved - Cancelled - Declined - Errors - Expired
x_signature	String	Signature for this payload. Your application should verify this signature to ensure veracity of the response

HTML Generation Sample Code

Below is a code snippet that demonstrates how the webpage that posts to Humm might be generated:

private function postToCheckout($checkoutUrl, $payload)
{
  echo
  "<html>
  <body>
  <form id='form' action='$checkoutUrl' method='post'>";
  foreach ($payload as $key => $value) {
      echo "<input type='hidden' id='$key' name='$key' value='$value'/>";
  }
  echo
  '</form>
  </body>';
  echo
  '<script>
      var form = document.getElementById("form");
      form.submit();
  </script>
  </html>';
}

Http responses sent from humm should be validated upon receipt. Make sure to use case-insensitive comparison when verifying the provided x_signature values.

Should the signature verification process fail, a 401 – Unauthorised error will be sent.

Signature Generation

All requests and responses must be signed/verified using HMAC-SHA256.

The message is a string of all key-value pairs that start with x_ prefix, sorted alphabetically, and concatenated without separators. This is then digested through the HMAC-SHA256 algorithm using the API key; the resulting code is hex-encoded and placed into the x_signature field.

Below is a code snippet that demonstrates how a signature might be generated:

function EziPay_sign($query, $api_key )
{
    $clear_text = '';
    ksort($query);
    foreach ($query as $key => $value) {
        if (substr($key, 0, 2) === "x_") {
            $clear_text .= $key . $value;
        }
    }
    $hash = hash_hmac( "sha256", $clear_text, $api_key);
    return str_replace('-', '', $hash);
}

Testing

The merchant API has a test page for constructing a valid POST message at https://uat-seller.shophumm.com.au/TEST/API. Make sure each request has a unique (GUID) API reference. You may want to use a form auto-filler such as Chrome recorder as this is a very large form.

📘
Need Sandbox Credentials
If you require Sandbox Credentials for the testing of the API, please reach out to us via the Integration Assistance From.

What is the Pre-Population API?

How does it work?

Resource Information

Data Definitions

Return Result

HTML Generation Sample Code

Signature Generation

Testing

📘Need Sandbox Credentials

📘
Need Sandbox Credentials