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

NodeJS SDK

Trang thanh toán payOS​

Khám phá mã nguồn mẫu hoàn chỉnh được phát triển bằng Framework NodeJS. Mã nguồn server-side chuyển hướng đến trang thanh toán do payOS phát triển. Trước khi bắt đầu, hãy tạo một kênh thanh toán trên trang payOS.

Example bannerGithub

Tài liệu​

Xem tài liệu API payOS để biết thêm thông tin.

Cài đặt thư viện payOS cho dự án NodeJS​

Cài đặt gói có tên là @payos/node vào dự án của bạn:

npm install @payos/node
# hoặc
yarn add @payos/node

Khởi tạo đối tượng PayOS​

Bạn cần khởi tạo đối tượng PayOS bằng Client ID, API Key và Checksum Key của kênh thanh toán mà bạn đã tạo.

Xem hướng dẫn
// CommonJS
const PayOS = require("@payos/node");

const payOS = new PayOS(
  "YOUR_PAYOS_CLIENT_ID",
  "YOUR_PAYOS_API_KEY",
  "YOUR_PAYOS_CHECKSUM_KEY"
);

// ES Modules
import PayOS from "@payos/node";

const payOS = new PayOS(
  "YOUR_PAYOS_CLIENT_ID",
  "YOUR_PAYOS_API_KEY",
  "YOUR_PAYOS_CHECKSUM_KEY"
);

Các phương thức có trong đối tượng PayOS​

Phương thứcKiểu tham số đầu vàoMô tảKiểu trả về
createPaymentLinkCheckoutRequestTypeTạo link thanh toán cho dữ liệu đơn hàngPromise<CheckoutResponseDataType>
getPaymentLinkInformationstring | numberLấy thông tin thanh toán của đơn hàng đã tạo link thanh toán.Promise<PaymentLinkDataType>
cancelPaymentLink
  • orderId: string | number
  • cancellationReason: string
Hủy link thanh toán của đơn hàng.Promise<PaymentLinkDataType>
confirmWebhookstringXác thực URL Webhook của kênh thanh toán và thêm hoặc cập nhật URL Webhook cho Kênh thanh toán đó nếu thành côngPromise<string>
verifyPaymentWebhookDataWebhookTypeXác minh dữ liệu nhận được qua webhook sau khi thanh toánWebhookDataType

Phương thức createPaymentLink có chức năng tạo link thanh toán cho dữ liệu đơn hàng với tham số đầu vào là requestData có kiểu dữ liệu CheckoutRequestType và trả về Promise<CheckoutResponseDataType>. Link thanh toán kiểm soát những gì khách hàng của bạn nhìn thấy trên trang thanh toán, chẳng hạn như Tên sản phẩm, số lượng đặt, số tiền cũng như số tài khoản thụ hưởng, tên ngân hàng. Các trường dữ liệu bắt buộc trong kiểu dữ liệu CheckoutRequestType:

  • orderCode: Mã đơn hàng
  • amount: Số tiền của đơn hàng
  • description: Mô tả đơn hàng
  • returnUrl: Đường dẫn sẽ được chuyển tiếp đến trang web hoặc ứng dụng của bạn khi người dùng đã thanh toán đơn hàng thành công
  • cancelUrl: Đường dẫn sẽ được chuyển tiếp đến trang web hoặc ứng dụng của bạn khi người dùng bấm hủy đơn hàng
Xem hướng dẫn
const body = {
  orderCode: 1234,
  amount: 2000,
  description: "Thanh toan don hang",
  items: [
    {
      name: "Mi tom hao hao",
      quantity: 1,
      price: 2000,
    },
  ],
  cancelUrl: "http://localhost:3000/cancel.html",
  returnUrl: "http://localhost:3000/success.html",
};

const paymentLinkRes = await payOS.createPaymentLink(body);

