NodeJS SDK

The official Node.js SDK library for SePay payment gateway. Supports integration methods for payments via VietQR bank transfers, Napas transfers, and international/domestic cards such as Visa/MasterCard/JCB.

Requirements

Node 16 or higher

Installation

npm i sepay-pg-node

Client Initialization

Initialize client

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

Name	Type	Required	Description
`env`	string	Required	Current environment. Supported values: sandbox, production
`merchant_id`	string	Required	Merchant identifier
`secret_key`	string	Required	Merchant secret key

Initialize checkout form object (One-time payment order)

Generate checkout URL

const checkoutURL = client.checkout.initCheckoutUrl();

Initialize one-time payment

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

Name	Type	Required	Description
`operation`	string	Required	Transaction type. Currently only supports: PURCHASE
`payment_method`	string	Required	Payment method: CARD, BANK_TRANSFER, NAPAS_BANK_TRANSFER
`order_invoice_number`	string	Required	Unique order/invoice number
`order_amount`	string	Required	Transaction amount
`currency`	string	Required	Currency unit (e.g., VND, USD)
`order_description`	string	Not required	Order description
`customer_id`	string	Not required	Customer ID (if available)
`success_url`	string	Not required	Callback URL when payment succeeds
`error_url`	string	Not required	Callback URL when an error occurs
`cancel_url`	string	Not required	Callback URL when the user cancels the payment
`custom_data`	string	Not required	Custom data (defined by merchant)

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 form

Important note on creating HTML form and signature

If you build your own HTML form and build the signature function without following the sample code, you need to ensure the order of the fields is the same as the parameter list above so that the signing process matches SePay's side absolutely; If you swap the positions of the fields, it may lead to an incorrect signature and SePay will consider this request invalid

Payment form

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

The SDK provides methods to call SePay's Open API for payment gateway operations.

Retrieve order list

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

Get order details

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

Void transaction (for credit card payments)

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

Cancel order (for QR code payments)

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

For more detailed setup and usage instructions, visit the GitHub Repository