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

npm i sepay-pg-node

Khởi tạo Client

Khởi tạo client

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ố

Tên	Loại	Bắt buộc	Mô tả
`env`	string	Bắt buộc	Môi trường hiện tại, giá trị hỗ trợ: sandbox, production
`merchant_id`	string	Bắt buộc	Mã đơn vị merchant
`secret_key`	string	Bắt buộc	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)

Tạo URL thanh toán

const checkoutURL = client.checkout.initCheckoutUrl();

Khởi tạo thanh toán một lần

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ố

Tên	Loại	Bắt buộc	Mô tả
`operation`	string	Bắt buộc	Loại giao dịch, hiện chỉ hỗ trợ: PURCHASE
`payment_method`	string	Bắt buộc	Phương thức thanh toán: CARD, BANK_TRANSFER, NAPAS_BANK_TRANSFER
`order_invoice_number`	string	Bắt buộc	Mã đơn hàng/hoá đơn (duy nhất)
`order_amount`	string	Bắt buộc	Số tiền giao dịch
`currency`	string	Bắt buộc	Đơn vị tiền tệ (VD: VND, USD)
`order_description`	string	Không bắt buộc	Mô tả đơn hàng
`customer_id`	string	Không bắt buộc	Mã khách hàng (nếu có)
`success_url`	string	Không bắt buộc	URL callback khi thanh toán thành công
`error_url`	string	Không bắt buộc	URL callback khi xảy ra lỗi
`cancel_url`	string	Không bắt buộc	URL callback khi người dùng hủy thanh toán
`custom_data`	string	Không bắt buộc	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ệ

Form thanh toán

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.

Tra cứu danh sách đơn hàng

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);
  }
};

Xem chi tiết đơn hàng

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);
  }
};

Hủy giao dịch đơn hàng (dành cho thanh toán bằng thẻ tín dụng)

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);
  }
};

Hủy đơn hàng (dành cho thanh toán bằng quét mã QR)

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