vnpayjs

https://vnpay.js.org
Admin
vnpayjs is an open-source Node.js library designed to simplify the integration of VNPay online...
Tokens:13,201
Snippets:81
Trust Score:8.1
Update:9 months ago
Show doc for...
Tokens:
Raw
### Initialize VNPay Instance in Node.js

Source: https://vnpay.js.org/en/installation

Code example for initializing the VNPay client instance with necessary configuration parameters. This setup is essential for making payment requests from your Node.js backend.

```javascript
import { VNPay, ignoreLogger } from 'vnpay';

const vnpay = new VNPay({
    tmnCode: 'YOUR_TMNCODE',
    secureSecret: 'YOUR_SECURE_SECRET',
    vnpayHost: 'https://sandbox.vnpayment.vn',
    queryDrAndRefundHost: 'https://sandbox.vnpayment.vn', // optional, when the url of querydr and refund is different from the payment url (usually used for production) 

    testMode: true, // optional, overrides vnpayHost to sandbox if true
    hashAlgorithm: 'SHA512', // optional

    /**
     * Enable/disable logging
     * If enableLog is false, loggerFn will not be used in any method
     */
    enableLog: true, // optional

    /**
     * `loggerFn` will be called to write logs when enableLog is true
     * By default, loggerFn will write logs to the console
     * If you want to write logs elsewhere, you can provide a custom function
     *
     * `ignoreLogger` is a function that does nothing
     */
    loggerFn: ignoreLogger, // optional

    /**
     * Customize VNPay API endpoints
     * Usually doesn't need to be changed unless:
     * - VNPay updates their paths
     * - There are differences between sandbox and production environments
     */
    endpoints: {
        paymentEndpoint: 'paymentv2/vpcpay.html',
        queryDrRefundEndpoint: 'merchant_webapi/transaction',
        getBankListEndpoint: 'qrpayauth/api/merchant/get_bank_list',
    }, // optional
});

```

--------------------------------

### Correct Frontend Type Imports for VNPay (TypeScript)

Source: https://vnpay.js.org/en/examples

This example shows the correct way to import types from the 'vnpay' library in a frontend TypeScript project. It emphasizes importing only types to avoid runtime errors, as the 'fs' module (often used by the library) is not available in a browser environment. This prevents build errors and ensures type safety.

```typescript
// ✅ Safe - import types only
import type { VNPayConfig, BuildPaymentUrl, Bank, VerifyReturnUrl } from 'vnpay/types-only';

// Or use type import with main package
import type { VNPayConfig } from 'vnpay';

interface PaymentComponentProps {
    config: VNPayConfig;
    onPaymentResult: (result: VerifyReturnUrl) => void;
}
```

--------------------------------

### IPN Handler Example

Source: https://vnpay.js.org/en/examples

This endpoint receives Instant Payment Notifications (IPN) from VNPay, verifies the payment status, and updates the order accordingly.

```APIDOC
## POST /api/payment/ipn

### Description
Handles Instant Payment Notifications (IPN) from VNPay. It verifies the IPN call and updates the order status based on the payment outcome.

### Method
POST

### Endpoint
/api/payment/ipn

### Request Body
- **vnpay_token** (string) - Required - The token containing payment details from VNPay.

### Request Example
```json
{
  "vnpay_token": "your_vnpay_token_here"
}
```

### Response
#### Success Response (200)
- **RspCode** (string) - '00' for success, '01' for failure.
- **Message** (string) - 'success' or 'fail'.

#### Error Response (500)
- **RspCode** (string) - '99' for internal server error.
- **Message** (string) - 'error'.

#### Response Example
```json
{
  "RspCode": "00",
  "Message": "success"
}
```
```

--------------------------------

### Install VNPay with NPM, Yarn, or PNPM

Source: https://vnpay.js.org/en/installation

Install the VNPay library using your preferred package manager. This is the initial step to integrate VNPay payment functionality into your Node.js project.

```bash
$ npm install vnpay
```

```bash
$ yarn add vnpay
```

```bash
$ pnpm install vnpay
```

--------------------------------

### Get VNPay Bank List using JavaScript

Source: https://vnpay.js.org/en/get-bank-list

This snippet demonstrates how to retrieve a list of banks supported by VNPay using the VNPay SDK in JavaScript. It requires the VNPay SDK to be installed and initialized.

```javascript
import { Bank } from 'vnpay';

/* ... */

const bankList: Bank[] = await vnpay.getBankList();
```

--------------------------------

### Build VNPay Payment URL with Console Logging

Source: https://vnpay.js.org/en/create-payment-url

This example shows how to build a VNPay payment URL and configure logging using the SDK's options. It utilizes a 'pick' type logger to selectively log specific fields to the console.