Phương thức getPaymentLinkInformation lấy thông tin thanh toán của đơn hàng đã tạo link thanh toán với tham số là orderId. orderId có thể là ID link thanh toán với kiểu dữ liệu là string (ví dụ: a7a9454060cd48909864b3747289ff38) hoặc Mã đơn hàng với kiểu dữ liệu là number (ví dụ: 1234) và trả về Promise<PaymentLinkDataType>

Xem hướng dẫn
const paymentLink = await payOS.getPaymentLinkInformation(
  "a7a9454060cd48909864b3747289ff38"
);
// hoặc
const paymentLink = await payOS.getPaymentLinkInformation(1234);

Phương thức cancelPaymentLink giúp bạn hủy link thanh toán của đơn hàng với 2 tham số đầu vào là orderId có kiểu dữ liệu string hoặc number (như đã mô tả ở mục Lấy thông tin link thanh toán) và cancellationReason, có kiểu dữ liệu string. Tham số cancellationReason là tham số không bắt buộc, do đó ta có thể bỏ qua tham số này. Phương thức này sẽ trả về Promise<PaymentLinkDataType>.

Xem hướng dẫn
const cancelledPaymentLink = await payOS.cancelPaymentLink(1234, "reason");

// Nếu bạn muốn hủy link thanh toán mà không cần lý do:
const cancelledPaymentLink = await payOS.cancelPaymentLink(1234);

Xác nhận Webhook URL​

Xác nhận Webhook URL của kênh thanh toán và cập nhật URL Webhook cho Kênh thanh toán với phương thức confirmWebhook. Tham số đầu vào có kiểu dữ liệu là string và trả về Promise<string>.

Xem hướng dẫn
await payOS.confirmWebhook("https://your-webhook-url/");

Xác minh dữ liệu Webhook​

Phương thức verifyPaymentWebhookData dùng để xác minh dữ liệu nhận được qua webhook sau khi thanh toán, tham số đầu vào có kiểu dữ liệu WebhookType, kiểu dữ liệu trả về là WebhookDataType.

Xem hướng dẫn
/* Dữ liệu webhook mẫu khi nhận từ hệ thống payOS
req.body = {
  "code": "string",
  "desc": "string",
  "data": {
    "orderCode": 123,
    "amount": 3000,
    "description": "VQRIO123",
    "accountNumber": "12345678",
    "reference": "TF230204212323",
    "transactionDateTime": "2023-02-04 18:25:00",
    "currency": "VND",
    "paymentLinkId": "124c33293c43417ab7879e14c8d9eb18",
    "code": "00",
    "desc": "Thành công",
    "counterAccountBankId": "",
    "counterAccountBankName": "",
    "counterAccountName": "",
    "counterAccountNumber": "",
    "virtualAccountName": "",
    "virtualAccountNumber": ""
  },
  "signature": "8d8640d802576397a1ce45ebda7f835055768ac7ad2e0bfb77f9b8f12cca4c7f"
}; */
const webhookData = payOS.verifyPaymentWebhookData(req.body);

Các kiểu dữ liệu​

Chúng tôi cung cấp danh sách kiểu dữ liệu sử dụng trong thư viện payOS cho NodeJS

Kiểu dữ liệu CheckoutRequestType​

export type CheckoutRequestType = {
  orderCode: number, // Mã đơn hàng
  amount: number, // Số tiền của đơn hàng
  description: string, // Mô tả đơn hàng, được sử dụng làm nội dung chuyển khoản
  cancelUrl: string, // URL của trang web hoặc ứng dụng sẽ được chuyển hướng tới khi khách hàng hủy thanh toán
  returnUrl: string, // URL của trang web hoặc ứng dụng sẽ được chuyển hướng tới khi khách hàng thanh toán thành công
  signature?: string, // Chữ ký cho dữ liệu của đơn hàng, có chức năng kiểm tra tính toàn vẹn của dữ liệu
  items?: { name: string, quantity: number, price: number }[],
  buyerName?: string, // Tên người mua hàng
  buyerEmail?: string, // Email người mua hàng
  buyerPhone?: string, // Số điện thoại người mua hàng
  buyerAddress?: string, // Địa chỉ người mua hàng
  expiredAt?: number, // Thời gian hết hạn của link thanh toán
};

