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 consistent experience though out the whole purchase.

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

order creation API​

create a payment order by providing the order information together with the customer information. if you want to reward your customer with divit miles, the miles reward defined in the create order payload will be credited to the customer account automatically, even the customer has not been registered with divit, we will save all their related transactions in a temporary space.

caution

all monetary values are in integer format. So, $987.50 = 98750

note

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

endpoint: POST [API_BASE_URL]/paynow/orders

order creation sample request
var data = JSON.stringify({
  "order": {
    "totalAmount": {
      "amount": 0,
      "currency": "string"
    },
    "webhookSuccess": "string",
    "webhookFailure": "string",
    "webhookEvents": "string",
    "expiredAt": 1696654130,  // unix time
    "merchantRef": "string"
    "merchantUniqueOrderID": "string",
    "language": "en",
    ...<orderItems: check 'order item details' section>...,
    ...<optional reward parameters: check 'miles reward mechanism' section>...
  },
  "customer": {
    "firstName": "string",
    "lastName": "string",
    "email": "[email protected]",
    "tel": "string",
    "address1": "string",
    "address2": "string",
    "district": "string",
    "province": "string",
    "postalCode": "string",
    "country": "HK",  // ISO 3166-1 alpha-2 country code
    "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");
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. skip all of them if you don't have want to give reward.

  • milesForReward is the number of miles you will directly award your customer without using the divit promoCode. don't give this parameter if you want to use promoCode instead.
  • 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.
  • totalForReward is the amount used to calculate the number miles to be rewarded. it is quite common that the total order amount might include some other fees that should not be a part of the reward, e.g. shipping fee. then the value of totalForReward will be the total pay amount minus the shipping fee.
caution

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

no mile will be given to customer

  ...
  "promoCode": "",
  ...
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

you can obtain the values of promoCode at our admin-portal.

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, 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/paynow/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/paynow/order/956db0a3-68b1-420c-9df9-3ec5d77136b9/fast?merchant=<merchant name>&mRef=<merchant code>&token=<token>");
}