Pre-Population API

Overview

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

Request Parameters

Account Details

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 details
x_guid	Guid (200)	False		Your GUID reference for this transaction (required for resuming transactions)
x_reference	String	False	ABC123	Your reference for this transaction
x_test	Boolean	False	True	Perform process under test mode

Staff Information

Key	Type	Required	Sample	Description
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

Transaction Details

Key	Type	Required	Sample	Description
x_currency	String	False	AUD, NZD	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

Customer Personal Information

Key	Type	Required	Sample	Description
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 (ISO8601), 18 years and older

Customer Address

Key	Type	Required	Sample	Description
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	Will default to AU if not specified

Employment Information

Key	Type	Required	Sample	Description
x_customer_employment_status	Integer	False	FullTime = 1, PartTime = 2, etc.	Employment type of the customer
x_customer_employment_hours_per_week	Decimal	False	38	Customer's total working hours (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
x_customer_work_phone	String	False	0882345678	Customer's work phone number
x_customer_abn	String	False	99 888 888 888	Customer's ABN/ACN (Only if Self Employed)
x_customer_last_pay_date	Date	False	2018-05-01	Customer's last pay date

Identification

Key	Type	Required	Sample	Description
x_customer_id_type	Integer	False	1: Driver's License, etc.	Identity type provided by the customer
x_customer_id_state	String	False	SA	State where the Customer's Identity issued
x_customer_id_expiry_date	Date	False	2020-01-01	Expiry date of Customer's Identity card
x_customer_id_number	String	False	abc255q	Identity card number
x_customer_id_reference	String	False	123	Additional identity card number/reference

URLs

Key	Type	Required	Sample	Description
x_url_cancel	String (200)	False	https://example.com/Cancel	Redirect URL for cancellation/errors
x_url_complete	String (200)	False	https://example.com/API	Callback URL for API response

Response Parameters

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
x_timestamp	DateTime	System timestamp for the transaction
x_result	String	Response code (Pending, Approved, Cancelled, Declined, Errors, Expired)
x_signature	String	Response signature for verification

Code Examples

HTML Generation

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>';

}

Signature Generation

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.

Note: If you require Sandbox Credentials for testing the API, please reach out to us via the Integration Assistance Form.