Overview | 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!


API Call

 

Send this api call in JSON format (like in the example) with a POST method to sandbox.hellopay.com.sg/merchant/create (remember to change the ending ‘com.sg’ to the ending of your country).

The content type should be application/json.

Note 1: If you don’t have the information (and the value is optional), please still include the parameter and just leave the value empty.

Note 2: “data=” has to be in the beginning of the JSON string, like in the example!

data={
"priceAmount":"550",
"priceCurrency":"SGD",
"discription":"Lazada purchase create",
"merchantReferenceId":"1234567890",
"basket":{
 "backetItems":[
     {
     "name":"Item 1",
     "quantity": 1,
     //        the quantity is an interger, not a String!
     "amount":"300",
     "taxAmount":"0",
     "imageUrl":"http://yourdomain.com/img/product1.png",
     "currency":"SGD"
     },
     {
     "name":"Item 2",
     "quantity": 1,
     //        the quantity is an interger, not a String!
     "amount":"250",
     "taxAmount":"0",
     "imageUrl":"http://yourdomain.com/img/product2.png",
     "currency":"SGD"
     }
 ],
 "shipping":"0.00",
 "totalAmount":"550",
 "currency":"SGD"
},
"shippingAddress":{
 "name":"Testint Tom",
 "firstName":"Testint",
 "lastName":"Tom",
 "addressLine1":"Test Street 22",
 "province":"Province",
 "city":"Kab. Kepulauan Seribu",
 "country":"SG",
 "mobilePhoneNumber":"+6531584888",
 //        should include country code
 "houseNumber":"House Number",
 "addressLine2":"Address Line 2",
 "district":"Kepulauan Seribu Utara",
 "zip":"247964"
},
"billingAddress":{
 "name":"Testint Tom",
 "firstName":"Testint",
 "lastName":"Tom",
 "addressLine1":"Test Street 22",
 "province":"Province",
 "city":"Kab. Kepulauan Seribu",
 "country":"SG",
 "mobilePhoneNumber":"+6531584888",
 //        should include country code
 "houseNumber":"House Number",
 "addressLine2":"Address Line 2",
 "district":"Kepulauan Seribu Utara",
 "zip":"247964"
},
"consumerData":{
 "mobilePhoneNumber":"+6531584888",
 //        should include country code
 "emailAdddress":"[email protected]",
 "country":"SG",
 "language":"en",
 "dateOfBirth":"14-08-1992",
 //        in this form: dd-mm-yyyy
 "gender":"male",
 "ipAddress":"127.0.0.1",
 "name":"Testint Tom",
 "firstName":"Testint",
 "lastName":"Tom"
},
"additionalData":{
},
"purchaseReturnUrl":"http://yourdomain.com/hellopay/respone",
"purchaseCallbackUrl":"http://yourdomain.com/hellopay/callback.php",
"shopConfig":"AAEAAADoKU7YCxb_Z9IU2RcBgnEg26xJsHuZCDK7cMK7vnm_vnTzGjLJ/AAEAAAgfi0MlUJfWeGEwG4ujB2VrcfJlF_L0PPqrhIjAnG4R6qiaKAar/a5c4123e5a1f196d896d908cf64764e1"
}


data={
"priceAmount":"",
"priceCurrency":"",
"discription":"",
"merchantReferenceId":"",
"basket":{
 "backetItems":[
     {
     "name":"",
     "quantity":,
     "amount":"",
     "taxAmount":"",
     "imageUrl":"",
     "currency":""
     },
     {
     "name":"",
     "quantity": ,
     "amount":"",
     "taxAmount":"",
     "imageUrl":"",
     "currency":""
     }
 ],
 "shipping":"",
 "totalAmount":"",
 "currency":""
},
"shippingAddress":{
 "name":"",
 "firstName":"",
 "lastName":"",
 "addressLine1":"",
 "province":"",
 "city":"",
 "country":"",
 "mobilePhoneNumber":"",
 "houseNumber":"",
 "addressLine2":"",
 "district":"",
 "zip":""
},
"billingAddress":{
 "name":"",
 "firstName":"",
 "lastName":"",
 "addressLine1":"",
 "province":"",
 "city":"",
 "country":"",
 "mobilePhoneNumber":"",
 "houseNumber":"",
 "addressLine2":"",
 "district":"",
 "zip":""
},
"consumerData":{
 "mobilePhoneNumber":"",
 "emailAdddress":"",
 "country":"",
 "language":"",
 "dateOfBirth":"",
 "gender":"",
 "ipAddress":"",
 "name":"",
 "firstName":"",
 "lastName":""
},
"additionalData":{
},
"purchaseReturnUrl":"",
"purchaseCallbackUrl":"",
"shopConfig":""
}

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.

Your ShopConfig

Also called API Key! A unique key for your shop, that we create for you. You can look it up in your helloPay or helloPay sandbox account (they are different, so please make sure you're using the correct one for testing and for the production), in the action "Account Settings".


API Response

This is the response, that you will get! That means you don’t need to provide this data, you’ll receive it and work with it:
-Use the checkout url to redirect the user to helloPay
-Save the purchase id to use the other services later

Success Response

{
"success":true,
"checkoutUrl":""https:\/\/www.hellopay.com.sg\/checkout\/?purchaseId=AAEAAADoKU7S PetIl5sQm3TX3UYQr2itSspQUO2yzCzCIYoUm9-MzfU0",
"purchaseId":"AAEAAADoKU7SPetIl5sQm3TX3UYQr2itSspQUO2yzCzCIYoUm9-MzfU"
}
Failure Response

{
"success": false,
"message": "There were errors in JSON data sent!"
}

Description

Success

A boolean so you can check, if it’s a success or failure response.

Checkout URL

A string, that contains the URL you can now send the user to, to make the checkout with helloPay.

Purchase ID

A string, that contains the purchase id. You will need it later, for some of the other services (sometimes it is called transaction ID, but it is still this one).

Success

A boolean so you can check, if it’s a success or failure response.

Message

A string with an error message

Simply Better Online Payment