Kiểu dữ liệu CheckoutResponseDataType​

export type CheckoutResponseDataType = {
  bin: string, // Mã BIN ngân hàng
  accountNumber: string, // Số tài khoản của kênh thanh toán
  accountName: string, // Tên chủ tài khoản của kênh thanh toán
  amount: number, // Số tiền của đơn hàng
  description: string, // Mô tả đơn hàng, được sử dụng làm nội dung chuyển khoản
  orderCode: number, // Mã đơn hàng
  currency: string, // Đơn vị tiền tệ
  paymentLinkId: string, // ID link thanh toán
  status: string, // Trạng thái của link thanh toán
  checkoutUrl: string, // Đường dẫn trang thanh toán
  qrCode: string, // Mã QR thanh toán
};

Kiểu dữ liệu PaymentLinkDataType​

export type PaymentLinkDataType = {
  id: string, // ID link thanh toán
  orderCode: number, // Mã đơn hàng
  amount: number, // Số tiền của đơn hàng
  amountPaid: number, // Số tiền đã thanh toán
  amountRemaining: number, // Số tiền cần thanh toán còn lại
  status: string, // Trạng thái của link thanh toán
  createdAt: string, // Thời gian tạo link thanh toán
  transactions: TransactionType[], // Danh sách các giao dịch của link thanh toán
  cancellationReason: string | null, // Lý do hủy link thanh toán nếu liên kết đã bị hủy/
  canceledAt: string | null, // Thời gian hủy link thanh toán
};

Kiểu dữ liệu TransactionType​

type TransactionType = {
  reference: string, // Mã tham chiếu của giao dịch
  amount: number, // Số tiền chuyển khoản của giao dịch
  accountNumber: string, // Số tài khoản nhận tiền (là số tài khoản của kênh thanh toán)
  description: string, // Nội dung chuyển khoản
  transactionDateTime: string, // Ngày giờ giao dịch
  virtualAccountName: string | null, // Tên chủ tài khoản ảo
  virtualAccountNumber: string | null, // Số tài khoản ảo
  counterAccountBankId: string | null, // ID ngân hàng đối ứng
  counterAccountBankName: string | null, // Tên ngân hàng đối ứng
  counterAccountName: string | null, // Tên chủ tài khoản đối ứng
  counterAccountNumber: string | null, // Số tài khoản đối ứng
};

Kiểu dữ liệu WebhookType​

export type WebhookType = {
  code: string, // Mã lỗi
  desc: string, // Mô tả lỗi
  success: boolean, // Trạng thái của webhook
  data: WebhookDataType, // Dữ liệu Webhook
  signature: string, // Chữ ký số của dữ liệu Webhook, dùng để kiểm tra tính toàn vẹn của dữ liệu
};

Kiểu dữ liệu WebhookDataType​

export type WebhookDataType = {
  orderCode: number, // Mã đơn hàng
  amount: number, // Số tiền của giao dịch chuyển khoản
  description: string, // Mô tả đơn hàng, được dùng làm nội dung chuyển khoản
  accountNumber: string, // Số tài khoản của kênh thanh toán
  reference: string, // Mã đối ứng của giao dịch chuyển khoản
  transactionDateTime: string, // Ngày giờ diễn ra giao dịch chuyển khoản
  currency: string, // Đơn vị tiền tệ
  paymentLinkId: string, // ID link thanh toán
  code: string, // Mã lỗi
  desc: string, // Mô tả lỗi
  counterAccountBankId?: string | null, // ID ngân hàng đối ứng
  counterAccountBankName?: string | null, // Tên ngân hàng đối ứng
  counterAccountName?: string | null, // Tên chủ tài khoản đối ứng
  counterAccountNumber?: string | null, // Số tài khoản đối ứng
  virtualAccountName?: string | null, // Tên chủ tài khoản ảo
  virtualAccountNumber?: string | null, // Số tài khoản ảo
};