create payment order

to initiate an instant bank-to-bank checkout via Faster Payment System (FPS), your backend server must make a secure server-to-server POST call to the divit payment gateway.

this endpoint validates the transaction parameters, records the order in our secure database, and generates a unique checkout link (redirectURI) where the customer completes the payment.

endpoint details

HTTP Method: POST
Production URL: https://api.divit.com.hk/directpay/o/order
Sandbox URL: https://sandbox-api.divit.dev/directpay/o/order

required headers

every API request to divit must include your secret API credential and specify the JSON content type:

api-key: your_api_key_here (e.g. dvt_rREeGJ4FXp69nQEJ...)
Content-Type: application/json

security best practice

never expose your api-key on the client side (e.g., in browser Javascript, mobile apps, or frontend templates). this key must reside securely in your backend environment configuration and be accessed only by server-to-server requests.

request parameters

the request body contains two main structures: the order details and the customer credentials.

order object parameters (`order`)

Parameter	Type	Required	Description
`totalAmount`	`object`	Yes	object containing `amount` (integer) and `currency` (three-letter ISO code, e.g., `"HKD"`).
`totalAmount.amount`	`integer`	Yes	smallest currency subunit format. for example, to charge HKD `$120.50`, convert the value to cents and pass `12050`.
`webhookEvents`	`string`	Yes	your unauthenticated secure backend endpoint that will listen for asynchronous status updates (e.g., success webhooks).
`webhookSuccess`	`string`	Yes	the absolute landing page URL on your storefront where the customer should be redirected after a successful payment.
`webhookFailure`	`string`	Yes	the absolute landing page URL on your storefront where the customer should be redirected after a failed or cancelled payment.
`merchantRef`	`string`	Yes	your unique internal transaction/order ID. max 36 characters. this value will be visible on the customer's payment screen and mobile bank app statements.
`merchantUniqueOrderID`	`string`	No	secondary reference ID to trace transactions inside your accounting systems. max 64 characters. shown on the daily transaction report.
`expiredAt`	`integer`	No	unix timestamp representing the precise expiration time of this checkout order. if left blank, divit's default system expiry will apply.
`language`	`string`	No	language locale code for the customer's payment screen interface. supports `"en"` (default), `"zh-hk"`, and `"zh-cn"`.

customer object parameters (`customer`)

Parameter	Type	Required	Description
`firstName`	`string`	Yes	customer's first name. required for joining reward campaigns, receipt delivery, and legal compliance.
`lastName`	`string`	Yes	customer's last name.
`email`	`string`	Yes	customer's valid email address. used for delivering purchase e-receipts.
`tel`	`string`	No	phone number, formatted with country code (e.g., `+85291234567`).
`language`	`string`	No	customer's preferred communication language (`"en"`, `"zh-hk"`, `"zh-cn"`).

payload examples

complete JSON request body

{
  "order": {
    "totalAmount": {
      "amount": 12050,
      "currency": "HKD"
    },
    "webhookSuccess": "https://your-site.com/checkout/success",
    "webhookFailure": "https://your-site.com/checkout/cancel",
    "webhookEvents": "https://your-api.com/api/webhooks/divit",
    "expiredAt": 1799999999,
    "merchantRef": "ORDER-10024A",
    "language": "en"
  },
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "tel": "+85291234567",
    "language": "en"
  }
}

implementation examples

we recommend utilizing modern async/await patterns. below is an example using Node's native fetch API to create a payment order:

/**
 * creates a new payment order with divit
 * @param {object} orderData - order details (amount, webhook URLs, reference etc.)
 * @param {object} customerData - customer details (first name, last name, email etc.)
 * @param {string} apiKey - your secret merchant API key
 * @returns {Promise<object>} - payment order response containing redirectURI and orderID
 */
async function createPaymentOrder(orderData, customerData, apiKey) {
  const baseUrl = "https://sandbox-api.divit.dev"; // use production URL for live transactions
  const url = `${baseUrl}/directpay/o/order`;

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        order: orderData,
        customer: customerData
      })
    });

    if (!response.ok) {
      const errorPayload = await response.json();
      throw new Error(`API Error [${errorPayload.code}]: ${errorPayload.message}`);
    }

    const payload = await response.json();
    return payload;
  } catch (error) {
    console.error("failed to create payment order:", error.message);
    throw error;
  }
}

response structure

upon successful order creation, you will receive an HTTP 200 OK status with a JSON payload containing the redirect URL, order references, and a secure validation token.

success response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "redirectURI": "https://sandbox-pay.divit.dev/request/fps/956db0a3-68b1-420c-9df9-3ec5d77136b9?signature=a1b2c3d4e5f6g7h8",
    "orderID": "956db0a3-68b1-420c-9df9-3ec5d77136b9",
    "token": ""
  }
}

parameter reference

code (integer): returns 0 for success. non-zero codes signify specific gateway errors.
message (string): general description of the API execution outcome (e.g., "OK").
data.redirectURI (string): the checkout URL where the merchant storefront must redirect the customer's browser session.
data.orderID (string): divit's global unique identifier (UUID) for this transaction. store this ID in your order database to link with webhooks.
data.token (string): legacy JWT token. this attribute has no active functional use for this version of the endpoint and is left empty. it is retained strictly for backward compatibility with older checkout systems that append the token to the redirect URL manually.

redirection implementation

as soon as your server processes the response and extracts redirectURI, immediately redirect your customer's browser or webview to it. the customer will be presented with our high-fidelity, localized FPS checkout screen.

javascript redirect example

// example: redirecting client browser after receiving redirectURI from your backend server
function redirectToCheckout(redirectURI) {
  if (redirectURI) {
    window.location.replace(redirectURI);
  } else {
    console.error("Invalid redirectURI received.");
  }
}

mobile webview integration

if you are integrating divit into a native iOS or Android mobile application, load the redirectURI into a standard webview. our payment screen automatically optimizes for mobile viewport dimensions and supports deep-linking directly into native Hong Kong retail banking applications with one click.

endpoint details​

required headers​

request parameters​

order object parameters (order)​

customer object parameters (customer)​

payload examples​

complete JSON request body​

implementation examples​

response structure​

success response example​

parameter reference​

redirection implementation​

javascript redirect example​

mobile webview integration​