initPaymentSession

initPaymentSession là JS API dùng để khởi tạo payment session tập trung cho một order.

Sau khi gọi API này, SDK sẽ mở màn hình thanh toán tập trung nơi user có thể:

• Tiêu VPoint.
• Áp dụng voucher/khuyến mãi.
• Chọn và thực hiện thanh toán online (thẻ, ví, QR, v.v.).

Khác với luồng initPayment hiện tại, MiniApp chỉ cần tạo order ở backend rồi gọi initPaymentSession, không cần gọi showPaymentMethod trước.

Luồng tổng quan:

• MiniApp Backend tạo order và sinh secureHash như mô tả trong Tích hợp thanh toán.
• MiniApp gọi initPaymentSession với thông tin order.
• SDK hiển thị màn hình thanh toán tập trung và điều khiển toàn bộ luồng tiêu VPoint/voucher/thanh toán online.

Chi tiết backend của luồng này xem tại Thanh toán tập trung (MiniApp). Backend có thể query trạng thái session qua Lấy chi tiết Payment Session (Backend).

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
miniAppId	String	❌	MiniApp ID trong SuperApp; Payment Hub dùng để xác định ngữ cảnh MiniApp. Hiện tại optional.
allowedCardPrefixes	string[]	❌	Danh sách prefix BIN (6 chữ số) để filter danh sách thẻ hiển thị trong payment session UI (VD: ["970436", "970418"]). Nếu không truyền thì hiển thị theo default của hệ thống.
orderInfo	OrderInfo	✅	Order info để khởi tạo payment session. Mỗi orderId chỉ được dùng để initPaymentSession một lần.
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

Payload request của initPaymentSession giống với initPayment, nhưng KHÔNG cần/không hỗ trợ các field chọn phương thức thanh toán (paymentMethodCode, providerId, userPaymentMethodId, paymentMethodId). Nếu cần giới hạn danh sách thẻ theo BIN, dùng allowedCardPrefixes ở level tham số API (không nằm trong orderInfo). Việc chọn phương thức thanh toán, áp dụng VPoint/voucher được SDK xử lý trong payment session.

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
amount	number	✅	Số tiền thanh toán (trước khi trừ VPoint/voucher)
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 thanh toán
orderInfo	CustomerOrderInfo	✅	Thông tin đơn hàng chi tiết
secureHash	string	✅	HMAC-SHA256 hash để verify
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. 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).
maxVpointAmount	number	❌	Số tiền tối đa (VND, minor unit, số nguyên) user được phép tiêu bằng VPoint trong payment session này. Bắt buộc nhỏ hơn amount. VD: 300000 = tối đa 300.000 VND quy đổi từ VPoint trên đơn 1.000.000 VND. SDK cho phép user tiêu trong khoảng từ 0 đến maxVpointAmount khi số VPoint khả dụng của user vượt quá maxVpointAmount; nếu số VPoint khả dụng nhỏ hơn hoặc bằng maxVpointAmount thì user có thể tiêu tối đa theo số dư thực tế. Nếu không truyền, hệ thống áp dụng rule mặc định. Khi có giá trị phải append vào chuỗi ký secureHash (xem Tạo SecureHash cho đơn hàng).
returnURL	string	❌	URL redirect sau khi thanh toán (nếu có)
providerData	string	❌	Dữ liệu bổ sung từ provider

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ề 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 initPaymentSession, 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ề 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.
• Nếu truyền maxVpointAmount, cần append vào cuối cùng của chuỗi ký (sau skipHolding nếu có).
• Nếu không truyền maxVpointAmount, 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.

Ví dụ

import apis from '@v-miniapp/apis'

// Sau khi đã tạo order ở backend và nhận lại orderId, referenceId, secureHash, v.v.
apis.initPaymentSession({
  paymentApiKey: 'xxx',
  miniAppId: 'vinfast_sales',
  allowedCardPrefixes: ['970436', '970418'], // optional: filter BIN card hiển thị trong UI
  orderInfo: {
    paymentType: '3D', // "2D" hoặc "3D", mặc định "3D". Xem lưu ý về paymentType ở trên.
    businessUnitId: 'BU_VINFAST_001',
    branchId: 'BR_HN_001',
    sellerMerchantId: 'SELLER_MERCHANT_001', // Optional: merchant của seller để filter/reporting theo seller (không đổi settlement account).
    maxVpointAmount: 300000, // Optional: tối đa 300.000 VND quy đổi từ VPoint user được tiêu.
    amount: 1000000,
    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('err', err)
  },
})