```javascript
import { ProductCode, VnpLocale, consoleLogger } from 'vnpay';  
  
/* ... */  
  
const paymentUrl = vnpay.buildPaymentUrl(  
    {  
        vnp_Amount: 10000,  
        vnp_IpAddr: '1.1.1.1',  
        vnp_TxnRef: '123456',  
        vnp_OrderInfo: 'Payment for order 123456',  
        vnp_OrderType: ProductCode.Other,  
        vnp_ReturnUrl: `http://localhost:${port}/vnpay-return`,  
    },  
    {  
        logger: {  
            type: 'pick', // The mode to select log fields, can be 'pick', 'omit' or 'all'  
            fields: ['createdAt', 'method', 'paymentUrl'], // Select the fields to log  
            loggerFn: consoleLogger, // Log data to console, can be replaced with another function  
        },  
    },  
);  
```

--------------------------------

### Initiate VNPay Payment (React/Next.js)

Source: https://vnpay.js.org/en/examples

Frontend React component to initiate a VNPay payment. It calls a backend API to create the payment URL and then redirects the user to VNPay. Handles loading states and errors during the process. Uses types from 'vnpay/types-only' for type safety.

```typescript
// frontend/components/PaymentButton.tsx
import { useState } from 'react';
import type { VerifyReturnUrl } from 'vnpay/types-only'; // ✅ Types only  
  
interface PaymentButtonProps {
  amount: number;
  orderInfo: string;
  onPaymentResult?: (result: VerifyReturnUrl) => void;
}
  
export const PaymentButton: React.FC<PaymentButtonProps> = ({  
  amount,  
  orderInfo,  
  onPaymentResult  
}) => {
  const [loading, setLoading] = useState(false);
  
  const handlePayment = async () => {
    setLoading(true);
  
    try {
      // ✅ Call backend API instead of direct import  
      const response = await fetch('/api/payments/create', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ amount, orderInfo }),
      });
  
      const data = await response.json();
  
      if (data.success) {
        // Redirect to VNPay
        window.location.href = data.paymentUrl;
      } else {
        alert('Payment creation failed');
      }
    } catch (error) {
      console.error('Payment error:', error);
      alert('Connection error');
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <button  
      onClick={handlePayment}  
      disabled={loading}  
      className="bg-blue-600 text-white px-6 py-2 rounded hover:bg-blue-700"
    >
      {loading ? 'Processing...' : `Pay ${amount.toLocaleString()} VND`}
    </button>
  );
};

```

--------------------------------

### Import VNPay Library Options (v2.4.0+)

Source: https://vnpay.js.org/en/installation

Demonstrates various ways to import components from the VNPay library starting from version 2.4.0. Choose the import method that best suits your needs, with modular imports recommended for optimizing bundle size.

```javascript
import { VNPay, HashAlgorithm, ProductCode } from 'vnpay';

```

```javascript
import { VNPay } from 'vnpay/vnpay';
import { HashAlgorithm, ProductCode } from 'vnpay/enums';
import { VNP_VERSION, PAYMENT_ENDPOINT } from 'vnpay/constants';
import { resolveUrlString, dateFormat } from 'vnpay/utils';

```

```typescript
import type { VNPayConfig, BuildPaymentUrl, Bank } from 'vnpay/types-only';

```

--------------------------------

### Enable and Configure VNPay Logging

Source: https://vnpay.js.org/en/troubleshooting

Demonstrates how to enable and configure the logging functionality within the VNPay JavaScript library. This helps in capturing detailed request and response data for debugging purposes. It requires initializing the VNPay instance with `enableLog: true` and providing a `loggerFn` to handle the log data.

```javascript
const vnpay = new VNPay({
    // ... other config
    enableLog: true,
    loggerFn: (data) => {
        console.log(JSON.stringify(data, null, 2));
        // Or save to a file/database
    },
});
```

--------------------------------

### Example VNPay Payment URL

Source: https://vnpay.js.org/en/create-payment-url

This is an example of a valid payment URL generated by VNPay. It includes all necessary parameters for processing an online payment transaction.

```url
https://sandbox.vnpayment.vn/paymentv2/vpcpay.html?vnp_Amount=1000000&vnp_Command=pay&vnp_CreateDate=20240814214148&vnp_CurrCode=VND&vnp_ExpireDate=20240815214148&vnp_IpAddr=1.1.1.1&vnp_Locale=vn&vnp_OrderInfo=order+information+of+123456-1723671708762&vnp_OrderType=other&vnp_ReturnUrl=http%3A%2F%2Flocalhost%3A3000%2Freturn&vnp_TmnCode=TEST12345&vnp_TxnRef=123456-1723671708762&vnp_Version=2.1.0&vnp_SecureHash=a4dc1ed51f7b9f5e4fe835b9cc85a12aa585d19b4b6f78fdb1cbb2a157deceba39d1517d1976fea8177b2db6b4de983ec6f8e4e439207fc6060491675be11111
```

--------------------------------

### Verify VNPay Payment Result (Node.js/Express)

Source: https://vnpay.js.org/en/examples

Backend route to verify the return URL parameters from VNPay after a payment attempt. It uses the VNPay library's `verifyReturnUrl` method to validate the transaction details. Returns the verification result.

```typescript
// backend/routes/payment.ts (continued)
// Verify payment result
app.get('/api/payments/verify', (req, res) => {
    const verification = vnpay.verifyReturnUrl(req.query);
    res.json(verification);
});
```

--------------------------------

### Create VNPay Payment URL (Node.js/Express)

Source: https://vnpay.js.org/en/examples

Backend route to create a VNPay payment URL using the VNPay library. It takes amount and order information from the request body and returns a payment URL for redirection. Requires VNPay configuration from environment variables.

```typescript
// backend/routes/payment.ts
import { VNPay } from 'vnpay'; // ✅ Full import on backend  
  
