NodeJS SDK

Thư viện Node.js SDK chính thức của cổng thanh toán SePay. Hỗ trợ các hình thức tích hợp thanh toán quét mã chuyển khoản ngân hàng VietQr, quét mã chuyển khoản Napas, thanh toán qua thẻ quốc tế/nội địa Visa/Master Card/JCB.

Yêu cầu

Node 16 hoặc cao hơn

Cài đặt

JSCài đặt
1
npm i sepay-pg-node

Khởi tạo Client

JSKhởi tạo client
1
2
3
4
5
6
7
import { SePayPgClient } from 'sepay-pg-node';
 
const client = new SePayPgClient({
env: 'sandbox',
merchant_id: 'YOUR_MERCHANT_ID',
secret_key: 'YOUR_MERCHANT_SECRET_KEY'
});

Giải thích tham số

envstringrequired
Môi trường hiện tại, giá trị hỗ trợ: sandbox, production
merchant_idstringrequired
Mã đơn vị merchant
secret_keystringrequired
Khóa bảo mật merchant

Khởi tạo đối tượng cho biểu mẫu thanh toán (Đơn hàng thanh toán 1 lần)

JSTạo URL thanh toán
1
const checkoutURL = client.checkout.initCheckoutUrl();
JSKhởi tạo thanh toán một lần
1
2
3
4
5
6
7
8
9
10
11
12
13
const checkoutFormfields = client.checkout.initOneTimePaymentFields({
operation: 'PURCHASE',
payment_method: 'CARD' | 'BANK_TRANSFER' | 'NAPAS_BANK_TRANSFER',
order_invoice_number: string,
order_amount: number,
currency: string,
order_description?: string,
customer_id?: string,
success_url?: string,
error_url?: string,
cancel_url?: string,
custom_data?: string,
});

Giải thích tham số

operationstringrequired
Loại giao dịch, hiện chỉ hỗ trợ: PURCHASE
payment_methodstringrequired
Phương thức thanh toán: CARD, BANK_TRANSFER, NAPAS_BANK_TRANSFER
order_invoice_numberstringrequired
Mã đơn hàng/hoá đơn (duy nhất)
order_amountstringrequired
Số tiền giao dịch
currencystringrequired
Đơn vị tiền tệ (VD: VND, USD)
order_descriptionstring
Mô tả đơn hàng
customer_idstring
Mã khách hàng (nếu có)
success_urlstring
URL callback khi thanh toán thành công
error_urlstring
URL callback khi xảy ra lỗi
cancel_urlstring
URL callback khi người dùng hủy thanh toán
custom_datastring
Dữ liệu tuỳ chỉnh (merchant tự định nghĩa)
Json trả về
{
  "merchant": "string",
  "operation": "string",
  "payment_method": "string",
  "order_invoice_number": "string",
  "order_amount": "string",
  "currency": "string",
  "order_description": "string",
  "customer_id": "string",
  "success_url": "string",
  "error_url": "string",
  "cancel_url": "string",
  "custom_data": "string",
  "signature": "string"
}

Tạo form xử lý thanh toán

Lưu ý quan trọng về tạo form HTML và chữ ký

Nếu bạn tự dựng form HTML và xây dựng hàm tạo chữ ký không theo code mẫu thì cần phải đảm bảo thứ tự các trường giống như danh sách tham số ở trên để quá trình ký khớp tuyệt đối phía SePay; Nếu bạn hoán đổi vị trí các trường thì có thể dẫn đến chữ ký bị sai và SePay sẽ xem yêu cầu này là không hợp lệ

JSForm thanh toán
1
2
3
4
5
6
7
8
return (
<form action={checkoutURL} method="POST">
  {Object.keys(checkoutFormfields).map(field => (
    <input type="hidden" name={field} value={checkoutFormfields[field]} />
  ))}
  <button type="submit">Thanh toán</button>
</form>
);

API

SDK cung cấp các phương thức để gọi Open API cho cổng thanh toán SePay.

JSTra cứu danh sách đơn hàng
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const fetchOrders = async () => {
try {
  const orders = await client.order.all({
    per_page: 20,
    q: 'search-keyword',
    order_status: 'COMPLETED',
    created_at: '2025-10-13',
    from_created_at: '2025-10-01',
    to_created_at: '2025-10-13',
    customer_id: null,
    sort: {
      created_at: 'desc'
    }
  });
 
  console.log('Orders:', orders.data);
} catch (error) {
  console.error('Error fetching orders:', error);
}
};
JSXem chi tiết đơn hàng
1
2
3
4
5
6
7
8
const fetchOrderDetail = async (orderInvoiceNumber) => {
try {
  const order = await client.order.retrieve(orderInvoiceNumber);
  console.log('Order detail:', order.data);
} catch (error) {
  console.error('Error fetching order detail:', error);
}
};
JSHủy giao dịch đơn hàng (dành cho thanh toán bằng thẻ tín dụng)
1
2
3
4
5
6
7
8
const voidTransaction = async (orderInvoiceNumber) => {
try {
  const response = await client.order.voidTransaction(orderInvoiceNumber);
  console.log('Transaction voided successfully:', response.data);
} catch (error) {
  console.error('Error voiding transaction:', error);
}
};
JSHủy đơn hàng (dành cho thanh toán bằng quét mã QR)
1
2
3
4
5
6
7
8
const cancelOrder = async (orderInvoiceNumber) => {
try {
  const response = await client.order.cancel(orderInvoiceNumber);
  console.log('Order cancelled successfully:', response.data);
} catch (error) {
  console.error('Error cancelling order:', error);
}
};

Xem chi tiết hướng dẫn cài đặt và sử dụng tại GitHub Repository

Trước
—
Tiếp theo
—