NodeJS SDK

Official Node.js SDK for SePay payment gateway. Supports bank transfer QR code scanning VietQR, Napas QR code transfer, and international/domestic card payments via Visa/Master Card/JCB.

Requirements

Node 16 or higher

Installation

JSInstallation
1
npm i sepay-pg-node

Initialize Client

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

Parameter explanation

envstringrequired
Current environment, supported values: sandbox, production
merchant_idstringrequired
Merchant unit code
secret_keystringrequired
Merchant secret key

Initialize Payment Form Object (One-time Payment Order)

JSCreate payment URL
1
const checkoutURL = client.checkout.initCheckoutUrl();
JSInitialize one-time payment
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,
});

Parameter explanation

operationstringrequired
Transaction type, currently only supports: PURCHASE
payment_methodstringrequired
Payment method: CARD, BANK_TRANSFER, NAPAS_BANK_TRANSFER
order_invoice_numberstringrequired
Order/invoice number (unique)
order_amountstringrequired
Transaction amount
currencystringrequired
Currency unit (e.g.: VND, USD)
order_descriptionstring
Order description
customer_idstring
Customer ID (if available)
success_urlstring
Callback URL on successful payment
error_urlstring
Callback URL on error
cancel_urlstring
Callback URL when user cancels payment
custom_datastring
Custom data (merchant defined)
Returned JSON
{
  "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"
}

Create payment processing form

Important note about creating HTML form and signature

If you build your own HTML form and signature generation function not following the sample code, you must ensure the field order matches the parameter list above so the signing process matches exactly with SePay; swapping field positions may cause invalid signature and SePay will consider the request invalid

JSPayment form
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">Pay now</button>
</form>
);

API

SDK provides methods to call Open API for SePay payment gateway.

JSQuery order list
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);
}
};
JSView order details
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);
}
};
JSVoid order transaction (for credit card payments)
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);
}
};
JSCancel order (for QR code payments)
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);
}
};

See detailed installation and usage guide at GitHub Repository

Previous page
—
Next page
—