const vnpay = new VNPay({
    tmnCode: process.env.VNP_TMNCODE!,
    secureSecret: process.env.VNP_SECRET!,
    testMode: true,
});

// Create payment URL
app.post('/api/payments/create', async (req, res) => {
    try {
        const { amount, orderInfo } = req.body;

        const paymentUrl = vnpay.buildPaymentUrl({
            vnp_Amount: amount,
            vnp_IpAddr: req.ip,
            vnp_ReturnUrl: `${process.env.APP_URL}/payment/callback`,
            vnp_TxnRef: `ORDER_${Date.now()}`,
            vnp_OrderInfo: orderInfo,
        });

        res.json({ success: true, paymentUrl });
    } catch (error) {
        res.status(500).json({ success: false, error: error.message });
    }
});
```

--------------------------------

### Handle VNPay IPN Request (TypeScript)

Source: https://vnpay.js.org/en/examples

This backend route handler processes Instant Payment Notification (IPN) calls from VNPay. It verifies the IPN request using the vnpay library and updates the order status based on the verification result. It expects `req.body` to contain the IPN data and returns a JSON response indicating success or failure.

```typescript
app.post('/api/payment/ipn', (req, res) => {
    try {
        const verification = vnpay.verifyIpnCall(req.body);

        if (verification.isSuccess) {
            // ✅ Payment successful - update database
            console.log('Payment successful:', verification.vnp_TxnRef);

            // Update order status in database
            // updateOrderStatus(verification.vnp_TxnRef, 'PAID');

            res.status(200).json({ RspCode: '00', Message: 'success' });
        } else {
            // ❌ Payment failed
            console.log('Payment failed:', verification.message);
            res.status(200).json({ RspCode: '01', Message: 'fail' });
        }
    } catch (error) {
        console.error('IPN processing error:', error);
        res.status(500).json({ RspCode: '99', Message: 'error' });
    }
});
```

--------------------------------

### Query Transaction Result (queryDr)

Source: https://vnpay.js.org/en/query-dr

This API allows merchant systems to query the payment result of a transaction in the VNPAY system. It is currently suitable for 'PAY' payments and does not support 'token', 'installment', or 'periodic' payment types.

```APIDOC
## POST /queryDr

### Description
This endpoint allows merchant systems to query the payment result of a transaction in the VNPAY system. It is designed for 'PAY' payment types.

### Method
POST

### Endpoint
/queryDr

### Parameters
#### Request Body
- **vnp_RequestId** (string) - Required - Request ID for transaction result query. This ID must be unique for each query request.
- **vnp_IpAddr** (string) - Required - IP address of the client.
- **vnp_TxnRef** (string) - Required - Transaction code of the merchant system.
- **vnp_TransactionNo** (number) - Required - Transaction code of the VNPAY system.
- **vnp_OrderInfo** (string) - Optional - Order information.
- **vnp_TransactionDate** (string) - Required - Transaction time in `yyyyMMddHHmmss` format (GMT+7).
- **vnp_CreateDate** (string) - Required - Transaction creation time in `yyyyMMddHHmmss` format (GMT+7).

### Request Example
```json
{
  "vnp_RequestId": "generateRandomString(16)",
  "vnp_IpAddr": "1.1.1.1",
  "vnp_TxnRef": "1716257871703",
  "vnp_TransactionNo": 14422574,
  "vnp_OrderInfo": "Payment for order",
  "vnp_TransactionDate": "20240521103000",
  "vnp_CreateDate": "20240521103000"
}
```

### Response
#### Success Response (200)
- **isSuccess** (boolean) - Result of the request.
- **isVerified** (boolean) - Verification result of data integrity when received from VNPay.
- **message** (string) - Verification message.
- ... (Other parameters as defined in VNPAY official documentation)

