The payOS library provides convenient access to the payOS API from applications written in server-side JavaScript.

Documentation

See the payOS API docs for more infomation.

Installation

Install the package with:

bun add @meewmeew/payos-bun

Usage

Initialize

You 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"
);

Methods included in the PayOS object

• 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 of id is 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 of id is 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;
}