Nhảy tới nội dung

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 KeyChecksum 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
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
}