Chuyển tới nội dung chính
ZZalo Platforms

createOrder

Cập nhật lần cuối:

Tạo yêu cầu thanh toán.

Lưu ý

Để truyền thêm giá trị mac trong API createOrder, vui lòng cập nhật phiên bản ZMP SDK >= 2.37.3 và dữ liệu extradata, method cần chuyển về kiểu dữ liệu string.

Từ phiên bản ZMP SDK 2.45.0, đối tác bắt buộc phải truyền dữ liệu MAC vào API. Checkout SDK sẽ không xử lý những request thiếu giá trị MAC.

Parameters​

Object object​

PropertyTypeRequiredDescription
amountnumbertrueSố tiền cần thanh toán
itemArray<Record<String, Any>>trueThông tin các items thanh toán
descstringtrueMô tả giao dịch thanh toán
extradataJSON StringThông tin mà đối tác cần gửi thêm
Toàn bộ dữ liệu sẽ được Checkout SDK chủ động gửi cho đối tác thanh toán:
  • Đối với ZaloPay: thông qua tham số embedData
  • Đối với MoMo:
    • thông qua tham số extraData
    • Riêng các thông tin như storeName, storeId, orderGroupId, Checkout SDK sẽ gửi trực tiếp qua các trường storeName, storeId, orderGroupId
methodJSON StringPhương thức thanh toán duy nhất mà đối tác muốn hiển thị cho người dùng.
Bao gồm: Quy trình chi tiết tham khảo ở dưới đây.
macstringtrueThông tin xác thực của dữ liệu đơn hàng, dùng PrivateKey được cung cấp để chứng thực toàn bộ dữ liệu. Các dữ liệu được sắp xếp theo thứ tự từ điển tăng dần để tạo mã hash cho thông tin. Tham khảo cách tạo mã tại đây
Lưu ý: Thông tin xác thực này phải được tạo tại Merchant Server khi đối tác tạo đơn hàng tại hệ thống đổi tác và tuyệt đối không lưu trữ PrivateKey tại Mini App
successfunctionCallback function khi gọi api thành công
failfunctionCallback function khi gọi api thất bại

Return Values​

Promise <Object data>​

PropertyTypeDescription
orderIdstringMã đơn hàng của yêu cầu thanh toán vừa tạo
messageTokenstringToken dùng để sử dụng tin Mini App. Chi tiết về tin Mini App tham khảo tại đây

Error code​

Tham khảo tại đây.

Sample Code​

import { CheckoutSDK } from "zmp-sdk/apis";

// tạo yêu cầu thanh toán 50.000VNĐ
CheckoutSDK.createOrder({
  desc: "Thanh toán 50.000",
  item: [
    { id: "1", amount: 20000 },
    { id: "2", amount: 30000 },
  ],
  amount: 50000,
  extradata: JSON.stringify({
    // toàn bộ extradata sẽ được truyền qua embedData (ZaloPay) hoặc extraData (MoMo)
    storeName: "Cửa hàng A", // field này sẽ được truyền trực tiếp qua storeName (MoMo)
    storeId: "123", // field này sẽ được truyền trực tiếp qua storeId (MoMo)
    orderGroupId: "345", // field này sẽ được truyền trực tiếp qua orderGroupId (MoMo)
    myTransactionId: "12345678", // transaction id riêng của hệ thống của bạn
    notes: "Đây là giá trị gửi thêm",
  }),
  method: JSON.stringify({
    id: "ZALOPAY_SANDBOX", // Phương thức thanh toán
    isCustom: false, // false: Phương thức thanh toán của Platform, true: Phương thức thanh toán riêng của đối tác
  }),
  mac: "YOUR MAC",
  success: (data) => {
    // Tạo đơn hàng thành công
    // Hệ thống tự động chuyển sang trang thanh toán.
    const { orderId } = data;
    console.log(orderId);
  },
  fail: (err) => {
    // Tạo đơn hàng lỗi
    console.log(err);
  },
});

// hoặc
const createOrder = async () => {
  try {
    await CheckoutSDK.createOrder({
      desc: "Thanh toán 50.000",
      item: [
        { id: "1", amount: 20000 },
        { id: "2", amount: 30000 },
      ],
      amount: 50000,
      mac: "YOUR MAC",
    });
  } catch (err) {
    // Tạo đơn hàng lỗi
    console.log(err);
  }
};

Cách tạo mac tại Merchant Server​

Dữ liệu mà đối tác muốn truyền vào createOrder cần được sắp xếp và tạo mac tại Merchant Server.

Lưu ý

Đối tác BẮT BUỘC phải thực hiện tạo mac tại Merchant Server khi tạo đơn hàng tại hệ thống của merchant.

Dữ liệu extradata và method phải có kiểu dữ liệu JSON String khi tạo mac và khi truyền vào API createOrder.

Dữ liệu item phải có kiểu dữ liệu String khi tạo mac.

Ví dụ:

// Với dữ liệu muốn truyền vào API createOrder gồm: amount, desc, item, extradata, method
// Dữ liệu extradata và method phải có kiểu dữ liệu JSON String
// Dữ liệu item cần chuyển về kiểu dữ liệu String
const dataMac = Object.keys(params)
  .sort() // sắp xếp key của Object data theo thứ tự từ điển tăng dần
  .map(
    (key) =>
      `${key}=${
        typeof params[key] === "object"
          ? JSON.stringify(params[key])
          : params[key]
      }`
  ) // trả về mảng dữ liệu dạng [{key=value}, ...]
  .join("&"); // chuyển về dạng string kèm theo "&", ví dụ: amount={amount}&desc={desc}&extradata={extradata}&item={item}&method={method}

// Tạo overall mac từ dữ liệu
mac = HMAC("HmacSHA256", privateKey, dataMac);

Quy trình hiển thị phương thức thanh toán cụ thể​

Để hiển thị một phương thức thanh toán cụ thể, đối tác cần truyền vào tham số method với id là mã phương thức thanh toán của Platform hoặc mã phương thức thanh toán riêng của đối tác, và isCustom quy định phương thức có phải là phương thức riêng hay không.

Sau đó Checkout SDK sẽ tự động chuyển người dùng sang trang thanh toán và chỉ trả về duy nhất phương thức mà đối tác đã quy định, người dùng không thể lựa chọn phương thức thanh toán khác.

Ví dụ quy trình

force-payment