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

Documentation

See the payOS API docs for more information.

Installation

Install the package with:

1npm install @payos/node
2# or
3yarn add @payos/node

Usage

Initialize

You need to initialize the PayOS object with the Client ID, Api Key and Checksum Key of the payment channel you created.

• CommonJS

1const PayOS = require("@payos/node");
2
3const payos = new PayOS("YOUR_PAYOS_CLIENT_ID", "YOUR_PAYOS_API_KEY", "YOUR_PAYOS_CHECKSUM_KEY");
4// or
5const payos = new PayOS("YOUR_PAYOS_CLIENT_ID", "YOUR_PAYOS_API_KEY", "YOUR_PAYOS_CHECKSUM_KEY", "YOUR_PARTNER_CODE" );

• ES Modules

1import PayOS from "@payos/node";
2
3const payos = new PayOS("YOUR_PAYOS_CLIENT_ID", "YOUR_PAYOS_API_KEY", "YOUR_PAYOS_CHECKSUM_KEY");
4//or
5const payos = new PayOS("YOUR_PAYOS_CLIENT_ID", "YOUR_PAYOS_API_KEY", "YOUR_PAYOS_CHECKSUM_KEY", "YOUR_PARTNER_CODE");

Methods included in the PayOS object

• createPaymentLink

Create a payment link for the order data

Syntax:

1await payos.createPaymentLink(requestData);

Parameter data type:

1{
2  orderCode: number;
3  amount: number;
4  description: string;
5  cancelUrl: string;
6  returnUrl: string;
7  signature?: string;
8  items?: { name: string; quantity: number; price: number }[];
9  buyerName?: string;
10  buyerEmail?: string;
11  buyerPhone?: string;
12  buyerAddress?: string;
13  expiredAt?: number;
14}

Return data type:

1{
2  bin: string;
3  accountNumber: string;
4  accountName: string;
5  amount: number;
6  description: string;
7  orderCode: number;
8  currency: string;
9  paymentLinkId: string;
10  status: string;
11  expiredAt: number;
12  checkoutUrl: string;
13  qrCode: string
14}

Example:

1const requestData = {
2    orderCode: 234234,
3    amount: 1000,
4    description: "Thanh toan don hang",
5    items: [
6      {
7        name: "Mì tôm hảo hảo ly",
8        quantity: 1,
9        price: 1000,
10      }
11    ],
12    cancelUrl: "https://your-domain.com",
13    returnUrl: "https://your-domain.com",
14};
15const paymentLinkData = await payos.createPaymentLink(requestData);

• getPaymentLinkInformation

Get payment information of an order that has created a payment link.

Syntax:

1await payos.getPaymentLinkInformation(id);

Parameters:

• id: Store order code (orderCode) or payOS payment link id (paymentLinkId). Type of id is string or number.

Return data type:

1{
2  id: string;
3  orderCode: number;
4  amount: number;
5  amountPaid: number;
6  amountRemaining: number;
7  status: string;
8  createdAt: string;
9  transactions: TransactionType[];
10  cancellationReason: string | null;
11  canceledAt: string | null;
12}

Transaction type:

1{
2  reference: string;
3  amount: number;
4  accountNumber: string;
5  description: string;
6  transactionDateTime: string;
7  virtualAccountName: string | null;
8  virtualAccountNumber: string | null;
9  counterAccountBankId: string | null;
10  counterAccountBankName: string | null;
11  counterAccountName: string | null;
12  counterAccountNumber: string | null
13}

Example:

1const paymentLinkInfo = await payos.getPaymentLinkInformation(1234);

• cancelPaymentLink

Cancel the payment link of the order.

Syntax:

1await 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:

1{
2  id: string;
3  orderCode: number;
4  amount: number;
5  amountPaid: number;
6  amountRemaining: number;
7  status: string;
8  createdAt: string;
9  transactions: TransactionType[];
10  cancellationReason: string | null;
11  canceledAt: string | null;
12}

Example:

1const orderCode = 123;
2const cancellationReason = "reason";
3
4const cancelledPaymentLinkInfo = await payos.cancelPaymentLink(orderCode, cancellationReason); 
5
6// If you want to cancel the payment link without reason:
7const 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:

1await payos.confirmWebhook("https://your-webhook-url/");

• verifyPaymentWebhookData

Verify data received via webhook after payment.

Syntax:

1const webhookBody = req.body;
2const paymentData = payos.verifyPaymentWebhookData(webhookBody);

Return data type:

1{
2  orderCode: number;
3  amount: number;
4  description: string;
5  accountNumber: string;
6  reference: string;
7  transactionDateTime: string;
8  currency: string;
9  paymentLinkId: string;
10  code: string;
11  desc: string;
12  counterAccountBankId?: string | null;
13  counterAccountBankName?: string | null;
14  counterAccountName?: string | null;
15  counterAccountNumber?: string | null;
16  virtualAccountName?: string | null;
17  virtualAccountNumber?: string | null;
18}