Overview | Information you need to collect | API Call | API Response

Create a Purchase

 

When the customer wants to checkout, you send an api call with information about the purchase to helloPay and helloPay response with the redirection url, you send the customer to. After you integrated this main feature you’re already able to use helloPay in your Online Shop!


The information you need to collect

 

This are the information you need to collect and save them in a variable. Some of it is mandatory and some of it optional, but if you can provide some of the optional information, please include it in the api call to help us making every transaction as safe as possible and improve the user experience.

$data['priceAmount'] = "250";
$data['priceCurrency'] = "SGD";
$data['description'] = "Lazada purchase create";
$data['merchantReferenceId'] = time();

# item 1
$data['basket'] = [];
$data['basket']['basketItems'] = [];
$data['basket']['basketItems'][] = [
  'name' => 'Item 1',
  'quantity' => 1, #Integer, not String
  "amount" => "250",
  "taxAmount" => "0",
  "imageUrl" => "http://yourdomain.com/img/product.png",
  "currency" => "SGD"
];

$data['basket']['shipping'] = "0.00";
$data['basket']['totalAmount'] = "250";
$data['basket']['currency'] = "SGD";
 
$data['shippingAddress']['name'] = 'Testint Tom';
$data['shippingAddress']['firstName'] = "Testint";
$data['shippingAddress']['lastName'] = "Tom";
$data['shippingAddress']['addressLine1'] = "Test Street 22";
$data['shippingAddress']['province'] = "DKI Jakarta";
$data['shippingAddress']['city'] = "Kab. Kepulauan Seribu";
$data['shippingAddress']['country'] = "SG";
$data['shippingAddress']['mobilePhoneNumber'] = "6563584754";#should include country code
$data['shippingAddress']['houseNumber'] = "House Number";
$data['shippingAddress']['addressLine2'] = "Address Line2";
$data['shippingAddress']['district'] = "Kepulauan Seribu Utara";
$data['shippingAddress']['zip'] = "247964";
 
$data['billingAddress']['name'] = "Testint Tom";
$data['billingAddress']['firstName'] = "Testint";
$data['billingAddress']['lastName'] = "Tom";
$data['billingAddress']['addressLine1'] = "Test Street 22";
$data['billingAddress']['province'] = "DKI Jakarta";
$data['billingAddress']['city'] = "Kab. Kepulauan Seribu";
$data['billingAddress']['country'] = "SG";
$data['billingAddress']['mobilePhoneNumber'] = "6563584754"; #should include country code
$data['billingAddress']['houseNumber'] = "House Number";
$data['billingAddress']['addressLine2'] = "Address Line2";
$data['billingAddress']['district'] = "Kepulauan Seribu Utara";
$data['billingAddress']['zip'] = "247964";
 
$data['consumerData']['mobilePhoneNumber'] = "6563584754"; #should include country code
$data['consumerData']['emailAddress'] = "[email protected]";
$data['consumerData']['country'] = "SG";
$data['consumerData']['language'] = "en";
$data['consumerData']['dateOfBirth'] = "14-08-1992"; #in this form: dd-mm-yyyy
$data['consumerData']['gender'] = "male";
$data['consumerData']['ipAddress'] = "127.0.0.1";
$data['consumerData']['name'] = "Testint Tom";
$data['consumerData']['firstName'] = "Testint";
$data['consumerData']['lastName'] = "Tom";
 
$data['additionalData']['deliveryNote'] = "Delivery Note";
$data['additionalData']['deliveryTime'] = "Delivery Time";
$data['additionalData']['deliveryTimeString'] = "Delivery Time String";
$data['additionalData']['deviceType'] = "Device Type";
 
$data['purchaseReturnUrl'] = "http://yourdomain.com/hellopay/response";
$data['purchaseCallbackUrl'] = "http://yourdomain.com/hellopay/callback.php";
$data['priceAmount'] = "";
$data['priceCurrency'] = "";
$data['description'] = "";
$data['merchantReferenceId'] = ;

# item 1
$data['basket'] = [];
$data['basket']['basketItems'] = [];
$data['basket']['basketItems'][] = [
  'name' => '', 
  'quantity' => ,
  "amount" => "",
  "taxAmount" => "",
  "imageUrl" => "",
  "currency" => ""
];
 
$data['basket']['shipping'] = "";
$data['basket']['totalAmount'] = "";
$data['basket']['currency'] = "";
 
$data['shippingAddress']['name'] = '';
$data['shippingAddress']['firstName'] = "";
$data['shippingAddress']['lastName'] = "";
$data['shippingAddress']['addressLine1'] = "";
$data['shippingAddress']['province'] = "";
$data['shippingAddress']['city'] = "";
$data['shippingAddress']['country'] = "";
$data['shippingAddress']['mobilePhoneNumber'] = "";
$data['shippingAddress']['houseNumber'] = "";
$data['shippingAddress']['addressLine2'] = "";
$data['shippingAddress']['district'] = "";
$data['shippingAddress']['zip'] = "";
 