#### Response Example
```json
{
  "isSuccess": true,
  "isVerified": true,
  "message": "Success",
  "vnp_TxnRef": "1716257871703",
  "vnp_Amount": 100000,
  "vnp_ResponseCode": "00",
  "vnp_TransactionStatus": "00",
  "vnp_OrderInfo": "Payment for order",
  "vnp_PayDate": "20240521103500"
}
```
```

--------------------------------

### Verify Return URL with VNPay SDK

Source: https://vnpay.js.org/en/verify-return-url

This snippet demonstrates how to import and use the `VerifyReturnUrl` function from the VNPay SDK to verify the return URL. It expects request query parameters as input and returns a `VerifyReturnUrl` object.

```typescript
import { VerifyReturnUrl } from 'vnpay';  
  
/* ... */  
  
const verify: VerifyReturnUrl = vnpay.verifyReturnUrl(req.query);
```

--------------------------------

### Build VNPay Payment URL using JavaScript SDK

Source: https://vnpay.js.org/en/create-payment-url

This JavaScript code snippet demonstrates how to use the VNPay SDK to build a payment URL. It imports necessary modules and calls the `buildPaymentUrl` function with essential payment details.

```javascript
import { ProductCode, VnpLocale, dateFormat } from 'vnpay';  
  
/* ... */  
  
const paymentUrl = vnpay.buildPaymentUrl({  
    vnp_Amount: 10000,  
    vnp_IpAddr: '13.160.92.202',  
    vnp_TxnRef: '12345',  
    vnp_OrderInfo: 'Payment for order 12345',  
    vnp_OrderType: ProductCode.Other,  
    vnp_ReturnUrl: 'http://localhost:3000/vnpay-return',  
    vnp_Locale: VnpLocale.VN, // 'vn' or 'en'  
});  
```

--------------------------------

### Handle Return URL Verification in Express MVC

Source: https://vnpay.js.org/en/verify-return-url

This Express.js route handler demonstrates how to verify the return URL using the VNPay SDK within an MVC pattern. It includes error handling for invalid data and checks the verification status (`isVerified`, `isSuccess`) to provide appropriate responses. Business logic should be handled server-side via IPN.

```typescript
// Route to handle return URL  
// Instead of sending text, you can render a template or redirect the customer to the necessary page  
app.get('/vnpay-return', (req, res) => {  
    let verify: VerifyReturnUrl;  
    try {  
        // Use try-catch to catch errors if the query is invalid or lacks data  
        verify = vnpay.verifyReturnUrl(req.query);  
        if (!verify.isVerified) {  
            return res.send('Data integrity verification failed');  
        }  
        if (!verify.isSuccess) {  
            return res.send('Payment order failed');  
        }  
    } catch (error) {  
        return res.send('Invalid data');  
    }  
  
    // Check order information and handle accordingly  
    // Only handle UI-related here, do not handle business logic  
    // Important business logic must be handled on the server side via IPN  
  
    return res.send('Return URL verification successful');  
});  
```

--------------------------------

### Incorrect Frontend Usage of VNPay Library

Source: https://vnpay.js.org/en/installation

Illustrates the incorrect way to import and use the VNPay library directly in a frontend application. This approach will lead to build errors due to the reliance on Node.js specific modules.

```javascript
// 🚫 WILL CAUSE BUILD ERRORS!
import { VNPay } from 'vnpay';
// Error: Module not found: Can't resolve 'fs'
// Error: Module not found: Can't resolve 'crypto'

const MyComponent = () => {
  const vnpay = new VNPay(config); // ❌ Cannot do this in browser!
  return <div>Payment</div>;
};

```

--------------------------------

### Initiate Refund Transaction using VNPAY SDK

Source: https://vnpay.js.org/en/refund

This snippet demonstrates how to use the VNPAY SDK to send a refund request. It highlights the necessary imports, date formatting for GMT+7, and the structure of the refund request object. Note that the `refund` function might be restricted in sandbox environments.

```typescript
import {
    Refund,
    RefundResponse,
    dateFormat,
    getDateInGMT7,
    VnpTransactionType,
    VnpLocale,
} from 'vnpay';

/* ... */

/**
 * The date must be in GMT+7 timezone
 * And formatted as `yyyyMMddHHmmss`
 * Use the `getDateInGMT7` and `dateFormat` functions to convert
 */
const refundRequestDate = dateFormat(getDateInGMT7(new Date('2024/05/26')));
const orderCreatedAt = dateFormat(getDateInGMT7(new Date('2024/05/21')));

const result: RefundResponse = await vnpay.refund({
    vnp_Amount: 10000,
    vnp_CreateBy: 'giang',
    vnp_CreateDate: refundRequestDate,
    vnp_IpAddr: '127.0.0.1',
    vnp_OrderInfo: 'Test order',
    vnp_RequestId: '123456',
    vnp_TransactionDate: orderCreatedAt,
    vnp_TransactionType: VnpTransactionType.FULL_REFUND,
    vnp_TxnRef: '123456',
    vnp_Locale: VnpLocale.EN,
    // vnp_TransactionNo: 123456, // optional
} as Refund);

