@isroilov_an/paylov 0.0.1

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.
@@ -0,0 +1,1620 @@
1
+ /**
2
+ * Gateway error codes the SDK knows. The groups say what a caller does about a code; no class or
3
+ * behavior is keyed by group.
4
+ */
5
+ type PaylovKnownErrorCode = "invalid_grant" | "invalid_client" | "invalid_request" | "unsupported_grant_type" | "invalid_token" | "invalid_or_expired" | "permission_denied" | "ip_not_allowed" | "validation_error" | "field_required" | "field_not_valid" | "method_not_allowed" | "not_found" | "payload_too_large" | "rate_limit_exceeded" | "server_error" | "card_not_found" | "card_not_match" | "card_exists" | "card_expired" | "card_is_blocked" | "card_is_blocked_in_processing_center" | "card_temporarily_blocked" | "card_not_active" | "card_is_not_supported" | "card_is_already_activated" | "card_is_not_for_this_check" | "card_not_found_in_processing_center" | "balance_refresh_error" | "invalid_card" | "invalid_card_token" | "pan_not_valid" | "lost_card" | "stolen_card" | "card_captured" | "restricted_card" | "error_create_card" | "sms_not_active" | "phone_not_match" | "card_phone_not_linked" | "card_has_no_phone" | "pinfl_not_match" | "link_expired" | "link_already_used" | "invalid_otp" | "otp_expired" | "try_new_otp" | "otp_code_already_sent" | "incorrect_pin" | "pin_attempts_exceeded" | "too_many_attempts" | "insufficient_funds" | "invalid_amount" | "limit_exceeded" | "daily_limit_used_for_this_card" | "insufficient_deposit" | "do_not_honor" | "call_issuer" | "transaction_not_permitted" | "duplicate_transaction" | "issuer_unavailable" | "invalid_merchant" | "merchant_not_available" | "processing_error" | "error_at_pay" | "unknown_error" | "transaction_not_found" | "transaction_already_payed" | "already_confirmed" | "transaction_not_available_for_payment" | "transaction_not_available_for_cancel" | "receipt_not_available_for_operation" | "external_id_already_exists" | "hold_not_found" | "hold_time_expired" | "bank_not_found" | "ofd_commitent_or_subcommission_not_active" | "ofd_check_already_generated" | "ofd_too_many_requests_for_this_receipt" | "ofd_check_not_found" | "ofd_error" | "fiscal_receipt_not_generated" | "split_already_done" | "split_not_found" | "recipient_not_found" | "receipt_not_available_for_split" | "sub_merchant_already_created" | "gateway_not_working" | "terminal_does_not_exist" | "service_not_found";
6
+ /** Known codes autocomplete; unknown codes still type-check because the gateway may add codes. */
7
+ type PaylovErrorCode = PaylovKnownErrorCode | (string & {});
8
+ /** Per-call options accepted by every SDK method that performs I/O. */
9
+ interface PaylovCallOptions {
10
+ /**
11
+ * Aborts the call with `PaylovConnectionError` `sdk_aborted`. Once a request was sent
12
+ * (`isSent`), the outcome of a POST is unknown, like any connection error. A shared token grant
13
+ * other calls wait on is never cancelled by one caller's abort.
14
+ */
15
+ readonly signal?: AbortSignal;
16
+ }
17
+ /** A JSON value as it travels on the wire. */
18
+ type PaylovJsonValue = string | number | boolean | null | readonly PaylovJsonValue[] | PaylovJsonObject;
19
+ /** A JSON object, such as merchant-owned `account` data. */
20
+ interface PaylovJsonObject {
21
+ readonly [key: string]: PaylovJsonValue;
22
+ }
23
+ /** The subset of `fetch` the SDK uses. Injectable so tests never touch the network. */
24
+ type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
25
+ /** The HTTP methods the gateway's endpoints use. */
26
+ type PaylovHttpMethod = "GET" | "POST" | "DELETE";
27
+ /** Request metadata. Bodies, headers, query values and path identifiers are never logged. */
28
+ interface PaylovLoggerRequestEvent {
29
+ readonly method: PaylovHttpMethod;
30
+ /** Static identity such as `"POST /merchant/oauth2/token/"`, without identifiers. */
31
+ readonly endpoint: string;
32
+ /** 1-based; a retry and a re-authentication replay both increment it. */
33
+ readonly attempt: number;
34
+ }
35
+ /**
36
+ * Closes every attempt that `onRequest` opened. An attempt without a complete response has
37
+ * `httpStatus` `0` and `errorCode` `sdk_timeout`, `sdk_network_error` or `sdk_aborted`, or
38
+ * `sdk_client_closed` when the client closed before the request was sent.
39
+ */
40
+ interface PaylovLoggerResponseEvent extends PaylovLoggerRequestEvent {
41
+ readonly httpStatus: number;
42
+ readonly durationMs: number;
43
+ /** The validated gateway `error.code` when the body carried one, or the SDK's own code. */
44
+ readonly errorCode?: PaylovErrorCode;
45
+ }
46
+ /** Metadata-only observability. Hook failures are discarded and async hooks are not awaited. */
47
+ interface PaylovLogger {
48
+ onRequest?(event: PaylovLoggerRequestEvent): void | Promise<void>;
49
+ onResponse?(event: PaylovLoggerResponseEvent): void | Promise<void>;
50
+ }
51
+ /** The transport options every network surface's configuration shares. */
52
+ interface PaylovTransportConfig {
53
+ /**
54
+ * Integer milliseconds in [1, 2147483647], default 30000. Bounds each HTTP attempt (fetch and
55
+ * body read), token requests included, not the whole call. Pass a `signal` to bound a call.
56
+ */
57
+ readonly timeoutMs?: number;
58
+ /** Defaults to `globalThis.fetch`. Injected in tests and behind proxies. */
59
+ readonly fetch?: FetchLike;
60
+ /** Observability hooks. Events contain metadata only; hook failures are discarded. */
61
+ readonly logger?: PaylovLogger;
62
+ }
63
+ /**
64
+ * Optional OTP SMS settings, forwarded to Paylov unchanged. Paylov does not document what they
65
+ * change; its test environment behaved the same with and without them.
66
+ */
67
+ interface OtpSmsSettings {
68
+ readonly hash?: string;
69
+ /** An integer; Paylov answers `validation_error` otherwise. */
70
+ readonly templateId?: number;
71
+ }
72
+ /**
73
+ * Card network as Paylov reports it. Casing differs between endpoints (the Card Bind docs show
74
+ * `uzcard`), so compare case-insensitively.
75
+ */
76
+ type CardVendor = "Uzcard" | "Humo" | "MIR" | (string & {});
77
+ /**
78
+ * Processing-center card state. `active` accompanies `isActive: true`; every other value is a
79
+ * block, capture or pending state. The list is open: never match it exhaustively.
80
+ */
81
+ type CardProcessingStatus = "active" | "call_issuer" | "warm_card" | "do_not_honor" | "honor_with_id" | "not_permitted" | "lost_card_capture" | "stolen_card_capture" | "call_security_capture" | "invalid_card_capture" | "pick_up_card_special_condition" | "call_acquirer_security" | "temporary_blocked_by_user" | "pin_attempts_exceeded" | "forced_pin_change" | "credit_debts" | "unknown" | "pin_activation" | "instant_card_personification_waiting" | "fraud_prevention" | "permanent_blocked_by_client" | "temporary_blocked_by_client" | "decline_restricted_card" | "decline_card_not_effective" | "pick_up_restricted_card" | "pick_up_special_conditions" | "pick_up_lost_card" | "pick_up_stolen_card" | "decline_card_not_active_at_bank_will" | "decline_card_not_active_at_cardholder_will" | (string & {});
82
+ /** Processing center handling a card. Compare case-insensitively; the list is open. */
83
+ type CardProcessing = "Uzcard" | "Humo" | (string & {});
84
+ /** A card bound to a merchant user. The card expiry is card data and is not surfaced. */
85
+ interface Card {
86
+ /** Paylov card id; payments and holds charge it. */
87
+ readonly cardId: string;
88
+ /** The merchant user id the card is bound to. */
89
+ readonly userId: string;
90
+ /** Cardholder name from the processing center. Personal data: keep it out of logs. */
91
+ readonly holderName: string;
92
+ /** Merchant-assigned display name; `null` when none was given. */
93
+ readonly cardName: string | null;
94
+ /** First 4 to 6 digits, a `*` mask and the last 4, e.g. `860000******0000`. Never a full PAN. */
95
+ readonly maskedCardNumber: string;
96
+ /** Card balance in tiyin, refreshed from the processing center by `cards.get`. */
97
+ readonly balanceTiyin: number;
98
+ /** Issuing bank id; numeric-looking but a string. */
99
+ readonly bankId: string;
100
+ /** Issuing bank name; `null` when the gateway omits it. */
101
+ readonly bankName: string | null;
102
+ readonly vendor: CardVendor;
103
+ readonly processing: CardProcessing;
104
+ /** The usable flag from the processing center: a card that is not active cannot be charged. */
105
+ readonly isActive: boolean;
106
+ /** The processing center's card state: why the card is not active, or `active` when it is. */
107
+ readonly processingStatus: CardProcessingStatus;
108
+ /** Whether SMS notifications are enabled; without them no OTP reaches the cardholder. */
109
+ readonly isSmsEnabled: boolean;
110
+ }
111
+ /** Parameters for `cards.createBindLink`. */
112
+ interface CreateBindLinkParams {
113
+ /** The merchant's own user id the card will be bound to. */
114
+ readonly userId: string;
115
+ /** Absolute http(s) URL the Card Bind page may redirect to when it finishes. */
116
+ readonly returnUrl?: string;
117
+ }
118
+ /** A one-time Card Bind link for one card, valid for about 20 minutes. */
119
+ interface CardBindLinkCreated {
120
+ /**
121
+ * Identifies the session in `cards.getBindSession` and the bind webhook. It works like a
122
+ * credential for the bind page: keep it, and `bindUrl`, which embeds it, out of logs.
123
+ */
124
+ readonly token: string;
125
+ /** The Paylov page to open in a webview, exactly as the gateway returned it. */
126
+ readonly bindUrl: string;
127
+ readonly expiresAt: Date;
128
+ }
129
+ /** Parameters for `cards.getBindSession`. */
130
+ interface GetBindSessionParams {
131
+ /** The `token` from `cards.createBindLink` or the bind webhook. */
132
+ readonly token: string;
133
+ }
134
+ /** `created`: nothing entered yet; `card_pending`: waiting for the SMS code; `confirmed`: bound. */
135
+ type CardBindStatus = "created" | "card_pending" | "confirmed" | (string & {});
136
+ /** A session whose card is bound. */
137
+ interface BoundCardBindSession {
138
+ readonly isBound: true;
139
+ readonly status: "confirmed";
140
+ readonly card: Card;
141
+ }
142
+ /** A session without a card yet. `status` is never `confirmed` here. */
143
+ interface PendingCardBindSession {
144
+ readonly isBound: false;
145
+ readonly status: CardBindStatus;
146
+ readonly card: null;
147
+ }
148
+ /** Result of `cards.getBindSession`; branch on `isBound`. */
149
+ type CardBindSession = BoundCardBindSession | PendingCardBindSession;
150
+ /** Parameters for `cards.startPanBinding`. */
151
+ interface StartPanBindingParams {
152
+ /** The merchant's own user id the card will be bound to. */
153
+ readonly userId: string;
154
+ /**
155
+ * Full card number. PCI scope; never logged and never placed in errors by the SDK. Paylov
156
+ * answers `validation_error` below 16 characters and `card_not_found` for an unknown card.
157
+ */
158
+ readonly cardNumber: string;
159
+ /** Card expiry as `YYMM`, year first; Paylov answers `validation_error` otherwise. */
160
+ readonly cardExpiry: string;
161
+ /** The phone linked to the card; when given, a different phone fails with `phone_not_match`. */
162
+ readonly phoneNumber?: string;
163
+ readonly sms?: OtpSmsSettings;
164
+ }
165
+ /** Result of `cards.startPanBinding`: the OTP was sent; the card is unusable until confirmed. */
166
+ interface PanBindingStarted {
167
+ /** The card id to confirm; the same id identifies the card once confirmed. */
168
+ readonly cardId: string;
169
+ /**
170
+ * The masked phone the processing center sent the OTP to, for display. The mask differs
171
+ * between sources, so treat it as an opaque string; it is still personal data.
172
+ */
173
+ readonly otpSentPhone: string;
174
+ }
175
+ /** Parameters for `cards.confirmPanBinding`. */
176
+ interface ConfirmPanBindingParams {
177
+ /** The `cardId` from `cards.startPanBinding`. */
178
+ readonly cardId: string;
179
+ /** The SMS code the cardholder received. Never logged. */
180
+ readonly otp: string;
181
+ /** Display name stored with the card. */
182
+ readonly cardName?: string;
183
+ /**
184
+ * Cardholder PINFL, 14 characters, else `validation_error`; a mismatch fails with
185
+ * `pinfl_not_match`. Personal data.
186
+ */
187
+ readonly pinfl?: string;
188
+ }
189
+ /** Parameters for `cards.get`. */
190
+ interface GetCardParams {
191
+ readonly cardId: string;
192
+ }
193
+ /** Parameters for `cards.delete`. */
194
+ interface DeleteCardParams {
195
+ readonly cardId: string;
196
+ }
197
+ /** Parameters for `cards.list`. */
198
+ interface ListCardsParams {
199
+ /** The merchant's own user id. */
200
+ readonly userId: string;
201
+ }
202
+ /** Parameters for `cards.checkPhone`. */
203
+ interface CheckCardPhoneParams {
204
+ readonly cardId: string;
205
+ /** E.g. `+998901234567`; Paylov accepts 7 to 15 characters. Personal data. */
206
+ readonly phoneNumber: string;
207
+ }
208
+ /** The `paylov.cards` namespace. Nothing here moves money. */
209
+ interface CardsResource {
210
+ /**
211
+ * Starts a Card Bind session, the preferred way to bind a card: the cardholder enters the card
212
+ * and the SMS code on a Paylov page, so the card number never reaches your servers. Open
213
+ * `bindUrl` in a webview; the result arrives through the `card.bind` webhook or
214
+ * {@link CardsResource.getBindSession}. A link binds one card and expires after about 20
215
+ * minutes. Each call creates a new link.
216
+ *
217
+ * @throws {@link PaylovApiError} `permission_denied` when Card Bind is not enabled for the
218
+ * merchant.
219
+ *
220
+ * @example
221
+ * const link = await paylov.cards.createBindLink({
222
+ * userId: 'user-42',
223
+ * returnUrl: 'https://app.example/wallet/cards',
224
+ * });
225
+ * await bindSessions.save({ userId: 'user-42', token: link.token, expiresAt: link.expiresAt });
226
+ * openWebView(link.bindUrl);
227
+ */
228
+ createBindLink(params: CreateBindLinkParams, options?: PaylovCallOptions): Promise<CardBindLinkCreated>;
229
+ /**
230
+ * Reads a Card Bind session, to recover a bind whose webhook never arrived (Paylov does not
231
+ * retry it). `isBound` is `true` exactly when the card is attached; `card` is the card as it was
232
+ * bound and stays even after the card is deleted, so read {@link CardsResource.get} for its
233
+ * current state. The token stays out of logger events.
234
+ *
235
+ * @throws {@link PaylovApiError} `link_expired` (expired or unknown token; a link that bound a
236
+ * card also answers it once expired, so check `cards.list` before offering a new link),
237
+ * `link_already_used` (a card was already bound with this link: never offer a new one).
238
+ *
239
+ * @example
240
+ * const session = await paylov.cards.getBindSession({ token: storedBindToken });
241
+ * if (session.isBound) await userCards.saveOnce(storedBindToken, session.card.cardId);
242
+ */
243
+ getBindSession(params: GetBindSessionParams, options?: PaylovCallOptions): Promise<CardBindSession>;
244
+ /**
245
+ * PCI scope: takes a full card number server-side; the SDK keeps it out of logger events and
246
+ * errors. Prefer {@link CardsResource.createBindLink}, which keeps it off your servers.
247
+ *
248
+ * Registers a card for a user and makes its processing center (Uzcard or Humo) send an OTP to
249
+ * the phone linked to the card; pass the returned `cardId` and the code to
250
+ * {@link CardsResource.confirmPanBinding}. Without SMS notifications on the card no OTP
251
+ * arrives. While the last OTP is still valid, starting again for the same user and card fails
252
+ * with `otp_code_already_sent`; after it expires, a new start sends a new OTP for the same
253
+ * `cardId`.
254
+ *
255
+ * Recovery: when the outcome is unknown, start again; an unconfirmed card is never charged.
256
+ *
257
+ * @throws {@link PaylovApiError} `card_not_found` (unknown or unsupported card number),
258
+ * `card_not_match` (wrong expiry), `phone_not_match`, `card_exists` (already bound to this
259
+ * user), `otp_code_already_sent`, `card_not_active`, `sms_not_active`, `card_has_no_phone`.
260
+ *
261
+ * @example
262
+ * const started = await paylov.cards.startPanBinding({
263
+ * userId: 'user-42',
264
+ * cardNumber: panFromSecureInput,
265
+ * cardExpiry: expiryFromSecureInput, // YYMM
266
+ * });
267
+ * showOtpPrompt(`Uzcard/Humo sent a code to ${started.otpSentPhone}`);
268
+ */
269
+ startPanBinding(params: StartPanBindingParams, options?: PaylovCallOptions): Promise<PanBindingStarted>;
270
+ /**
271
+ * Confirms a card from {@link CardsResource.startPanBinding} with the cardholder's OTP and
272
+ * returns the bound card, which can still read `isActive: false` with the reason in
273
+ * `processingStatus`: check it before charging. A wrong code, a PINFL mismatch or invalid input
274
+ * leaves the OTP usable, so the cardholder can retry. On Paylov's test environment an OTP lasts
275
+ * about 90 seconds, and the fourth wrong OTP blocks the card for about five minutes, for
276
+ * bindings and payments alike: `card_is_blocked`, with the rest of the block in
277
+ * `retryAfterSeconds`. Stop prompting before that.
278
+ *
279
+ * Recovery: when the outcome is unknown (`isPaylovOutcomeUnknown`), read
280
+ * `cards.get({ cardId })`. A repeated confirm answering `card_is_already_activated` means the
281
+ * card is already confirmed.
282
+ *
283
+ * @throws {@link PaylovApiError} `invalid_otp`, `otp_expired`, `card_is_blocked`, `try_new_otp`,
284
+ * `too_many_attempts`, `pinfl_not_match`, `card_is_already_activated`, `card_not_found`.
285
+ *
286
+ * @example
287
+ * const card = await paylov.cards.confirmPanBinding({
288
+ * cardId: started.cardId,
289
+ * otp: otpFromCardholder,
290
+ * });
291
+ * await userCards.save('user-42', card.cardId);
292
+ */
293
+ confirmPanBinding(params: ConfirmPanBindingParams, options?: PaylovCallOptions): Promise<Card>;
294
+ /**
295
+ * Reads one card with its balance and status refreshed from the processing center.
296
+ *
297
+ * @throws {@link PaylovApiError} `card_not_found` (unknown or deleted),
298
+ * `card_not_found_in_processing_center`, `card_is_blocked`,
299
+ * `card_is_blocked_in_processing_center`, `balance_refresh_error`.
300
+ *
301
+ * @example
302
+ * const card = await paylov.cards.get({ cardId: savedCardId });
303
+ * if (!card.isActive) askForAnotherCard(card.processingStatus);
304
+ */
305
+ get(params: GetCardParams, options?: PaylovCallOptions): Promise<Card>;
306
+ /**
307
+ * Lists a merchant user's bound cards; an unknown user has none. One malformed card fails the
308
+ * whole call.
309
+ *
310
+ * @example
311
+ * const cards = await paylov.cards.list({ userId: 'user-42' });
312
+ * const usable = cards.filter((card) => card.isActive);
313
+ */
314
+ list(params: ListCardsParams, options?: PaylovCallOptions): Promise<readonly Card[]>;
315
+ /**
316
+ * Unbinds a card. A repeated delete answers `card_not_found`, which means the card is already
317
+ * gone. `cards.list` and `cards.get` can still return it for a short time.
318
+ *
319
+ * @throws {@link PaylovApiError} `card_not_found`.
320
+ *
321
+ * @example
322
+ * await paylov.cards.delete({ cardId: savedCardId });
323
+ */
324
+ delete(params: DeleteCardParams, options?: PaylovCallOptions): Promise<void>;
325
+ /**
326
+ * Answers whether a phone number is the one linked to a card, as Paylov's `match` reports it.
327
+ *
328
+ * @throws {@link PaylovApiError} `card_not_found`, `permission_denied` (the check is not enabled
329
+ * for the merchant), `phone_not_match`: Paylov documents a mismatch as `false`, yet the
330
+ * development gateway answers this code for every phone, the card's own included, so it does not
331
+ * prove a mismatch.
332
+ *
333
+ * @example
334
+ * const linked = await paylov.cards.checkPhone({ cardId: savedCardId, phoneNumber: verifiedPhone });
335
+ * if (!linked) flagForReview(savedCardId);
336
+ */
337
+ checkPhone(params: CheckCardPhoneParams, options?: PaylovCallOptions): Promise<boolean>;
338
+ }
339
+ /** Fields every receipt item carries besides its `tin` or `pinfl`. */
340
+ interface FiscalReceiptItemBase {
341
+ /** Item name as it appears on the fiscal receipt. */
342
+ readonly title: string;
343
+ /**
344
+ * Integer tiyin, the price of one unit before discount. The SDK assumes a line totals
345
+ * `(priceTiyin - discountTiyin) * count`; Paylov documents no formula.
346
+ */
347
+ readonly priceTiyin: number;
348
+ /** Integer tiyin off each unit; Paylov allows at most `priceTiyin`. */
349
+ readonly discountTiyin?: number;
350
+ /** Integer quantity; Paylov answers `validation_error` below 1. */
351
+ readonly count: number;
352
+ /** IKPU classifier code of the item. */
353
+ readonly code: string;
354
+ /** Integer VAT percentage. */
355
+ readonly vatPercent: number;
356
+ /** Package-type code. */
357
+ readonly packageCode: string;
358
+ }
359
+ /** One receipt line, carrying exactly one of `tin` or `pinfl`. */
360
+ type FiscalReceiptItem = (FiscalReceiptItemBase & {
361
+ /** Taxpayer id (INN) of the commitent; Paylov documents 9 digits. */
362
+ readonly tin: string;
363
+ readonly pinfl?: undefined;
364
+ }) | (FiscalReceiptItemBase & {
365
+ /**
366
+ * Personal identification number; Paylov documents 14 digits. Personal data; never logged or
367
+ * quoted.
368
+ */
369
+ readonly pinfl: string;
370
+ readonly tin?: undefined;
371
+ });
372
+ /** The gateway transaction an operation created or acted on. */
373
+ interface TransactionReference {
374
+ /** Gateway transaction id. */
375
+ readonly transactionId: string;
376
+ }
377
+ /**
378
+ * Exactly one of the gateway `transactionId` or the merchant's own `externalId`.
379
+ *
380
+ * @example
381
+ * const byId: TransactionLookup = { transactionId };
382
+ * const byOrder: TransactionLookup = { externalId: `order-${order.id}` };
383
+ */
384
+ type TransactionLookup = {
385
+ readonly transactionId: string;
386
+ readonly externalId?: undefined;
387
+ } | {
388
+ readonly externalId: string;
389
+ readonly transactionId?: undefined;
390
+ };
391
+ /** Parameters for `fiscalization.registerReceipt` for a paid Paylov card payment. */
392
+ interface RegisterCardFiscalReceiptParams {
393
+ /** The paid Paylov transaction (UUID). */
394
+ readonly transactionId: string;
395
+ /** Receipt lines; their total must equal the transaction amount. */
396
+ readonly items: readonly FiscalReceiptItem[];
397
+ readonly externalId?: undefined;
398
+ readonly phoneNumber?: undefined;
399
+ }
400
+ /** Parameters for `fiscalization.registerReceipt` for a cash sale made outside Paylov. */
401
+ interface RegisterCashFiscalReceiptParams {
402
+ /** Your own receipt id, the key `getReceipt` reads it back by. */
403
+ readonly externalId: string;
404
+ /** The customer's phone, `+998XXXXXXXXX`. Personal data; never logged or quoted. */
405
+ readonly phoneNumber: string;
406
+ /** Receipt lines. */
407
+ readonly items: readonly FiscalReceiptItem[];
408
+ readonly transactionId?: undefined;
409
+ }
410
+ /** A card payment by `transactionId`, or a cash sale by `externalId` and `phoneNumber`. */
411
+ type RegisterFiscalReceiptParams = RegisterCardFiscalReceiptParams | RegisterCashFiscalReceiptParams;
412
+ /**
413
+ * Parameters for `fiscalization.getReceipt`: a card payment's `transactionId`, or the `externalId`
414
+ * a cash sale was registered with.
415
+ */
416
+ type GetFiscalReceiptParams = TransactionLookup & {
417
+ /**
418
+ * `true` reads the refund receipt, `false` the sale receipt. Omit it to send no filter; which
419
+ * receipt Paylov then returns for a refunded transaction is not documented.
420
+ */
421
+ readonly isRefund?: boolean;
422
+ };
423
+ /** A fiscal receipt the OFD registered. */
424
+ interface FiscalReceipt {
425
+ /** OFD receipt id; keep it with its `transactionId` or `externalId`. */
426
+ readonly receiptId: number;
427
+ /** Public receipt page on `ofd.soliq.uz`. */
428
+ readonly receiptUrl: string;
429
+ readonly terminalId: string;
430
+ readonly fiscalSign: string;
431
+ /** Whether this is a refund receipt rather than a sale receipt. */
432
+ readonly isRefund: boolean;
433
+ }
434
+ /** A receipt the OFD just registered; registration does not report `isRefund`. */
435
+ type FiscalReceiptRegistered = Omit<FiscalReceipt, "isRefund">;
436
+ /**
437
+ * Parameters for `fiscalization.attachReceipt`: a receipt the merchant fiscalized itself, for a
438
+ * paid Paylov transaction.
439
+ */
440
+ interface AttachFiscalReceiptParams {
441
+ /** The paid Paylov transaction (UUID). */
442
+ readonly transactionId: string;
443
+ /** OFD terminal id; Paylov documents at most 32 characters. */
444
+ readonly terminalId: string;
445
+ /** When the receipt was issued, `YYYYMMDDHHMMSS`, as Paylov documents it. */
446
+ readonly issuedAtRaw: string;
447
+ /** Fiscal signature; Paylov documents at most 64 characters. */
448
+ readonly fiscalSign: string;
449
+ /** The receipt's `https://ofd.soliq.uz/...` page. */
450
+ readonly receiptUrl: string;
451
+ /** OFD receipt id; Paylov answers `validation_error` for 0. */
452
+ readonly receiptId: number;
453
+ /** Your own receipt id; unique per merchant. */
454
+ readonly externalId?: string;
455
+ }
456
+ /** Parameters for `fiscalization.refundReceipt`. */
457
+ interface RefundFiscalReceiptParams {
458
+ /** The sale receipt to reverse. */
459
+ readonly receiptId: number;
460
+ }
461
+ /** The OFD refund receipt and the sale receipt it reverses. */
462
+ interface FiscalReceiptRefunded {
463
+ /** The new refund receipt. */
464
+ readonly refund: FiscalReceiptRegistered;
465
+ /** The original sale receipt; its `receiptId` is the one sent. */
466
+ readonly sale: FiscalReceiptRegistered;
467
+ }
468
+ /**
469
+ * The tax-service status to check: an individual entrepreneur (YATT), a self-employed person, or
470
+ * income above 100 million (currency and period undocumented).
471
+ */
472
+ type FiscalActivityType = "individual_entrepreneur" | "self_employed" | "high_income";
473
+ /** Parameters for `fiscalization.checkActivityType`. */
474
+ interface CheckActivityTypeParams {
475
+ /**
476
+ * The person's PINFL, 14 digits; Paylov answers `validation_error` for a shorter one. Personal
477
+ * data; never logged or quoted.
478
+ */
479
+ readonly pinfl: string;
480
+ readonly activityType: FiscalActivityType;
481
+ }
482
+ /** The tax service's answer. Its free-text `reason` is withheld. */
483
+ interface ActivityTypeCheck {
484
+ /**
485
+ * Whether the tax service confirmed the activity type, for every activity type. Paylov's examples
486
+ * do not define which answer field carries the result; this is the SDK's reading of them.
487
+ */
488
+ readonly isConfirmed: boolean;
489
+ /** `high_income` only: the activity names the tax service lists, otherwise empty. */
490
+ readonly activityNames: readonly string[];
491
+ }
492
+ /**
493
+ * The `paylov.fiscalization` namespace: OFD fiscal receipts and tax-service activity checks.
494
+ * Every method except `getReceipt` needs fiscalization enabled for the merchant; otherwise it
495
+ * fails with `permission_denied`.
496
+ */
497
+ interface FiscalizationResource {
498
+ /**
499
+ * Has Paylov register a fiscal receipt with the OFD: for a paid card payment by
500
+ * `transactionId`, or for a cash sale by `externalId` and `phoneNumber`. Moves no money. Item
501
+ * prices are integer tiyin; the lines, each `(priceTiyin - discountTiyin) * count`, must total
502
+ * the transaction amount.
503
+ *
504
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `getReceipt` before registering again;
505
+ * `null` means nothing is registered yet. `ofd_check_already_generated` on a repeated call
506
+ * means a receipt exists.
507
+ *
508
+ * @throws {@link PaylovApiError} `ofd_check_already_generated`,
509
+ * `receipt_not_available_for_operation` (not paid), `invalid_amount` (item total),
510
+ * `ofd_commitent_or_subcommission_not_active` (an item's TIN or PINFL has no active OFD
511
+ * contract), `ofd_error`, `fiscal_receipt_not_generated`, `permission_denied`.
512
+ *
513
+ * @example
514
+ * const receipt = await paylov.fiscalization.registerReceipt({
515
+ * transactionId,
516
+ * items: [
517
+ * {
518
+ * title: 'Consultation',
519
+ * priceTiyin: 25_000_000,
520
+ * count: 1,
521
+ * code: ikpuCode,
522
+ * vatPercent: 12,
523
+ * packageCode,
524
+ * tin: commitentTin,
525
+ * },
526
+ * ],
527
+ * });
528
+ * await receipts.save(transactionId, receipt.receiptId, receipt.receiptUrl);
529
+ */
530
+ registerReceipt(params: RegisterFiscalReceiptParams, options?: PaylovCallOptions): Promise<FiscalReceiptRegistered>;
531
+ /**
532
+ * Reads the receipt of a card payment by `transactionId`, or of a cash sale by the `externalId`
533
+ * it was registered with. Resolves `null` when no receipt is found for the transaction or the
534
+ * `externalId`; the OFD may register one later, so `null` is an observation, not proof. Moves
535
+ * no money and works without fiscalization enabled.
536
+ *
537
+ * @throws {@link PaylovApiError} `transaction_not_found` for an unknown `transactionId`.
538
+ *
539
+ * @example
540
+ * const receipt = await paylov.fiscalization.getReceipt({ transactionId, isRefund: false });
541
+ * if (receipt !== null) await receipts.save(transactionId, receipt.receiptId, receipt.receiptUrl);
542
+ */
543
+ getReceipt(params: GetFiscalReceiptParams, options?: PaylovCallOptions): Promise<FiscalReceipt | null>;
544
+ /**
545
+ * Attaches a receipt you fiscalized yourself to a paid Paylov transaction; nothing is sent to
546
+ * the OFD. Moves no money. Needs fiscalization in client-side mode, otherwise
547
+ * `permission_denied`.
548
+ *
549
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `getReceipt` before attaching again;
550
+ * `ofd_check_already_generated` on a repeated call means a receipt is attached.
551
+ *
552
+ * @throws {@link PaylovApiError} `ofd_check_already_generated`, `field_not_valid` (`fields`
553
+ * names the wire field `transactionId`, `dateTime` for `issuedAtRaw`, or `qrCodeUrl` for
554
+ * `receiptUrl`), `external_id_already_exists`,
555
+ * `transaction_not_found`, `receipt_not_available_for_operation`,
556
+ * `ofd_too_many_requests_for_this_receipt`, `permission_denied`.
557
+ *
558
+ * @example
559
+ * await paylov.fiscalization.attachReceipt({
560
+ * transactionId,
561
+ * terminalId: ofdReceipt.terminalId,
562
+ * issuedAtRaw: '20260915143025',
563
+ * fiscalSign: ofdReceipt.fiscalSign,
564
+ * receiptUrl: ofdReceipt.receiptUrl,
565
+ * receiptId: ofdReceipt.receiptId,
566
+ * });
567
+ */
568
+ attachReceipt(params: AttachFiscalReceiptParams, options?: PaylovCallOptions): Promise<void>;
569
+ /**
570
+ * Registers an OFD refund receipt that reverses a sale receipt. Moves no money: refund a card
571
+ * payment with `payments.refund`, which Paylov documents also cancels its fiscalization. For a
572
+ * card payment, call this only when `getReceipt({ transactionId, isRefund: true })` shows no
573
+ * refund receipt after `payments.refund`.
574
+ *
575
+ * Recovery: store each `receiptId` with its `transactionId` or `externalId`; when
576
+ * `isPaylovOutcomeUnknown(error)`, read `getReceipt({ ..., isRefund: true })` before refunding
577
+ * again.
578
+ *
579
+ * @throws {@link PaylovApiError} `ofd_check_not_found`, `ofd_error`, `permission_denied`.
580
+ *
581
+ * @example
582
+ * const { refund } = await paylov.fiscalization.refundReceipt({ receiptId: sale.receiptId });
583
+ * await receipts.saveRefund(sale.externalId, refund.receiptId, refund.receiptUrl);
584
+ */
585
+ refundReceipt(params: RefundFiscalReceiptParams, options?: PaylovCallOptions): Promise<FiscalReceiptRefunded>;
586
+ /**
587
+ * Asks the tax service whether a person has an activity type, before fiscalizing on their
588
+ * behalf. Moves no money. A negative answer may arrive as `PaylovApiError`
589
+ * `gateway_not_working` instead of `isConfirmed: false`; treat that as unconfirmed.
590
+ *
591
+ * @throws {@link PaylovApiError} `gateway_not_working`, `permission_denied`.
592
+ *
593
+ * @example
594
+ * const check = await paylov.fiscalization.checkActivityType({
595
+ * pinfl: sellerPinfl,
596
+ * activityType: 'self_employed',
597
+ * });
598
+ * if (!check.isConfirmed) await sellers.flagForReview(sellerId);
599
+ */
600
+ checkActivityType(params: CheckActivityTypeParams, options?: PaylovCallOptions): Promise<ActivityTypeCheck>;
601
+ }
602
+ /** A bank as `paylov.gateway.listBanks()` returns it. */
603
+ interface Bank {
604
+ /** The gateway's integer id as a string, so it compares equal to a card's `bankId`. */
605
+ readonly bankId: string;
606
+ /** Display name, e.g. `Hamkorbank`; may contain non-ASCII letters and backticks. */
607
+ readonly name: string;
608
+ /** `null` when Paylov has no official name for the bank. */
609
+ readonly officialName: string | null;
610
+ }
611
+ /** The `paylov.gateway` namespace. */
612
+ interface GatewayResource {
613
+ /**
614
+ * Checks that the gateway answers (`GET /merchant/status/`). It sends no token and Paylov
615
+ * validates none, so it proves neither the credentials nor the account: use it as a liveness
616
+ * probe only. Resolves for `{"status":"ok"}`; any other answer throws.
617
+ *
618
+ * @throws {@link PaylovConnectionError} when the gateway is unreachable or times out.
619
+ * @throws {@link PaylovProtocolError} `sdk_malformed_response` for any other success body.
620
+ *
621
+ * @example
622
+ * try {
623
+ * await paylov.gateway.getStatus({ signal: AbortSignal.timeout(5_000) });
624
+ * return { paylov: 'up' };
625
+ * } catch {
626
+ * return { paylov: 'down' };
627
+ * }
628
+ */
629
+ getStatus(options?: PaylovCallOptions): Promise<void>;
630
+ /**
631
+ * Lists the banks Paylov knows (`GET /merchant/bankList/`). Each `bankId` is a string that
632
+ * matches a card's `bankId`.
633
+ *
634
+ * @throws {@link PaylovApiError} `invalid_grant` when the credentials are rejected.
635
+ *
636
+ * @example
637
+ * const banks = await paylov.gateway.listBanks();
638
+ * const bankNames = new Map(banks.map((bank) => [bank.bankId, bank.officialName ?? bank.name]));
639
+ */
640
+ listBanks(options?: PaylovCallOptions): Promise<readonly Bank[]>;
641
+ }
642
+ /**
643
+ * `held` (reserved), `captured` or `released`. `held` means what it means in `TransactionStatus`,
644
+ * where a captured hold reads `paid` and an expired hold Paylov released has read `refunded`. An
645
+ * expired hold can still read `held`, so `held` alone does not prove the hold can be captured.
646
+ * Paylov also documents `created`, which has not been observed. Other values pass through
647
+ * unchanged.
648
+ */
649
+ type HoldStatus = "held" | "captured" | "released" | "created" | (string & {});
650
+ /** Parameters for `holds.create`. */
651
+ interface CreateHoldParams {
652
+ /** Your id for the cardholder. */
653
+ readonly userId: string;
654
+ /** A card bound to this merchant (UUID). */
655
+ readonly cardId: string;
656
+ /**
657
+ * The amount to reserve, a multiple of 100: the wire takes whole SUM. Paylov answers
658
+ * `validation_error` below 1000 (10 SUM).
659
+ */
660
+ readonly amountTiyin: number;
661
+ /**
662
+ * How long the hold lasts, in minutes. Paylov accepts 1 to 40320 (28 days): 0 answers
663
+ * `validation_error`, more answers `field_not_valid`.
664
+ */
665
+ readonly durationMinutes: number;
666
+ /**
667
+ * Your reference for this hold, unique per merchant; Paylov answers `validation_error` above
668
+ * 64 characters. It is the key that finds the hold again with `holds.get({ externalId })` after
669
+ * an ambiguous failure.
670
+ */
671
+ readonly externalId: string;
672
+ /** Merchant data sent with the hold. */
673
+ readonly account?: PaylovJsonObject;
674
+ /** An existing Paylov service (UUID); the gateway defaults to the merchant itself. */
675
+ readonly serviceId?: string;
676
+ }
677
+ /** Parameters for `holds.capture`. */
678
+ interface CaptureHoldParams {
679
+ readonly transactionId: string;
680
+ /**
681
+ * The amount to capture, a multiple of 100, up to the held amount. A smaller amount is a
682
+ * partial capture; it ends the hold. Paylov answers `validation_error` below 1000 (10 SUM) and
683
+ * `invalid_amount` above the held amount.
684
+ */
685
+ readonly amountTiyin: number;
686
+ }
687
+ /** Result of `holds.capture`. */
688
+ interface HoldCaptured extends TransactionReference {
689
+ /** The card that was charged. */
690
+ readonly cardId: string;
691
+ /** When the capture happened (sent in UTC). */
692
+ readonly capturedAt: Date;
693
+ }
694
+ /** Parameters for `holds.release`. */
695
+ interface ReleaseHoldParams {
696
+ readonly transactionId: string;
697
+ }
698
+ /** Parameters for `holds.get`: exactly one of `transactionId` or `externalId`. */
699
+ type GetHoldParams = TransactionLookup;
700
+ /** A hold as `holds.get` reports it. */
701
+ interface Hold {
702
+ readonly transactionId: string;
703
+ readonly status: HoldStatus;
704
+ /**
705
+ * The held amount while `held` or `released`; the captured amount once `captured`. Keep the
706
+ * original held amount yourself: after a partial capture it is no longer reported.
707
+ */
708
+ readonly amountTiyin: number;
709
+ /** When the hold was captured (sent in UTC); `null` until then. */
710
+ readonly capturedAt: Date | null;
711
+ /**
712
+ * When Paylov reports the hold released (sent in UTC): after `holds.release`, or after a capture
713
+ * of an expired hold failed with `hold_time_expired`. `null` otherwise; expiry alone has not
714
+ * been seen to set it.
715
+ */
716
+ readonly releasedAt: Date | null;
717
+ /** The service the hold belongs to: the one sent on create, or the merchant id. */
718
+ readonly serviceId: string;
719
+ }
720
+ /**
721
+ * The `paylov.holds` namespace: reserve funds on a bound card with `create`, then either
722
+ * `capture` them once or `release` them before the hold runs out. Paylov sends no hold webhook,
723
+ * so reconcile open holds by polling `get`.
724
+ */
725
+ interface HoldsResource {
726
+ /**
727
+ * Reserves `amountTiyin` on a bound card for `durationMinutes`. Money is reserved, not
728
+ * captured.
729
+ *
730
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, the hold may exist. Read
731
+ * `holds.get({ externalId })`; a hold found is the result. `null` is not proof that the
732
+ * create did not run: read again after a delay, then call `create` again with the same
733
+ * `externalId`. A repeat answers `external_id_already_exists` when the hold exists.
734
+ *
735
+ * @throws {@link PaylovApiError} `insufficient_funds` or another card decline,
736
+ * `external_id_already_exists`, `card_not_found` (unknown or deleted card), `service_not_found`.
737
+ *
738
+ * @example
739
+ * const hold = await paylov.holds.create({
740
+ * userId: booking.customerId,
741
+ * cardId: booking.cardId,
742
+ * amountTiyin: 150_000, // 1 500.00 SUM
743
+ * durationMinutes: 24 * 60,
744
+ * externalId: `booking-${booking.id}`,
745
+ * });
746
+ * await bookings.saveHold(booking.id, hold.transactionId);
747
+ */
748
+ create(params: CreateHoldParams, options?: PaylovCallOptions): Promise<TransactionReference>;
749
+ /**
750
+ * Captures a hold: **this moves money.** Capture is single-use. An amount below the held
751
+ * amount is a partial capture and ends the hold: the remainder can be neither captured nor
752
+ * released afterwards. Paylov does not document what happens to it; the SDK assumes Paylov and
753
+ * the card's bank return it to the cardholder. After the hold's duration runs out, capture fails
754
+ * with `hold_time_expired`, and Paylov's test environment then reported the hold `released`.
755
+ *
756
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `holds.get({ transactionId })` before
757
+ * anything else: `captured` means the capture happened and `amountTiyin` is the captured amount.
758
+ * Never capture again blindly; a repeat answers `transaction_not_available_for_payment` once
759
+ * the hold is captured or released.
760
+ *
761
+ * @throws {@link PaylovApiError} `invalid_amount` (more than the held amount),
762
+ * `transaction_not_available_for_payment` (already captured, released, or not a hold),
763
+ * `hold_time_expired`, `transaction_not_found`.
764
+ *
765
+ * @example
766
+ * const captured = await paylov.holds.capture({
767
+ * transactionId: booking.holdTransactionId,
768
+ * amountTiyin: 150_000,
769
+ * });
770
+ * await bookings.markPaid(booking.id, captured.capturedAt);
771
+ */
772
+ capture(params: CaptureHoldParams, options?: PaylovCallOptions): Promise<HoldCaptured>;
773
+ /**
774
+ * Releases an uncaptured hold in full; moves no money. It cannot undo a capture: after one,
775
+ * only `payments.refund` remains, and Paylov's test environment refuses it for a captured hold
776
+ * with `processing_error`. Release every hold you will not capture, also after its duration runs
777
+ * out. Release is the only documented way to free a hold, so the SDK reads `hold_not_found`
778
+ * then as nothing left to release.
779
+ *
780
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `holds.get({ transactionId })`: status
781
+ * `released` means the release took effect.
782
+ *
783
+ * @throws {@link PaylovApiError} `hold_not_found` (already released, captured, or expired).
784
+ *
785
+ * @example
786
+ * await paylov.holds.release({ transactionId: booking.holdTransactionId });
787
+ */
788
+ release(params: ReleaseHoldParams, options?: PaylovCallOptions): Promise<TransactionReference>;
789
+ /**
790
+ * Looks a hold up by exactly one of `transactionId` or `externalId`; `null` when the gateway
791
+ * knows no such hold (`transaction_not_found`). A miss right after an ambiguous `create` is not
792
+ * proof: read again after a delay. An expired hold can still read `held`: track its deadline
793
+ * (creation time plus `durationMinutes`) yourself.
794
+ *
795
+ * @example
796
+ * const hold = await paylov.holds.get({ externalId: `booking-${booking.id}` });
797
+ * if (hold === null) await retryCreateLater(booking.id);
798
+ * else if (hold.status === 'captured') await bookings.markPaid(booking.id, hold.capturedAt);
799
+ */
800
+ get(params: GetHoldParams, options?: PaylovCallOptions): Promise<Hold | null>;
801
+ }
802
+ /** Parameters for `payments.create`. */
803
+ interface CreatePaymentParams {
804
+ /**
805
+ * A multiple of 100: the wire takes whole SUM. Paylov answers `field_not_valid` for 0 or an
806
+ * amount out of its range.
807
+ */
808
+ readonly amountTiyin: number;
809
+ /**
810
+ * Merchant data stored with the transaction. Transaction reads do not return it, so keep your
811
+ * own mapping from order to transaction.
812
+ */
813
+ readonly account?: PaylovJsonObject;
814
+ /** Your id for the payer. When omitted, `pay` sets it. */
815
+ readonly userId?: string;
816
+ }
817
+ /** Parameters for `payments.pay`. */
818
+ interface PayPaymentParams {
819
+ /** From `payments.create`. */
820
+ readonly transactionId: string;
821
+ /** A card bound to `userId`. */
822
+ readonly cardId: string;
823
+ /** The user the card is bound to. */
824
+ readonly userId: string;
825
+ }
826
+ /** Parameters for `payments.refund`. */
827
+ interface RefundPaymentParams {
828
+ readonly transactionId: string;
829
+ }
830
+ /** Parameters for `payments.startPanPayment`. */
831
+ interface StartPanPaymentParams {
832
+ /** Full card number. PCI scope: never log or store it. */
833
+ readonly cardNumber: string;
834
+ /**
835
+ * Card expiry as `YYMM`, year first, e.g. `2911` for November 2029; Paylov answers
836
+ * `validation_error` for `MMYY`.
837
+ */
838
+ readonly cardExpiry: string;
839
+ /** A multiple of 100: the wire takes whole SUM. Paylov answers `invalid_amount` for 0. */
840
+ readonly amountTiyin: number;
841
+ /** Merchant data stored with the transaction; transaction reads do not return it. */
842
+ readonly account?: PaylovJsonObject;
843
+ readonly sms?: OtpSmsSettings;
844
+ }
845
+ /** Parameters for `payments.confirmPanPayment`. */
846
+ interface ConfirmPanPaymentParams {
847
+ /** From `payments.startPanPayment`. */
848
+ readonly transactionId: string;
849
+ /** The code the cardholder received by SMS. */
850
+ readonly otp: string;
851
+ readonly sms?: OtpSmsSettings;
852
+ }
853
+ /** The result of `payments.refund`. */
854
+ interface PaymentRefunded extends TransactionReference {
855
+ /** When the refund happened; `transactions.get` then reads it as `cancelledAt`. */
856
+ readonly refundedAt: Date;
857
+ }
858
+ /**
859
+ * The result of `payments.startPanPayment`; pass its `transactionId` to
860
+ * `payments.confirmPanPayment`.
861
+ */
862
+ interface PanPaymentStarted extends TransactionReference {
863
+ /** The masked phone the card's processing center sent the OTP to, e.g. `+9989*****00`. */
864
+ readonly otpSentPhone: string;
865
+ }
866
+ /** The `paylov.payments` namespace. */
867
+ interface PaymentsResource {
868
+ /**
869
+ * Creates an unpaid payment transaction for a saved card. **No money moves**; charge it with
870
+ * {@link PaymentsResource.pay}.
871
+ *
872
+ * Each call creates a new transaction, and an unpaid one is never charged, so after any
873
+ * failure just call again.
874
+ *
875
+ * @throws {@link PaylovApiError} `field_not_valid` (an amount outside the gateway's range),
876
+ * `validation_error`.
877
+ *
878
+ * @example
879
+ * const { transactionId } = await paylov.payments.create({
880
+ * amountTiyin: 2_500_000, // 25 000.00 SUM
881
+ * account: { order_id: 'A-1024' },
882
+ * userId: 'user-42',
883
+ * });
884
+ */
885
+ create(params: CreatePaymentParams, options?: PaylovCallOptions): Promise<TransactionReference>;
886
+ /**
887
+ * Charges a saved card for a transaction from {@link PaymentsResource.create}, for the amount
888
+ * fixed there. **Moves money**; no OTP is involved. A declined charge leaves the transaction
889
+ * either `failed`, with the code in `declineCode`, which can never be paid again, or still
890
+ * `created`, which another card can pay.
891
+ *
892
+ * Recovery: after a decline or when `isPaylovOutcomeUnknown(error)`, read
893
+ * `paylov.transactions.get` before acting again; never repeat `pay` blindly. A repeated `pay`
894
+ * of a paid transaction fails with `transaction_already_payed`, of a `failed` one with
895
+ * `transaction_not_available_for_payment`. Paylov does not document whether a pay can still land
896
+ * while the status reads `created`; the SDK assumes a status that stays `created` across
897
+ * repeated reads means the pay did not take effect: pay again with the same `transactionId`,
898
+ * never a new transaction.
899
+ *
900
+ * @throws {@link PaylovApiError} `transaction_already_payed`,
901
+ * `transaction_not_available_for_payment` (refunded, failed or not payable),
902
+ * `card_is_not_for_this_check` (the card belongs to another user), `card_not_found`, and
903
+ * declines such as `insufficient_funds` and `processing_error`.
904
+ *
905
+ * @example
906
+ * await paylov.payments.pay({ transactionId, cardId, userId: 'user-42' });
907
+ */
908
+ pay(params: PayPaymentParams, options?: PaylovCallOptions): Promise<TransactionReference>;
909
+ /**
910
+ * Refunds a paid transaction **in full**; there is no partial refund. **Moves money back** to
911
+ * the card and also cancels the payment's fiscal (OFD) receipt. Release an uncaptured hold with
912
+ * `holds.release` instead.
913
+ *
914
+ * Paylov may refuse an API refund for some payment kinds: checkout and PAN payments, and on
915
+ * Paylov's test environment captured holds. Then refund from the Paylov business panel or
916
+ * through Paylov support, and confirm with `paylov.transactions.get`.
917
+ *
918
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `paylov.transactions.get`: a refunded
919
+ * transaction reads status `refunded` with `cancelledAt`. A repeated refund fails with
920
+ * `transaction_not_available_for_cancel`.
921
+ *
922
+ * @throws {@link PaylovApiError} `transaction_not_available_for_cancel` (already refunded, never
923
+ * paid, or a checkout or PAN payment), `processing_error` (a captured hold on Paylov's test
924
+ * environment), `transaction_not_found`, `permission_denied`.
925
+ *
926
+ * @example
927
+ * const { refundedAt } = await paylov.payments.refund({ transactionId });
928
+ */
929
+ refund(params: RefundPaymentParams, options?: PaylovCallOptions): Promise<PaymentRefunded>;
930
+ /**
931
+ * PCI scope: takes a full card number server-side; the SDK keeps it and the expiry out of
932
+ * logger events and errors.
933
+ *
934
+ * Starts a one-off payment by card number, without binding the card. **No money moves yet**:
935
+ * the card's processing center (Uzcard or Humo, not Paylov) sends an OTP by SMS to the phone
936
+ * linked to the card. Finish with {@link PaymentsResource.confirmPanPayment}. A card without
937
+ * SMS notifications never receives the OTP.
938
+ *
939
+ * Recovery: each call creates a new transaction and an unconfirmed one is never charged, so
940
+ * after any failure start again.
941
+ *
942
+ * @throws {@link PaylovApiError} `card_not_found` (wrong number or expiry), `invalid_amount`.
943
+ *
944
+ * @example
945
+ * const started = await paylov.payments.startPanPayment({
946
+ * cardNumber: cardNumberFromSecureInput,
947
+ * cardExpiry: cardExpiryFromSecureInput, // YYMM
948
+ * amountTiyin: 120_000, // 1 200.00 SUM
949
+ * account: { order_id: 'A-1025' },
950
+ * });
951
+ * showOtpPrompt(`Uzcard/Humo sent a code to ${started.otpSentPhone}`);
952
+ */
953
+ startPanPayment(params: StartPanPaymentParams, options?: PaylovCallOptions): Promise<PanPaymentStarted>;
954
+ /**
955
+ * Confirms a payment from {@link PaymentsResource.startPanPayment} with the cardholder's OTP.
956
+ * **Moves money.** A wrong OTP fails with `invalid_otp` and can be retried with the right one.
957
+ * On Paylov's test environment an OTP lasts about 90 seconds, and the fourth wrong OTP blocks
958
+ * the card for about five minutes, for payments and bindings alike: `card_is_blocked`, with the
959
+ * rest of the block in `retryAfterSeconds`. Stop prompting before that.
960
+ *
961
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `paylov.transactions.get` before acting
962
+ * again. A repeated confirm of a paid transaction fails with `otp_expired`, the same code as a
963
+ * really expired OTP, so only the read tells them apart.
964
+ *
965
+ * @throws {@link PaylovApiError} `invalid_otp`, `otp_expired`, `card_is_blocked`,
966
+ * `transaction_not_found`, and declines such as `insufficient_funds`.
967
+ *
968
+ * @example
969
+ * await paylov.payments.confirmPanPayment({
970
+ * transactionId: started.transactionId,
971
+ * otp: otpFromUser,
972
+ * });
973
+ */
974
+ confirmPanPayment(params: ConfirmPanPaymentParams, options?: PaylovCallOptions): Promise<TransactionReference>;
975
+ }
976
+ /** Parameters for `splits.create`. */
977
+ interface CreateSplitParams {
978
+ /** The paid Paylov transaction to split (UUID). */
979
+ readonly transactionId: string;
980
+ /**
981
+ * The amounts must add up to the transaction amount, else `invalid_amount`; Paylov answers
982
+ * `validation_error` for an empty list.
983
+ */
984
+ readonly recipients: readonly SplitRecipient[];
985
+ /**
986
+ * Sent as Paylov's `resendOFD`: resend the split to the fiscal system. Paylov says to resend when
987
+ * the response lacks fiscal data, without saying where that data appears.
988
+ */
989
+ readonly resendOfd?: boolean;
990
+ }
991
+ interface SplitRecipient {
992
+ /** Opaque recipient id issued by Paylov. */
993
+ readonly recipientId: string;
994
+ /** Integer tiyin. */
995
+ readonly amountTiyin: number;
996
+ /** Receipt lines for this recipient's share; sending them starts OFD fiscalization. */
997
+ readonly items?: readonly FiscalReceiptItem[];
998
+ }
999
+ /** Parameters for `splits.get`. */
1000
+ interface GetSplitParams {
1001
+ /** The paid transaction passed to `splits.create` (UUID). */
1002
+ readonly transactionId: string;
1003
+ }
1004
+ /** A recipient's sub-transaction status. Open: Paylov may add values. */
1005
+ type SplitRecipientStatus = "paid" | "cancelled" | "check" | (string & {});
1006
+ /** One recipient's share of a split transaction. */
1007
+ interface SplitShare {
1008
+ readonly recipientId: string;
1009
+ /** Integer tiyin. */
1010
+ readonly amountTiyin: number;
1011
+ readonly status: SplitRecipientStatus;
1012
+ /** `YYYY-MM-DD HH:MM:SS` verbatim; the time zone is undocumented. */
1013
+ readonly createdAtRaw: string;
1014
+ }
1015
+ /**
1016
+ * The `paylov.splits` namespace: divides a paid transaction among recipients. Both methods need
1017
+ * split payments enabled for the merchant; otherwise they fail with `permission_denied`.
1018
+ */
1019
+ interface SplitsResource {
1020
+ /**
1021
+ * Splits a paid transaction: each recipient receives a sub-transaction with its amount. Moves
1022
+ * money to the recipients. Amounts are integer tiyin and must add up to the transaction amount.
1023
+ * A recipient's `items` start OFD fiscalization of its share in the background.
1024
+ *
1025
+ * Recovery: when `isPaylovOutcomeUnknown(error)`, read `splits.get` before splitting again;
1026
+ * `split_already_done` on a repeated call means the split exists.
1027
+ *
1028
+ * @throws {@link PaylovApiError} `split_already_done`, `transaction_not_found`,
1029
+ * `invalid_amount` (amounts do not add up), `recipient_not_found`,
1030
+ * `ofd_commitent_or_subcommission_not_active`, `permission_denied`.
1031
+ *
1032
+ * @example
1033
+ * await paylov.splits.create({
1034
+ * transactionId,
1035
+ * recipients: [
1036
+ * { recipientId: platformRecipientId, amountTiyin: 150_000 },
1037
+ * { recipientId: sellerRecipientId, amountTiyin: 850_000 },
1038
+ * ],
1039
+ * });
1040
+ */
1041
+ create(params: CreateSplitParams, options?: PaylovCallOptions): Promise<TransactionReference>;
1042
+ /**
1043
+ * Reads every recipient's share of a split transaction. Moves no money.
1044
+ *
1045
+ * Unlike `holds.get`, a miss throws instead of returning `null`: Paylov documents
1046
+ * `split_not_found` for a transaction without a split, but that code has not been observed.
1047
+ *
1048
+ * @throws {@link PaylovApiError} `split_not_found`, `transaction_not_found`,
1049
+ * `permission_denied`.
1050
+ *
1051
+ * @example
1052
+ * const shares = await paylov.splits.get({ transactionId });
1053
+ * const unpaid = shares.filter((share) => share.status !== 'paid');
1054
+ */
1055
+ get(params: GetSplitParams, options?: PaylovCallOptions): Promise<readonly SplitShare[]>;
1056
+ }
1057
+ /** The fields of `CreateSubMerchantParams` beside its tax ids. */
1058
+ interface SubMerchantProfile {
1059
+ /** 1 to 128 characters; unique among your sub-merchants. */
1060
+ readonly name: string;
1061
+ /** Your own sub-merchant id, 1 to 64 characters; unique among your sub-merchants. */
1062
+ readonly externalId?: string;
1063
+ /** Enables the self-employed OFD service. Default `false`. */
1064
+ readonly isSelfEmployed?: boolean;
1065
+ /** Integer VAT percentage for OFD receipts, 0 to 100. */
1066
+ readonly ofdVatPercent?: number;
1067
+ /** SPIC (IKPU) classifier code, at most 64 characters. */
1068
+ readonly spic?: string;
1069
+ /** SPIC package code, at most 20 characters. */
1070
+ readonly spicPackageCode?: string;
1071
+ }
1072
+ /**
1073
+ * Parameters for `subMerchants.create`: a `tin`, a `pinfl`, or both. With `organization`, Paylov
1074
+ * creates a new organization for the sub-merchant, which needs a `tin`; without it the
1075
+ * sub-merchant uses your organization. The lengths and formats stated here are Paylov's; a value
1076
+ * that breaks one of these rules fails with `validation_error`.
1077
+ */
1078
+ type CreateSubMerchantParams = SubMerchantProfile & ({
1079
+ /** Organization TIN (INN), 9 digits. */
1080
+ readonly tin: string;
1081
+ /** Individual's PINFL, 14 digits. Personal data; never logged or quoted. */
1082
+ readonly pinfl?: string;
1083
+ /** A new organization for the sub-merchant. */
1084
+ readonly organization?: SubMerchantOrganization;
1085
+ } | {
1086
+ /** Individual's PINFL, 14 digits. Personal data; never logged or quoted. */
1087
+ readonly pinfl: string;
1088
+ readonly tin?: undefined;
1089
+ readonly organization?: undefined;
1090
+ });
1091
+ /**
1092
+ * A new organization for the sub-merchant. Director, passport and bank fields are personal or
1093
+ * banking data. The lengths and formats stated here are Paylov's; a value that breaks one fails
1094
+ * with `validation_error` on `organization.<field>`.
1095
+ */
1096
+ interface SubMerchantOrganization {
1097
+ /** At most 256 characters. */
1098
+ readonly name: string;
1099
+ /** 14 digits. */
1100
+ readonly directorPinfl: string;
1101
+ /** Bank account number, up to 32 digits. */
1102
+ readonly accountNumber: string;
1103
+ /** OKED activity code, 5 digits. */
1104
+ readonly oked: string;
1105
+ /** At most 256 characters. */
1106
+ readonly legalName?: string;
1107
+ /** The director's full name, at most 256 characters. */
1108
+ readonly directorFullName?: string;
1109
+ /** Passport series and number, at most 9 characters. */
1110
+ readonly directorPassport?: string;
1111
+ /** `YYYY-MM-DD`. */
1112
+ readonly directorPassportValidTo?: string;
1113
+ /** `YYYY-MM-DD`. */
1114
+ readonly directorBirthDate?: string;
1115
+ /** At most 2 characters, e.g. `UZ`. */
1116
+ readonly directorNationality?: string;
1117
+ /** Nationality code for Uzcard, at most 3 characters. */
1118
+ readonly directorNationalityUzcard?: string;
1119
+ /** Nationality code for Humo, at most 3 characters. */
1120
+ readonly directorNationalityHumo?: string;
1121
+ /** Bank MFO code, at most 10 characters. */
1122
+ readonly mfo?: string;
1123
+ }
1124
+ /** Result of `subMerchants.create`. */
1125
+ interface SubMerchantCreated {
1126
+ readonly subMerchantId: string;
1127
+ readonly name: string;
1128
+ }
1129
+ /**
1130
+ * The `paylov.subMerchants` namespace. Needs sub-merchant creation enabled for the merchant;
1131
+ * otherwise `permission_denied`.
1132
+ */
1133
+ interface SubMerchantsResource {
1134
+ /**
1135
+ * Creates a child merchant under yours; Paylov staff activate it later. Moves no money. Tax ids,
1136
+ * director and bank details never reach logger events or errors.
1137
+ *
1138
+ * Recovery: no lookup exists. When `isPaylovOutcomeUnknown(error)`, repeat the call with the
1139
+ * same data; `sub_merchant_already_created` then means it exists.
1140
+ *
1141
+ * @throws {@link PaylovApiError} `sub_merchant_already_created` (the `name`, `tin`, `pinfl` or
1142
+ * `externalId` is taken among your sub-merchants), `validation_error` (`fields` names wire
1143
+ * fields such as `organization.oked` or `non_field_errors`), `rate_limit_exceeded` (more than
1144
+ * 100 calls per minute), `permission_denied`.
1145
+ *
1146
+ * @example
1147
+ * const { subMerchantId } = await paylov.subMerchants.create({
1148
+ * name: shop.displayName,
1149
+ * tin: shop.tin,
1150
+ * externalId: shop.id,
1151
+ * ofdVatPercent: 12,
1152
+ * });
1153
+ * await shops.linkPaylov(shop.id, subMerchantId);
1154
+ */
1155
+ create(params: CreateSubMerchantParams, options?: PaylovCallOptions): Promise<SubMerchantCreated>;
1156
+ }
1157
+ /** Parameters for `transactions.get`. */
1158
+ interface GetTransactionParams {
1159
+ readonly transactionId: string;
1160
+ }
1161
+ /** Parameters for `transactions.list`. */
1162
+ interface ListTransactionsParams {
1163
+ /** First day to include, `YYYY-MM-DD`, a calendar date in Tashkent time (UTC+5). */
1164
+ readonly fromDate?: string;
1165
+ /** Last day to include, `YYYY-MM-DD` in Tashkent time; the day itself is included. */
1166
+ readonly toDate?: string;
1167
+ /** 1-based page number; default 1. Pages held 20 rows on Paylov's test environment. */
1168
+ readonly page?: number;
1169
+ }
1170
+ /** Parameters for `transactions.getRrn`. */
1171
+ interface GetRrnParams {
1172
+ readonly transactionId: string;
1173
+ }
1174
+ /**
1175
+ * `created` (not yet paid), `held` (an uncaptured hold, as in `HoldStatus`), `paid` (a captured
1176
+ * hold too), `failed` (declined; see `declineCode`) or `refunded`. A refunded sale reads
1177
+ * `refunded`; so can an expired hold Paylov released, seen once with `isHold` true and no capture.
1178
+ * `transfer` and `pending` are documented but were never observed. Other values pass through
1179
+ * unchanged.
1180
+ */
1181
+ type TransactionStatus = "created" | "held" | "paid" | "failed" | "refunded" | "transfer" | "pending" | (string & {});
1182
+ /** A fiscal (OFD) receipt attached to a transaction. */
1183
+ interface FiscalReceiptSummary {
1184
+ readonly receiptId: number;
1185
+ /** The tax authority's receipt page. */
1186
+ readonly receiptUrl: string;
1187
+ /** When it was issued: `YYYY-MM-DD HH:MM:SS` as sent; Paylov does not state its zone. */
1188
+ readonly issuedAtRaw: string;
1189
+ /** `true` for the receipt of a refund. */
1190
+ readonly isRefund: boolean;
1191
+ }
1192
+ /** One gateway transaction: a receipt, PAN, hold or checkout payment. */
1193
+ interface Transaction {
1194
+ /** Gateway transaction id. */
1195
+ readonly transactionId: string;
1196
+ /**
1197
+ * The external reference stored with the transaction: a hold's `externalId`, and possibly a
1198
+ * value on checkout payments. `null` for receipt and PAN payments.
1199
+ */
1200
+ readonly externalId: string | null;
1201
+ /** `null` for PAN and checkout payments, and for a receipt created without one until paid. */
1202
+ readonly userId: string | null;
1203
+ /** Card id; `null` until a card is attached. A PAN payment gets a new one each time. */
1204
+ readonly cardId: string | null;
1205
+ readonly maskedCardNumber: string | null;
1206
+ /** For a captured hold, the captured amount. */
1207
+ readonly amountTiyin: number;
1208
+ readonly status: TransactionStatus;
1209
+ /** The decline code of a `failed` transaction, e.g. `processing_error`; otherwise `null`. */
1210
+ readonly declineCode: string | null;
1211
+ /** The creation time, replaced by the payment or capture time once paid. */
1212
+ readonly paidOrCreatedAt: Date;
1213
+ /** When it was `refunded`; `null` otherwise. */
1214
+ readonly cancelledAt: Date | null;
1215
+ readonly isHold: boolean;
1216
+ readonly isSplit: boolean;
1217
+ readonly isA2c: boolean;
1218
+ /** Paid through a checkout link. */
1219
+ readonly isCheckout: boolean;
1220
+ readonly fiscalReceipts: readonly FiscalReceiptSummary[];
1221
+ }
1222
+ /** One page of `transactions.list`. */
1223
+ interface TransactionPage {
1224
+ /** Matching transactions across all pages, not the length of this page. */
1225
+ readonly total: number;
1226
+ /** Paid transactions only, newest payment first. */
1227
+ readonly transactions: readonly Transaction[];
1228
+ }
1229
+ /** The `paylov.transactions` namespace. */
1230
+ interface TransactionsResource {
1231
+ /**
1232
+ * Reads one transaction in any status: a receipt, PAN, hold or checkout payment. This is the
1233
+ * read to reconcile with after an ambiguous failure of a money-moving call.
1234
+ *
1235
+ * Resolves to `null` when the gateway knows no such transaction. A miss right after a failed
1236
+ * call is an observation, not proof that nothing was created: read again after a delay.
1237
+ *
1238
+ * @example
1239
+ * const transaction = await paylov.transactions.get({ transactionId });
1240
+ * if (transaction === null) {
1241
+ * // unknown to the gateway (so far)
1242
+ * } else if (transaction.status === 'paid') {
1243
+ * await orders.markPaid(orderId, transaction.paidOrCreatedAt);
1244
+ * } else if (transaction.status === 'failed') {
1245
+ * await orders.markDeclined(orderId, transaction.declineCode);
1246
+ * }
1247
+ */
1248
+ get(params: GetTransactionParams, options?: PaylovCallOptions): Promise<Transaction | null>;
1249
+ /**
1250
+ * Lists the merchant's **paid** transactions, newest payment first, one page at a time.
1251
+ *
1252
+ * Created, held, failed and refunded transactions are not listed, so a refunded
1253
+ * payment drops out: this is a settled-sales feed, not an audit log, and never a way to
1254
+ * reconcile. The list is merchant-wide (no user filter). Paylov does not document the page size
1255
+ * (20 on its test environment): page until `transactions` is empty or the rows seen reach
1256
+ * `total`.
1257
+ *
1258
+ * @throws {@link PaylovApiError} `field_not_valid` (a date the gateway rejects).
1259
+ *
1260
+ * @example
1261
+ * const seen: Transaction[] = [];
1262
+ * for (let page = 1; ; page += 1) {
1263
+ * const result = await paylov.transactions.list({
1264
+ * fromDate: '2026-11-01',
1265
+ * toDate: '2026-11-30',
1266
+ * page,
1267
+ * });
1268
+ * seen.push(...result.transactions);
1269
+ * if (result.transactions.length === 0 || seen.length >= result.total) break;
1270
+ * }
1271
+ */
1272
+ list(params?: ListTransactionsParams, options?: PaylovCallOptions): Promise<TransactionPage>;
1273
+ /**
1274
+ * Reads the card network's retrieval reference number (RRN) of a paid transaction, for
1275
+ * disputes and bank-side lookups. Known to work for `payments.pay` payments, also after a
1276
+ * refund. PAN payments have none (`transaction_not_available_for_payment`); whether captured
1277
+ * holds and checkout payments have one is undocumented.
1278
+ *
1279
+ * @throws {@link PaylovApiError} `transaction_not_found`, `receipt_not_available_for_operation`
1280
+ * (not paid), `transaction_not_available_for_payment` (a payment type without an RRN).
1281
+ *
1282
+ * @example
1283
+ * const rrn = await paylov.transactions.getRrn({ transactionId });
1284
+ */
1285
+ getRrn(params: GetRrnParams, options?: PaylovCallOptions): Promise<string>;
1286
+ }
1287
+ /** Configuration for `PaylovClient`. Retries are not configurable: only GET requests retry. */
1288
+ interface PaylovClientConfig extends PaylovTransportConfig {
1289
+ /**
1290
+ * Gateway origin with no path: DEV `https://dev.gw.paylov.uz`, PROD `https://gw2.paylov.uz`.
1291
+ * Required, with no default. Must use `https`; a path, including `/merchant`, is rejected.
1292
+ */
1293
+ readonly baseUrl: string;
1294
+ readonly consumerKey: string;
1295
+ /** Secret. Never logged, never quoted in an error message. */
1296
+ readonly consumerSecret: string;
1297
+ readonly username: string;
1298
+ /** Secret. Never logged, never quoted in an error message. */
1299
+ readonly password: string;
1300
+ }
1301
+ /**
1302
+ * Server-side client for the Paylov payment gateway.
1303
+ *
1304
+ * Create one long-lived instance per merchant credential set per process and share it across
1305
+ * requests. It keeps the OAuth2 token pair in memory and refreshes it transparently; tokens are
1306
+ * not coordinated across processes.
1307
+ *
1308
+ * @example
1309
+ * import { PaylovClient } from '@isroilov_an/paylov';
1310
+ *
1311
+ * const paylov = new PaylovClient({
1312
+ * baseUrl: 'https://dev.gw.paylov.uz',
1313
+ * consumerKey: paylovConsumerKey,
1314
+ * consumerSecret: paylovConsumerSecret,
1315
+ * username: paylovUsername,
1316
+ * password: paylovPassword,
1317
+ * });
1318
+ * // ... on shutdown:
1319
+ * await paylov.close();
1320
+ *
1321
+ * @throws {@link PaylovInputError} `sdk_config_error` for malformed configuration.
1322
+ */
1323
+ declare class PaylovClient {
1324
+ #private;
1325
+ /**
1326
+ * Gateway liveness and the bank list. See docs/usage/setup.md.
1327
+ * @example await paylov.gateway.getStatus({ signal: AbortSignal.timeout(5_000) });
1328
+ */
1329
+ readonly gateway: GatewayResource;
1330
+ /**
1331
+ * Card Bind links, PAN binding, saved cards and the phone check. Moves no money.
1332
+ * See docs/usage/cards.md.
1333
+ * @example const cards = await paylov.cards.list({ userId: 'user-42' });
1334
+ */
1335
+ readonly cards: CardsResource;
1336
+ /**
1337
+ * Receipt payments with a saved card, one-off PAN payments and refunds. See
1338
+ * docs/usage/payments.md.
1339
+ * @example await paylov.payments.pay({ transactionId, cardId, userId: 'user-42' });
1340
+ */
1341
+ readonly payments: PaymentsResource;
1342
+ /**
1343
+ * Transaction lookups, paid-transaction listings and RRNs. See docs/usage/transactions.md.
1344
+ * @example const transaction = await paylov.transactions.get({ transactionId });
1345
+ */
1346
+ readonly transactions: TransactionsResource;
1347
+ /**
1348
+ * Two-phase card holds: create, capture once, release. See docs/usage/holds.md.
1349
+ * @example await paylov.holds.release({ transactionId: holdTransactionId });
1350
+ */
1351
+ readonly holds: HoldsResource;
1352
+ /**
1353
+ * Splits of a paid transaction between recipients. See docs/usage/splits.md.
1354
+ * @example const shares = await paylov.splits.get({ transactionId });
1355
+ */
1356
+ readonly splits: SplitsResource;
1357
+ /**
1358
+ * OFD fiscal receipts and activity-type checks. See docs/usage/fiscalization.md.
1359
+ * @example const receipt = await paylov.fiscalization.registerReceipt({ transactionId, items });
1360
+ */
1361
+ readonly fiscalization: FiscalizationResource;
1362
+ /**
1363
+ * Sub-merchant registration for splits. See docs/usage/splits.md.
1364
+ * @example const { subMerchantId } = await paylov.subMerchants.create(subMerchantParams);
1365
+ */
1366
+ readonly subMerchants: SubMerchantsResource;
1367
+ constructor(config: PaylovClientConfig);
1368
+ /**
1369
+ * Closes the client, waits for a token grant already under way, then revokes the access token
1370
+ * (`POST /merchant/oauth2/revoke/`, sent without `Authorization`). The SDK assumes the revoked
1371
+ * token stops authorizing at once on production; on the development gateway it keeps working.
1372
+ * Every later call throws `PaylovClientClosedError` `sdk_client_closed`. A request still in
1373
+ * flight may also fail with it once the revocation lands; Paylov rejected it before running it,
1374
+ * so it had no effect. Settle requests before closing to keep their results. Concurrent calls
1375
+ * share one revocation. Resolves once the client is closed locally even when the revocation fails or
1376
+ * `signal` abandons the wait: the revoke attempt's `logger` events report its outcome, metadata
1377
+ * only.
1378
+ *
1379
+ * @throws {@link PaylovInputError} `sdk_invalid_input` for options without an `AbortSignal`.
1380
+ *
1381
+ * @example
1382
+ * process.once('SIGTERM', () => {
1383
+ * void paylov.close({ signal: AbortSignal.timeout(5_000) });
1384
+ * });
1385
+ */
1386
+ close(options?: PaylovCallOptions): Promise<void>;
1387
+ }
1388
+ /** Numeric currency codes the checkout accepts: 860 UZS, 840 USD. */
1389
+ type CheckoutCurrency = 860 | 840;
1390
+ /**
1391
+ * An amount in the minor unit of its currency: tiyin for 860 (UZS), cents for 840 (USD).
1392
+ *
1393
+ * @example
1394
+ * const amount: CheckoutAmount = { currency: 860, amountTiyin: 50_000 }; // 500.00 SUM
1395
+ */
1396
+ type CheckoutAmount = {
1397
+ readonly currency: 860;
1398
+ readonly amountTiyin: number;
1399
+ } | {
1400
+ readonly currency: 840;
1401
+ readonly amountCents: number;
1402
+ };
1403
+ /** Configuration for `PaylovOnboarding`. It needs no credentials. */
1404
+ interface PaylovOnboardingConfig extends PaylovTransportConfig {
1405
+ /** Gateway origin with no path, e.g. `https://dev.gw.paylov.uz`. */
1406
+ readonly baseUrl: string;
1407
+ }
1408
+ /** Parameters of `PaylovOnboarding.checkToken`. */
1409
+ interface CheckOnboardingTokenParams {
1410
+ /**
1411
+ * The single-use onboarding token Paylov issued. Paylov answers `validation_error` for one
1412
+ * shorter than 8 characters. Secret.
1413
+ */
1414
+ readonly token: string;
1415
+ }
1416
+ /** Parameters of `PaylovOnboarding.complete`. */
1417
+ interface CompleteOnboardingParams {
1418
+ /** The single-use onboarding token Paylov issued. Secret. */
1419
+ readonly token: string;
1420
+ /** The merchant API username to create. */
1421
+ readonly username: string;
1422
+ /**
1423
+ * The merchant API password to set. Secret. Paylov requires a lowercase and an uppercase
1424
+ * letter, a digit and a special character, and answers `validation_error` when the token,
1425
+ * username or password is shorter than 8 characters.
1426
+ */
1427
+ readonly password: string;
1428
+ }
1429
+ /** The API credentials onboarding issues. Store all of them in a secret manager at once. */
1430
+ interface OnboardingCompleted {
1431
+ readonly consumerKey: string;
1432
+ /** Secret, and shown only once: Paylov cannot return it again. */
1433
+ readonly consumerSecret: string;
1434
+ readonly username: string;
1435
+ }
1436
+ /**
1437
+ * Completes Paylov merchant onboarding with the single-use token Paylov issues. It needs no
1438
+ * merchant credentials and is an operator step, run once, not part of a running integration.
1439
+ * The token travels in the query string and is never logged; the password and the issued
1440
+ * consumer secret never reach logger events or errors.
1441
+ *
1442
+ * @example
1443
+ * const onboarding = new PaylovOnboarding({ baseUrl: 'https://dev.gw.paylov.uz' });
1444
+ * if (!(await onboarding.checkToken({ token: onboardingToken }))) {
1445
+ * throw new Error('onboarding token is consumed or expired; ask Paylov for a new one');
1446
+ * }
1447
+ *
1448
+ * @throws {@link PaylovInputError} `sdk_config_error` for malformed configuration.
1449
+ */
1450
+ declare class PaylovOnboarding {
1451
+ #private;
1452
+ constructor(config: PaylovOnboardingConfig);
1453
+ /**
1454
+ * Checks whether an onboarding token can still be used (`GET /merchant/onboarding/?token=`).
1455
+ * Resolves `false` when Paylov reports the token unknown, consumed or expired
1456
+ * (`invalid_or_expired`).
1457
+ *
1458
+ * @throws {@link PaylovApiError} any other gateway error, e.g. `validation_error`.
1459
+ *
1460
+ * @example
1461
+ * const usable = await onboarding.checkToken({ token: onboardingToken });
1462
+ * if (!usable) throw new Error('ask Paylov for a new onboarding token');
1463
+ */
1464
+ checkToken(params: CheckOnboardingTokenParams, options?: PaylovCallOptions): Promise<boolean>;
1465
+ /**
1466
+ * Sets the merchant API username and password and returns the issued credentials
1467
+ * (`POST /merchant/onboarding/?token=`). The token is single-use and `consumerSecret` is shown
1468
+ * only once: persist the whole result before doing anything else. The account stays inactive
1469
+ * until Paylov activates it; until then a `PaylovClient` with these credentials fails with
1470
+ * `invalid_grant`.
1471
+ *
1472
+ * Recovery: never retried. When `isPaylovOutcomeUnknown(error)`, the credentials may have been
1473
+ * issued and lost: call `checkToken`; `true` means `complete` can run again, `false` that the
1474
+ * token was used, so ask Paylov to reissue the credentials.
1475
+ *
1476
+ * @throws {@link PaylovApiError} `validation_error` (see `fields`), or `invalid_or_expired`
1477
+ * for an unknown, used or expired token.
1478
+ *
1479
+ * @example
1480
+ * const credentials = await onboarding.complete({
1481
+ * token: onboardingToken,
1482
+ * username: merchantUsername,
1483
+ * password: merchantPassword,
1484
+ * });
1485
+ * await secretManager.store('paylov', credentials);
1486
+ */
1487
+ complete(params: CompleteOnboardingParams, options?: PaylovCallOptions): Promise<OnboardingCompleted>;
1488
+ }
1489
+ /** JSON-RPC identifier forms accepted and echoed for `transaction.check` / `transaction.perform`. */
1490
+ type WebhookCallbackId = string | number;
1491
+ /** Checkout `transaction.check`: the merchant validates the order before payment. */
1492
+ interface TransactionCheckEvent {
1493
+ readonly kind: "transaction.check";
1494
+ /** JSON-RPC identifier that `createWebhookResponse` echoes. */
1495
+ readonly id: WebhookCallbackId;
1496
+ /** Merchant order fields as received. The checkout link is unsigned: match them yourself. */
1497
+ readonly account: PaylovJsonObject;
1498
+ /**
1499
+ * From the integer `amount_tiyin` and `currency`; the whole-currency `amount` is ignored. The
1500
+ * link is unsigned: match the currency and the amount against the order.
1501
+ */
1502
+ readonly amount: CheckoutAmount;
1503
+ }
1504
+ /**
1505
+ * Checkout `transaction.perform`: the merchant applies the payment and answers `accept`. The SDK
1506
+ * assumes only `accept` completes it; Paylov documents no other answer.
1507
+ */
1508
+ interface TransactionPerformEvent {
1509
+ readonly kind: "transaction.perform";
1510
+ /** JSON-RPC identifier that `createWebhookResponse` echoes. */
1511
+ readonly id: WebhookCallbackId;
1512
+ /** Paylov transaction UUID; the dedupe key. */
1513
+ readonly transactionId: string;
1514
+ readonly account: PaylovJsonObject;
1515
+ /** From the integer `amount_tiyin` and `currency`; re-check it against the order. */
1516
+ readonly amount: CheckoutAmount;
1517
+ }
1518
+ /**
1519
+ * `transaction.cancel` notification, sent when a transaction is cancelled from the Paylov
1520
+ * business panel or by Paylov staff. Acknowledge with any 2xx; the body is ignored.
1521
+ */
1522
+ interface TransactionCancelEvent {
1523
+ readonly kind: "transaction.cancel";
1524
+ /** Paylov transaction UUID; the dedupe key. */
1525
+ readonly transactionId: string;
1526
+ readonly account: PaylovJsonObject;
1527
+ /** From the integer `amount_in_tiyin`; the whole-UZS `amount` is ignored. */
1528
+ readonly amountTiyin: number;
1529
+ /** From `cancel_time` (Unix seconds). */
1530
+ readonly cancelledAt: Date;
1531
+ }
1532
+ /**
1533
+ * `merchant.deposit` notification, sent when an A2C, Paynet or Munis deposit reaches the merchant
1534
+ * account. Acknowledge with any 2xx; the body is ignored.
1535
+ */
1536
+ interface MerchantDepositEvent {
1537
+ readonly kind: "merchant.deposit";
1538
+ /** Deposit UUID; the dedupe key. */
1539
+ readonly depositId: string;
1540
+ /** Paylov's merchant identifier as sent, an opaque string (the docs example is numeric). */
1541
+ readonly merchantId: string;
1542
+ /** The deposit channel. */
1543
+ readonly source: "a2c" | "paynet" | "munis" | (string & {});
1544
+ /** From the integer `amount_in_tiyin`. */
1545
+ readonly amountTiyin: number;
1546
+ /** From `create_time` (Unix seconds). */
1547
+ readonly createdAt: Date;
1548
+ }
1549
+ /**
1550
+ * Card Bind notification. Only the bound card's id is surfaced; read the card itself with
1551
+ * `paylov.cards.get({ cardId })`. Paylov never retries this webhook, so a bind session read is
1552
+ * the fallback.
1553
+ */
1554
+ interface CardBindEvent {
1555
+ readonly kind: "card.bind";
1556
+ /** Bind-session token; the dedupe key. */
1557
+ readonly token: string;
1558
+ /** The `userId` the bind link was created for. */
1559
+ readonly userId: string;
1560
+ /** Documented as always `confirmed`. */
1561
+ readonly status: "confirmed" | (string & {});
1562
+ /** The bound card's id (UUID). */
1563
+ readonly cardId: string;
1564
+ }
1565
+ /** A decoded, authenticated webhook. */
1566
+ type WebhookEvent = TransactionCheckEvent | TransactionPerformEvent | TransactionCancelEvent | MerchantDepositEvent | CardBindEvent;
1567
+ /** Locally classified invalid input. Paylov documents no failure response for these. */
1568
+ type InvalidWebhookReason = "unauthorized" | "unsupported_http_method" | "malformed_body" | "invalid_request" | "unknown_method" | "invalid_params";
1569
+ /** A webhook the receiver could not authenticate or decode. */
1570
+ interface InvalidWebhook {
1571
+ readonly kind: "invalid";
1572
+ readonly reason: InvalidWebhookReason;
1573
+ }
1574
+ /** Receiver outcome, discriminated by `kind`. */
1575
+ type WebhookOutcome = WebhookEvent | InvalidWebhook;
1576
+ /**
1577
+ * Framework-neutral inbound request supplied to `PaylovWebhookReceiver.receive`. The `method` and
1578
+ * `headers` of a Node `http` request or a Fetch `Request` fit as they are; read the body first.
1579
+ */
1580
+ interface WebhookInput {
1581
+ /** Incoming HTTP method. Only `POST` is accepted. */
1582
+ readonly method: string | undefined;
1583
+ /** Fetch `Headers` or a Node-style header record; names are matched case-insensitively. */
1584
+ readonly headers: Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
1585
+ /**
1586
+ * The body as read: JSON text, UTF-8 JSON bytes, or the JSON value a body parser produced. A
1587
+ * stream, `Blob` or other object is answered `malformed_body`.
1588
+ */
1589
+ readonly body: string | Uint8Array | ArrayBuffer | PaylovJsonValue;
1590
+ }
1591
+ /** Configuration for `PaylovWebhookReceiver`. */
1592
+ interface PaylovWebhookReceiverConfig {
1593
+ /** Basic auth login registered with Paylov; it cannot contain `:`. */
1594
+ readonly login: string;
1595
+ /** Basic auth password registered with Paylov. */
1596
+ readonly password: string;
1597
+ }
1598
+ /**
1599
+ * The merchant's answer to `transaction.check` or `transaction.perform`:
1600
+ * - `accept`: status `0`, the order matches (check) or the payment is applied (perform);
1601
+ * - `maintenance`: status `3`;
1602
+ * - `invalid_amount`: status `5`, the amount or currency does not match the order;
1603
+ * - `order_not_found`: status `303`, no order matches the account;
1604
+ * - `{ custom }`: status `+1` with your own non-blank reason as `statusText`.
1605
+ */
1606
+ type WebhookDecision = "accept" | "maintenance" | "invalid_amount" | "order_not_found" | {
1607
+ readonly custom: string;
1608
+ };
1609
+ /** The wire `result.status` of a webhook answer. */
1610
+ type WebhookResponseStatus = "0" | "3" | "5" | "303" | "+1";
1611
+ /** Documented JSON-RPC result body answering `transaction.check` / `transaction.perform`. */
1612
+ interface WebhookResponseBody {
1613
+ readonly jsonrpc: "2.0";
1614
+ readonly id: WebhookCallbackId;
1615
+ readonly result: {
1616
+ readonly status: WebhookResponseStatus;
1617
+ readonly statusText: string;
1618
+ };
1619
+ }
1620
+ export { CreateHoldParams as $, PaylovErrorCode as $t, Transaction as A, CardProcessing as At, SplitRecipient as B, PanBindingStarted as Bt, PaylovClient as C, FiscalReceiptItemBase as Ct, GetRrnParams as D, CardBindLinkCreated as Dt, FiscalReceiptSummary as E, Card as Et, SubMerchantCreated as F, CreateBindLinkParams as Ft, CreatePaymentParams as G, PaylovCallOptions as Gt, SplitShare as H, StartPanBindingParams as Ht, SubMerchantOrganization as I, DeleteCardParams as It, PaymentRefunded as J, PaylovJsonValue as Jt, PanPaymentStarted as K, PaylovHttpMethod as Kt, SplitsResource as L, GetBindSessionParams as Lt, TransactionStatus as M, CardVendor as Mt, SubMerchantsResource as N, CheckCardPhoneParams as Nt, GetTransactionParams as O, CardBindSession as Ot, CreateSubMerchantParams as P, ConfirmPanBindingParams as Pt, CaptureHoldParams as Q, PaylovTransportConfig as Qt, CreateSplitParams as R, GetCardParams as Rt, CheckoutCurrency as S, FiscalReceiptItem as St, TransactionsResource as T, BoundCardBindSession as Tt, PaymentsResource as U, OtpSmsSettings as Ut, SplitRecipientStatus as V, PendingCardBindSession as Vt, ConfirmPanPaymentParams as W, FetchLike as Wt, StartPanPaymentParams as X, PaylovLoggerRequestEvent as Xt, RefundPaymentParams as Y, PaylovLogger as Yt, HoldsResource as Z, PaylovLoggerResponseEvent as Zt, CheckOnboardingTokenParams as _, RegisterCardFiscalReceiptParams as _t, PaylovWebhookReceiverConfig as a, GatewayResource as at, PaylovOnboardingConfig as b, TransactionLookup as bt, TransactionPerformEvent as c, ActivityTypeCheck as ct, WebhookEvent as d, FiscalActivityType as dt, PaylovKnownErrorCode as en, GetHoldParams as et, WebhookInput as f, FiscalReceipt as ft, PaylovOnboarding as g, RefundFiscalReceiptParams as gt, WebhookResponseStatus as h, GetFiscalReceiptParams as ht, MerchantDepositEvent as i, ReleaseHoldParams as it, TransactionPage as j, CardProcessingStatus as jt, ListTransactionsParams as k, CardBindStatus as kt, WebhookCallbackId as l, AttachFiscalReceiptParams as lt, WebhookResponseBody as m, FiscalReceiptRegistered as mt, InvalidWebhook as n, HoldCaptured as nt, TransactionCancelEvent as o, Bank as ot, WebhookOutcome as p, FiscalReceiptRefunded as pt, PayPaymentParams as q, PaylovJsonObject as qt, InvalidWebhookReason as r, HoldStatus as rt, TransactionCheckEvent as s, FiscalizationResource as st, CardBindEvent as t, Hold as tt, WebhookDecision as u, CheckActivityTypeParams as ut, CompleteOnboardingParams as v, RegisterCashFiscalReceiptParams as vt, PaylovClientConfig as w, CardsResource as wt, CheckoutAmount as x, TransactionReference as xt, OnboardingCompleted as y, RegisterFiscalReceiptParams as yt, GetSplitParams as z, ListCardsParams as zt };