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.
- Node 16 hoặc cao hơn
Cài đặt qua thư mục đã tải xuống:
npm install github:sepay/sepay-pg-node
Thư viện cần cấu hình các thông tin từ đơn vị bán hàng của bạn (merchant) được lấy từ my.sepay.vn.
import { SePayPgClient } from 'sepay-pg-node';
const client = new SePayPgClient({
env: 'sandbox',
merchant_id: 'YOUR_MERCHANT_ID',
secret_key: 'YOUR_MERCHANT_SECRET_KEY',
});Tạo biểu mẫu thanh toán cho đơn hàng có mã DH0001, số tiền thanh toán là 10.000đ. Sau khi thanh toán thành công sẽ tự động chuyển hướng về đường dẫn: https://example.com/order/DH0001
const fields = client.checkout.initOneTimePaymentFields({
operation: 'PURCHASE',
order_invoice_number: 'DH0001',
order_amount: 10000,
currency: 'VND',
success_url: 'https://example.com/order/DH0001'
order_description: 'Thanh toan don hang DH0001',
});
console.log(fields)Kết quả trả về kiểu object key-value
{
merchant: 'YOUR_MERCHANT_ID',
operation: 'PURCHASE',
order_invoice_number: 'DH0001',
order_amount: 10000,
currency: 'VND',
order_description: 'Thanh toan don hang DH0001',
success_url: 'https://example.com/order/DH0001'
signature: 'AUTO_GENERATED_SIGNATURE'
}Kết hợp với client.checkout.initCheckoutUrl() để lấy URL và tạo form xử lý thanh toán sau khi đã tạo đơn hàng.
return (
<form action={client.checkout.initCheckoutUrl()} method="POST">
{Object.keys(fields).map(field => <input type="hidden" name={field} value={fields[field]} />)}
<button type="submit">Thanh toán</button>
</form>
)import { SePayPgClient } from 'sepay-pg-node';
const client = new SePayPgClient({
env: 'sandbox',
merchant_id: 'YOUR_MERCHANT_ID',
secret_key: 'YOUR_MERCHANT_SECRET_KEY',
});| Tham số | Mô tả |
|---|---|
| env | Môi trường hiện tại, giá trị hỗ trợ: "sandbox", "production" |
| merchant_id | Mã đơn vị merchant |
| secret_key | Khóa bảo mật merchant |
| api_version | Phiên bản API sử dụng, giá trị hỗ trợ: "v1" |
| checkout_version | Phiên bản trang thanh toán sử dụng, giá trị hỗ trợ: "v1" |
Sử dụng client.checkout.initCheckoutUrl() để tạo URL thanh toán theo thông tin đã cấu hình.
| Môi trường | URL thanh toán |
|---|---|
| sandbox | https://sandbox.pay.sepay.vn/[VERSION]/init |
| production | https://pay.sepay.vn/[VERSION]/init |
client.checkout.initOneTimePaymentFields({
operation: 'PURCHASE';
payment_method: '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;
});| Tham số | Bắt buộc | Mô tả |
|---|---|---|
| operation | ✔︎ | Loại giao dịch, hiện chỉ hỗ trợ: "PURCHASE" |
| payment_method | ✔︎ | Phương thức thanh toán: "BANK_TRANSFER", "NAPAS_BANK_TRANSFER" |
| order_invoice_number | ✔︎ | Mã đơn hàng/hoá đơn (duy nhất) |
| order_amount | ✔︎ | Số tiền giao dịch |
| currency | ✔︎ | Đơn vị tiền tệ (VD: "VND", "USD") |
| order_description | Mô tả đơn hàng | |
| customer_id | Mã khách hàng (nếu có) | |
| success_url | URL callback khi thanh toán thành công | |
| error_url | URL callback khi xảy ra lỗi | |
| cancel_url | URL callback khi người dùng hủy thanh toán | |
| custom_data | Dữ liệu tuỳ chỉnh (merchant tự định nghĩa) |
Dữ liệu trả về dạng object:
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
| merchant | ✔︎ | Mã merchant |
| operation | ✔︎ | Loại giao dịch, hiện chỉ hỗ trợ: "PURCHASE" |
| payment_method | ✔︎ | Phương thức thanh toán: "BANK_TRANSFER", "NAPAS_BANK_TRANSFER" |
| order_invoice_number | ✔︎ | Mã đơn hàng/hoá đơn (duy nhất) |
| order_amount | ✔︎ | Số tiền giao dịch |
| currency | ✔︎ | Đơn vị tiền tệ (VD: "VND", "USD") |
| order_description | ✔︎ | Mô tả đơn hàng |
| customer_id | Mã khách hàng (nếu có) | |
| success_url | URL callback khi thanh toán thành công | |
| error_url | URL callback khi xảy ra lỗi | |
| cancel_url | URL callback khi người dùng hủy thanh toán | |
| custom_data | Dữ liệu tuỳ chỉnh (merchant tự định nghĩa) | |
| signature | ✔︎ | Chữ ký bảo mật (HMAC SHA256) để xác thực dữ liệu trả về |
SDK cung cấp các phương thức để gọi Open API cho cổng thanh toán SePay.
client.order.all({
per_page?: number,
q?: string,
order_status?: string,
created_at?: string,
from_created_at?: string,
to_created_at?: string,
customer_id?: string | null,
sort?: {
created_at?: string
}
})client.order.retrieve(order_invoice_number: string)client.order.voidTransaction(order_invoice_number: string)client.order.cancel(order_invoice_number: string)Thư viện sử dụng giấy phép MIT. Xem chi tiết LICENSE.
- Email: [email protected]
- Tài liệu: https://docs.sepay.vn