initPayment

initPayment là API dùng để tạo payment. Luồng payment như sau:

Gọi API showPaymentMethod để hiển thị màn hình chọn phương thức thanh toán.
Developer gọi BE để tạo order từ đơn hàng. Tham khảo Tích hợp thanh toán
Gọi API initPayment để tạo khởi tạo payment. Kế đó, ứng dụng sẽ được redirect tới trang quick payment của V-App.

Lưu ý

Việc initPayment cần phải tạo order trước đó. Sử dụng jsapi getAuthCode để lấy auth code và sau đó tạo order.

Tham số

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
paymentApiKey	String	✅	Payment api key tương ứng với điểm thanh toán
orderInfo	OrderInfo	✅	Order info để thực hiện payment. Mỗi orderId chỉ được dùng để initPayment một lần, không được dùng orderId cũ để initPayment lại.
success	Function	❌	Callback function khi payment được thực hiện thành công, argument luôn là `success`
fail	Function	❌	Callback function khi payment thất bại, argument sẽ là error message
complete	Function	❌	Callback function khi việc gọi payment kết thúc cho dù thành công hay thất bại.

Callback function payload

success callback payload là string và luôn là success
fail callback payload là string và sẽ là error message

OrderInfo

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
amount	number	✅	Số tiền thanh toán
currency	string	✅	Đơn vị tiền tệ (VD: VND, USD)
description	string	✅	Mô tả đơn hàng
orderId	string	✅	Mã đơn hàng (unique, chỉ được dùng một lần)
referenceId	string	✅	Mã tham chiếu
orderInfo	CustomerOrderInfo	✅	Thông tin đơn hàng chi tiết
secureHash	string	✅	HMAC-SHA256 hash để verify
paymentMethodCode	string	*	Mã phương thức thanh toán (bắt buộc nếu không có userPaymentMethodId)
providerId	string	*	ID payment provider (bắt buộc nếu không có userPaymentMethodId)
userPaymentMethodId	string	❌	ID phương thức thanh toán đã liên kết của user (chỉ có khi user đã liên kết thẻ)
paymentMethodId	string	❌	ID phương thức thanh toán (deprecated)
paymentType	string	❌	Loại thanh toán: `"2D"` hoặc `"3D"`. Mặc định: `"3D"` nếu không truyền. Với `"2D"`, user không cần verify token/OTP, hệ thống tự động trừ tiền. Lưu ý: Chỉ áp dụng với thanh toán thẻ Visa, không áp dụng với ATM.
businessUnitId	string	❌	Mã cơ sở kinh doanh (Business Unit ID). Xem phần lưu ý chung bên dưới.
branchId	string	❌	Mã chi nhánh. Yêu cầu với Xem phần lưu ý chung bên dưới.
sellerMerchantId	string	❌	Mã merchant của seller (marketplace/multi-seller) để filter/reporting/hạch toán theo seller. Field này không thay đổi settlement account (tiền vẫn về merchant theo `paymentApiKey`).
platformCode	string	❌	Mã platform
returnURL	string	❌	URL redirect sau khi thanh toán
providerData	string	❌	Dữ liệu bổ sung từ provider

Lưu ý về phương thức thanh toán:

Bắt buộc: Phải truyền một trong hai cách:
1. Cặp paymentMethodCode + providerId (thanh toán mới)
2. userPaymentMethodId (thanh toán bằng thẻ đã liên kết)
Ưu tiên: Nếu truyền cả hai, hệ thống sẽ ưu tiên sử dụng userPaymentMethodId

Lưu ý về businessUnitId và branchId:

Lý do thêm 2 field này:
- Payment Hub tiếp tục cung cấp paymentApiKey theo từng điểm thanh toán (terminal) như các version trước. Tuy nhiên, theo yêu cầu của Biz, mỗi transaction cần biết rõ đang ghi nhận doanh thu cho cơ sở kinh doanh / chi nhánh nào.
- Vì vậy, khi initPayment, các PnL cần truyền thêm businessUnitId (mã cơ sở kinh doanh) và branchId (mã chi nhánh) để Payment Hub/COV có thể xác định được đơn hàng thuộc cơ sở/chi nhánh kinh doanh nào và sync đúng xuống các hệ thống phía sau (SAP, BI, ...).
Bắt buộc: Trên production, với các PnL onboard SAP/Payment Hub/BI cần truyền đầy đủ cả 2 giá trị này. Với PnL không cần sync xuống các hệ thống phía sau, có thể bỏ trống.

Lưu ý về paymentType:

Phạm vi áp dụng: Chỉ áp dụng với thanh toán thẻ Visa, không áp dụng với ATM.
Điều kiện hoạt động: Field này chỉ có tác dụng khi PnL cấu hình riêng MID 2D, 3D (mặc định là 3D). Nếu không cấu hình riêng thì giá trị paymentType truyền vào sẽ không có tác dụng.
Fallback behavior: Trong trường hợp không cấu hình MID 2D trên hệ thống nhưng truyền paymentType = "2D" trong giao dịch, hệ thống sẽ tự động fallback về dùng cấu hình MID 3D.

Lưu ý về sellerMerchantId và secureHash:

Nếu truyền sellerMerchantId, cần append vào chuỗi ký secureHash sau businessUnitId (nếu có) và trước paymentType.
Nếu không truyền sellerMerchantId, không append field này vào raw data string.
Tham khảo công thức đầy đủ tại Tạo SecureHash cho đơn hàng.

CustomerOrderInfo

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
customerName	string	❌	Tên khách hàng (khuyến nghị truyền để xác định thông tin KH)
customerEmail	string	❌	Email khách hàng (khuyến nghị truyền để xác định thông tin KH)
customerPhone	string	❌	Số điện thoại khách hàng (khuyến nghị truyền để xác định thông tin KH)
orderCreatedAt	number	✅	Unix timestamp (milliseconds) khi đơn hàng được tạo
notes	string	❌	Ghi chú về đơn hàng
items	OrderInfoItem[]	❌	Danh sách sản phẩm/dịch vụ trong đơn hàng

OrderInfoItem

Thuộc tính	Kiểu dữ liệu	Mô tả
name	string	Tên sản phẩm/dịch vụ
sku	string	Mã SKU sản phẩm
quantity	number	Số lượng (phải >= 0)
description	string	Mô tả sản phẩm/dịch vụ
unitPrice	number	Giá đơn vị (phải >= 0)
categoryCode	string	Mã danh mục/ngành hàng (optional)
categoryName	string	Tên danh mục/ngành hàng (optional)

Lưu ý về phương thức thanh toán

Khi user đã liên kết thẻ: Trong payload của showPaymentMethod sẽ có field userPaymentMethodId. Nếu có, truyền field này vào initPayment để thanh toán bằng thẻ đã liên kết.
Khi thanh toán mới: Truyền cặp paymentMethodCode và providerId từ paymentMethod object.
Ưu tiên: Nếu truyền cả userPaymentMethodId và cặp paymentMethodCode + providerId, hệ thống sẽ ưu tiên sử dụng userPaymentMethodId.

Ví dụ

import apis from '@v-miniapp/apis'

apis.showPaymentMethod({
  success: (paymentMethod) => {
    // tạo đơn hàng, gọi initPayment để thực hiện thanh toán
    apis.initPayment({
      paymentApiKey: "xxx"
      orderInfo: {
        paymentMethodCode: paymentMethod.code,
        providerId: paymentMethod.providerId,
        userPaymentMethodId: paymentMethod.userProviderId || "",
        paymentType: "3D", // "2D" hoặc "3D", mặc định "3D". Với "2D", user không cần verify token/OTP, hệ thống tự động trừ tiền. Xem lưu ý chi tiết về paymentType bên dưới.
        businessUnitId: "BU_VINFAST_001", // Payment Hub/COV dùng để xác định đơn hàng thuộc cơ sở kinh doanh nào. Trên production cần truyền giá trị này.
        branchId: "BR_HN_001", // Payment Hub/COV dùng để xác định đơn hàng thuộc chi nhánh nào. Trên production cần truyền giá trị này.
        sellerMerchantId: "SELLER_MERCHANT_001", // Optional: merchant của seller để filter/reporting theo seller (không đổi settlement account).
        amount: 100000,
        currency: "VND",
        description: "Payment for order #123456",
        orderId: "Order Id 001",
        referenceId: "Reference_123456",
        orderInfo: {
          customerName: "Nguyen Van A",
          customerEmail: "[email protected]",
          customerPhone: "+84901234567",
          orderCreatedAt: 1640995200000,
          items: [
            {
              name: "Product A",
              sku: "Sku 001",
              quantity: 2,
              unitPrice: 50000,
              description: "High quality product",
              categoryCode: "CAT_ELECTRONICS",
              categoryName: "Electronics",
            },
          ],
          notes:"Bill: 001",
        },
        secureHash: "string",
      },
      success: (res) => {
        apis.alert({ title: "payment", content: res });
      },
      fail: (err) => {
        console.log("errr", err);
      },
    });
  },
});

Tham số​

Callback function payload​

OrderInfo​

CustomerOrderInfo​

OrderInfoItem​

Ví dụ​