```

--------------------------------

### Verify Return URL Endpoint

Source: https://vnpay.js.org/en/verify-return-url

This section details how to verify the return URL after a customer completes a payment. VNPay redirects the customer to the specified `vnp_ReturnUrl`, and this process ensures the data's integrity.

```APIDOC
## POST /vnpay-return

### Description
Verifies the return URL parameters received from VNPay after a customer completes a payment. This endpoint should be configured as your `vnp_ReturnUrl` in VNPay's payment setup.

### Method
GET

### Endpoint
`/vnpay-return`

### Query Parameters
- **vnp_Amount** (string) - Required - The total amount of the transaction.
- **vnp_BankCode** (string) - Required - The bank code used for the transaction.
- **vnp_CardType** (string) - Required - The type of card used (e.g., "ATM", "QRCODE").
- **vnp_OrderInfo** (string) - Required - Description of the order.
- **vnp_OrderType** (string) - Required - The type of order (e.g., "topup").
- **vnp_ResponseCode** (string) - Required - The response code from VNPay.
- **vnp_TmnCode** (string) - Required - The terminal code assigned to your merchant account.
- **vnp_TransactionNo** (string) - Required - The transaction number assigned by VNPay.
- **vnp_TransactionStatus** (string) - Required - The status of the transaction (e.g., "00" for success).
- **vnp_TxnRef** (string) - Required - Your unique order reference ID.
- **vnp_SecureHash** (string) - Required - A hash value used to verify the integrity of the request parameters.

### Request Example
```javascript
// Assumed to be handled by the framework, e.g., Express.js
app.get('/vnpay-return', (req, res) => {
    let verify;
    try {
        // req.query contains the parameters passed by VNPay
        verify = vnpay.verifyReturnUrl(req.query);
        if (!verify.isVerified) {
            return res.status(400).send('Data integrity verification failed');
        }
        if (!verify.isSuccess) {
            return res.status(400).send('Payment order failed');
        }
    } catch (error) {
        return res.status(400).send('Invalid data');
    }

    // Handle successful verification
    // IMPORTANT: Business logic should primarily be handled server-side via IPN.
    // This is for UI feedback or redirection.
    res.status(200).send('Return URL verification successful');
});
```

### Response
#### Success Response (200)
- **isVerified** (boolean) - Indicates if the data integrity check passed.
- **isSuccess** (boolean) - Indicates if the payment was successful.

#### Response Example
```json
{
  "isVerified": true,
  "isSuccess": true
}
```

#### Error Responses
- **400 Bad Request**: Returned if data integrity verification fails, the payment order failed, or the data is invalid.
```

--------------------------------

### Verify IPN Call with VNPay JS

Source: https://vnpay.js.org/en/ipn/verify-ipn-call

This snippet demonstrates how to initiate the verification of an IPN call using the `vnpay.verifyIpnCall` method from the VNPay JS library. It takes the request query parameters as input and returns a `VerifyIpnCall` object containing verification results.

```typescript
import { VerifyIpnCall } from 'vnpay';

/* ... */

const verify: VerifyIpnCall = vnpay.verifyIpnCall(req.query);
```

--------------------------------

### Build VNPay Payment URL with Custom Database Logging

Source: https://vnpay.js.org/en/create-payment-url

This JavaScript snippet demonstrates building a VNPay payment URL with a custom logger function. The `loggerFn` is configured to log specific data fields to a database, requiring a user-defined `logToDatabase` implementation.

```javascript
import { ProductCode, VnpLocale } from 'vnpay';  
  
/* ... */  
  
const paymentUrl = vnpay.buildPaymentUrl(  
    {  
        vnp_Amount: 10000,  
        vnp_IpAddr: '1.1.1.1',  
        vnp_TxnRef: '123456',  
        vnp_OrderInfo: 'Payment for order 123456',  
        vnp_OrderType: ProductCode.Other,  
        vnp_ReturnUrl: `http://localhost:${port}/vnpay-return`,  
    },  
    {  
        logger: {  
            type: 'pick', // The mode to select log fields, can be 'pick', 'omit' or 'all'  
            fields: ['createdAt', 'method', 'paymentUrl'], // Select the fields to log  
            loggerFn: (data) => logToDatabase(data), // Function to log data to database, you need to implement it  
        },  
    },  
);  
```

--------------------------------

### Create Payment URL with API in Express.js

Source: https://vnpay.js.org/en/create-payment-url

This snippet illustrates how to create a payment URL for an Express.js API. It includes handling order creation and generating the payment URL via the VNPay SDK. The payment URL and order details are then returned as JSON to the frontend for redirection. It allows for a dynamic `returnUrl` from the frontend.

```typescript
app.post('/api/order', async (req, res) => {
    // Create order
    const order = await createOrder(req.body); // Order creation function, you need to implement it yourself
  
    // Get returnUrl from frontend, if not use default
    const returnUrl = req.body?.returnUrl || 'http://localhost:3000/vnpay-return';
  
    // Create payment URL
    const paymentUrl = vnpay.buildPaymentUrl({
        vnp_Amount: 10000,
        vnp_IpAddr:  
            req.headers['x-forwarded-for'] ||  
            req.connection.remoteAddress ||  
            req.socket.remoteAddress ||  
            req.ip,
        vnp_TxnRef: order.orderId,
        vnp_OrderInfo: `Payment for order ${order.orderId}`,
        vnp_OrderType: ProductCode.Other,
        vnp_ReturnUrl: returnUrl, // The path should be of the frontend
        vnp_Locale: VnpLocale.VN,
    });
  
    return res.json({ paymentUrl, order });
});

