bankopenapi 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +217 -2
- package/dist/cjs/core.d.ts +52 -0
- package/dist/cjs/core.js +131 -0
- package/dist/cjs/errors.d.ts +56 -0
- package/dist/cjs/errors.js +91 -0
- package/dist/cjs/index.d.ts +60 -0
- package/dist/cjs/index.js +95 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/pagination.d.ts +13 -0
- package/dist/cjs/pagination.js +18 -0
- package/dist/cjs/resources.d.ts +219 -0
- package/dist/cjs/resources.js +192 -0
- package/dist/cjs/types.d.ts +198 -0
- package/dist/cjs/types.js +4 -0
- package/dist/cjs/webhooks.d.ts +42 -0
- package/dist/cjs/webhooks.js +98 -0
- package/dist/esm/core.d.ts +52 -0
- package/dist/esm/core.js +127 -0
- package/dist/esm/errors.d.ts +56 -0
- package/dist/esm/errors.js +76 -0
- package/dist/esm/index.d.ts +60 -0
- package/dist/esm/index.js +73 -0
- package/dist/esm/pagination.d.ts +13 -0
- package/dist/esm/pagination.js +15 -0
- package/dist/esm/resources.d.ts +219 -0
- package/dist/esm/resources.js +182 -0
- package/dist/esm/types.d.ts +198 -0
- package/dist/esm/types.js +3 -0
- package/dist/esm/webhooks.d.ts +42 -0
- package/dist/esm/webhooks.js +94 -0
- package/package.json +58 -4
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { type ClientOptions } from './core.js';
|
|
2
|
+
import { AccountResource, BankAccounts, Events, PaymentRequests, Sandbox, Transactions, WebhookEndpoints } from './resources.js';
|
|
3
|
+
import type { WebhookEvent } from './types.js';
|
|
4
|
+
import { type VerifyOptions, type WebhookHeaders } from './webhooks.js';
|
|
5
|
+
/**
|
|
6
|
+
* Thư viện chính thức của BankOpenAPI: nhận tiền chuyển khoản vào tài khoản ngân hàng Việt Nam, hiện VietQR, nhận
|
|
7
|
+
* webhook khi tiền về. Tài liệu: https://bankopenapi.com/tai-lieu
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* import BankOpenAPI from 'bankopenapi';
|
|
11
|
+
*
|
|
12
|
+
* const boa = new BankOpenAPI(); // đọc BANKOPENAPI_API_KEY
|
|
13
|
+
* const pr = await boa.paymentRequests.create({ amount: 150000, orderId: 'DH1028' }, { idempotencyKey: 'order-DH1028' });
|
|
14
|
+
* // Hiện pr.qr.payload thành mã QR, hoặc chuyển người mua tới pr.hostedUrl
|
|
15
|
+
*/
|
|
16
|
+
export declare class BankOpenAPI {
|
|
17
|
+
readonly account: AccountResource;
|
|
18
|
+
readonly paymentRequests: PaymentRequests;
|
|
19
|
+
readonly transactions: Transactions;
|
|
20
|
+
readonly bankAccounts: BankAccounts;
|
|
21
|
+
readonly webhookEndpoints: WebhookEndpoints;
|
|
22
|
+
readonly events: Events;
|
|
23
|
+
/** Giả lập tiền về, thanh toán, tài khoản ngân hàng thử: chỉ với API key `boa_test_…` */
|
|
24
|
+
readonly sandbox: Sandbox;
|
|
25
|
+
readonly webhooks: Webhooks;
|
|
26
|
+
private readonly client;
|
|
27
|
+
/**
|
|
28
|
+
* @param options API key (mặc định biến môi trường `BANKOPENAPI_API_KEY`), signing secret webhook, timeout, số lần thử lại.
|
|
29
|
+
* Truyền chuỗi thì coi là API key.
|
|
30
|
+
*/
|
|
31
|
+
constructor(options?: ClientOptions | string);
|
|
32
|
+
/** true với khóa `boa_live_` (tiền thật), false với khóa Sandbox `boa_test_` */
|
|
33
|
+
get livemode(): boolean;
|
|
34
|
+
}
|
|
35
|
+
export declare class Webhooks {
|
|
36
|
+
private readonly secret;
|
|
37
|
+
constructor(secret: string | undefined);
|
|
38
|
+
private secretOrThrow;
|
|
39
|
+
/**
|
|
40
|
+
* Kiểm chữ ký webhook rồi trả sự kiện. Truyền **body thô** (`await req.text()`, `express.raw()`), không parse trước.
|
|
41
|
+
* Sai chữ ký thì ném `WebhookVerificationError`: trả HTTP 400.
|
|
42
|
+
*/
|
|
43
|
+
verify(payload: string | ArrayBuffer | Uint8Array, headers: WebhookHeaders, secret?: string, options?: VerifyOptions): Promise<WebhookEvent>;
|
|
44
|
+
/** Ký payload như BankOpenAPI gửi, để viết test cho endpoint nhận webhook */
|
|
45
|
+
sign(payload: string, secret?: string, options?: {
|
|
46
|
+
id?: string;
|
|
47
|
+
timestamp?: Date;
|
|
48
|
+
}): Promise<{
|
|
49
|
+
'webhook-id': string;
|
|
50
|
+
'webhook-timestamp': string;
|
|
51
|
+
'webhook-signature': string;
|
|
52
|
+
}>;
|
|
53
|
+
}
|
|
54
|
+
export default BankOpenAPI;
|
|
55
|
+
export { VERSION, type ClientOptions, type RequestOptions } from './core.js';
|
|
56
|
+
export * from './errors.js';
|
|
57
|
+
export type { PagePromise } from './pagination.js';
|
|
58
|
+
export type * from './resources.js';
|
|
59
|
+
export type * from './types.js';
|
|
60
|
+
export { signWebhook, verifyWebhook, type VerifyOptions, type WebhookHeaders } from './webhooks.js';
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { APIClient } from "./core.js";
|
|
2
|
+
import { WebhookVerificationError } from "./errors.js";
|
|
3
|
+
import { AccountResource, BankAccounts, Events, PaymentRequests, Sandbox, Transactions, WebhookEndpoints } from "./resources.js";
|
|
4
|
+
import { signWebhook, verifyWebhook } from "./webhooks.js";
|
|
5
|
+
/**
|
|
6
|
+
* Thư viện chính thức của BankOpenAPI: nhận tiền chuyển khoản vào tài khoản ngân hàng Việt Nam, hiện VietQR, nhận
|
|
7
|
+
* webhook khi tiền về. Tài liệu: https://bankopenapi.com/tai-lieu
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* import BankOpenAPI from 'bankopenapi';
|
|
11
|
+
*
|
|
12
|
+
* const boa = new BankOpenAPI(); // đọc BANKOPENAPI_API_KEY
|
|
13
|
+
* const pr = await boa.paymentRequests.create({ amount: 150000, orderId: 'DH1028' }, { idempotencyKey: 'order-DH1028' });
|
|
14
|
+
* // Hiện pr.qr.payload thành mã QR, hoặc chuyển người mua tới pr.hostedUrl
|
|
15
|
+
*/
|
|
16
|
+
export class BankOpenAPI {
|
|
17
|
+
account;
|
|
18
|
+
paymentRequests;
|
|
19
|
+
transactions;
|
|
20
|
+
bankAccounts;
|
|
21
|
+
webhookEndpoints;
|
|
22
|
+
events;
|
|
23
|
+
/** Giả lập tiền về, thanh toán, tài khoản ngân hàng thử: chỉ với API key `boa_test_…` */
|
|
24
|
+
sandbox;
|
|
25
|
+
webhooks;
|
|
26
|
+
client;
|
|
27
|
+
/**
|
|
28
|
+
* @param options API key (mặc định biến môi trường `BANKOPENAPI_API_KEY`), signing secret webhook, timeout, số lần thử lại.
|
|
29
|
+
* Truyền chuỗi thì coi là API key.
|
|
30
|
+
*/
|
|
31
|
+
constructor(options = {}) {
|
|
32
|
+
this.client = new APIClient(typeof options === 'string' ? { apiKey: options } : options);
|
|
33
|
+
this.account = new AccountResource(this.client);
|
|
34
|
+
this.paymentRequests = new PaymentRequests(this.client);
|
|
35
|
+
this.transactions = new Transactions(this.client);
|
|
36
|
+
this.bankAccounts = new BankAccounts(this.client);
|
|
37
|
+
this.webhookEndpoints = new WebhookEndpoints(this.client);
|
|
38
|
+
this.events = new Events(this.client);
|
|
39
|
+
this.sandbox = new Sandbox(this.client);
|
|
40
|
+
this.webhooks = new Webhooks(this.client.webhookSecret);
|
|
41
|
+
}
|
|
42
|
+
/** true với khóa `boa_live_` (tiền thật), false với khóa Sandbox `boa_test_` */
|
|
43
|
+
get livemode() {
|
|
44
|
+
return this.client.livemode;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
export class Webhooks {
|
|
48
|
+
secret;
|
|
49
|
+
constructor(secret) {
|
|
50
|
+
this.secret = secret;
|
|
51
|
+
}
|
|
52
|
+
secretOrThrow(secret) {
|
|
53
|
+
const s = secret ?? this.secret;
|
|
54
|
+
if (!s)
|
|
55
|
+
throw new WebhookVerificationError('Thiếu signing secret: truyền { webhookSecret } khi tạo client hoặc đặt BANKOPENAPI_WEBHOOK_SECRET (lấy ở trang Webhook trong app). / Missing webhook secret.');
|
|
56
|
+
return s;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Kiểm chữ ký webhook rồi trả sự kiện. Truyền **body thô** (`await req.text()`, `express.raw()`), không parse trước.
|
|
60
|
+
* Sai chữ ký thì ném `WebhookVerificationError`: trả HTTP 400.
|
|
61
|
+
*/
|
|
62
|
+
verify(payload, headers, secret, options) {
|
|
63
|
+
return verifyWebhook(payload, headers, this.secretOrThrow(secret), options);
|
|
64
|
+
}
|
|
65
|
+
/** Ký payload như BankOpenAPI gửi, để viết test cho endpoint nhận webhook */
|
|
66
|
+
sign(payload, secret, options) {
|
|
67
|
+
return signWebhook(payload, this.secretOrThrow(secret), options);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
export default BankOpenAPI;
|
|
71
|
+
export { VERSION } from "./core.js";
|
|
72
|
+
export * from "./errors.js";
|
|
73
|
+
export { signWebhook, verifyWebhook } from "./webhooks.js";
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { List } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Kết quả của các hàm `list()` có phân trang: `await` để lấy một trang (`{ data, hasMore }`), hoặc `for await` để duyệt
|
|
4
|
+
* hết mọi phần tử, thư viện tự gọi trang tiếp theo bằng `starting_after`.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* const page = await boa.transactions.list({ limit: 20 });
|
|
8
|
+
* for await (const tx of boa.transactions.list({ type: 'credit', from: '2026-11-01' })) console.log(tx.amount);
|
|
9
|
+
*/
|
|
10
|
+
export type PagePromise<T> = Promise<List<T>> & AsyncIterable<T>;
|
|
11
|
+
export declare function pagePromise<T extends {
|
|
12
|
+
id: string;
|
|
13
|
+
}>(fetchPage: (startingAfter: string | undefined) => Promise<List<T>>, startingAfter?: string): PagePromise<T>;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export function pagePromise(fetchPage, startingAfter) {
|
|
2
|
+
const first = fetchPage(startingAfter);
|
|
3
|
+
const iterate = async function* () {
|
|
4
|
+
let page = await first;
|
|
5
|
+
for (;;) {
|
|
6
|
+
for (const item of page.data)
|
|
7
|
+
yield item;
|
|
8
|
+
const last = page.data.at(-1);
|
|
9
|
+
if (!page.hasMore || !last)
|
|
10
|
+
return;
|
|
11
|
+
page = await fetchPage(last.id);
|
|
12
|
+
}
|
|
13
|
+
};
|
|
14
|
+
return Object.assign(first, { [Symbol.asyncIterator]: iterate });
|
|
15
|
+
}
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
import type { APIClient, RequestOptions } from './core.js';
|
|
2
|
+
import { type PagePromise } from './pagination.js';
|
|
3
|
+
import type { Account, BankAccount, Event, List, PaymentRequest, Transaction, WebhookDelivery, WebhookEndpoint, WebhookEventType } from './types.js';
|
|
4
|
+
/** Lớp gốc của các nhóm API: giữ client dùng chung */
|
|
5
|
+
declare class Resource {
|
|
6
|
+
protected readonly client: APIClient;
|
|
7
|
+
constructor(client: APIClient);
|
|
8
|
+
}
|
|
9
|
+
interface PageParams {
|
|
10
|
+
/** 1–100 */
|
|
11
|
+
limit?: number;
|
|
12
|
+
/** ID của phần tử cuối trang trước */
|
|
13
|
+
startingAfter?: string;
|
|
14
|
+
}
|
|
15
|
+
export declare class AccountResource extends Resource {
|
|
16
|
+
/** Tài khoản sở hữu API key: dùng để thử khóa có hoạt động không */
|
|
17
|
+
retrieve(options?: RequestOptions): Promise<Account>;
|
|
18
|
+
}
|
|
19
|
+
export interface PaymentRequestCreateParams {
|
|
20
|
+
/** Số tiền VND, số nguyên 1.000–500.000.000 */
|
|
21
|
+
amount: number;
|
|
22
|
+
/** Mã đơn hàng bên hệ thống của bạn (chữ, số, `_ . : / # -`, tối đa 64 ký tự) */
|
|
23
|
+
orderId?: string;
|
|
24
|
+
/** Mô tả hiện cho người trả, tối đa 200 ký tự */
|
|
25
|
+
description?: string;
|
|
26
|
+
/** Hạn thanh toán, phút (5–10080). Mặc định 1440 (24 giờ) */
|
|
27
|
+
expiresInMinutes?: number;
|
|
28
|
+
/** Tài khoản nhận tiền `ba_…`. Mặc định: tài khoản liên kết gần nhất */
|
|
29
|
+
bankAccountId?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Link quay lại website của bạn (vd. trang đơn hàng): trang `hostedUrl` có nút "Quay lại" và tự chuyển về sau khi trả
|
|
32
|
+
* xong. Phải là `https://` (sandbox cho thêm `http://`), tối đa 2048 ký tự
|
|
33
|
+
*/
|
|
34
|
+
returnUrl?: string;
|
|
35
|
+
}
|
|
36
|
+
export interface PaymentRequestListParams extends PageParams {
|
|
37
|
+
/** open: chờ thanh toán; paid: đã thanh toán; attention: thiếu hoặc thừa tiền; closed: hết hạn hoặc đã hủy */
|
|
38
|
+
status?: 'open' | 'paid' | 'attention' | 'closed';
|
|
39
|
+
/** Lọc đúng mã đơn hàng */
|
|
40
|
+
orderId?: string;
|
|
41
|
+
}
|
|
42
|
+
export declare class PaymentRequests extends Resource {
|
|
43
|
+
/**
|
|
44
|
+
* Tạo yêu cầu thanh toán cho một đơn: trả về `qr.payload` (vẽ mã QR), `transfer` (thông tin chuyển khoản) và `hostedUrl`
|
|
45
|
+
* (trang thanh toán để gửi cho người trả). Tiền về đúng mã thì trạng thái tự thành `paid` và có webhook
|
|
46
|
+
* `payment_request.paid`.
|
|
47
|
+
*
|
|
48
|
+
* Nên truyền `idempotencyKey` gắn với đơn hàng (vd. `order-${orderId}`): bấm hai lần cũng chỉ tạo một yêu cầu.
|
|
49
|
+
*/
|
|
50
|
+
create(params: PaymentRequestCreateParams, options?: RequestOptions): Promise<PaymentRequest>;
|
|
51
|
+
/** Xem một yêu cầu, kèm danh sách giao dịch đã khớp (`transactions`) */
|
|
52
|
+
retrieve(id: string, options?: RequestOptions): Promise<PaymentRequest>;
|
|
53
|
+
/** Danh sách, mới nhất trước */
|
|
54
|
+
list(params?: PaymentRequestListParams, options?: RequestOptions): PagePromise<PaymentRequest>;
|
|
55
|
+
/** Hủy yêu cầu chưa nhận tiền (đang chờ hoặc đã hết hạn). Tiền chuyển tới sau khi hủy không khớp yêu cầu này nữa */
|
|
56
|
+
cancel(id: string, options?: RequestOptions): Promise<PaymentRequest>;
|
|
57
|
+
}
|
|
58
|
+
export interface TransactionListParams extends PageParams {
|
|
59
|
+
/** Lọc theo tài khoản ngân hàng `ba_…` */
|
|
60
|
+
bankAccountId?: string;
|
|
61
|
+
/** credit: tiền vào, debit: tiền ra */
|
|
62
|
+
type?: 'credit' | 'debit';
|
|
63
|
+
/** Từ thời điểm (Date hoặc chuỗi ISO 8601), tính theo `transactedAt` */
|
|
64
|
+
from?: Date | string;
|
|
65
|
+
/** Đến thời điểm (Date hoặc chuỗi ISO 8601) */
|
|
66
|
+
to?: Date | string;
|
|
67
|
+
}
|
|
68
|
+
export declare class Transactions extends Resource {
|
|
69
|
+
/** Giao dịch trên các tài khoản đã liên kết, mới nhất trước */
|
|
70
|
+
list(params?: TransactionListParams, options?: RequestOptions): PagePromise<Transaction>;
|
|
71
|
+
retrieve(id: string, options?: RequestOptions): Promise<Transaction>;
|
|
72
|
+
}
|
|
73
|
+
export declare class BankAccounts extends Resource {
|
|
74
|
+
/** Tài khoản đang liên kết (không phân trang). Liên kết tài khoản mới làm trong app vì cần OTP của ngân hàng */
|
|
75
|
+
list(options?: RequestOptions): Promise<List<BankAccount>>;
|
|
76
|
+
/** Xem một tài khoản ở mọi trạng thái (cả đã hủy liên kết) */
|
|
77
|
+
retrieve(id: string, options?: RequestOptions): Promise<BankAccount>;
|
|
78
|
+
}
|
|
79
|
+
export interface WebhookHeader {
|
|
80
|
+
name: string;
|
|
81
|
+
value: string;
|
|
82
|
+
}
|
|
83
|
+
export interface WebhookEndpointCreateParams {
|
|
84
|
+
/** URL https công khai nhận webhook */
|
|
85
|
+
url: string;
|
|
86
|
+
/** Loại sự kiện cần nhận, hoặc `['*']` để nhận mọi loại */
|
|
87
|
+
events: (WebhookEventType | '*')[];
|
|
88
|
+
description?: string | null;
|
|
89
|
+
/** Chỉ nhận sự kiện của các tài khoản ngân hàng này. null: mọi tài khoản */
|
|
90
|
+
bankAccountIds?: string[] | null;
|
|
91
|
+
/** Tối đa 5 header gửi kèm mỗi webhook (vd. khóa riêng của hệ thống bạn) */
|
|
92
|
+
headers?: WebhookHeader[] | null;
|
|
93
|
+
/**
|
|
94
|
+
* Vé kiểm tra URL (`testUrl().token`). Bỏ trống thì thư viện tự gọi `testUrl` trước: URL phải trả 2xx, 401 hoặc 403
|
|
95
|
+
* mới tạo được endpoint.
|
|
96
|
+
*/
|
|
97
|
+
urlTestToken?: string;
|
|
98
|
+
}
|
|
99
|
+
export interface WebhookEndpointUpdateParams extends Partial<Omit<WebhookEndpointCreateParams, 'urlTestToken'>> {
|
|
100
|
+
/** Tắt hoặc bật lại endpoint */
|
|
101
|
+
status?: 'enabled' | 'disabled';
|
|
102
|
+
urlTestToken?: string;
|
|
103
|
+
}
|
|
104
|
+
export interface UrlTestResult {
|
|
105
|
+
object: 'url_test';
|
|
106
|
+
url: string;
|
|
107
|
+
/** true khi URL trả 2xx, 401 hoặc 403 */
|
|
108
|
+
reachable: boolean;
|
|
109
|
+
responseStatus: number | null;
|
|
110
|
+
responseBody: string | null;
|
|
111
|
+
durationMs: number;
|
|
112
|
+
message: string | null;
|
|
113
|
+
/** Vé dùng cho `create`/`update` (30 phút), null khi không thông */
|
|
114
|
+
token: string | null;
|
|
115
|
+
}
|
|
116
|
+
export declare class WebhookEndpoints extends Resource {
|
|
117
|
+
list(options?: RequestOptions): Promise<List<WebhookEndpoint>>;
|
|
118
|
+
/** Gửi thử một request tới URL để chắc chắn URL nhận được webhook */
|
|
119
|
+
testUrl(params: {
|
|
120
|
+
url: string;
|
|
121
|
+
headers?: WebhookHeader[];
|
|
122
|
+
endpointId?: string;
|
|
123
|
+
}, options?: RequestOptions): Promise<UrlTestResult>;
|
|
124
|
+
private tokenFor;
|
|
125
|
+
/**
|
|
126
|
+
* Tạo endpoint. Thư viện tự kiểm tra URL trước (trừ khi truyền `urlTestToken`). Lấy signing secret bằng
|
|
127
|
+
* `retrieveSecret(endpoint.id)`.
|
|
128
|
+
*/
|
|
129
|
+
create(params: WebhookEndpointCreateParams, options?: RequestOptions): Promise<WebhookEndpoint>;
|
|
130
|
+
retrieve(id: string, options?: RequestOptions): Promise<WebhookEndpoint>;
|
|
131
|
+
/** Sửa endpoint. Đổi `url` thì thư viện tự kiểm tra URL mới (trừ khi truyền `urlTestToken`) */
|
|
132
|
+
update(id: string, params: WebhookEndpointUpdateParams, options?: RequestOptions): Promise<WebhookEndpoint>;
|
|
133
|
+
delete(id: string, options?: RequestOptions): Promise<{
|
|
134
|
+
id: string;
|
|
135
|
+
object: 'webhook_endpoint';
|
|
136
|
+
deleted: true;
|
|
137
|
+
}>;
|
|
138
|
+
/** Signing secret (`whsec_…`) để verify webhook. Cần API key toàn quyền */
|
|
139
|
+
retrieveSecret(id: string, options?: RequestOptions): Promise<{
|
|
140
|
+
object: 'webhook_endpoint_secret';
|
|
141
|
+
secret: string;
|
|
142
|
+
}>;
|
|
143
|
+
/**
|
|
144
|
+
* Đổi signing secret. Secret cũ vẫn ký song song trong `expiresInHours` giờ (0, 1, 24 hoặc 168; mặc định 24) để bạn kịp
|
|
145
|
+
* cập nhật hệ thống.
|
|
146
|
+
*/
|
|
147
|
+
rotateSecret(id: string, params?: {
|
|
148
|
+
expiresInHours?: 0 | 1 | 24 | 168;
|
|
149
|
+
}, options?: RequestOptions): Promise<{
|
|
150
|
+
object: 'webhook_endpoint_secret';
|
|
151
|
+
secret: string;
|
|
152
|
+
previousSecretExpiresAt: string | null;
|
|
153
|
+
}>;
|
|
154
|
+
/** Gửi ngay một sự kiện `webhook.test` (một lần, không thử lại) và trả kết quả */
|
|
155
|
+
sendTest(id: string, options?: RequestOptions): Promise<WebhookDelivery>;
|
|
156
|
+
/** Lịch sử gửi webhook tới endpoint, mới nhất trước */
|
|
157
|
+
listDeliveries(id: string, params?: PageParams, options?: RequestOptions): PagePromise<WebhookDelivery>;
|
|
158
|
+
retrieveDelivery(id: string, deliveryId: string, options?: RequestOptions): Promise<WebhookDelivery>;
|
|
159
|
+
/** Gửi lại một lần gửi */
|
|
160
|
+
retryDelivery(id: string, deliveryId: string, options?: RequestOptions): Promise<WebhookDelivery>;
|
|
161
|
+
/** Gửi lại mọi sự kiện lỗi hoặc bị lỡ từ `since` (tối đa 30 ngày trước), mỗi sự kiện một lần, tối đa 500 */
|
|
162
|
+
retryFailed(id: string, params: {
|
|
163
|
+
since: Date | string;
|
|
164
|
+
}, options?: RequestOptions): Promise<{
|
|
165
|
+
object: 'webhook_bulk_retry';
|
|
166
|
+
queued: number;
|
|
167
|
+
failed: number;
|
|
168
|
+
missed: number;
|
|
169
|
+
hasMore: boolean;
|
|
170
|
+
}>;
|
|
171
|
+
}
|
|
172
|
+
export interface EventListParams extends PageParams {
|
|
173
|
+
type?: WebhookEventType | 'webhook.test';
|
|
174
|
+
}
|
|
175
|
+
export type EventWithDeliveryCounts = Event & {
|
|
176
|
+
deliveries: {
|
|
177
|
+
succeeded: number;
|
|
178
|
+
pending: number;
|
|
179
|
+
failed: number;
|
|
180
|
+
};
|
|
181
|
+
};
|
|
182
|
+
export type EventWithDeliveries = Event & {
|
|
183
|
+
deliveries: (WebhookDelivery & {
|
|
184
|
+
endpointUrl: string;
|
|
185
|
+
})[];
|
|
186
|
+
};
|
|
187
|
+
export declare class Events extends Resource {
|
|
188
|
+
/** Sự kiện 30 ngày gần nhất (kể cả khi chưa có endpoint nhận), mới nhất trước */
|
|
189
|
+
list(params?: EventListParams, options?: RequestOptions): PagePromise<EventWithDeliveryCounts>;
|
|
190
|
+
retrieve(id: string, options?: RequestOptions): Promise<EventWithDeliveries>;
|
|
191
|
+
/** Gửi lại một sự kiện tới một endpoint */
|
|
192
|
+
resend(id: string, params: {
|
|
193
|
+
endpointId: string;
|
|
194
|
+
}, options?: RequestOptions): Promise<WebhookDelivery & {
|
|
195
|
+
endpointUrl: string;
|
|
196
|
+
}>;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Giả lập cho Sandbox, chỉ dùng với API key `boa_test_…`: chạy đúng luồng thật (khớp đơn, webhook `livemode: false`),
|
|
200
|
+
* không cần ngân hàng, không tính phí. Tối đa 10 lần mỗi phút.
|
|
201
|
+
*/
|
|
202
|
+
export declare class Sandbox extends Resource {
|
|
203
|
+
private assertTest;
|
|
204
|
+
/** Tạo tài khoản ngân hàng thử, liên kết xong ngay (không cần OTP). Tối đa 5 tài khoản thử */
|
|
205
|
+
createBankAccount(params?: {
|
|
206
|
+
accountName?: string;
|
|
207
|
+
}, options?: RequestOptions): Promise<BankAccount>;
|
|
208
|
+
/** Giả lập tiền chuyển vào tài khoản thử. Nội dung có mã `TT…` của một yêu cầu thanh toán thì khớp yêu cầu đó */
|
|
209
|
+
createTransaction(params: {
|
|
210
|
+
amount: number;
|
|
211
|
+
content?: string;
|
|
212
|
+
bankAccountId?: string;
|
|
213
|
+
}, options?: RequestOptions): Promise<Transaction>;
|
|
214
|
+
/** Giả lập người mua thanh toán một yêu cầu. `amount` mặc định là số tiền còn thiếu */
|
|
215
|
+
payPaymentRequest(id: string, params?: {
|
|
216
|
+
amount?: number;
|
|
217
|
+
}, options?: RequestOptions): Promise<PaymentRequest>;
|
|
218
|
+
}
|
|
219
|
+
export {};
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
import { BankOpenAPIError } from "./errors.js";
|
|
2
|
+
import { pagePromise } from "./pagination.js";
|
|
3
|
+
const enc = encodeURIComponent;
|
|
4
|
+
/** Lớp gốc của các nhóm API: giữ client dùng chung */
|
|
5
|
+
class Resource {
|
|
6
|
+
client;
|
|
7
|
+
constructor(client) {
|
|
8
|
+
this.client = client;
|
|
9
|
+
}
|
|
10
|
+
}
|
|
11
|
+
// ---------- Tài khoản ----------
|
|
12
|
+
export class AccountResource extends Resource {
|
|
13
|
+
/** Tài khoản sở hữu API key: dùng để thử khóa có hoạt động không */
|
|
14
|
+
retrieve(options) {
|
|
15
|
+
return this.client.request('GET', '/account', options);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
export class PaymentRequests extends Resource {
|
|
19
|
+
/**
|
|
20
|
+
* Tạo yêu cầu thanh toán cho một đơn: trả về `qr.payload` (vẽ mã QR), `transfer` (thông tin chuyển khoản) và `hostedUrl`
|
|
21
|
+
* (trang thanh toán để gửi cho người trả). Tiền về đúng mã thì trạng thái tự thành `paid` và có webhook
|
|
22
|
+
* `payment_request.paid`.
|
|
23
|
+
*
|
|
24
|
+
* Nên truyền `idempotencyKey` gắn với đơn hàng (vd. `order-${orderId}`): bấm hai lần cũng chỉ tạo một yêu cầu.
|
|
25
|
+
*/
|
|
26
|
+
create(params, options) {
|
|
27
|
+
return this.client.request('POST', '/payment-requests', { ...options, body: params });
|
|
28
|
+
}
|
|
29
|
+
/** Xem một yêu cầu, kèm danh sách giao dịch đã khớp (`transactions`) */
|
|
30
|
+
retrieve(id, options) {
|
|
31
|
+
return this.client.request('GET', `/payment-requests/${enc(id)}`, options);
|
|
32
|
+
}
|
|
33
|
+
/** Danh sách, mới nhất trước */
|
|
34
|
+
list(params = {}, options) {
|
|
35
|
+
return pagePromise((startingAfter) => this.client.request('GET', '/payment-requests', {
|
|
36
|
+
...options,
|
|
37
|
+
query: { limit: params.limit, status: params.status, order_id: params.orderId, starting_after: startingAfter },
|
|
38
|
+
}), params.startingAfter);
|
|
39
|
+
}
|
|
40
|
+
/** Hủy yêu cầu chưa nhận tiền (đang chờ hoặc đã hết hạn). Tiền chuyển tới sau khi hủy không khớp yêu cầu này nữa */
|
|
41
|
+
cancel(id, options) {
|
|
42
|
+
return this.client.request('POST', `/payment-requests/${enc(id)}/cancel`, options);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
export class Transactions extends Resource {
|
|
46
|
+
/** Giao dịch trên các tài khoản đã liên kết, mới nhất trước */
|
|
47
|
+
list(params = {}, options) {
|
|
48
|
+
return pagePromise((startingAfter) => this.client.request('GET', '/transactions', {
|
|
49
|
+
...options,
|
|
50
|
+
query: { limit: params.limit, bank_account: params.bankAccountId, type: params.type, from: params.from, to: params.to, starting_after: startingAfter },
|
|
51
|
+
}), params.startingAfter);
|
|
52
|
+
}
|
|
53
|
+
retrieve(id, options) {
|
|
54
|
+
return this.client.request('GET', `/transactions/${enc(id)}`, options);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
// ---------- Tài khoản ngân hàng ----------
|
|
58
|
+
export class BankAccounts extends Resource {
|
|
59
|
+
/** Tài khoản đang liên kết (không phân trang). Liên kết tài khoản mới làm trong app vì cần OTP của ngân hàng */
|
|
60
|
+
list(options) {
|
|
61
|
+
return this.client.request('GET', '/bank-accounts', options);
|
|
62
|
+
}
|
|
63
|
+
/** Xem một tài khoản ở mọi trạng thái (cả đã hủy liên kết) */
|
|
64
|
+
retrieve(id, options) {
|
|
65
|
+
return this.client.request('GET', `/bank-accounts/${enc(id)}`, options);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
export class WebhookEndpoints extends Resource {
|
|
69
|
+
list(options) {
|
|
70
|
+
return this.client.request('GET', '/webhook-endpoints', options);
|
|
71
|
+
}
|
|
72
|
+
/** Gửi thử một request tới URL để chắc chắn URL nhận được webhook */
|
|
73
|
+
testUrl(params, options) {
|
|
74
|
+
return this.client.request('POST', '/webhook-endpoints/test-url', { ...options, body: params });
|
|
75
|
+
}
|
|
76
|
+
async tokenFor(url, headers, endpointId) {
|
|
77
|
+
const test = await this.testUrl({ url, headers: headers ?? undefined, endpointId });
|
|
78
|
+
if (!test.reachable || !test.token)
|
|
79
|
+
throw new BankOpenAPIError(`URL ${url} chưa nhận được request thử${test.responseStatus ? ` (HTTP ${test.responseStatus})` : ''}${test.message ? `: ${test.message}` : ''}. Endpoint phải trả 2xx, 401 hoặc 403. / Webhook URL is not reachable.`, { code: 'URL_NOT_REACHABLE' });
|
|
80
|
+
return test.token;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Tạo endpoint. Thư viện tự kiểm tra URL trước (trừ khi truyền `urlTestToken`). Lấy signing secret bằng
|
|
84
|
+
* `retrieveSecret(endpoint.id)`.
|
|
85
|
+
*/
|
|
86
|
+
async create(params, options) {
|
|
87
|
+
const urlTestToken = params.urlTestToken ?? (await this.tokenFor(params.url, params.headers));
|
|
88
|
+
return this.client.request('POST', '/webhook-endpoints', { ...options, body: { ...params, urlTestToken } });
|
|
89
|
+
}
|
|
90
|
+
retrieve(id, options) {
|
|
91
|
+
return this.client.request('GET', `/webhook-endpoints/${enc(id)}`, options);
|
|
92
|
+
}
|
|
93
|
+
/** Sửa endpoint. Đổi `url` thì thư viện tự kiểm tra URL mới (trừ khi truyền `urlTestToken`) */
|
|
94
|
+
async update(id, params, options) {
|
|
95
|
+
let body = params;
|
|
96
|
+
if (params.url !== undefined && params.urlTestToken === undefined) {
|
|
97
|
+
const current = await this.retrieve(id, options);
|
|
98
|
+
if (current.url !== params.url)
|
|
99
|
+
body = { ...params, urlTestToken: await this.tokenFor(params.url, params.headers, id) };
|
|
100
|
+
}
|
|
101
|
+
return this.client.request('PATCH', `/webhook-endpoints/${enc(id)}`, { ...options, body });
|
|
102
|
+
}
|
|
103
|
+
delete(id, options) {
|
|
104
|
+
return this.client.request('DELETE', `/webhook-endpoints/${enc(id)}`, options);
|
|
105
|
+
}
|
|
106
|
+
/** Signing secret (`whsec_…`) để verify webhook. Cần API key toàn quyền */
|
|
107
|
+
retrieveSecret(id, options) {
|
|
108
|
+
return this.client.request('GET', `/webhook-endpoints/${enc(id)}/secret`, options);
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Đổi signing secret. Secret cũ vẫn ký song song trong `expiresInHours` giờ (0, 1, 24 hoặc 168; mặc định 24) để bạn kịp
|
|
112
|
+
* cập nhật hệ thống.
|
|
113
|
+
*/
|
|
114
|
+
rotateSecret(id, params = {}, options) {
|
|
115
|
+
return this.client.request('POST', `/webhook-endpoints/${enc(id)}/rotate-secret`, { ...options, body: params });
|
|
116
|
+
}
|
|
117
|
+
/** Gửi ngay một sự kiện `webhook.test` (một lần, không thử lại) và trả kết quả */
|
|
118
|
+
sendTest(id, options) {
|
|
119
|
+
return this.client.request('POST', `/webhook-endpoints/${enc(id)}/test`, options);
|
|
120
|
+
}
|
|
121
|
+
/** Lịch sử gửi webhook tới endpoint, mới nhất trước */
|
|
122
|
+
listDeliveries(id, params = {}, options) {
|
|
123
|
+
return pagePromise((startingAfter) => this.client.request('GET', `/webhook-endpoints/${enc(id)}/deliveries`, {
|
|
124
|
+
...options,
|
|
125
|
+
query: { limit: params.limit, starting_after: startingAfter },
|
|
126
|
+
}), params.startingAfter);
|
|
127
|
+
}
|
|
128
|
+
retrieveDelivery(id, deliveryId, options) {
|
|
129
|
+
return this.client.request('GET', `/webhook-endpoints/${enc(id)}/deliveries/${enc(deliveryId)}`, options);
|
|
130
|
+
}
|
|
131
|
+
/** Gửi lại một lần gửi */
|
|
132
|
+
retryDelivery(id, deliveryId, options) {
|
|
133
|
+
return this.client.request('POST', `/webhook-endpoints/${enc(id)}/deliveries/${enc(deliveryId)}/retry`, options);
|
|
134
|
+
}
|
|
135
|
+
/** Gửi lại mọi sự kiện lỗi hoặc bị lỡ từ `since` (tối đa 30 ngày trước), mỗi sự kiện một lần, tối đa 500 */
|
|
136
|
+
retryFailed(id, params, options) {
|
|
137
|
+
const since = params.since instanceof Date ? params.since.toISOString() : params.since;
|
|
138
|
+
return this.client.request('POST', `/webhook-endpoints/${enc(id)}/deliveries/retry-failed`, { ...options, body: { since } });
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
export class Events extends Resource {
|
|
142
|
+
/** Sự kiện 30 ngày gần nhất (kể cả khi chưa có endpoint nhận), mới nhất trước */
|
|
143
|
+
list(params = {}, options) {
|
|
144
|
+
return pagePromise((startingAfter) => this.client.request('GET', '/events', {
|
|
145
|
+
...options,
|
|
146
|
+
query: { limit: params.limit, type: params.type, starting_after: startingAfter },
|
|
147
|
+
}), params.startingAfter);
|
|
148
|
+
}
|
|
149
|
+
retrieve(id, options) {
|
|
150
|
+
return this.client.request('GET', `/events/${enc(id)}`, options);
|
|
151
|
+
}
|
|
152
|
+
/** Gửi lại một sự kiện tới một endpoint */
|
|
153
|
+
resend(id, params, options) {
|
|
154
|
+
return this.client.request('POST', `/events/${enc(id)}/resend`, { ...options, body: params });
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
// ---------- Sandbox ----------
|
|
158
|
+
/**
|
|
159
|
+
* Giả lập cho Sandbox, chỉ dùng với API key `boa_test_…`: chạy đúng luồng thật (khớp đơn, webhook `livemode: false`),
|
|
160
|
+
* không cần ngân hàng, không tính phí. Tối đa 10 lần mỗi phút.
|
|
161
|
+
*/
|
|
162
|
+
export class Sandbox extends Resource {
|
|
163
|
+
assertTest() {
|
|
164
|
+
if (this.client.livemode)
|
|
165
|
+
throw new BankOpenAPIError('Sandbox chỉ dùng với API key boa_test_…. / Sandbox helpers require a boa_test_ key.', { code: 'LIVE_MODE' });
|
|
166
|
+
}
|
|
167
|
+
/** Tạo tài khoản ngân hàng thử, liên kết xong ngay (không cần OTP). Tối đa 5 tài khoản thử */
|
|
168
|
+
createBankAccount(params = {}, options) {
|
|
169
|
+
this.assertTest();
|
|
170
|
+
return this.client.request('POST', '/test/bank-accounts', { ...options, body: params });
|
|
171
|
+
}
|
|
172
|
+
/** Giả lập tiền chuyển vào tài khoản thử. Nội dung có mã `TT…` của một yêu cầu thanh toán thì khớp yêu cầu đó */
|
|
173
|
+
createTransaction(params, options) {
|
|
174
|
+
this.assertTest();
|
|
175
|
+
return this.client.request('POST', '/test/transactions', { ...options, body: params });
|
|
176
|
+
}
|
|
177
|
+
/** Giả lập người mua thanh toán một yêu cầu. `amount` mặc định là số tiền còn thiếu */
|
|
178
|
+
payPaymentRequest(id, params = {}, options) {
|
|
179
|
+
this.assertTest();
|
|
180
|
+
return this.client.request('POST', `/test/payment-requests/${enc(id)}/pay`, { ...options, body: params });
|
|
181
|
+
}
|
|
182
|
+
}
|