@vexpay/node 0.14.0 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -13
- package/dist/index.cjs +56 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1320 -507
- package/dist/index.d.ts +1320 -507
- package/dist/index.js +56 -7
- package/dist/index.js.map +1 -1
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# VEX Pay Node.js SDK
|
|
2
2
|
|
|
3
|
-
The official Node.js / TypeScript library for the [
|
|
3
|
+
The official Node.js / TypeScript library for the [VEX Pay](https://vexpay.app) API: accept Venezuelan payments (Pago Móvil C2P, cards, débito inmediato), pay out to merchants, create checkout sessions, and verify signed webhooks.
|
|
4
4
|
|
|
5
|
-
- Fully typed from the
|
|
5
|
+
- Fully typed from the VEX Pay OpenAPI contract
|
|
6
6
|
- Safe retries: every `POST` carries an `Idempotency-Key`, so a retried charge never charges twice
|
|
7
7
|
- Auto-pagination with `for await`
|
|
8
8
|
- Webhook signature verification with replay protection
|
|
@@ -61,7 +61,7 @@ console.log(payment.status); // "COMPLETED" or "PENDING" — confirm with the pa
|
|
|
61
61
|
|
|
62
62
|
## Checkout sessions (hosted or embedded)
|
|
63
63
|
|
|
64
|
-
Let
|
|
64
|
+
Let VEX Pay collect the payment details. Redirect the buyer to `url`, or embed the checkout on your own site with [`@vexpay/js`](https://www.npmjs.com/package/@vexpay/js) and the one-time `clientSecret`.
|
|
65
65
|
|
|
66
66
|
```ts
|
|
67
67
|
import VexPay from '@vexpay/node';
|
|
@@ -91,7 +91,7 @@ The hosted page lets the buyer pick the currency — bolívares, stablecoins or
|
|
|
91
91
|
|
|
92
92
|
## USDT
|
|
93
93
|
|
|
94
|
-
USDT settles in USDT, into your
|
|
94
|
+
USDT settles in USDT, into your VEX Pay USDT balance (never converted to VES). It must be enabled on your account — otherwise these calls fail with `method_not_allowed` (403). Pay-ins cost 2.5 % + 0.50 USDT; payouts cost the network fee listed by `crypto.networks.list()`.
|
|
95
95
|
|
|
96
96
|
```ts
|
|
97
97
|
import VexPay from '@vexpay/node';
|
|
@@ -151,7 +151,7 @@ Responses and events include `currency`, `amount` and `fee` for both coins (`amo
|
|
|
151
151
|
|
|
152
152
|
## Convert VES or COP to USDT
|
|
153
153
|
|
|
154
|
-
Turn available VES or Colombian pesos into your USDT balance. A quote locks the rate (market USDT rate in that currency plus your spread) for 60 seconds; accepting it debits the source at once (`conversion.created`) and returns a `PENDING` conversion.
|
|
154
|
+
Turn available VES or Colombian pesos into your USDT balance. A quote locks the rate (market USDT rate in that currency plus your spread) for 60 seconds; accepting it debits the source at once (`conversion.created`) and returns a `PENDING` conversion. VEX Pay then delivers the USDT and sends `conversion.completed` (or `conversion.canceled`, with the VES or COP returned). Conversions are on for every account that has USDT enabled (COP also needs COP enabled) — otherwise the calls fail with `conversions_not_enabled` (403). In test mode they complete immediately. COP amounts are whole pesos.
|
|
155
155
|
|
|
156
156
|
```ts
|
|
157
157
|
import VexPay from '@vexpay/node';
|
|
@@ -241,7 +241,7 @@ const { availableCop } = await vexpay.cop.balance.retrieve();
|
|
|
241
241
|
|
|
242
242
|
## Subscriptions
|
|
243
243
|
|
|
244
|
-
Bill a customer on a recurring USD price. Each period
|
|
244
|
+
Bill a customer on a recurring USD price. Each period VEX Pay issues an invoice; with `send_invoice` (default) the customer pays it on a hosted page (`hostedInvoiceUrl`), with `charge_automatically` VEX Pay charges their domiciliación. Listen for `invoice.paid`, `invoice.payment_failed` and `customer.subscription.*` webhooks.
|
|
245
245
|
|
|
246
246
|
```ts
|
|
247
247
|
import VexPay from '@vexpay/node';
|
|
@@ -274,15 +274,15 @@ for await (const method of vexpay.customers.paymentMethods.list(customer.id)) {
|
|
|
274
274
|
await vexpay.subscriptions.update(subscription.id, { cancelAtPeriodEnd: true });
|
|
275
275
|
```
|
|
276
276
|
|
|
277
|
-
`subscriptions.cancel(id)` cancels at once and voids its open invoices. On an open invoice, `invoices.void(id)`, `invoices.markUncollectible(id)` (stays payable) and `invoices.pay(id, { paidOutOfBand: true })` (paid outside
|
|
277
|
+
`subscriptions.cancel(id)` cancels at once and voids its open invoices. On an open invoice, `invoices.void(id)`, `invoices.markUncollectible(id)` (stays payable) and `invoices.pay(id, { paidOutOfBand: true })` (paid outside VEX Pay; no money moves). `paymentMethods.detach(id)` stops a domiciliación from being charged again.
|
|
278
278
|
|
|
279
279
|
## Testing card payments
|
|
280
280
|
|
|
281
|
-
With a test API key, VPOS test cards return a fixed outcome without reaching the bank: `4242424242424242` succeeds, `4000000000009995` is declined with `G51` (insufficient funds), `4000000000000259` completes and is then charged back, and more. A decline fails exactly like a live one (422, the bank code in `code` and `failureCode`, a `payment.failed` webhook). With a live key these numbers are refused with 400 `test_card_in_live_mode`. Full list: [test cards](https://docs.
|
|
281
|
+
With a test API key, VPOS test cards return a fixed outcome without reaching the bank: `4242424242424242` succeeds, `4000000000009995` is declined with `G51` (insufficient funds), `4000000000000259` completes and is then charged back, and more. A decline fails exactly like a live one (422, the bank code in `code` and `failureCode`, a `payment.failed` webhook). With a live key these numbers are refused with 400 `test_card_in_live_mode`. Full list: [test cards](https://docs.vexpay.app/vpos#test-card).
|
|
282
282
|
|
|
283
283
|
## Webhooks
|
|
284
284
|
|
|
285
|
-
|
|
285
|
+
VEX Pay signs every delivery with a `VexPay-Signature` header. Verify it with the **raw** request body — parsing and re-serializing JSON changes the bytes and breaks the signature.
|
|
286
286
|
|
|
287
287
|
```ts
|
|
288
288
|
import VexPay from '@vexpay/node';
|
|
@@ -403,7 +403,7 @@ try {
|
|
|
403
403
|
|
|
404
404
|
## Retries and idempotency
|
|
405
405
|
|
|
406
|
-
The SDK retries connection errors, timeouts, `429`, `5xx`, and `409 idempotency_request_in_progress` up to `maxNetworkRetries` times (default 2) with exponential backoff, honouring `Retry-After`. Every `POST` gets a random `Idempotency-Key` that stays the same across its retries, so
|
|
406
|
+
The SDK retries connection errors, timeouts, `429`, `5xx`, and `409 idempotency_request_in_progress` up to `maxNetworkRetries` times (default 2) with exponential backoff, honouring `Retry-After`. Every `POST` gets a random `Idempotency-Key` that stays the same across its retries, so VEX Pay executes it at most once. Supply your own key to make retries safe across process restarts too:
|
|
407
407
|
|
|
408
408
|
```ts
|
|
409
409
|
import VexPay from '@vexpay/node';
|
|
@@ -475,7 +475,7 @@ console.log(recentPayouts.length);
|
|
|
475
475
|
import VexPay from '@vexpay/node';
|
|
476
476
|
|
|
477
477
|
const vexpay = new VexPay(process.env.VEXPAY_API_KEY!, {
|
|
478
|
-
baseUrl: 'http://localhost:3010', // default: https://api.
|
|
478
|
+
baseUrl: 'http://localhost:3010', // default: https://api.vexpay.app
|
|
479
479
|
timeoutMs: 30_000,
|
|
480
480
|
maxNetworkRetries: 2,
|
|
481
481
|
});
|
|
@@ -541,7 +541,7 @@ console.log(describe, {} as NewPayout, {} as Session);
|
|
|
541
541
|
| `paymentMethods` | `retrieve`, `detach` |
|
|
542
542
|
| `webhooks` | `constructEvent`, `generateTestHeader` (offline) |
|
|
543
543
|
|
|
544
|
-
Full API reference: [docs](https://
|
|
544
|
+
Full API reference: [docs](https://docs.vexpay.app) · OpenAPI: `/openapi.json`.
|
|
545
545
|
|
|
546
546
|
## License
|
|
547
547
|
|
package/dist/index.cjs
CHANGED
|
@@ -91,7 +91,7 @@ function messageFrom(body, status) {
|
|
|
91
91
|
if (typeof error === "string" && error) return error;
|
|
92
92
|
}
|
|
93
93
|
if (typeof body === "string" && body) return body;
|
|
94
|
-
return `
|
|
94
|
+
return `VEX Pay API responded with HTTP ${status}`;
|
|
95
95
|
}
|
|
96
96
|
function errorFromResponse(status, body, requestId) {
|
|
97
97
|
const rawCode = body && typeof body === "object" ? body.error : void 0;
|
|
@@ -107,7 +107,7 @@ function errorFromResponse(status, body, requestId) {
|
|
|
107
107
|
}
|
|
108
108
|
|
|
109
109
|
// src/version.ts
|
|
110
|
-
var VERSION = "0.
|
|
110
|
+
var VERSION = "0.17.0";
|
|
111
111
|
|
|
112
112
|
// src/core.ts
|
|
113
113
|
var INITIAL_RETRY_DELAY_MS = 500;
|
|
@@ -202,11 +202,11 @@ var HttpClient = class {
|
|
|
202
202
|
return await this.config.fetch(url, { ...init, signal: controller.signal });
|
|
203
203
|
} catch (caught) {
|
|
204
204
|
if (timedOut) {
|
|
205
|
-
throw new VexPayTimeoutError(`Request to
|
|
205
|
+
throw new VexPayTimeoutError(`Request to VEX Pay timed out after ${timeoutMs}ms`);
|
|
206
206
|
}
|
|
207
207
|
if (signal?.aborted) throw caught;
|
|
208
208
|
const reason = caught instanceof Error ? caught.message : String(caught);
|
|
209
|
-
throw new VexPayConnectionError(`Could not reach
|
|
209
|
+
throw new VexPayConnectionError(`Could not reach VEX Pay: ${reason}`);
|
|
210
210
|
} finally {
|
|
211
211
|
clearTimeout(timer);
|
|
212
212
|
signal?.removeEventListener("abort", onAbort);
|
|
@@ -292,6 +292,8 @@ var ROUTES = {
|
|
|
292
292
|
Invoices_pay: { method: "POST", path: "/v1/invoices/{id}/pay" },
|
|
293
293
|
Invoices_retrieve: { method: "GET", path: "/v1/invoices/{id}" },
|
|
294
294
|
Invoices_void: { method: "POST", path: "/v1/invoices/{id}/void" },
|
|
295
|
+
MarketplaceSettings_get: { method: "GET", path: "/v1/marketplace/settings" },
|
|
296
|
+
MarketplaceSettings_update: { method: "PATCH", path: "/v1/marketplace/settings" },
|
|
295
297
|
Merchants_addPayoutMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods" },
|
|
296
298
|
Merchants_confirmVerify: { method: "POST", path: "/v1/merchants/{id}/verify" },
|
|
297
299
|
Merchants_confirmVerifyMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods/{methodId}/verify" },
|
|
@@ -366,6 +368,11 @@ var ROUTES = {
|
|
|
366
368
|
TenantPayoutAccount_startVerify: { method: "POST", path: "/v1/tenant/payout-account/verify/start" },
|
|
367
369
|
TenantPayoutAccount_upsert: { method: "PUT", path: "/v1/tenant/payout-account" },
|
|
368
370
|
TenantPayoutAccount_upsertPost: { method: "POST", path: "/v1/tenant/payout-account" },
|
|
371
|
+
TestClocks_advance: { method: "POST", path: "/v1/test-clocks/{id}/advance" },
|
|
372
|
+
TestClocks_create: { method: "POST", path: "/v1/test-clocks" },
|
|
373
|
+
TestClocks_list: { method: "GET", path: "/v1/test-clocks" },
|
|
374
|
+
TestClocks_remove: { method: "DELETE", path: "/v1/test-clocks/{id}" },
|
|
375
|
+
TestClocks_retrieve: { method: "GET", path: "/v1/test-clocks/{id}" },
|
|
369
376
|
Topups_create: { method: "POST", path: "/v1/balance/topups" },
|
|
370
377
|
Topups_get: { method: "GET", path: "/v1/balance/topups/{id}" },
|
|
371
378
|
Topups_instant: { method: "POST", path: "/v1/balance/topups/{id}/instant" },
|
|
@@ -610,7 +617,7 @@ var Invoices = class extends APIResource {
|
|
|
610
617
|
markUncollectible(id, options) {
|
|
611
618
|
return this.call("Invoices_markUncollectible", { path: { id } }, options);
|
|
612
619
|
}
|
|
613
|
-
/** Record an open invoice as paid outside
|
|
620
|
+
/** Record an open invoice as paid outside VEX Pay (`paidOutOfBand: true`); no money moves. */
|
|
614
621
|
pay(id, params, options) {
|
|
615
622
|
return this.call("Invoices_pay", { path: { id }, body: params }, options);
|
|
616
623
|
}
|
|
@@ -633,6 +640,33 @@ var PaymentMethods = class extends APIResource {
|
|
|
633
640
|
return this.call("PaymentMethods_detach", { path: { id } }, options);
|
|
634
641
|
}
|
|
635
642
|
};
|
|
643
|
+
var TestClocks = class extends APIResource {
|
|
644
|
+
/** `frozenTime` is an ISO 8601 time. */
|
|
645
|
+
create(params, options) {
|
|
646
|
+
return this.call("TestClocks_create", { body: params }, options);
|
|
647
|
+
}
|
|
648
|
+
/** Await for one page, or `for await` over every clock (newest first). */
|
|
649
|
+
list(params = {}, options) {
|
|
650
|
+
return new PagePromise(
|
|
651
|
+
(cursor) => this.call("TestClocks_list", { query: { ...params, cursor } }, options),
|
|
652
|
+
params.cursor
|
|
653
|
+
);
|
|
654
|
+
}
|
|
655
|
+
retrieve(id, options) {
|
|
656
|
+
return this.call("TestClocks_retrieve", { path: { id } }, options);
|
|
657
|
+
}
|
|
658
|
+
/** Deletes the clock with its customers, subscriptions, invoices and payment methods. */
|
|
659
|
+
delete(id, options) {
|
|
660
|
+
return this.call("TestClocks_remove", { path: { id } }, options);
|
|
661
|
+
}
|
|
662
|
+
/**
|
|
663
|
+
* Move the clock forward (at most two intervals of its shortest subscription). It returns at
|
|
664
|
+
* once with `status: "advancing"`; poll `retrieve` or wait for `test_clock.ready`.
|
|
665
|
+
*/
|
|
666
|
+
advance(id, params, options) {
|
|
667
|
+
return this.call("TestClocks_advance", { path: { id }, body: params }, options);
|
|
668
|
+
}
|
|
669
|
+
};
|
|
636
670
|
|
|
637
671
|
// src/resources/commerce.ts
|
|
638
672
|
var CheckoutSessions = class extends APIResource {
|
|
@@ -847,8 +881,18 @@ var PayoutMethods = class extends APIResource {
|
|
|
847
881
|
);
|
|
848
882
|
}
|
|
849
883
|
};
|
|
884
|
+
var MarketplaceSettings = class extends APIResource {
|
|
885
|
+
retrieve(options) {
|
|
886
|
+
return this.call("MarketplaceSettings_get", {}, options);
|
|
887
|
+
}
|
|
888
|
+
/** `merchantAutoPayoutDefault` and/or `merchantAutoPayoutMinUsd` (USD; null clears it). */
|
|
889
|
+
update(params, options) {
|
|
890
|
+
return this.call("MarketplaceSettings_update", { body: params }, options);
|
|
891
|
+
}
|
|
892
|
+
};
|
|
850
893
|
var Merchants = class extends APIResource {
|
|
851
894
|
payoutMethods = new PayoutMethods(this.http);
|
|
895
|
+
marketplaceSettings = new MarketplaceSettings(this.http);
|
|
852
896
|
/** `externalRef` is required and is the idempotency key for merchant creation. */
|
|
853
897
|
create(params, options) {
|
|
854
898
|
return this.call("Merchants_create", { body: params }, options);
|
|
@@ -1063,6 +1107,8 @@ var WEBHOOK_EVENT_NAMES = [
|
|
|
1063
1107
|
"payment_method.attached",
|
|
1064
1108
|
"payment_method.updated",
|
|
1065
1109
|
"payment_method.detached",
|
|
1110
|
+
"test_clock.advancing",
|
|
1111
|
+
"test_clock.ready",
|
|
1066
1112
|
"notification.test"
|
|
1067
1113
|
];
|
|
1068
1114
|
var SIGNATURE_HEADER = "VexPay-Signature";
|
|
@@ -1143,7 +1189,7 @@ var Webhooks = class {
|
|
|
1143
1189
|
};
|
|
1144
1190
|
|
|
1145
1191
|
// src/client.ts
|
|
1146
|
-
var DEFAULT_BASE_URL = "https://api.
|
|
1192
|
+
var DEFAULT_BASE_URL = "https://api.vexpay.app";
|
|
1147
1193
|
var VexPay = class {
|
|
1148
1194
|
/** @internal */
|
|
1149
1195
|
http;
|
|
@@ -1175,12 +1221,14 @@ var VexPay = class {
|
|
|
1175
1221
|
setupSessions;
|
|
1176
1222
|
/** Billing: domiciliación payment methods (bolívar methods your account takes: `payments.methods()`). */
|
|
1177
1223
|
paymentMethods;
|
|
1224
|
+
/** Billing, test mode only: simulated time for trials, renewals and dunning. */
|
|
1225
|
+
testClocks;
|
|
1178
1226
|
/** Offline helpers: `constructEvent` verifies deliveries; no API calls. */
|
|
1179
1227
|
webhooks = new Webhooks();
|
|
1180
1228
|
constructor(apiKey, options = {}) {
|
|
1181
1229
|
if (typeof apiKey !== "string" || apiKey.trim() === "") {
|
|
1182
1230
|
throw new VexPayConfigurationError(
|
|
1183
|
-
"A
|
|
1231
|
+
"A VEX Pay API key is required: new VexPay(process.env.VEXPAY_API_KEY)."
|
|
1184
1232
|
);
|
|
1185
1233
|
}
|
|
1186
1234
|
const fetchImpl = options.fetch ?? globalThis.fetch;
|
|
@@ -1215,6 +1263,7 @@ var VexPay = class {
|
|
|
1215
1263
|
this.invoices = new Invoices(this.http);
|
|
1216
1264
|
this.setupSessions = new SetupSessions(this.http);
|
|
1217
1265
|
this.paymentMethods = new PaymentMethods(this.http);
|
|
1266
|
+
this.testClocks = new TestClocks(this.http);
|
|
1218
1267
|
}
|
|
1219
1268
|
};
|
|
1220
1269
|
// Annotate the CommonJS export names for ESM import in node:
|