```

--------------------------------

### Handle IPN Call Verification in Express

Source: https://vnpay.js.org/en/ipn/verify-ipn-call

This Express.js route handler demonstrates a complete workflow for verifying an IPN call from VNPay. It checks for verification success, order details, amount, and existing confirmation status before updating the order in the database and responding to VNPay. It includes error handling for various scenarios.

```typescript
import {
    IpnFailChecksum,
    IpnOrderNotFound,
    IpnInvalidAmount,
    InpOrderAlreadyConfirmed,
    IpnUnknownError,
    IpnSuccess,
} from 'vnpay';

/* ... */

app.get('/vnpay-ipn', async (req, res) => {
    try {
        const verify: VerifyReturnUrl = vnpay.verifyIpnCall(req.query);
        if (!verify.isVerified) {
            return res.json(IpnFailChecksum);
        }

        if (!verify.isSuccess) {
            return res.json(IpnUnknownError);
        }

        // Find the order in your database
        const foundOrder = await findOrderById(verify.vnp_TxnRef); // Method to find an order by id, you need to implement it

        // If the order is not found or the order code does not match
        if (!foundOrder || verify.vnp_TxnRef !== foundOrder.orderId) {
            return res.json(IpnOrderNotFound);
        }

        // If the payment amount does not match
        if (verify.vnp_Amount !== foundOrder.amount) {
            return res.json(IpnInvalidAmount);
        }

        // If the order has been confirmed before
        if (foundOrder.status === 'completed') {
            return res.json(InpOrderAlreadyConfirmed);
        }

        /**
         * After verifying the order is complete,
         * you can update the order status in your database
         */
        foundOrder.status = 'completed';
        await updateOrder(foundOrder); // Function to update the order status, you need to implement it

        // Then update the status back to VNPay to let them know that you have confirmed the order
        return res.json(IpnSuccess);
    } catch (error) {
        /**
         * Handle exceptions
         * For example, insufficient data, invalid data, database update failure
         */
        console.log(`verify error: ${error}`);
        return res.json(IpnUnknownError);
    }
});
```

--------------------------------

### Query Transaction Result with Logger using VNPAY JS

Source: https://vnpay.js.org/en/query-dr

Shows how to query a transaction result with an integrated logger using the VNPAY JS library. The logger can be configured to capture different types of log data, which can then be processed as needed.

```javascript
import { QueryDr, QueryDrResponse, getDateInGMT7, dateFormat } from 'vnpay';

/* ... */

/**
 * The date must be in GMT+7 timezone
 * And formatted as `yyyyMMddHHmmss`
 * Use the `getDateInGMT7` and `dateFormat` functions to convert
 */
const date = dateFormat(getDateInGMT7(new Date('2024/05/21')));

const res: QueryDrResponse = await vnpay.queryDr(
    {
        vnp_RequestId: generateRandomString(16),
        vnp_IpAddr: '1.1.1.1',
        vnp_TxnRef: '1716257871703',
        vnp_TransactionNo: 14422574,
        vnp_OrderInfo: 'Payment for order',
        vnp_TransactionDate: date,
        vnp_CreateDate: date,
    } as QueryDr,
    {
        logger: {
            type: 'all',
            loggerFn: (data) => {
                console.log(data.message);
                // Or send logs to a server, database, etc.
            },
        },
    },
);

```

--------------------------------

### Query Transaction Result using VNPAY JS

Source: https://vnpay.js.org/en/query-dr

Demonstrates how to query a transaction result using the VNPAY JS library. It requires importing necessary functions and date formatting utilities. The function takes transaction details as input and returns a QueryDrResponse object.

```javascript
import { QueryDr, QueryDrResponse, getDateInGMT7, dateFormat } from 'vnpay';

/* ... */

/**
 * The date must be in GMT+7 timezone
 * And formatted as `yyyyMMddHHmmss`
 * Use the `getDateInGMT7` and `dateFormat` functions to convert
 */
const date = dateFormat(getDateInGMT7(new Date('2024/05/21')));

const res: QueryDrResponse = await vnpay.queryDr({
    vnp_RequestId: generateRandomString(16),
    vnp_IpAddr: '1.1.1.1',
    vnp_TxnRef: '1716257871703',
    vnp_TransactionNo: 14422574,
    vnp_OrderInfo: 'Payment for order',
    vnp_TransactionDate: date,
    vnp_CreateDate: date,
} as QueryDr);

