SePay Node.js 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

Cài đặt qua thư mục đã tải xuống:

npm install github:sepay/sepay-pg-node

Bắt đầu nhanh

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

Cấu hình

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" |

Khởi tạo đối tượng cho biểu mẫu thanh toán

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 |

Đơn hàng thanh toán 1 lần

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ề |

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

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

Xem chi tiết đơn hàng

client.order.retrieve(order_invoice_number: string)

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

client.order.voidTransaction(order_invoice_number: string)

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

client.order.cancel(order_invoice_number: string)

Giấy phép sử dụng

Thư viện sử dụng giấy phép MIT. Xem chi tiết LICENSE.

Hỗ trợ

• Email: [email protected]
• Tài liệu: https://docs.sepay.vn