The payOS library provides convenient access to the payOS API from applications written in server-side JavaScript.
See the payOS API docs for more infomation.
Install the package with:
bun add @meewmeew/payos-bunYou need to initialize the PayOS object with the Client ID, Api Key and Checksum Key of the payment channel you created.
import PayOS from "@meewmeew/payos-bun";
const payos = new PayOS(
"YOUR_PAYOS_CLIENT_ID",
"YOUR_PAYOS_API_KEY",
"YOUR_PAYOS_CHECKSUM_KEY"
);- createPaymentLink
Create a payment link for the order data
Syntax:
await payos.createPaymentLink(requestData);Parameter data type:
{
orderCode: number;
amount: number;
description: string;
cancelUrl: string;
returnUrl: string;
signature?: string;
items?: { name: string; quantity: number; price: number }[];
buyerName?: string;
buyerEmail?: string;
buyerPhone?: string;
buyerAddress?: string;
expiredAt?: number;
}Return data type:
{
bin: string;
accountNumber: string;
accountName: string;
amount: number;
description: string;
orderCode: number;
paymentLinkId: string;
status: string;
checkoutUrl: string;
qrCode: string;
}Example:
const requestData = {
orderCode: 234234,
amount: 1000,
description: "Thanh toan don hang",
items: [
{
name: "Mì tôm hảo hảo ly",
quantity: 1,
price: 1000,
},
],
cancelUrl: "https://your-domain.com",
returnUrl: "https://your-domain.com",
};
const paymentLinkData = await payos.createPaymentLink(requestData);- getPaymentLinkInfomation
Get payment information of an order that has created a payment link.
Syntax:
await payos.getPaymentLinkInfomation(id);Parameters:
-
id: Store order code (orderCode) or payOS payment link id (paymentLinkId). Type ofidis string or number.
Return data type:
{
id: string;
orderCode: number;
amount: number;
amountPaid: number;
amountRemaining: number;
status: string;
createdAt: string;
transactions: TransactionType[];
cancellationReason: string | null;
canceledAt: string | null;
}Transaction type:
{
reference: string;
amount: number;
accountNumber: string;
description: string;
transactionDateTime: string;
virtualAccountName: string | null;
virtualAccountNumber: string | null;
counterAccountBankId: string | null;
counterAccountBankName: string | null;
counterAccountName: string | null;
counterAccountNumber: string | null;
}Example:
const paymentLinkInfo = await payos.getPaymentLinkInfomation(1234);- cancelPaymentLink
Cancel the payment link of the order.
Syntax:
await payos.cancelPaymentLink(orderCode, cancellationReason);Parameters:
-
id: Store order code (orderCode) or payOS payment link id (paymentLinkId). Type ofidis string or number. -
cancellationReason: Reason for canceling payment link (optional).
Return data type:
{
id: string;
orderCode: number;
amount: number;
amountPaid: number;
amountRemaining: number;
status: string;
createdAt: string;
transactions: TransactionType[];
cancellationReason: string | null;
canceledAt: string | null;
}Example:
const orderCode = 123;
const cancellationReason = "reason";
const cancelledPaymentLinkInfo = await payos.cancelPaymentLink(
orderCode,
cancellationReason
);
// If you want to cancel the payment link without reason:
const cancelledPaymentLinkInfo = await payos.cancelPaymentLink(orderCode);- confirmWebhook
Validate the Webhook URL of a payment channel and add or update the Webhook URL for that Payment Channel if successful.
Syntax:
await payos.confirmWebhook("https://your-webhook-url/");- verifyPaymentWebhookData
Verify data received via webhook after payment.
Syntax:
const webhookBody = req.body;
const paymentData = payos.verifyPaymentWebhookData(webhookBody);Return data type:
{
orderCode: number;
amount: number;
description: string;
accountNumber: string;
reference: string;
transactionDateTime: string;
paymentLinkId: string;
code: string;
desc: string;
counterAccountBankId?: string | null;
counterAccountBankName?: string | null;
counterAccountName?: string | null;
counterAccountNumber?: string | null;
virtualAccountName?: string | null;
virtualAccountNumber?: string | null;
}