@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.
- package/CHANGELOG.md +35 -0
- package/LICENSE +21 -0
- package/README.md +81 -0
- package/dist/client-DOu4B-bL.js +2576 -0
- package/dist/client-DOu4B-bL.js.map +1 -0
- package/dist/index.d.ts +393 -0
- package/dist/index.js +458 -0
- package/dist/index.js.map +1 -0
- package/dist/testing.d.ts +198 -0
- package/dist/testing.js +1079 -0
- package/dist/testing.js.map +1 -0
- package/dist/types-Bj9umT2M.d.ts +1620 -0
- package/docs/usage/INDEX.md +30 -0
- package/docs/usage/cards.md +69 -0
- package/docs/usage/checkout.md +30 -0
- package/docs/usage/errors.md +107 -0
- package/docs/usage/fiscalization.md +62 -0
- package/docs/usage/holds.md +82 -0
- package/docs/usage/money-and-time.md +45 -0
- package/docs/usage/onboarding.md +28 -0
- package/docs/usage/payments.md +57 -0
- package/docs/usage/setup.md +85 -0
- package/docs/usage/splits.md +46 -0
- package/docs/usage/testing.md +132 -0
- package/docs/usage/transactions.md +43 -0
- package/docs/usage/webhooks.md +168 -0
- package/package.json +86 -0
|
@@ -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 };
|