lehuygiang28 · lehuygiang28 · May 26, 2024 · May 26, 2024 · May 26, 2024 · May 26, 2024
diff --git a/docs/docs/intro.md → docs/docs/01_intro.md b/docs/docs/intro.md → docs/docs/01_intro.md
diff --git a/docs/docs/installation.md → docs/docs/02_installation.md b/docs/docs/installation.md → docs/docs/02_installation.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Hướng dẫn cài đặt
 
 ## Cài đặt với các trình quản lý thư viện

diff --git a/docs/docs/03_get-bank-list.md b/docs/docs/03_get-bank-list.md
@@ -0,0 +1,29 @@
+# Danh sách ngân hàng {#get-bank-list}
+
+:::info
+Danh sách ngân hàng, sử dụng cho `vnp_BankCode`
+:::
+
+## Lấy danh sách ngân hàng
+
+```typescript
+import { Bank } from 'vnpay';
+
+/* ... */
+
+const bankList: Bank[] = await vnpay.getBankList();
+```
+
+## Các thuộc tính của đối tượng `Bank`
+
+| Thuộc tính      | Kiểu dữ liệu | Mô tả                        |
+| --------------- | ------------ | ---------------------------- |
+| `bank_code`     | `string`     | Mã ngân hàng                 |
+| `bank_name`     | `string`     | Tên ngân hàng                |
+| `logo_link`     | `string`     | Đường dẫn logo của ngân hàng |
+| `bank_type`     | `number`     | Loại ngân hàng               |
+| `display_order` | `number`     | Thứ tự hiển thị              |
+
+:::info
+Xem thêm [tại đây](https://sandbox.vnpayment.vn/apis/docs/chuyen-doi-thuat-toan/changeTypeHash.html#tao-url-thanh-toan)
+:::
diff --git a/docs/docs/create-payment-url.md → docs/docs/04_create-payment-url.md b/docs/docs/create-payment-url.md → docs/docs/04_create-payment-url.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Tạo URL thanh toán
 
 Tạo đường dẫn thanh toán cho VNPay.
@@ -41,6 +37,7 @@ buildPaymentUrl(params: BuildPaymentUrl, options?: BuildPaymentUrlOptions): stri
 | vnp_OrderType | Loại đơn hàng                                  | Mỗi hàng hóa sẽ thuộc một nhóm danh mục do VNPAY quy định. Sử dụng enum có sẵn từ `ProductCode` hoặc xem thêm bảng [Danh mục hàng hóa](https://sandbox.vnpayment.vn/apis/docs/loai-hang-hoa/) |
 | vnp_ReturnUrl | Đường dẫn trả về sau khi thanh toán            | URL thông báo kết quả giao dịch khi Khách hàng kết thúc thanh toán. Ví dụ: https://domain.vn/VnPayReturn                                                                                      |
 | vnp_Locale    | Ngôn ngữ hiển thị trên cổng thanh toán         | Hiện tại hỗ trợ Tiếng Việt (vn), Tiếng Anh (en)                                                                                                                                               |
+| vnp_BankCode  | Mã ngân hàng                                   | Mã ngân hàng lựa chọn thanh toán, xem thêm [tại đây](get-bank-list)                                                                                                                           |
 
 Xem thêm các thuộc tính khác tại [VNPay](https://sandbox.vnpayment.vn/apis/docs/thanh-toan-pay/pay.html#danh-s%C3%A1ch-tham-s%E1%BB%91).
 

diff --git a/docs/docs/config-ipn.md → docs/docs/05_ipn/01_config-ipn.md b/docs/docs/config-ipn.md → docs/docs/05_ipn/01_config-ipn.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 # Cài đặt IPN url
 
 Khi thanh toán hoàn tất, VNPay sẽ gửi lời gọi IPN (Instant Payment Notification) đến URL IPN mà bạn đã cài đặt. Để xác thực lời gọi IPN, bạn có thể sử dụng thư viện VNPay.

diff --git a/docs/docs/verify-ipn-call.md → docs/docs/05_ipn/02_verify-ipn-call.md b/docs/docs/verify-ipn-call.md → docs/docs/05_ipn/02_verify-ipn-call.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 5
----
-
 # Xác thực lời gọi IPN
 
 Khi thanh toán hoàn tất, VNPay sẽ gửi lời gọi IPN (Instant Payment Notification) đến URL IPN mà bạn đã cài đặt. Để xác thực lời gọi IPN, bạn có thể sử dụng thư viện VNPay.
@@ -38,7 +34,7 @@ Các tham số mà VNPay trả về cũng nằm trong đối tượng `VerifyIpn
 ### Sử dụng logger
 
 -   Tương tự như khi tạo URL thanh toán, bạn có thể sử dụng logger để ghi log thông tin xác thực IPN
-    [xem tại đây](./create-payment-url.md#use-logger).
+    [xem tại đây](create-payment-url.md#use-logger).
 
 ### Với Express
 

diff --git a/docs/docs/05_ipn/_category_.json b/docs/docs/05_ipn/_category_.json
@@ -0,0 +1,5 @@
+{
+    "label": "IPN",
+    "collapsible": true,
+    "collapsed": false
+}
diff --git a/docs/docs/verify-return-url.md → docs/docs/06_verify-return-url.md b/docs/docs/verify-return-url.md → docs/docs/06_verify-return-url.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # Xác thực URL thông báo trả về
 
 Khi khách hàng thanh toán thành công, VNPay sẽ chuyển hướng khách hàng đến URL thông báo trả về (`vnp_ReturnUrl`) mà bạn đã cung cấp.

diff --git a/docs/docs/query-dr.md → docs/docs/07_query-dr.md b/docs/docs/query-dr.md → docs/docs/07_query-dr.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 7
----
-
 # Truy vấn kết quả giao dịch (queryDr) {#query-dr}
 
 Đây là API để hệ thống merchant truy vấn kết quả thanh toán của giao dịch tại hệ thống VNPAY.

diff --git a/docs/docs/08_refund.md b/docs/docs/08_refund.md
@@ -0,0 +1,71 @@
+# Giao dịch hoàn tiền (refund) {#refund}
+
+Đây là API để hệ thống merchant gửi yêu cầu hoàn tiền cho giao dịch qua hệ thống Cổng thanh toán VNPAY.
+
+:::warning Chú ý:
+
+-   `refund` là một trong các chức năng bị hạn chế bởi VNPAY trong môi trường sandbox, bạn cần liên hệ VNPAY để được hỗ trợ.
+-   Xem thêm tại [issue#12](https://github.com/lehuygiang28/vnpay/issues/12)
+
+:::
+
+## Refund
+
+```typescript
+import { Refund, RefundResponse, dateFormat, getDateInGMT7, VnpTransactionType } from 'vnpay';
+
+/* ... */
+
+/**
+ * Date phải là timezone GMT+7
+ * Và format theo định dạng `yyyyMMddHHmmss`
+ * Dùng 2 hàm `getDateInGMT7` và `dateFormat` để chuyển đổi
+ */
+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);
+```
+
+## Các thuộc tính
+
+### `Refund` {#Refund-properties}
+
+| Thuộc tính            | Kiểu dữ liệu         | Mô tả                                                                                                                                                                      |
+| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vnp_Amount`          | `number`             | Số tiền hoàn trả lại cho khách hàng. Số tiền này nhỏ hơn hoặc bằng số tiền của giao dịch                                                                                   |
+| `vnp_CreateBy`        | `string`             | Người khởi tạo hoàn tiền. Có thể là tên user thực hiện hoàn tiền của merchant.                                                                                             |
+| `vnp_CreateDate`      | `number`             | Thời gian phát sinh request hoàn (Request Date) GMT+7                                                                                                                      |
+| `vnp_IpAddr`          | `string`             | Địa chỉ IP của máy chủ thực hiện gọi API                                                                                                                                   |
+| `vnp_OrderInfo`       | `string`             | Mô tả thông tin yêu cầu hoàn( Request description)                                                                                                                         |
+| `vnp_RequestId`       | `string`             | Mã hệ thống merchant tự sinh ứng với mỗi yêu cầu hoàn trả giao dịch. Mã này là duy nhất dùng để phân biệt các yêu cầu hoàn trả giao dịch. Không được trùng lặp trong ngày. |
+| `vnp_TransactionDate` | `number`             | Thời gian ghi nhận giao dịch tại website của merchant tính theo GMT+7                                                                                                      |
+| `vnp_TransactionNo`   | `number`             | Mã giao dịch ghi nhận tại hệ thống VNPAY                                                                                                                                   |
+| `vnp_TransactionType` | `VnpTransactionType` | Loại giao dịch tại hệ thống VNPAY                                                                                                                                          |
+| `vnp_TxnRef`          | `string`             | Là mã giao dịch thanh toán của hệ thống merchant gửi VNPAY yêu cầu thanh toán.                                                                                             |
+
+### `RefundResponse` {#refund-response-properties}
+
+| Thuộc tính | Kiểu dữ liệu | Mô tả                                                                                                                                                                          |
+| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| isSuccess  | boolean      | Kết quả của yêu cầu                                                                                                                                                            |
+| isVerified | boolean      | Kết quả xác thực tính toàn vẹn của dữ liệu khi nhận về từ VNPay                                                                                                                |
+| message    | string       | Thông báo xác thực                                                                                                                                                             |
+| ...        | ...          | Các tham số khác của VNPay sẽ trả về, tham khảo tại [đây](https://sandbox.vnpayment.vn/apis/docs/truy-van-hoan-tien/querydr&refund.html#danh-s%C3%A1ch-tham-s%E1%BB%91-refund) |
+
+Xem thêm các thuộc tính VNPay sẽ trả về tại [VNPay](https://sandbox.vnpayment.vn/apis/docs/truy-van-hoan-tien/querydr&refund.html#danh-s%C3%A1ch-tham-s%E1%BB%91-refund).
+:::tip
+Các tham số mà [VNPay trả về](https://sandbox.vnpayment.vn/apis/docs/truy-van-hoan-tien/querydr&refund.html#danh-s%C3%A1ch-tham-s%E1%BB%91-refund) cũng nằm trong đối tượng `RefundResponse`.
+:::
diff --git a/docs/docs/examples.md → docs/docs/20_examples.md b/docs/docs/examples.md → docs/docs/20_examples.md
@@ -1,7 +1,3 @@
----
-sidebar_position: 8
----
-
 # Các ví dụ
 
 ## Dự án mẫu với Express MVC

diff --git a/docs/docs/support.md → docs/docs/21_support.md b/docs/docs/support.md → docs/docs/21_support.md
diff --git a/src/types/index.ts b/src/types/index.ts
@@ -2,8 +2,9 @@ export * from './common.type';
 export * from './vnpay-config.type';
 export * from './build-payment-url.type';
 export * from './return-from-vnpay.type';
-export { QueryDr, QueryDrResponse } from './query-dr.type';
-export { Refund } from './refund.type';
+export { QueryDr, QueryDrResponse, QueryDrResponseFromVNPay } from './query-dr.type';
+export { Refund, RefundResponse, RefundResponseFromVNPay } from './refund.type';
 export * from './logger.type';
 export * from './verify-return-url.type';
 export * from './verify-ipn-call.type';
+export * from './bank.type';
diff --git a/src/types/refund.type.ts b/src/types/refund.type.ts
@@ -1,12 +1,13 @@
 import { RefundTransactionType } from '../enums';
 import { BuildPaymentUrl } from './build-payment-url.type';
+import { ResultVerified } from './common.type';
+import { LoggerData, LoggerOptions } from './logger.type';
 import { QueryDr, QueryDrResponseFromVNPay } from './query-dr.type';
 
-export type Refund = Pick<
-    QueryDr,
-    'vnp_RequestId' | 'vnp_TransactionNo' | 'vnp_TransactionDate' | 'vnp_IpAddr'
-> &
-    Pick<BuildPaymentUrl, 'vnp_Amount' | 'vnp_OrderInfo' | 'vnp_TxnRef'> & {
+export type Refund = Partial<Pick<QueryDr, 'vnp_TransactionNo'>> &
+    Pick<QueryDr, 'vnp_RequestId' | 'vnp_TransactionDate' | 'vnp_IpAddr'> &
+    Pick<BuildPaymentUrl, 'vnp_Amount' | 'vnp_OrderInfo' | 'vnp_TxnRef'> &
+    Partial<Pick<BuildPaymentUrl, 'vnp_Locale'>> & {
         /**
          * Loại giao dịch tại hệ thống VNPAY:
          * - `02`: Giao dịch hoàn trả toàn phần
@@ -35,7 +36,7 @@ export type Refund = Pick<
         vnp_CreateDate: number;
     };
 
-export type RefundResponse = Pick<
+export type RefundResponseFromVNPay = Pick<
     QueryDrResponseFromVNPay,
     | 'vnp_TxnRef'
     | 'vnp_Amount'
@@ -78,3 +79,16 @@ export type RefundResponse = Pick<
      */
     vnp_OrderInfo: string;
 };
+
+export type RefundResponse = ResultVerified & RefundResponseFromVNPay;
+
+export type RefundResponseLogger = LoggerData<
+    {
+        createdAt: Date;
+    } & RefundResponse
+>;
+
+export type RefundOptions<Fields extends keyof RefundResponseLogger> = LoggerOptions<
+    RefundResponseLogger,
+    Fields
+>;
diff --git a/src/utils/common.ts b/src/utils/common.ts
@@ -65,9 +65,17 @@ export function isValidVnpayDateFormat(date: number): boolean {
     return regex.test(dateString);
 }
 
-export function generateRandomString(length: number) {
+export function generateRandomString(
+    length: number,
+    options?: {
+        onlyNumber?: boolean;
+    },
+) {
     let result = '';
-    const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    if (options?.onlyNumber) {
+        characters = '0123456789';
+    }
     const charactersLength = characters.length;
     for (let i = 0; i < length; i++) {
         result += `${characters[(Math.random() * charactersLength) | 0]}`;