Skip to main content

create order

to start the divit journey for your customer, you need to create an order with divit so we know what the customer is expected to pay and what type of product the customer is buying.

we would need to know some basic information on what the user is buying. mainly the price of the product and some small details about the product so the user can have a consistant experience though out the whole flow.

for this, you only need to make one POST request with details below and we will return you an URL. you should redirect the user to this URL and they will then be able to complete the purchase.

we will notify you though a webhook when the user has completed the purchase on divit's platform. you set those webhooks at webhookEvents

caution

all monetary values are in integer format. So, $987.65 = 98765

order creation API

there are 2 order creation APIs in paynow service, either you provide only the order information or together with the customer information. the difference between these 2 methods is customer can complete the purchase without having a divit account or we will ask them to signup/signin before completing the purchase.

we strongly recommend you to implement the "fast-checkout" mode to shorten the payment process, just by providing us your customer email/phone number, the mile reward will be credited into customer account automatically. even the customer has not been registered with divit, we will save all their related transactions in a temporary space.

using the fast checkout mode, you need to provide details of the order item, and some basic information of your customer

the main difference of "fast-checkout" and "normal" order creation is that we have added a customer object to the request where we can recognize coming back customer before trigger the FPS payment.

note

please refer to different value of orderType and the data struct of ...<orderItems>... according to the specific industry in the next section

fast-checkout sample request
var data = JSON.stringify({
"order": {
"totalAmount": {
"amount": 0,
"currency": "string"
},
"nonrefundableAmount": {
"amount": 0,
"currency": "string"
},
"refundableAmount": {
"amount": 0,
"currency": "string"
},
"orderType": "<industry type>",
...<orderItems>...,
"webhookSuccess": "string",
"webhookFailure": "string",
"webhookEvents": "string",
"expiredAt": 0,
"merchantRef": "string"
"promoCode": "string",
"milesForReward": 0,
"totalForReward": {
"amount": 0,
"currency": "string"
}
},
"customer": {
"firstName": "string",
"lastName": "string",
"email": "[email protected]",
"tel": "string",
"floor": "string",
"building": "string",
"street": "string",
"district": "string",
"region": "string",
"language": "en"
}
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://sandbox-api.divit.dev/paynow/orders/fast");
xhr.setRequestHeader("api-key", "<your api-key, e.g. dvt_rREeGJ4FXp69nQEJ7Arq08stvtacFyPrTzKr>");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

miles reward mechanism

you can reward your customer by providing the following parameter values during the order creation.

  • milesForReward is the number of miles that you will give to your customer. since every business has different formulas and reward scheme to calculate this reward amount, to keep the integration simple, divit does not integrate your calculation. instead, we provide the following parameters promoCode and totalForReward to help verifying your calculation. order alert will be created when the number does not match, or the number of miles to be rewarded go beyond the cost of the order.
  • promoCode is an internal secret code predefined by divit when your merchant account is setup. you will have a set of promoCode with different rewarding ratios. and you can create some alias codes and let your VIP customer to override your default reward scheme to obtain more reward.
  • totalForReward is the amount used to calculate the number miles to be rewarded. it is normal that your total order amount might include some other fees that are not a part of the reward, e.g. shipping fee. then the value of totalForReward will be the total pay amount minus the shipping fee. by different value of promoCode, the calculated result will then be used to compared against the value of milesForReward. if they are not the same, an internal order ticket will be created. our staff will then double check if there is any abnormality that might possibly happened.
caution

this is important to keep the promoCode value in server-side only

server will reward 1750 miles to customer. The promoCode XYZ01 given will be served as verification purpose only.

  ...
"promoCode": "XYZ01",
"milesForReward": 1750,
"totalForReward": {
"amount": 250000,
"currency": "HKD"
}
...

or, no verification in the miles calculation

...
"promoCode": "",
"milesForReward": 1750,
"totalForReward": {
"amount": 0,
"currency": "HKD"
}
...
tip

for example the promoCode has the value XYZ01 which represents the reward ratio of 1:2. when the order with the totalForReward HKD 2500, the milesForReward should be 1250.

noted that you can provide a different value of milesForReward, for instance, your customer has an additional 500 miles for his birthday month purchase. we will credit your customer with 1750 miles according to your given amount, and our system will create an alert ticket with this order. we will look into the order and might double check with you

you can either obtain the values of promoCode at our admin-portal or by calling our miles reward APIs.

order item details

online merchants have a few special details they need to provide when creating an order. these details will ensure that the customer will have continuity while paying with divit.

  • productID is your own SKU that is attached to the product.
  • productTitle usually the product name
  • qty how many items of the SKU did the user order
  • pics any product images to give the user a visual representation of the order
sample orderItems
{
...,
"orderType": "retail",
"orderItems": [
{
"itemType": "retail",
"itemData": {
"productID": "string",
"productTitle": "string",
"qty": 0,
"pics": {}
}
}
],
...
}
---

create order response

when creating the order in "fast-checkout" mode, you will receive the redirectURI together with a token. the token is used to claim back the order created by the backend, linking the purchase session together. redirect the user to divit with the URI value and append token as the parameter.

success response
{
"code": 0,
"message": "OK",
"data": {
"redirectURI": "https://sandbox-consumer.divit.dev/orders/956db0a3-68b1-420c-9df9-3ec5d77136b9/fast?merchant=<merchant name>&mRef=<merchant code>",
"orderID": "956db0a3-68b1-420c-9df9-3ec5d77136b9",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NDQ2NzU1NjYsIm9yZCI6Ijk1NmRiMGEzLTY4YjEtNDIwYy05ZGY5LTNlYzVkNzcxMzZiOSIsIm9yaWdfaWF0IjoxNjQ0NjcxOTY2LCJzY29wZSI6InRtcGVuZHVzZXIiLCJzdWIiOiJlYmZmYWZkYS0yNmMwLTRlYzAtODAzNS01MTgzYmYyMjdiMzYifQ.OW4dLVPeoXYvRnqoeGAlKZLTJ2s0ocYNy7DJCvefCTOPue6LPXd08ZdEzFd7MEdOvTpVro9a3J26TvQ22sBEDNIA6DHLTb6wHRi9Bl2bUzRAwrsvoS8w9LUL9VAXAH9qs9kE2Se5hEYGLfAuFSjQ-dBaQ2w_eZpkK3SHEw2SRd_lmpTO76WIN7UqImX35yttWa2p9FPtKFbIoLIBsF3N1xLQveEzl3A_hiDp5asuryDVl73PTy5f01GrDoUS6SekSaVEVOMuPFhBv9MZPEet91_Oe0jrcTqgczxFBY9otODurUJcwzw5LhhwDOm2d-5YYVYzryhr5nHLib_-6TAxJA"
}
}

redirect user

almost done! just redirect your user to the supplied URL and we will take it from there. now you can sit back and wait for our webhookEvents call.

redirect sample
function pageRedirect() {
window.location.replace("https://sandbox-consumer.divit.dev/order/8a6638b2-b5e6-4d11-9cbe-272e8010875e?merchant=<merchant name>&mRef=<merchant code>&token=<token>");
}