$data['billingAddress']['name'] = "";
$data['billingAddress']['firstName'] = "";
$data['billingAddress']['lastName'] = "";
$data['billingAddress']['addressLine1'] = "";
$data['billingAddress']['province'] = "";
$data['billingAddress']['city'] = "";
$data['billingAddress']['country'] = "";
$data['billingAddress']['mobilePhoneNumber'] = "";
$data['billingAddress']['houseNumber'] = "";
$data['billingAddress']['addressLine2'] = "";
$data['billingAddress']['district'] = "";
$data['billingAddress']['zip'] = "";
 
$data['consumerData']['mobilePhoneNumber'] = ""; 
$data['consumerData']['emailAddress'] = "";
$data['consumerData']['country'] = "";
$data['consumerData']['language'] = "";
$data['consumerData']['dateOfBirth'] = "";
$data['consumerData']['gender'] = "";
$data['consumerData']['ipAddress'] = "";
$data['consumerData']['name'] = "";
$data['consumerData']['firstName'] = "";
$data['consumerData']['lastName'] = "";
 
$data['additionalData']['deliveryNote'] = "";
$data['additionalData']['deliveryTime'] = "";
$data['additionalData']['deliveryTimeString'] = "";
$data['additionalData']['deviceType'] = "";
 
$data['purchaseReturnUrl'] = "";
$data['purchaseCallbackUrl'] = "";

Description

* = Mandatory!

(*) = Not Mandatory, but highly recommanded (without this parameters, we will have to ask the User again for the information)!

The other parameters are optional!


Price Amount*

The order amount in total as a string, for example “1234.56”.

Price Currency*

A string in form of a shorthand symbol of your currency. For example: “SGD” - Singapore dollar.

Purchase Description*

A short sentence to (can be auto generated) to see, what this api call was about in the future.

Merchant Reference ID*

A unique order Id of the merchant. The merchant will be able to search for the orders using your Id in merchant account area.

Basket*

An object with every basket item inside (in an array of basket item-objects), extra shipping charges, the total amount and the currency. In detail:

Basket: Basket Item

An array of objects. Each object represents one item in the shopping cart. If one item is in the shopping cart multiple times, there should be only one item, only the value ‘quantity’ in the basket item object changes. Every Object contains following values:

name - The name of the product
quantity - How many of these items wants the customer to buy
amount - The price times the quantity
taxAmount - The taxes times the quantity
imageUrl- An url of an image of the product
currency – The same like Price Currency

every value in this array is optional, but you should create one basket item array for every item the customer wants to buy, with at least the name, quantity, amount and the imageUrl.

Basket: Shipping

The costs of shipping the products.

Basket: Total Amount

The total costs of every basket item in every quantity, it is the same like the Price Amount.

Basket: Currency

The same like Price Currency.

Shipping Address: Name
Shipping Address: First name
Shipping Address: Last name
Shipping Address: Address
Shipping Address: Province
Shipping Address: City
Shipping Address: Country
Shipping Address: Mobile phone number
Shipping Address: House number
Shipping Address: Alternate address
Shipping Address: District
Shipping Address: Zip

Billing Address: Name
Billing Address: First name
Billing Address: Last name
Billing Address: Address(*)
Billing Address: Province(*)
Billing Address: City(*)
Billing Address: Country
Billing Address: Mobile phone number
Billing Address: House number
Billing Address: Alternate address
Billing Address: District(*)
Billing Address: Zip

Consumer Data: Mobile phone number(*)
Consumer Data: Email address(*)
Consumer Data: Country
Consumer Data: Language
Consumer Data: Date of birth (in this form dd-mm-yyyy) the minus is important!
Consumer Data: Gender
Consumer Data: Ip address*
Consumer Data: Name(*)
Consumer Data: First name
Consumer Data: Last name

Additional Data

It can contain any special values, objects, arrays etc. you want to/need to share.

Purchase Return URL

Besides your normal success url, you can also have an individual url for each purchase by sending the special return url with this api call.

Purchase Callback URL

Besides your normal callback url, you can also have an individual url for each purchase by sending the special callback url with this api call.


API Call

Now this is the actual API Call execution. While it sounds like the biggest part to integrate, the biggest part is actually already done with collecting the data and saving it in a variable.

$response = $helloPay->createPurchase($data);

Description

This single line of code to executes the api call. It will transform your collected data ($data) into JSON format, which is the format we’re using to send and receive api calls, sends the JSON file to helloPay and immediately saves our response in the $response variable (it is advisable to rename this variable).


API Response

Since the response is already saved in $response, this last step just shows you what to do with the response.

$response->getCheckoutUrl()

$response->getPurchaseId()

Description

Checkout Url

This is the checkout url, you can now send the user to, in form of a string.

Purchase ID

This is the Purchase ID. You should save it, because you will need it later to use the other features/services (it is sometimes called transaction ID, but it’s still the same).