barkapay 0.0.0-stage → 2.0.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/CHANGELOG.md +191 -0
- package/LICENSE +21 -0
- package/README.md +516 -2
- package/dist/index.cjs +1513 -0
- package/dist/index.d.cts +989 -0
- package/dist/index.d.ts +989 -0
- package/dist/index.mjs +1484 -0
- package/package.json +88 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,989 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Minimal transport contract. The SDK uses the global `fetch` (Node 18+) by
|
|
3
|
+
* default; pass your own `fetch`-compatible function to integrate a custom HTTP
|
|
4
|
+
* stack or to fake the network in tests. The shape is intentionally narrow so a
|
|
5
|
+
* fake is trivial to write, while the global `fetch` remains assignable.
|
|
6
|
+
*/
|
|
7
|
+
interface BarkaPayRequestInit {
|
|
8
|
+
method: string;
|
|
9
|
+
headers: Record<string, string>;
|
|
10
|
+
body?: string;
|
|
11
|
+
signal?: AbortSignal;
|
|
12
|
+
/**
|
|
13
|
+
* Always `'manual'`: the SDK never follows a redirect, so the
|
|
14
|
+
* `Authorization` header can never be replayed against another URL. A
|
|
15
|
+
* custom transport must honour it (or at least never forward credentials
|
|
16
|
+
* across a redirect).
|
|
17
|
+
*/
|
|
18
|
+
redirect?: 'manual';
|
|
19
|
+
}
|
|
20
|
+
/** The subset of response headers the SDK reads (`Retry-After`, `X-Request-Id`). */
|
|
21
|
+
interface BarkaPayResponseHeaders {
|
|
22
|
+
get(name: string): string | null;
|
|
23
|
+
}
|
|
24
|
+
interface BarkaPayResponse {
|
|
25
|
+
status: number;
|
|
26
|
+
/** Optional so that a minimal fake (`{ status, text }`) stays valid. */
|
|
27
|
+
headers?: BarkaPayResponseHeaders;
|
|
28
|
+
text(): Promise<string>;
|
|
29
|
+
}
|
|
30
|
+
type FetchFn = (url: string, init: BarkaPayRequestInit) => Promise<BarkaPayResponse>;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* When may a request be sent again automatically?
|
|
34
|
+
*
|
|
35
|
+
* - `idempotent`: a read (GET/HEAD). Retried on network failures, timeouts
|
|
36
|
+
* and 429 / 502 / 503 / 504.
|
|
37
|
+
* - `rate-limit-only`: every write (POST/PATCH/DELETE: create a payment, a
|
|
38
|
+
* transfer or a link, confirm or resend an OTP, update / cancel / pause /
|
|
39
|
+
* resume a link). Retried ONLY on 429, the one answer that proves the API
|
|
40
|
+
* refused it before doing any work, and only when the wait it asks for is
|
|
41
|
+
* at most 10 s. A timeout, a network error or a 5xx leaves the outcome
|
|
42
|
+
* unknown, and the API has no idempotency-key header: replaying could
|
|
43
|
+
* charge or pay twice.
|
|
44
|
+
*/
|
|
45
|
+
type RetryMode = 'idempotent' | 'rate-limit-only';
|
|
46
|
+
interface ApiClientOptions {
|
|
47
|
+
fetchFn: FetchFn;
|
|
48
|
+
/** The complete `Authorization` header value (`Bearer key_id:secret`). */
|
|
49
|
+
authorization: string;
|
|
50
|
+
baseUrl: string;
|
|
51
|
+
defaultCountry: string;
|
|
52
|
+
maxRetries: number;
|
|
53
|
+
timeoutMs: number;
|
|
54
|
+
userAgent: string;
|
|
55
|
+
/** Test seams — default to a real timer and `Math.random`. */
|
|
56
|
+
sleep?: (ms: number) => Promise<void>;
|
|
57
|
+
random?: () => number;
|
|
58
|
+
}
|
|
59
|
+
interface RequestOptions {
|
|
60
|
+
country?: string | null;
|
|
61
|
+
body?: object | null;
|
|
62
|
+
query?: Record<string, unknown> | null;
|
|
63
|
+
/** Defaults to `idempotent` for GET/HEAD and `rate-limit-only` otherwise. */
|
|
64
|
+
retry?: RetryMode;
|
|
65
|
+
/** Accept a 2xx with an empty body (endpoints that return nothing useful). */
|
|
66
|
+
allowEmpty?: boolean;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Internal transport: turns a logical call (method, path, country, body) into
|
|
70
|
+
* an authenticated HTTP request against `https://hub.barkapay.com/{country}/v1/…`,
|
|
71
|
+
* retries what is safe to retry, and unwraps the standard response envelope
|
|
72
|
+
* (throwing a typed {@link ApiError} on error).
|
|
73
|
+
*
|
|
74
|
+
* Credentials live in private fields: they never show up in `console.log`,
|
|
75
|
+
* `util.inspect` or `JSON.stringify` output, nor in the errors the SDK throws.
|
|
76
|
+
*
|
|
77
|
+
* @internal
|
|
78
|
+
*/
|
|
79
|
+
declare class ApiClient {
|
|
80
|
+
#private;
|
|
81
|
+
constructor(options: ApiClientOptions);
|
|
82
|
+
get baseUrl(): string;
|
|
83
|
+
get defaultCountry(): string;
|
|
84
|
+
request(method: string, path: string, { country, body, query, retry, allowEmpty }?: RequestOptions): Promise<Record<string, unknown>>;
|
|
85
|
+
/** Safe summary for `JSON.stringify` — never includes the credentials. */
|
|
86
|
+
toJSON(): Record<string, unknown>;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Lifecycle of a collection (payment). */
|
|
90
|
+
type PaymentStatus = 'CREATED' | 'AWAITING_OTP' | 'QUEUED_FOR_PROCESSING' | 'PROCESSING_OPERATOR' | 'PROCESSING_SYSTEM' | 'SUCCESSFUL' | 'FAILED' | 'EXPIRED' | 'COMPLIANCE_FLAGGED' | 'CANCELED';
|
|
91
|
+
/** Lifecycle of a disbursement (transfer). */
|
|
92
|
+
type TransferStatus = 'CREATED' | 'PROCESSING_OPERATOR' | 'PROCESSING_SYSTEM' | 'SUCCESSFUL' | 'FAILED' | 'COMPLIANCE_FLAGGED' | 'REFUNDED' | 'UNRESOLVED' | 'UNCERTAIN';
|
|
93
|
+
/** Lifecycle of a payment link. */
|
|
94
|
+
type PaymentLinkStatus = 'active' | 'paused' | 'paid' | 'expired' | 'canceled' | 'admin_blocked';
|
|
95
|
+
declare const PAYMENT_STATUSES: readonly PaymentStatus[];
|
|
96
|
+
declare const TRANSFER_STATUSES: readonly TransferStatus[];
|
|
97
|
+
declare const PAYMENT_LINK_STATUSES: readonly PaymentLinkStatus[];
|
|
98
|
+
/** No further transitions: SUCCESSFUL, FAILED, EXPIRED or CANCELED. */
|
|
99
|
+
declare function isPaymentStatusFinal(status: PaymentStatus | null): boolean;
|
|
100
|
+
/**
|
|
101
|
+
* No further transitions: SUCCESSFUL, FAILED or REFUNDED. `UNCERTAIN` is NOT
|
|
102
|
+
* final: the operator outcome is unknown and the verdict arrives by webhook.
|
|
103
|
+
*/
|
|
104
|
+
declare function isTransferStatusFinal(status: TransferStatus | null): boolean;
|
|
105
|
+
/** The stable failure codes published by the API in `reason_code`. */
|
|
106
|
+
type KnownReasonCode = 'payer_insufficient_funds' | 'payer_refused' | 'payer_unreachable' | 'invalid_otp' | 'otp_expired' | 'expired' | 'recipient_invalid' | 'operator_unavailable' | 'operator_timeout' | 'unconfirmed_after_window' | 'payment_not_completed' | 'amount_out_of_bounds' | 'duplicate' | 'provider_float_insufficient' | 'internal_error' | 'unknown';
|
|
107
|
+
/**
|
|
108
|
+
* A failure code. The catalogue only grows: codes this SDK version does not
|
|
109
|
+
* know yet are passed through as plain strings.
|
|
110
|
+
*/
|
|
111
|
+
type ReasonCode = KnownReasonCode | (string & {});
|
|
112
|
+
declare const REASON_CODES: readonly KnownReasonCode[];
|
|
113
|
+
/**
|
|
114
|
+
* A collection (payment) as returned by the API. Documented fields are typed;
|
|
115
|
+
* `raw` keeps the full payload for forward-compatibility.
|
|
116
|
+
*/
|
|
117
|
+
interface Payment {
|
|
118
|
+
/** Discriminant — always `'payment'`. */
|
|
119
|
+
object: 'payment';
|
|
120
|
+
publicId: string;
|
|
121
|
+
amount: number | string | null;
|
|
122
|
+
/** Fees charged to you, as a decimal string (e.g. `"6.25"`). */
|
|
123
|
+
fees: string | null;
|
|
124
|
+
currency: string | null;
|
|
125
|
+
phoneNumber: string | null;
|
|
126
|
+
country: string | null;
|
|
127
|
+
operator: string | null;
|
|
128
|
+
/** `api` (created through the API) or `hosted` (paid through a payment link). */
|
|
129
|
+
channel: string | null;
|
|
130
|
+
/** `null` when the API returns a status this SDK version does not know (see `raw.status`). */
|
|
131
|
+
status: PaymentStatus | null;
|
|
132
|
+
/** Your reference (`order.id` at creation). */
|
|
133
|
+
orderId: string | null;
|
|
134
|
+
/** The operator's transaction id, once the operator has confirmed. */
|
|
135
|
+
providerTransactionId: string | null;
|
|
136
|
+
/** The operator-side handle of this attempt (OTP transaction, checkout session…). */
|
|
137
|
+
providerReference: string | null;
|
|
138
|
+
orderData: Record<string, unknown> | null;
|
|
139
|
+
/** The `PL-…` id of the payment link this payment was made through, if any. */
|
|
140
|
+
linkPublicId: string | null;
|
|
141
|
+
/** Human-readable failure phrase (English), `null` unless the payment failed. */
|
|
142
|
+
reason: string | null;
|
|
143
|
+
/** Stable, machine-actionable failure code — branch on this, not on `reason`. */
|
|
144
|
+
reasonCode: ReasonCode | null;
|
|
145
|
+
/** The operator's own sentence, for support/debugging — not contractual. */
|
|
146
|
+
providerReason: string | null;
|
|
147
|
+
/** Page the payer must open to approve the payment (redirect-based operators such as Wave). */
|
|
148
|
+
redirectUrl: string | null;
|
|
149
|
+
createdAt: string | null;
|
|
150
|
+
raw: Record<string, unknown>;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* A disbursement (transfer) as returned by the API. Documented fields are typed;
|
|
154
|
+
* `raw` keeps the full payload for forward-compatibility.
|
|
155
|
+
*/
|
|
156
|
+
interface Transfer {
|
|
157
|
+
/** Discriminant — always `'transfer'`. */
|
|
158
|
+
object: 'transfer';
|
|
159
|
+
publicId: string;
|
|
160
|
+
amount: number | string | null;
|
|
161
|
+
/** Fees charged to you, as a decimal string (e.g. `"6.25"`). */
|
|
162
|
+
fees: string | null;
|
|
163
|
+
currency: string | null;
|
|
164
|
+
phoneNumber: string | null;
|
|
165
|
+
country: string | null;
|
|
166
|
+
operator: string | null;
|
|
167
|
+
channel: string | null;
|
|
168
|
+
/** `null` when the API returns a status this SDK version does not know (see `raw.status`). */
|
|
169
|
+
status: TransferStatus | null;
|
|
170
|
+
/** Your reference (`order.id` at creation). */
|
|
171
|
+
orderId: string | null;
|
|
172
|
+
/** The operator's transaction id, once the operator has confirmed. */
|
|
173
|
+
providerTransactionId: string | null;
|
|
174
|
+
/** The operator-side handle of this payout — what appears on the operator statement. */
|
|
175
|
+
providerReference: string | null;
|
|
176
|
+
orderData: Record<string, unknown> | null;
|
|
177
|
+
/** Human-readable failure phrase (English), `null` unless the transfer failed. */
|
|
178
|
+
reason: string | null;
|
|
179
|
+
/** Stable, machine-actionable failure code — branch on this, not on `reason`. */
|
|
180
|
+
reasonCode: ReasonCode | null;
|
|
181
|
+
/** The operator's own sentence, for support/debugging — not contractual. */
|
|
182
|
+
providerReason: string | null;
|
|
183
|
+
createdAt: string | null;
|
|
184
|
+
raw: Record<string, unknown>;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* The merchant wallet balance for a country: `currency` plus
|
|
188
|
+
* `available` / `total` / `holds` as decimal strings (e.g. `"150000.00"`).
|
|
189
|
+
*/
|
|
190
|
+
interface Balance {
|
|
191
|
+
country: string | null;
|
|
192
|
+
currency: string | null;
|
|
193
|
+
available: string | null;
|
|
194
|
+
total: string | null;
|
|
195
|
+
holds: string | null;
|
|
196
|
+
/** Per-asset breakdown, for multi-asset wallets only — `null` for mobile-money wallets. */
|
|
197
|
+
balances: Array<Record<string, unknown>> | null;
|
|
198
|
+
raw: Record<string, unknown>;
|
|
199
|
+
}
|
|
200
|
+
interface PaymentLinkAmount {
|
|
201
|
+
/** `fixed` (one price), `open` (the payer chooses) or `range` (between `min` and `max`). */
|
|
202
|
+
type: 'fixed' | 'open' | 'range' | (string & {}) | null;
|
|
203
|
+
value: string | null;
|
|
204
|
+
min: string | null;
|
|
205
|
+
max: string | null;
|
|
206
|
+
currency: string | null;
|
|
207
|
+
}
|
|
208
|
+
interface PaymentLinkStats {
|
|
209
|
+
/** Number of SUCCESSFUL payments made through the link (all countries). */
|
|
210
|
+
paymentsCount: number | null;
|
|
211
|
+
/** Total collected through the link, as a decimal string. */
|
|
212
|
+
totalCollected: string | null;
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* A payment link: a durable page on the barkapay-hosted checkout where your
|
|
216
|
+
* customer picks an operator and pays. Share its `url`.
|
|
217
|
+
*/
|
|
218
|
+
interface PaymentLink {
|
|
219
|
+
/** Discriminant — always `'payment_link'`. */
|
|
220
|
+
object: 'payment_link';
|
|
221
|
+
/** The `PL-…` identifier. */
|
|
222
|
+
publicId: string;
|
|
223
|
+
/** The 13-character public slug (last segment of `url`). */
|
|
224
|
+
slug: string | null;
|
|
225
|
+
/** The checkout URL to share with your customer. */
|
|
226
|
+
url: string | null;
|
|
227
|
+
/** `null` when the API returns a status this SDK version does not know (see `raw.status`). */
|
|
228
|
+
status: PaymentLinkStatus | null;
|
|
229
|
+
/** `api` (created through the API) or `ui` (created from the dashboard). */
|
|
230
|
+
source: string | null;
|
|
231
|
+
/** `single` (closed by the first successful payment) or `multi` (reusable). */
|
|
232
|
+
usage: 'single' | 'multi' | (string & {}) | null;
|
|
233
|
+
amount: PaymentLinkAmount;
|
|
234
|
+
title: string | null;
|
|
235
|
+
description: string | null;
|
|
236
|
+
/** Your order reference, as sent at creation (`{ id, data? }`). */
|
|
237
|
+
order: Record<string, unknown> | null;
|
|
238
|
+
redirect: {
|
|
239
|
+
successUrl: string | null;
|
|
240
|
+
cancelUrl: string | null;
|
|
241
|
+
} | null;
|
|
242
|
+
restrictions: {
|
|
243
|
+
countries: string[] | null;
|
|
244
|
+
operators: string[] | null;
|
|
245
|
+
} | null;
|
|
246
|
+
payer: {
|
|
247
|
+
fullName: string | null;
|
|
248
|
+
email: string | null;
|
|
249
|
+
phone: string | null;
|
|
250
|
+
locale: string | null;
|
|
251
|
+
} | null;
|
|
252
|
+
/** Fields the checkout asks the payer for: `{ full_name?, email?, city?, motif? }` → `required | optional | off`. */
|
|
253
|
+
collect: Record<string, unknown>;
|
|
254
|
+
/** Whether the payment-request email is sent to `payer.email`. */
|
|
255
|
+
notifyEmailInvoice: boolean | null;
|
|
256
|
+
expiresAt: string | null;
|
|
257
|
+
stats: PaymentLinkStats;
|
|
258
|
+
/** For a `single` link that has been paid: the payment that closed it. */
|
|
259
|
+
paidByPaymentPublicId: string | null;
|
|
260
|
+
createdAt: string | null;
|
|
261
|
+
raw: Record<string, unknown>;
|
|
262
|
+
}
|
|
263
|
+
/** The link summary returned alongside {@link PaymentLinkPaymentList}. */
|
|
264
|
+
interface PaymentLinkSummary {
|
|
265
|
+
publicId: string;
|
|
266
|
+
slug: string | null;
|
|
267
|
+
status: PaymentLinkStatus | null;
|
|
268
|
+
stats: PaymentLinkStats;
|
|
269
|
+
}
|
|
270
|
+
interface Pagination {
|
|
271
|
+
currentPage: number | null;
|
|
272
|
+
/** Not returned by `paymentLinks.list` — compute it from `total` / `perPage`. */
|
|
273
|
+
lastPage: number | null;
|
|
274
|
+
perPage: number | null;
|
|
275
|
+
total: number | null;
|
|
276
|
+
}
|
|
277
|
+
interface PaymentList {
|
|
278
|
+
data: Payment[];
|
|
279
|
+
meta: Pagination | null;
|
|
280
|
+
}
|
|
281
|
+
interface TransferList {
|
|
282
|
+
data: Transfer[];
|
|
283
|
+
meta: Pagination | null;
|
|
284
|
+
}
|
|
285
|
+
interface PaymentLinkList {
|
|
286
|
+
data: PaymentLink[];
|
|
287
|
+
meta: Pagination | null;
|
|
288
|
+
}
|
|
289
|
+
/** Payments made through one payment link, in the country queried. */
|
|
290
|
+
interface PaymentLinkPaymentList {
|
|
291
|
+
data: Payment[];
|
|
292
|
+
meta: Pagination | null;
|
|
293
|
+
/** Global summary of the link (its `stats` span every country). */
|
|
294
|
+
paymentLink: PaymentLinkSummary | null;
|
|
295
|
+
}
|
|
296
|
+
/** Per-call options; `country` overrides the client default for this call. */
|
|
297
|
+
interface CallOptions {
|
|
298
|
+
country?: string;
|
|
299
|
+
}
|
|
300
|
+
/** List/filter query parameters (null/undefined values are dropped). */
|
|
301
|
+
type ListFilters = Record<string, string | number | boolean | null | undefined>;
|
|
302
|
+
/** Comparison used with the `amount` filter. */
|
|
303
|
+
type AmountOperator = '<' | '=' | '>' | '<=' | '>=';
|
|
304
|
+
/** Filters of `payments.list` (newest first, 50 per page by default). */
|
|
305
|
+
interface PaymentListParams extends ListFilters {
|
|
306
|
+
status?: PaymentStatus | (string & {});
|
|
307
|
+
operator?: string;
|
|
308
|
+
phone_number?: string;
|
|
309
|
+
/** `api` or `hosted`. */
|
|
310
|
+
channel?: string;
|
|
311
|
+
order_id?: string;
|
|
312
|
+
/** Only applied together with `amount_operator`. */
|
|
313
|
+
amount?: number | string;
|
|
314
|
+
amount_operator?: AmountOperator;
|
|
315
|
+
/** `YYYY-MM-DD` (or any date). Only applied together with `to_date`. */
|
|
316
|
+
from_date?: string;
|
|
317
|
+
/** `YYYY-MM-DD` (or any date). Only applied together with `from_date`. */
|
|
318
|
+
to_date?: string;
|
|
319
|
+
page?: number;
|
|
320
|
+
/** 1–200, default 50. */
|
|
321
|
+
per_page?: number;
|
|
322
|
+
}
|
|
323
|
+
/** Filters of `transfers.list` (newest first, 50 per page by default). */
|
|
324
|
+
interface TransferListParams extends ListFilters {
|
|
325
|
+
/** The API refuses `UNCERTAIN` and `UNRESOLVED` here (422): filter those client-side. */
|
|
326
|
+
status?: TransferStatus | (string & {});
|
|
327
|
+
operator?: string;
|
|
328
|
+
phone_number?: string;
|
|
329
|
+
channel?: string;
|
|
330
|
+
order_id?: string;
|
|
331
|
+
/** Only applied together with `amount_operator`. */
|
|
332
|
+
amount?: number | string;
|
|
333
|
+
amount_operator?: AmountOperator;
|
|
334
|
+
/** `YYYY-MM-DD` (or any date). Only applied together with `to_date`. */
|
|
335
|
+
from_date?: string;
|
|
336
|
+
/** `YYYY-MM-DD` (or any date). Only applied together with `from_date`. */
|
|
337
|
+
to_date?: string;
|
|
338
|
+
page?: number;
|
|
339
|
+
/** 1–200, default 50. */
|
|
340
|
+
per_page?: number;
|
|
341
|
+
}
|
|
342
|
+
/** Filters of `paymentLinks.list` (newest first, 25 per page by default). */
|
|
343
|
+
interface PaymentLinkListParams extends ListFilters {
|
|
344
|
+
/** One status, or several separated by commas (e.g. `"active,paid"`). */
|
|
345
|
+
status?: PaymentLinkStatus | (string & {});
|
|
346
|
+
usage?: 'single' | 'multi' | (string & {});
|
|
347
|
+
/** `api` or `ui`. */
|
|
348
|
+
source?: string;
|
|
349
|
+
page?: number;
|
|
350
|
+
/** 1–100, default 25. */
|
|
351
|
+
per_page?: number;
|
|
352
|
+
}
|
|
353
|
+
/** Filters of `paymentLinks.listPayments` (newest first, 25 per page by default). */
|
|
354
|
+
interface PaymentLinkPaymentListParams extends ListFilters {
|
|
355
|
+
status?: PaymentStatus | (string & {});
|
|
356
|
+
operator?: string;
|
|
357
|
+
phone_number?: string;
|
|
358
|
+
/** `YYYY-MM-DD` — payments created on or after that day. */
|
|
359
|
+
from_date?: string;
|
|
360
|
+
/** `YYYY-MM-DD` — payments created on or before that day. */
|
|
361
|
+
to_date?: string;
|
|
362
|
+
page?: number;
|
|
363
|
+
/** 1–100, default 25. */
|
|
364
|
+
per_page?: number;
|
|
365
|
+
}
|
|
366
|
+
/** Your order reference, attached to a payment or a transfer. */
|
|
367
|
+
interface OrderParams {
|
|
368
|
+
/** Your own reference (max 255 characters). Look operations up with it later. */
|
|
369
|
+
id: string;
|
|
370
|
+
/**
|
|
371
|
+
* `true` makes the API refuse (409 `duplicate_transaction`) any second
|
|
372
|
+
* operation carrying the same `id` — the way to make a create call safe to
|
|
373
|
+
* send again after a timeout.
|
|
374
|
+
*/
|
|
375
|
+
unique?: boolean;
|
|
376
|
+
/** Up to 20 free-form string values echoed back in `orderData` and webhooks. */
|
|
377
|
+
data?: Record<string, string>;
|
|
378
|
+
[key: string]: unknown;
|
|
379
|
+
}
|
|
380
|
+
interface PaymentCreateParams {
|
|
381
|
+
/** Upper-case operator code, e.g. `ORANGE`, `MOOV`, `MTN`, `WAVE` (see `operators.info()`). */
|
|
382
|
+
operator: string;
|
|
383
|
+
/** National format, without the country code (8 digits in `bf`, 9 in `sn`, 10 in `bj`). */
|
|
384
|
+
phone_number: string;
|
|
385
|
+
/** In the country's currency; at most 2 decimals. */
|
|
386
|
+
amount: number | string;
|
|
387
|
+
/** `{ id, unique?, data? }` — see {@link OrderParams}. */
|
|
388
|
+
order: OrderParams | Record<string, unknown>;
|
|
389
|
+
/**
|
|
390
|
+
* Only for operators that take the payer's OTP at creation (e.g. Orange).
|
|
391
|
+
* Always a string: a leading zero is significant.
|
|
392
|
+
*/
|
|
393
|
+
otp?: string;
|
|
394
|
+
/**
|
|
395
|
+
* Where an operator that redirects the payer (WAVE in Sénégal today) sends
|
|
396
|
+
* them back after the payment; other operators accept and ignore it.
|
|
397
|
+
* Absolute `https` URL, at most 2000 characters, without credentials or
|
|
398
|
+
* `#fragment` — otherwise the API answers 422 (`ValidationError`,
|
|
399
|
+
* `errors.return_url`). Left out: the URL set on your API application, else
|
|
400
|
+
* a barkapay page. The API appends `payment_id` and `order_id` to the query
|
|
401
|
+
* string, never a status: **the payer coming back is not a proof of
|
|
402
|
+
* payment** — wait for the webhook or call `payments.get()`. Not echoed back
|
|
403
|
+
* on the payment.
|
|
404
|
+
*/
|
|
405
|
+
return_url?: string | null;
|
|
406
|
+
/**
|
|
407
|
+
* Where the payer goes after a failure or a cancellation (falls back on
|
|
408
|
+
* `return_url`). Same rules as `return_url`; `errors.cancel_url` on a 422.
|
|
409
|
+
*/
|
|
410
|
+
cancel_url?: string | null;
|
|
411
|
+
[key: string]: unknown;
|
|
412
|
+
}
|
|
413
|
+
interface TransferCreateParams {
|
|
414
|
+
/** Upper-case operator code, e.g. `ORANGE`, `MOOV`, `MTN`, `WAVE` (see `operators.info()`). */
|
|
415
|
+
operator: string;
|
|
416
|
+
/** National format, without the country code (8 digits in `bf`, 9 in `sn`, 10 in `bj`). */
|
|
417
|
+
phone_number: string;
|
|
418
|
+
/** In the country's currency; at most 2 decimals. */
|
|
419
|
+
amount: number | string;
|
|
420
|
+
/** `{ id, unique?, data? }` — see {@link OrderParams}. */
|
|
421
|
+
order: OrderParams | Record<string, unknown>;
|
|
422
|
+
/**
|
|
423
|
+
* Bypass the guard that refuses (409) a transfer carrying the same order id,
|
|
424
|
+
* recipient, amount and operator as one sent in the last 60 seconds —
|
|
425
|
+
* whatever became of that first attempt. Leave unset unless you really mean
|
|
426
|
+
* to send it twice.
|
|
427
|
+
*/
|
|
428
|
+
ignore_double_spend_risk?: boolean;
|
|
429
|
+
[key: string]: unknown;
|
|
430
|
+
}
|
|
431
|
+
/** What the hosted checkout asks the payer for. */
|
|
432
|
+
type PaymentLinkCollectMode = 'required' | 'optional' | 'off';
|
|
433
|
+
interface PaymentLinkCreateParams {
|
|
434
|
+
/** Shown to the payer (max 120 characters). */
|
|
435
|
+
title: string;
|
|
436
|
+
amount: {
|
|
437
|
+
type: 'fixed' | 'open' | 'range';
|
|
438
|
+
/** Defaults to `XOF`. */
|
|
439
|
+
currency?: string;
|
|
440
|
+
/** Required for `fixed`. */
|
|
441
|
+
value?: number | string;
|
|
442
|
+
/** Required for `range`. */
|
|
443
|
+
min?: number | string;
|
|
444
|
+
/** Required for `range`. */
|
|
445
|
+
max?: number | string;
|
|
446
|
+
};
|
|
447
|
+
description?: string | null;
|
|
448
|
+
/** `single` (default): closed by the first successful payment. `multi`: reusable. */
|
|
449
|
+
usage?: 'single' | 'multi';
|
|
450
|
+
/** Your reference, copied onto every payment made through the link. */
|
|
451
|
+
order?: {
|
|
452
|
+
id: string;
|
|
453
|
+
data?: Record<string, unknown>;
|
|
454
|
+
} | null;
|
|
455
|
+
/** Where the checkout sends the payer afterwards (http/https URLs). */
|
|
456
|
+
redirect?: {
|
|
457
|
+
success_url?: string | null;
|
|
458
|
+
cancel_url?: string | null;
|
|
459
|
+
} | null;
|
|
460
|
+
/** Narrow the payer's choices. `countries` defaults to the country you call. */
|
|
461
|
+
restrictions?: {
|
|
462
|
+
countries?: string[];
|
|
463
|
+
operators?: string[];
|
|
464
|
+
} | null;
|
|
465
|
+
/** A payer you already know — prefills the checkout. */
|
|
466
|
+
payer?: {
|
|
467
|
+
full_name?: string | null;
|
|
468
|
+
email?: string | null;
|
|
469
|
+
phone?: string | null;
|
|
470
|
+
locale?: 'fr' | 'en' | null;
|
|
471
|
+
} | null;
|
|
472
|
+
collect?: {
|
|
473
|
+
full_name?: PaymentLinkCollectMode;
|
|
474
|
+
email?: PaymentLinkCollectMode;
|
|
475
|
+
city?: PaymentLinkCollectMode;
|
|
476
|
+
motif?: PaymentLinkCollectMode;
|
|
477
|
+
};
|
|
478
|
+
/** Email the payment request to `payer.email` on creation. */
|
|
479
|
+
notify_email_invoice?: boolean;
|
|
480
|
+
/** ISO 8601 date-time in the future (a `Date` works too). Omitted: never expires. */
|
|
481
|
+
expires_at?: string | Date | null;
|
|
482
|
+
[key: string]: unknown;
|
|
483
|
+
}
|
|
484
|
+
/** Only these fields can change after creation; send `null` to clear a nullable one. */
|
|
485
|
+
interface PaymentLinkUpdateParams {
|
|
486
|
+
title?: string;
|
|
487
|
+
description?: string | null;
|
|
488
|
+
/** ISO 8601 date-time in the future (a `Date` works too). */
|
|
489
|
+
expires_at?: string | Date | null;
|
|
490
|
+
redirect?: {
|
|
491
|
+
success_url?: string | null;
|
|
492
|
+
cancel_url?: string | null;
|
|
493
|
+
} | null;
|
|
494
|
+
[key: string]: unknown;
|
|
495
|
+
}
|
|
496
|
+
/** `ping()` — liveness of the API for a country. */
|
|
497
|
+
interface PingResult {
|
|
498
|
+
version?: string;
|
|
499
|
+
documentation?: string | null;
|
|
500
|
+
[key: string]: unknown;
|
|
501
|
+
}
|
|
502
|
+
/** `me()` — the merchant and API application behind the key. */
|
|
503
|
+
interface MeResult {
|
|
504
|
+
merchant?: {
|
|
505
|
+
public_id?: string;
|
|
506
|
+
name?: string;
|
|
507
|
+
country?: string;
|
|
508
|
+
email?: string;
|
|
509
|
+
[key: string]: unknown;
|
|
510
|
+
};
|
|
511
|
+
api_app?: {
|
|
512
|
+
public_id?: string;
|
|
513
|
+
name?: string;
|
|
514
|
+
label?: string;
|
|
515
|
+
scopes?: string[];
|
|
516
|
+
/** The country × operator × service matrix enabled for the application. */
|
|
517
|
+
permissions?: Array<Record<string, unknown>>;
|
|
518
|
+
allowed_countries?: string[];
|
|
519
|
+
allowed_services?: string;
|
|
520
|
+
can_perform_transfers?: boolean;
|
|
521
|
+
[key: string]: unknown;
|
|
522
|
+
};
|
|
523
|
+
[key: string]: unknown;
|
|
524
|
+
}
|
|
525
|
+
interface OperatorServiceAvailability {
|
|
526
|
+
/** `operational`, `degraded` or `down`. */
|
|
527
|
+
status?: 'operational' | 'degraded' | 'down' | (string & {});
|
|
528
|
+
reason?: string | null;
|
|
529
|
+
/** When this availability was last published — `null` when it never was. */
|
|
530
|
+
updated_at?: string | null;
|
|
531
|
+
[key: string]: unknown;
|
|
532
|
+
}
|
|
533
|
+
/** `operators.availability()` — keyed by ISO-3 country, then operator, then service. */
|
|
534
|
+
interface OperatorsAvailability {
|
|
535
|
+
operational?: boolean;
|
|
536
|
+
services?: Record<string, Record<string, {
|
|
537
|
+
payment?: OperatorServiceAvailability;
|
|
538
|
+
transfer?: OperatorServiceAvailability;
|
|
539
|
+
[key: string]: unknown;
|
|
540
|
+
}>>;
|
|
541
|
+
[key: string]: unknown;
|
|
542
|
+
}
|
|
543
|
+
interface OperatorInfo {
|
|
544
|
+
/** Whether a payment with this operator involves an OTP typed by the payer. */
|
|
545
|
+
otp_required?: boolean;
|
|
546
|
+
/** What to tell the payer (e.g. the USSD code that generates the OTP). */
|
|
547
|
+
payment_instructions?: string;
|
|
548
|
+
/** Seconds the payer has to complete the payment; `null` when unknown. */
|
|
549
|
+
pay_delay?: number | null;
|
|
550
|
+
min_amount?: number;
|
|
551
|
+
max_amount?: number;
|
|
552
|
+
[key: string]: unknown;
|
|
553
|
+
}
|
|
554
|
+
/** `operators.info()` — the authoritative operator list, keyed by ISO-3 country then operator. */
|
|
555
|
+
interface OperatorsInfo {
|
|
556
|
+
operators?: Record<string, Record<string, OperatorInfo>>;
|
|
557
|
+
supported_countries?: string[];
|
|
558
|
+
[key: string]: unknown;
|
|
559
|
+
}
|
|
560
|
+
interface WebhookEventBase {
|
|
561
|
+
/** Stable across re-deliveries of the same event — deduplicate on it. */
|
|
562
|
+
event_id: string;
|
|
563
|
+
/** When the event was created (ISO 8601). */
|
|
564
|
+
timestamp: string;
|
|
565
|
+
public_id: string;
|
|
566
|
+
amount?: number | string | null;
|
|
567
|
+
/** Decimal string (e.g. `"6.25"`). */
|
|
568
|
+
fees?: string | null;
|
|
569
|
+
phone_number?: string | null;
|
|
570
|
+
country?: string | null;
|
|
571
|
+
order_id?: string | null;
|
|
572
|
+
order_data?: Record<string, unknown> | null;
|
|
573
|
+
provider_transaction_id?: string | null;
|
|
574
|
+
reason?: string | null;
|
|
575
|
+
reason_code?: ReasonCode | null;
|
|
576
|
+
provider_reason?: string | null;
|
|
577
|
+
app_label?: string | null;
|
|
578
|
+
[key: string]: unknown;
|
|
579
|
+
}
|
|
580
|
+
/** Body of a `payment.succeeded` / `payment.failed` / `payment.expired` delivery. */
|
|
581
|
+
interface PaymentWebhookEvent extends WebhookEventBase {
|
|
582
|
+
type: 'payment';
|
|
583
|
+
/** `SUCCESSFUL`, `FAILED`, `CANCELED` or `EXPIRED`. */
|
|
584
|
+
status: PaymentStatus | (string & {});
|
|
585
|
+
/** The `PL-…` id when the payment was made through a payment link. */
|
|
586
|
+
link_public_id?: string | null;
|
|
587
|
+
}
|
|
588
|
+
/** Body of a `transfer.succeeded` / `transfer.failed` delivery. */
|
|
589
|
+
interface TransferWebhookEvent extends WebhookEventBase {
|
|
590
|
+
type: 'transfer';
|
|
591
|
+
/** `SUCCESSFUL`, `FAILED` or `CANCELED`. */
|
|
592
|
+
status: TransferStatus | (string & {});
|
|
593
|
+
}
|
|
594
|
+
/**
|
|
595
|
+
* A verified webhook body. There is no `event` field: derive the event from
|
|
596
|
+
* `type` + `status` (`payment` + `SUCCESSFUL` = `payment.succeeded`, …).
|
|
597
|
+
*/
|
|
598
|
+
type WebhookEvent = PaymentWebhookEvent | TransferWebhookEvent;
|
|
599
|
+
|
|
600
|
+
declare class BalanceResource {
|
|
601
|
+
#private;
|
|
602
|
+
constructor(api: ApiClient);
|
|
603
|
+
/** The merchant's wallet balance for the country. */
|
|
604
|
+
get(options?: CallOptions): Promise<Balance>;
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
declare class Operators {
|
|
608
|
+
#private;
|
|
609
|
+
constructor(api: ApiClient);
|
|
610
|
+
/** Real-time payment/transfer availability per operator (`operational`, `degraded`, `down`). */
|
|
611
|
+
availability(options?: CallOptions): Promise<OperatorsAvailability>;
|
|
612
|
+
/**
|
|
613
|
+
* Operator capabilities (OTP requirement, amount bounds, payer instructions).
|
|
614
|
+
* This is the authoritative list of operators for the country.
|
|
615
|
+
*/
|
|
616
|
+
info(options?: CallOptions): Promise<OperatorsInfo>;
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
/**
|
|
620
|
+
* Payment links — durable pages on the barkapay-hosted checkout. Wherever an
|
|
621
|
+
* `id` is expected you can pass the `PL-…` public id or the 13-character slug.
|
|
622
|
+
*/
|
|
623
|
+
declare class PaymentLinks {
|
|
624
|
+
#private;
|
|
625
|
+
constructor(api: ApiClient);
|
|
626
|
+
/**
|
|
627
|
+
* Create a payment link (`title` + `amount` are required). No payment exists
|
|
628
|
+
* yet: payments are born when your customers pay on `link.url`.
|
|
629
|
+
*
|
|
630
|
+
* ⚠️ Never re-sent automatically on a timeout or a 5xx (it could create the
|
|
631
|
+
* link twice).
|
|
632
|
+
*/
|
|
633
|
+
create(params: PaymentLinkCreateParams, options?: CallOptions): Promise<PaymentLink>;
|
|
634
|
+
/**
|
|
635
|
+
* List your payment links, newest first. Filters: `status` (one or several,
|
|
636
|
+
* comma-separated), `usage`, `source`, `page`, `per_page` (max 100).
|
|
637
|
+
*/
|
|
638
|
+
list(params?: PaymentLinkListParams, options?: CallOptions): Promise<PaymentLinkList>;
|
|
639
|
+
/** Retrieve a payment link by its `PL-…` id or its slug. */
|
|
640
|
+
get(id: string, options?: CallOptions): Promise<PaymentLink>;
|
|
641
|
+
/**
|
|
642
|
+
* Edit an active or paused link. Only `title`, `description`, `expires_at`
|
|
643
|
+
* and `redirect` can change; pass `null` to clear a nullable field.
|
|
644
|
+
*/
|
|
645
|
+
update(id: string, params: PaymentLinkUpdateParams, options?: CallOptions): Promise<PaymentLink>;
|
|
646
|
+
/** Cancel a link for good (active or paused → canceled). Cancelling twice is harmless. */
|
|
647
|
+
cancel(id: string, options?: CallOptions): Promise<PaymentLink>;
|
|
648
|
+
/**
|
|
649
|
+
* Pause an active link: the checkout refuses new payers at once. A link in
|
|
650
|
+
* any other state is returned unchanged — check `status` on the result.
|
|
651
|
+
*/
|
|
652
|
+
pause(id: string, options?: CallOptions): Promise<PaymentLink>;
|
|
653
|
+
/**
|
|
654
|
+
* Re-open a paused link. A link in any other state is returned unchanged —
|
|
655
|
+
* check `status` on the result.
|
|
656
|
+
*/
|
|
657
|
+
resume(id: string, options?: CallOptions): Promise<PaymentLink>;
|
|
658
|
+
/**
|
|
659
|
+
* Payments made through a link, newest first — the country you call only.
|
|
660
|
+
* A link open to several countries spreads its payments across them: call
|
|
661
|
+
* each one (`{ country }`) for the full picture. `paymentLink.stats` on the
|
|
662
|
+
* result is global either way.
|
|
663
|
+
*/
|
|
664
|
+
listPayments(id: string, params?: PaymentLinkPaymentListParams, options?: CallOptions): Promise<PaymentLinkPaymentList>;
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
declare class Payments {
|
|
668
|
+
#private;
|
|
669
|
+
constructor(api: ApiClient);
|
|
670
|
+
/**
|
|
671
|
+
* Create a collection (payment): charge a payer now. Pass `operator`,
|
|
672
|
+
* `phone_number`, `amount`, `order: { id }` and, for operators that take it
|
|
673
|
+
* up-front, `otp`. Branch on the returned `status` (`SUCCESSFUL`,
|
|
674
|
+
* `AWAITING_OTP`, `PROCESSING_OPERATOR`…).
|
|
675
|
+
*
|
|
676
|
+
* Optional `return_url` / `cancel_url`: where an operator that redirects the
|
|
677
|
+
* payer (WAVE in Sénégal) sends them back. Only sent when given; validated
|
|
678
|
+
* by the API (422 `ValidationError`). The return is not a proof of payment.
|
|
679
|
+
*
|
|
680
|
+
* This is always a direct payment. For a hosted checkout page where the
|
|
681
|
+
* payer chooses how to pay, use `paymentLinks.create`.
|
|
682
|
+
*
|
|
683
|
+
* A refused payment rejects with `PaymentFailedError` (its `payment`
|
|
684
|
+
* property holds the `FAILED` snapshot).
|
|
685
|
+
*
|
|
686
|
+
* ⚠️ Never re-sent automatically on a timeout or a 5xx (it could charge the
|
|
687
|
+
* payer twice). Set `order.unique: true` and, if the outcome is unknown,
|
|
688
|
+
* look the payment up with `payments.list({ order_id })` before retrying.
|
|
689
|
+
*/
|
|
690
|
+
create(params: PaymentCreateParams, options?: CallOptions): Promise<Payment>;
|
|
691
|
+
/**
|
|
692
|
+
* List payments, newest first. Filters: `status`, `operator`, `phone_number`,
|
|
693
|
+
* `channel`, `order_id`, `amount` + `amount_operator`, `from_date` +
|
|
694
|
+
* `to_date` (both or neither), `page`, `per_page` (max 200).
|
|
695
|
+
*/
|
|
696
|
+
list(filters?: PaymentListParams, options?: CallOptions): Promise<PaymentList>;
|
|
697
|
+
/**
|
|
698
|
+
* Look up a payment by its `publicId` (UUID) or by your `order.id`.
|
|
699
|
+
*
|
|
700
|
+
* An id shaped like a UUID is always read as a `publicId`. If several
|
|
701
|
+
* payments share the same order id, the first match is returned — use
|
|
702
|
+
* `list({ order_id })` to get them all.
|
|
703
|
+
*/
|
|
704
|
+
get(id: string, options?: CallOptions): Promise<Payment>;
|
|
705
|
+
/**
|
|
706
|
+
* Confirm a payment that is `AWAITING_OTP` with the code the payer received.
|
|
707
|
+
* Pass the OTP as a string: a leading zero is significant.
|
|
708
|
+
*
|
|
709
|
+
* Only operators that send the OTP after creation use this step — today
|
|
710
|
+
* MOOV in Burkina Faso; the endpoint exists on `bf` only.
|
|
711
|
+
*/
|
|
712
|
+
confirmOtp(publicId: string, otp: string, options?: CallOptions): Promise<Payment>;
|
|
713
|
+
/** Send the payer a new OTP for a payment that is still `AWAITING_OTP` (`bf` only, see `confirmOtp`). */
|
|
714
|
+
resendOtp(publicId: string, options?: CallOptions): Promise<void>;
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
declare class Transfers {
|
|
718
|
+
#private;
|
|
719
|
+
constructor(api: ApiClient);
|
|
720
|
+
/**
|
|
721
|
+
* Create a disbursement (transfer): `operator`, `phone_number`, `amount`,
|
|
722
|
+
* `order: { id }`.
|
|
723
|
+
*
|
|
724
|
+
* A transfer whose status is `UNCERTAIN` was accepted but the operator has
|
|
725
|
+
* not confirmed yet: do NOT send it again, the verdict arrives by webhook.
|
|
726
|
+
* A refused transfer rejects with `TransferFailedError`, an underfunded one
|
|
727
|
+
* with `InsufficientBalanceError`, a duplicate with `ConflictError`.
|
|
728
|
+
*
|
|
729
|
+
* ⚠️ Never re-sent automatically on a timeout or a 5xx (it could pay the
|
|
730
|
+
* recipient twice). Set `order.unique: true` and, if the outcome is unknown,
|
|
731
|
+
* look the transfer up with `transfers.list({ order_id })` before retrying.
|
|
732
|
+
*/
|
|
733
|
+
create(params: TransferCreateParams, options?: CallOptions): Promise<Transfer>;
|
|
734
|
+
/**
|
|
735
|
+
* List transfers, newest first. Filters: `status`, `operator`,
|
|
736
|
+
* `phone_number`, `channel`, `order_id`, `amount` + `amount_operator`,
|
|
737
|
+
* `from_date` + `to_date` (both or neither), `page`, `per_page` (max 200).
|
|
738
|
+
*/
|
|
739
|
+
list(filters?: TransferListParams, options?: CallOptions): Promise<TransferList>;
|
|
740
|
+
/**
|
|
741
|
+
* Look up a transfer by its `publicId` (UUID) or by your `order.id`.
|
|
742
|
+
*
|
|
743
|
+
* An id shaped like a UUID is always read as a `publicId`. If several
|
|
744
|
+
* transfers share the same order id, the first match is returned — use
|
|
745
|
+
* `list({ order_id })` to get them all.
|
|
746
|
+
*/
|
|
747
|
+
get(id: string, options?: CallOptions): Promise<Transfer>;
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
interface BarkaPayOptions {
|
|
751
|
+
/**
|
|
752
|
+
* The merchant key as `"key_id:secret"` (what you copy from the dashboard).
|
|
753
|
+
* Do NOT prefix it with `Bearer` — the SDK does that. An accidental `Bearer `
|
|
754
|
+
* prefix is forgiven.
|
|
755
|
+
*/
|
|
756
|
+
apiKey?: string;
|
|
757
|
+
/** Alternatively, the key id… */
|
|
758
|
+
keyId?: string;
|
|
759
|
+
/** …and the secret, passed separately. */
|
|
760
|
+
secret?: string;
|
|
761
|
+
/** Default country code (`"bf"`, `"bj"` or `"sn"`); overridable per call. */
|
|
762
|
+
country?: string;
|
|
763
|
+
/**
|
|
764
|
+
* API base URL (default `https://hub.barkapay.com`). Must be `https://`;
|
|
765
|
+
* plain `http://` is accepted for a loopback host only (`localhost`,
|
|
766
|
+
* `127.0.0.1`, `[::1]`) — or for any non-barkapay host when you pass your
|
|
767
|
+
* own `fetch`, which then owns the connection.
|
|
768
|
+
*/
|
|
769
|
+
baseUrl?: string;
|
|
770
|
+
/**
|
|
771
|
+
* Automatic retries (default 2). Reads (GET) are retried on network
|
|
772
|
+
* failures, timeouts and 429/502/503/504; writes (create, confirm, update,
|
|
773
|
+
* cancel, pause, resume…) on 429 only, and only when the API asks to wait
|
|
774
|
+
* 10 s or less. `0` disables retries.
|
|
775
|
+
*/
|
|
776
|
+
maxRetries?: number;
|
|
777
|
+
/** Per-attempt timeout in milliseconds, headers and body included (default 40000). */
|
|
778
|
+
timeoutMs?: number;
|
|
779
|
+
/** A `fetch`-compatible function; defaults to the global `fetch` (Node 18+). */
|
|
780
|
+
fetch?: FetchFn;
|
|
781
|
+
}
|
|
782
|
+
/**
|
|
783
|
+
* Entry point to the barkapay API.
|
|
784
|
+
*
|
|
785
|
+
* ```ts
|
|
786
|
+
* const barkapay = new BarkaPay({ apiKey: process.env.BARKAPAY_API_KEY, country: 'bf' });
|
|
787
|
+
* const payment = await barkapay.payments.create({
|
|
788
|
+
* operator: 'ORANGE',
|
|
789
|
+
* phone_number: '74000000', // national format, without the country code
|
|
790
|
+
* amount: 10000,
|
|
791
|
+
* otp: '123456',
|
|
792
|
+
* order: { id: 'ORDER-2026-001', unique: true },
|
|
793
|
+
* });
|
|
794
|
+
* ```
|
|
795
|
+
*/
|
|
796
|
+
declare class BarkaPay {
|
|
797
|
+
#private;
|
|
798
|
+
static readonly VERSION = "2.0.0";
|
|
799
|
+
readonly payments: Payments;
|
|
800
|
+
readonly paymentLinks: PaymentLinks;
|
|
801
|
+
readonly transfers: Transfers;
|
|
802
|
+
readonly balance: BalanceResource;
|
|
803
|
+
readonly operators: Operators;
|
|
804
|
+
constructor(options: BarkaPayOptions);
|
|
805
|
+
/** Liveness check (also confirms your key works). */
|
|
806
|
+
ping(country?: string): Promise<PingResult>;
|
|
807
|
+
/** Current merchant + API application details (scopes, operator permissions). */
|
|
808
|
+
me(country?: string): Promise<MeResult>;
|
|
809
|
+
/** Safe summary for `JSON.stringify` — never includes the API key. */
|
|
810
|
+
toJSON(): Record<string, unknown>;
|
|
811
|
+
}
|
|
812
|
+
|
|
813
|
+
/** SDK version — kept in sync with `package.json`. */
|
|
814
|
+
declare const VERSION = "2.0.0";
|
|
815
|
+
|
|
816
|
+
/** Name of the HTTP header that carries the signature (header names are case-insensitive). */
|
|
817
|
+
declare const WEBHOOK_SIGNATURE_HEADER = "Barkapay-Signature";
|
|
818
|
+
declare const DEFAULT_TOLERANCE_SECONDS = 300;
|
|
819
|
+
/** The raw request body: the exact bytes received, as a string or a `Buffer` / `Uint8Array`. */
|
|
820
|
+
type WebhookPayload = string | Uint8Array;
|
|
821
|
+
/**
|
|
822
|
+
* The signature header value. `string[]` and `undefined` are accepted so that
|
|
823
|
+
* `req.headers['barkapay-signature']` can be passed as is.
|
|
824
|
+
*/
|
|
825
|
+
type WebhookSignatureHeader = string | readonly string[] | null | undefined;
|
|
826
|
+
/**
|
|
827
|
+
* Verify the `Barkapay-Signature` header of an incoming webhook.
|
|
828
|
+
*
|
|
829
|
+
* The header is `t=<unix_ts>,v1=<hex>` where `v1 = HMAC-SHA256("{t}.{rawBody}")`
|
|
830
|
+
* keyed with your endpoint secret (`whsec_…`).
|
|
831
|
+
*
|
|
832
|
+
* ⚠️ `payload` MUST be the raw request body, byte for byte. A body that was
|
|
833
|
+
* parsed and re-serialised (`express.json()` then `JSON.stringify(req.body)`)
|
|
834
|
+
* does not have the same bytes and will never verify — see the README.
|
|
835
|
+
*
|
|
836
|
+
* @returns `true` when the signature is valid, `false` otherwise.
|
|
837
|
+
* @throws {ConfigurationError} when called with a parsed body, without a secret
|
|
838
|
+
* or with a tolerance that is not a positive number of seconds.
|
|
839
|
+
*/
|
|
840
|
+
declare function verifyWebhookSignature(payload: WebhookPayload, signatureHeader: WebhookSignatureHeader, secret: string, toleranceSeconds?: number): boolean;
|
|
841
|
+
/**
|
|
842
|
+
* Verify and decode the webhook body in one step.
|
|
843
|
+
*
|
|
844
|
+
* @throws {SignatureVerificationError} when the signature is missing, malformed,
|
|
845
|
+
* stale or wrong, or when the body is not a JSON object.
|
|
846
|
+
* @throws {ConfigurationError} when called with a parsed body or without a secret.
|
|
847
|
+
*/
|
|
848
|
+
declare function parseWebhook(payload: WebhookPayload, signatureHeader: WebhookSignatureHeader, secret: string, toleranceSeconds?: number): WebhookEvent;
|
|
849
|
+
|
|
850
|
+
/**
|
|
851
|
+
* Base class for every error the SDK throws — catch this to trap anything from
|
|
852
|
+
* the SDK in one place.
|
|
853
|
+
*/
|
|
854
|
+
declare class BarkaPayError extends Error {
|
|
855
|
+
constructor(message: string, options?: {
|
|
856
|
+
cause?: unknown;
|
|
857
|
+
});
|
|
858
|
+
}
|
|
859
|
+
/** The SDK was constructed or called with invalid arguments. */
|
|
860
|
+
declare class ConfigurationError extends BarkaPayError {
|
|
861
|
+
}
|
|
862
|
+
/**
|
|
863
|
+
* The HTTP request never produced a usable response (DNS, connection reset,
|
|
864
|
+
* timeout, body cut mid-stream).
|
|
865
|
+
*
|
|
866
|
+
* ⚠️ For a request that moves money (`payments.create`, `transfers.create`,
|
|
867
|
+
* `payments.confirmOtp`) this does NOT mean "nothing happened": the API may
|
|
868
|
+
* have processed it. Look the operation up by your order id
|
|
869
|
+
* (`list({ order_id })`) before sending it again.
|
|
870
|
+
*/
|
|
871
|
+
declare class NetworkError extends BarkaPayError {
|
|
872
|
+
/** `true` when the SDK gave up because `timeoutMs` elapsed. */
|
|
873
|
+
readonly timedOut: boolean;
|
|
874
|
+
/**
|
|
875
|
+
* The `X-Request-Id` the SDK sent with the request — quote it to support to
|
|
876
|
+
* find out whether the request reached the API.
|
|
877
|
+
*/
|
|
878
|
+
readonly requestId: string | null;
|
|
879
|
+
constructor(message: string, options?: {
|
|
880
|
+
cause?: unknown;
|
|
881
|
+
timedOut?: boolean;
|
|
882
|
+
requestId?: string | null;
|
|
883
|
+
});
|
|
884
|
+
}
|
|
885
|
+
/** A webhook signature could not be verified (bad/stale/malformed/invalid JSON). */
|
|
886
|
+
declare class SignatureVerificationError extends BarkaPayError {
|
|
887
|
+
}
|
|
888
|
+
interface ApiErrorContext {
|
|
889
|
+
code?: string;
|
|
890
|
+
httpStatus?: number;
|
|
891
|
+
requestId?: string | null;
|
|
892
|
+
errors?: Record<string, unknown>;
|
|
893
|
+
/** The `data` member of the error envelope, when the API sends one. */
|
|
894
|
+
data?: Record<string, unknown> | null;
|
|
895
|
+
/** Seconds to wait before retrying, from the `Retry-After` response header. */
|
|
896
|
+
retryAfter?: number | null;
|
|
897
|
+
/** Response headers the SDK keeps (lower-cased names). */
|
|
898
|
+
headers?: Record<string, string>;
|
|
899
|
+
}
|
|
900
|
+
/**
|
|
901
|
+
* Base class for every error returned by the barkapay API (any response with
|
|
902
|
+
* the standard error envelope or a non-2xx status). Subclasses map the most
|
|
903
|
+
* common cases so you can catch them precisely.
|
|
904
|
+
*/
|
|
905
|
+
declare class ApiError extends BarkaPayError {
|
|
906
|
+
/** Machine-readable code from the envelope (e.g. `validation_error`). */
|
|
907
|
+
readonly code: string;
|
|
908
|
+
readonly httpStatus: number;
|
|
909
|
+
/** Correlation id echoed by the API — quote it to support. */
|
|
910
|
+
readonly requestId: string | null;
|
|
911
|
+
/** Field-level details (validation): `{ field: [messages] }`. */
|
|
912
|
+
readonly errors: Record<string, unknown>;
|
|
913
|
+
/**
|
|
914
|
+
* The `data` member of the error envelope. A payment or transfer the
|
|
915
|
+
* operator refused comes back here as a `FAILED` snapshot — see
|
|
916
|
+
* {@link ApiError.payment} / {@link ApiError.transfer}.
|
|
917
|
+
*/
|
|
918
|
+
readonly data: Record<string, unknown> | null;
|
|
919
|
+
/** Seconds to wait before retrying (`Retry-After` header), when the API says so. */
|
|
920
|
+
readonly retryAfter: number | null;
|
|
921
|
+
/**
|
|
922
|
+
* Response headers, lower-cased names: `retry-after`, `x-request-id`,
|
|
923
|
+
* `x-ratelimit-limit`, `x-ratelimit-remaining` (when the API sent them).
|
|
924
|
+
*/
|
|
925
|
+
readonly headers: Record<string, string>;
|
|
926
|
+
constructor(message: string, context?: ApiErrorContext);
|
|
927
|
+
/**
|
|
928
|
+
* The payment snapshot carried by the error, if any. Present when a payment
|
|
929
|
+
* was created and then refused (`payment_failed`, `operator_unavailable`…):
|
|
930
|
+
* it holds the `publicId`, the `FAILED` status and the `reasonCode`.
|
|
931
|
+
*/
|
|
932
|
+
get payment(): Payment | null;
|
|
933
|
+
/** The transfer snapshot carried by the error, if any (see {@link ApiError.payment}). */
|
|
934
|
+
get transfer(): Transfer | null;
|
|
935
|
+
/** Build the most specific exception for an error envelope. */
|
|
936
|
+
static fromEnvelope(httpStatus: number, envelope: Record<string, unknown>, fallbackRequestId?: string | null, retryAfter?: number | null, headers?: Record<string, string>): ApiError;
|
|
937
|
+
}
|
|
938
|
+
/** 401 — bad credentials. */
|
|
939
|
+
declare class AuthenticationError extends ApiError {
|
|
940
|
+
}
|
|
941
|
+
/** 403/410/451 — not allowed (scope, IP allowlist, suspended or closed merchant). */
|
|
942
|
+
declare class AuthorizationError extends ApiError {
|
|
943
|
+
}
|
|
944
|
+
/** 422 (or 400 for an unreadable body) — the request is invalid; `errors` holds the field → messages map. */
|
|
945
|
+
declare class ValidationError extends ApiError {
|
|
946
|
+
}
|
|
947
|
+
/** 404 — resource (or country, or endpoint) not found. */
|
|
948
|
+
declare class NotFoundError extends ApiError {
|
|
949
|
+
}
|
|
950
|
+
/** 409 — duplicate (`order.unique`, or the same transfer sent again within 60 seconds). */
|
|
951
|
+
declare class ConflictError extends ApiError {
|
|
952
|
+
}
|
|
953
|
+
/**
|
|
954
|
+
* 429 — rate limited; the request was NOT executed. `retryAfter` says how long
|
|
955
|
+
* to wait; `headers['x-ratelimit-limit']` / `headers['x-ratelimit-remaining']`
|
|
956
|
+
* carry the budget.
|
|
957
|
+
*/
|
|
958
|
+
declare class RateLimitError extends ApiError {
|
|
959
|
+
}
|
|
960
|
+
/** 400 `insufficient_balance` — your barkapay balance does not cover the transfer and its fees. */
|
|
961
|
+
declare class InsufficientBalanceError extends ApiError {
|
|
962
|
+
}
|
|
963
|
+
/**
|
|
964
|
+
* 424 `payment_failed` — the payer or the operator definitively refused the
|
|
965
|
+
* payment. Final for this attempt: do not retry it as is. `payment` holds the
|
|
966
|
+
* `FAILED` snapshot with its `reasonCode`.
|
|
967
|
+
*/
|
|
968
|
+
declare class PaymentFailedError extends ApiError {
|
|
969
|
+
}
|
|
970
|
+
/**
|
|
971
|
+
* 424 `transfer_failed` — the operator definitively refused the transfer.
|
|
972
|
+
* Final for this attempt. `transfer` holds the `FAILED` snapshot.
|
|
973
|
+
*/
|
|
974
|
+
declare class TransferFailedError extends ApiError {
|
|
975
|
+
}
|
|
976
|
+
/**
|
|
977
|
+
* 503 — `service_unavailable` or `operator_unavailable`.
|
|
978
|
+
*
|
|
979
|
+
* ⚠️ On `payments.create` / `transfers.create` the operation may already
|
|
980
|
+
* exist (`payment` / `transfer` then holds its snapshot): the SDK never
|
|
981
|
+
* re-sends those on its own.
|
|
982
|
+
*/
|
|
983
|
+
declare class ServiceUnavailableError extends ApiError {
|
|
984
|
+
}
|
|
985
|
+
/** Other 5xx — server error (`internal_error`, `external_service_error`). */
|
|
986
|
+
declare class ServerError extends ApiError {
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
export { type AmountOperator, ApiError, type ApiErrorContext, AuthenticationError, AuthorizationError, type Balance, BalanceResource, BarkaPay, BarkaPayError, type BarkaPayOptions, type BarkaPayRequestInit, type BarkaPayResponse, type BarkaPayResponseHeaders, type CallOptions, ConfigurationError, ConflictError, DEFAULT_TOLERANCE_SECONDS, type FetchFn, InsufficientBalanceError, type KnownReasonCode, type ListFilters, type MeResult, NetworkError, NotFoundError, type OperatorInfo, type OperatorServiceAvailability, Operators, type OperatorsAvailability, type OperatorsInfo, type OrderParams, PAYMENT_LINK_STATUSES, PAYMENT_STATUSES, type Pagination, type Payment, type PaymentCreateParams, PaymentFailedError, type PaymentLink, type PaymentLinkAmount, type PaymentLinkCollectMode, type PaymentLinkCreateParams, type PaymentLinkList, type PaymentLinkListParams, type PaymentLinkPaymentList, type PaymentLinkPaymentListParams, type PaymentLinkStats, type PaymentLinkStatus, type PaymentLinkSummary, type PaymentLinkUpdateParams, PaymentLinks, type PaymentList, type PaymentListParams, type PaymentStatus, type PaymentWebhookEvent, Payments, type PingResult, REASON_CODES, RateLimitError, type ReasonCode, ServerError, ServiceUnavailableError, SignatureVerificationError, TRANSFER_STATUSES, type Transfer, type TransferCreateParams, TransferFailedError, type TransferList, type TransferListParams, type TransferStatus, type TransferWebhookEvent, Transfers, VERSION, ValidationError, WEBHOOK_SIGNATURE_HEADER, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeader, isPaymentStatusFinal, isTransferStatusFinal, parseWebhook, verifyWebhookSignature };
|