```

--------------------------------

### Create Payment URL with MVC in Express.js

Source: https://vnpay.js.org/en/create-payment-url

This snippet demonstrates how to create a payment URL within an Express.js MVC application. It handles order creation, payment URL generation using the VNPay SDK, and redirects the customer to the payment gateway. Ensure you have implemented the `createOrder` function and configured the VNPay SDK.

```typescript
app.post('/order', async (req, res) => {
    // Create order
    const order = await createOrder(req.body); // Order creation function, you need to implement it yourself
  
    // Create payment URL
    const paymentUrl = vnpay.buildPaymentUrl({
        vnp_Amount: 10000,
        vnp_IpAddr:  
            req.headers['x-forwarded-for'] ||  
            req.connection.remoteAddress ||  
            req.socket.remoteAddress ||  
            req.ip,
        vnp_TxnRef: order.orderId,
        vnp_OrderInfo: `Payment for order ${order.orderId}`,
        vnp_OrderType: ProductCode.Other,
        vnp_ReturnUrl: 'http://localhost:3000/vnpay-return',
        vnp_Locale: VnpLocale.VN,
    });
  
    return res.redirect(paymentUrl);
});

```

--------------------------------

### Verify IPN Call

Source: https://vnpay.js.org/en/ipn/verify-ipn-call

This endpoint handles the Instant Payment Notification (IPN) call from VNPay. It allows you to verify the authenticity and details of the payment notification received.

```APIDOC
## POST /vnpay-ipn

### Description
Handles Instant Payment Notification (IPN) calls from VNPay to verify payment details and update order status.

### Method
GET

### Endpoint
/vnpay-ipn

### Query Parameters
- **vnp_Amount** (number) - Required - The payment amount.
- **vnp_BankCode** (string) - Required - The bank code used for the transaction.
- **vnp_OrderInfo** (string) - Required - Information about the order.
- **vnp_ResponseCode** (string) - Required - The response code from VNPay.
- **vnp_TmnCode** (string) - Required - The terminal code.
- **vnp_TransactionNo** (string) - Required - The transaction number.
- **vnp_TransactionStatus** (string) - Required - The status of the transaction.
- **vnp_TxnRef** (string) - Required - The reference transaction ID.
- **vnp_SecureHash** (string) - Required - The secure hash for verification.

### Request Example
```javascript
// Example of query parameters received from VNPay
{
  "vnp_Amount": "100000",
  "vnp_BankCode": "VNBANK",
  "vnp_OrderInfo": "Order Description",
  "vnp_ResponseCode": "00",
  "vnp_TmnCode": "YOUR_TMN_CODE",
  "vnp_TransactionNo": "123456789",
  "vnp_TransactionStatus": "00",
  "vnp_TxnRef": "ORDER_REF_123",
  "vnp_SecureHash": "a1b2c3d4e5f6..."
}
```

### Response
#### Success Response (200)
- **isVerified** (boolean) - Indicates if the IPN call has been successfully verified.
- **isSuccess** (boolean) - Indicates if the payment transaction was successful.
- **message** (string) - A message indicating the result of the verification or transaction.
- **vnp_Amount** (number) - The payment amount.

#### Response Example
```json
{
  "isVerified": true,
  "isSuccess": true,
  "message": "Payment successful and verified.",
  "vnp_Amount": 100000
}
```

#### Error Handling
- **IpnFailChecksum**: Returned if the secure hash verification fails.
- **IpnOrderNotFound**: Returned if the order referenced in the IPN call cannot be found.
- **IpnInvalidAmount**: Returned if the payment amount in the IPN call does not match the expected amount.
- **InpOrderAlreadyConfirmed**: Returned if the order has already been confirmed.
- **IpnUnknownError**: Returned for any other unexpected errors during verification or processing.

```

--------------------------------

### Create Payment URL API

Source: https://vnpay.js.org/en/create-payment-url

This API endpoint allows you to create a payment URL for VNPay. The generated URL contains all necessary payment information that the e-commerce website sends to the VNPAY Payment Gateway.

```APIDOC
## POST /websites/vnpay_js/createPaymentUrl

### Description
Generates a payment URL for VNPay transactions. This URL includes all required payment details for the VNPAY Payment Gateway.

### Method
POST

### Endpoint
/websites/vnpay_js/createPaymentUrl

### Parameters
#### Request Body
- **vnp_Amount** (number) - Required - Payment amount in VND. The amount has been automatically calculated, no need to multiply by 100.
- **vnp_IpAddr** (string) - Required - IP address of the customer making the transaction. Example: `13.160.92.202`
- **vnp_TxnRef** (string) - Required - Customer's unique order code for the day. Example: `12345`
- **vnp_OrderInfo** (string) - Required - Order information. Data regulations sent to VNPAY (Vietnamese without accents and does not include special characters). Example: `Payment for order 12345`
- **vnp_OrderType** (string) - Required - Order type. Use enum from `ProductCode` or see Product Category table. Example: `Other`
- **vnp_ReturnUrl** (string) - Required - Return URL after payment. Example: `http://localhost:3000/vnpay-return`
- **vnp_Locale** (string) - Optional - Language displayed on the payment gateway. Supports `vn` (Vietnamese) or `en` (English).
- **vnp_BankCode** (string) - Optional - Bank code selected for payment.

### Request Example
```json
{
  "vnp_Amount": 10000,
  "vnp_IpAddr": "1.1.1.1",
  "vnp_TxnRef": "123456",
  "vnp_OrderInfo": "Payment for order 123456",
  "vnp_OrderType": "Other",
  "vnp_ReturnUrl": "http://localhost:3000/vnpay-return",
  "vnp_Locale": "vn"
}
```

### Response
#### Success Response (200)
- **paymentUrl** (string) - The generated VNPay payment URL.

#### Response Example
```json
{
  "paymentUrl": "https://sandbox.vnpayment.vn/paymentv2/vpcpay.html?vnp_Amount=10000&vnp_Command=pay&vnp_CreateDate=20240814214148&vnp_CurrCode=VND&vnp_ExpireDate=20240815214148&vnp_IpAddr=1.1.1.1&vnp_Locale=vn&vnp_OrderInfo=order+information+of+123456-1723671708762&vnp_OrderType=other&vnp_ReturnUrl=http%3A%2F%2Flocalhost%3A3000%2Freturn&vnp_TmnCode=TEST12345&vnp_TxnRef=123456-1723671708762&vnp_Version=2.1.0&vnp_SecureHash=..."
}
```
```

--------------------------------

### POST /vnpay/refund

Source: https://vnpay.js.org/en/refund

Initiates a refund request for a specific transaction through the VNPAY Payment Gateway. This API is used by the merchant system to process refunds.

```APIDOC
## POST /vnpay/refund

### Description
This endpoint allows merchants to send a refund request for a transaction through the VNPAY Payment Gateway. It is designed for use within the merchant's system.

### Method
POST

### Endpoint
/vnpay/refund

### Parameters
#### Request Body
- **vnp_Amount** (number) - Required - The amount to be refunded to the customer. This amount must be less than or equal to the original transaction amount.
- **vnp_CreateBy** (string) - Required - The identifier of the user or system initiating the refund (e.g., merchant username).
- **vnp_CreateDate** (string) - Required - The timestamp when the refund request is made, formatted as `yyyyMMddHHmmss` in GMT+7 timezone.
- **vnp_IpAddr** (string) - Required - The IP address of the server making the API call.
- **vnp_OrderInfo** (string) - Required - A description of the refund request.
- **vnp_RequestId** (string) - Required - A unique identifier for each refund request generated by the merchant's system. This must not be duplicated within the same day.
- **vnp_TransactionDate** (string) - Required - The timestamp of the original transaction, formatted as `yyyyMMddHHmmss` in GMT+7 timezone.
- **vnp_TransactionType** (string) - Required - Specifies the type of refund, e.g., `FULL_REFUND`.
- **vnp_TxnRef** (string) - Required - The merchant's unique payment transaction reference code previously sent to VNPAY.
- **vnp_Locale** (string) - Optional - The language for the response. Supported values include 'vn' (Vietnamese) and 'en' (English).
- **vnp_TransactionNo** (number) - Optional - The transaction code assigned by the VNPAY system.

### Request Example
```json
{
  "vnp_Amount": 10000,
  "vnp_CreateBy": "merchant_user",
  "vnp_CreateDate": "20240526103000",
  "vnp_IpAddr": "192.168.1.100",
  "vnp_OrderInfo": "Refund for order #12345",
  "vnp_RequestId": "REFUND123456789",
  "vnp_TransactionDate": "20240521090000",
  "vnp_TransactionType": "FULL_REFUND",
  "vnp_TxnRef": "ORDER98765",
  "vnp_Locale": "en"
}
```

### Response
#### Success Response (200)
- **isSuccess** (boolean) - Indicates if the refund request was successful.
- **isVerified** (boolean) - Indicates if the refund data has been successfully verified by VNPay.
- **message** (string) - A message detailing the result of the verification process.
- Other parameters returned by VNPay (refer to official documentation).

#### Response Example
```json
{
  "isSuccess": true,
  "isVerified": true,
  "message": "Refund processed successfully."
}
```

### Notes
- The `refund` function might be restricted in the sandbox environment. Contact VNPAY for assistance.
- Dates for `vnp_CreateDate` and `vnp_TransactionDate` must be in GMT+7 timezone and formatted as `yyyyMMddHHmmss`.
```
Tokens:
Raw