@vexpay/node 0.10.0 → 0.12.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 +46 -2
- package/dist/index.cjs +181 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2787 -94
- package/dist/index.d.ts +2787 -94
- package/dist/index.js +181 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -219,6 +219,43 @@ const { availableCop } = await vexpay.cop.balance.retrieve();
|
|
|
219
219
|
| Nequi | Any valid data, e.g. phone `3001234567`, `CC` `1234567890`, any email | Completes on its own within about a minute |
|
|
220
220
|
| Daviplata | Same buyer data (`CC`, `CE` or `TI` only) | OTP `123456`, `000000` or `111111` completes it; any other code fails with `invalid_otp` |
|
|
221
221
|
|
|
222
|
+
## Subscriptions
|
|
223
|
+
|
|
224
|
+
Bill a customer on a recurring USD price. Each period VEXPay issues an invoice; with `send_invoice` (default) the customer pays it on a hosted page (`hostedInvoiceUrl`), with `charge_automatically` VEXPay charges their domiciliación. Listen for `invoice.paid`, `invoice.payment_failed` and `customer.subscription.*` webhooks.
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
import VexPay from '@vexpay/node';
|
|
228
|
+
|
|
229
|
+
const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
|
|
230
|
+
|
|
231
|
+
const customer = await vexpay.customers.create({ name: 'María Pérez', email: 'maria@example.com' });
|
|
232
|
+
const price = await vexpay.prices.create({
|
|
233
|
+
product: 'prod_123',
|
|
234
|
+
unitAmountUsd: 10,
|
|
235
|
+
recurring: { interval: 'month' },
|
|
236
|
+
});
|
|
237
|
+
|
|
238
|
+
const subscription = await vexpay.subscriptions.create(
|
|
239
|
+
{ customer: customer.id, price: price.id, methods: ['c2p', 'pago_movil'] },
|
|
240
|
+
{ idempotencyKey: `sub-${customer.id}` },
|
|
241
|
+
);
|
|
242
|
+
|
|
243
|
+
for await (const invoice of vexpay.invoices.list({ subscription: subscription.id })) {
|
|
244
|
+
console.log(invoice.number, invoice.status, invoice.amountDueUsd, invoice.hostedInvoiceUrl);
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
// Domiciliación: send the customer a setup link, then charge automatically.
|
|
248
|
+
const setup = await vexpay.setupSessions.create({ customer: customer.id });
|
|
249
|
+
console.log(setup.url);
|
|
250
|
+
for await (const method of vexpay.customers.paymentMethods.list(customer.id)) {
|
|
251
|
+
console.log(method.id, method.status);
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
await vexpay.subscriptions.update(subscription.id, { cancelAtPeriodEnd: true });
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
`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 VEXPay; no money moves). `paymentMethods.detach(id)` stops a domiciliación from being charged again.
|
|
258
|
+
|
|
222
259
|
## Testing card payments
|
|
223
260
|
|
|
224
261
|
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.pay.vexwallet.co/vpos#test-card).
|
|
@@ -312,7 +349,7 @@ try {
|
|
|
312
349
|
| `VexPayAuthenticationError` | 401 — missing or invalid API key |
|
|
313
350
|
| `VexPayInvalidRequestError` | 400, 403, 410, 422 — fix the request |
|
|
314
351
|
| `VexPayNotFoundError` | 404 |
|
|
315
|
-
| `VexPayConflictError` | 409 — e.g. `external_ref_conflict`, `idempotency_key_reused` |
|
|
352
|
+
| `VexPayConflictError` | 409 — e.g. `external_ref_conflict`, `external_ref_already_paid` (body `paymentId`), `idempotency_key_reused` |
|
|
316
353
|
| `VexPayRateLimitError` | 429, after retries |
|
|
317
354
|
| `VexPayAPIError` | 5xx, after retries |
|
|
318
355
|
| `VexPayConnectionError` / `VexPayTimeoutError` | no HTTP answer, after retries |
|
|
@@ -342,7 +379,7 @@ await vexpay.payments.c2p.execute(
|
|
|
342
379
|
|
|
343
380
|
## Pagination
|
|
344
381
|
|
|
345
|
-
`list()` methods on payouts, merchants, and
|
|
382
|
+
`list()` methods on payouts, merchants, products, customers, prices, subscriptions and invoices return the first page when awaited, and every item when iterated:
|
|
346
383
|
|
|
347
384
|
```ts
|
|
348
385
|
import VexPay from '@vexpay/node';
|
|
@@ -420,6 +457,13 @@ console.log(describe, {} as NewPayout, {} as Session);
|
|
|
420
457
|
| `paymentLinks` | `retrieve`, `update`, `delete` |
|
|
421
458
|
| `tenantPayoutAccount` | `retrieve`, `upsert`, `create`, `startVerification`, `confirmVerification` |
|
|
422
459
|
| `webhookEndpoints` | `create`, `list`, `update`, `delete`, `sendTest` |
|
|
460
|
+
| `customers` | `create`, `list`, `retrieve`, `update`, `delete` |
|
|
461
|
+
| `customers.paymentMethods` | `list` |
|
|
462
|
+
| `prices` | `create`, `list`, `retrieve`, `update` |
|
|
463
|
+
| `subscriptions` | `create`, `list`, `retrieve`, `update`, `cancel` |
|
|
464
|
+
| `invoices` | `list`, `retrieve`, `void`, `markUncollectible`, `pay` |
|
|
465
|
+
| `setupSessions` | `create`, `retrieve` |
|
|
466
|
+
| `paymentMethods` | `retrieve`, `detach` |
|
|
423
467
|
| `webhooks` | `constructEvent`, `generateTestHeader` (offline) |
|
|
424
468
|
|
|
425
469
|
Full API reference: [docs](https://pay.vexwallet.co/docs) · OpenAPI: `/openapi.json`.
|
package/dist/index.cjs
CHANGED
|
@@ -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.12.0";
|
|
111
111
|
|
|
112
112
|
// src/core.ts
|
|
113
113
|
var INITIAL_RETRY_DELAY_MS = 500;
|
|
@@ -280,6 +280,16 @@ var ROUTES = {
|
|
|
280
280
|
Crypto_getBalances: { method: "GET", path: "/v1/crypto/balances" },
|
|
281
281
|
Crypto_getPayout: { method: "GET", path: "/v1/crypto/payouts/{id}" },
|
|
282
282
|
Crypto_listNetworks: { method: "GET", path: "/v1/crypto/networks" },
|
|
283
|
+
Customers_create: { method: "POST", path: "/v1/customers" },
|
|
284
|
+
Customers_list: { method: "GET", path: "/v1/customers" },
|
|
285
|
+
Customers_remove: { method: "DELETE", path: "/v1/customers/{id}" },
|
|
286
|
+
Customers_retrieve: { method: "GET", path: "/v1/customers/{id}" },
|
|
287
|
+
Customers_update: { method: "POST", path: "/v1/customers/{id}" },
|
|
288
|
+
Invoices_list: { method: "GET", path: "/v1/invoices" },
|
|
289
|
+
Invoices_markUncollectible: { method: "POST", path: "/v1/invoices/{id}/mark-uncollectible" },
|
|
290
|
+
Invoices_pay: { method: "POST", path: "/v1/invoices/{id}/pay" },
|
|
291
|
+
Invoices_retrieve: { method: "GET", path: "/v1/invoices/{id}" },
|
|
292
|
+
Invoices_void: { method: "POST", path: "/v1/invoices/{id}/void" },
|
|
283
293
|
Merchants_addPayoutMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods" },
|
|
284
294
|
Merchants_confirmVerify: { method: "POST", path: "/v1/merchants/{id}/verify" },
|
|
285
295
|
Merchants_confirmVerifyMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods/{methodId}/verify" },
|
|
@@ -300,6 +310,9 @@ var ROUTES = {
|
|
|
300
310
|
PaymentLinks_get: { method: "GET", path: "/v1/payment-links/{id}" },
|
|
301
311
|
PaymentLinks_remove: { method: "DELETE", path: "/v1/payment-links/{id}" },
|
|
302
312
|
PaymentLinks_update: { method: "PATCH", path: "/v1/payment-links/{id}" },
|
|
313
|
+
PaymentMethods_detach: { method: "DELETE", path: "/v1/payment-methods/{id}" },
|
|
314
|
+
PaymentMethods_list: { method: "GET", path: "/v1/customers/{id}/payment-methods" },
|
|
315
|
+
PaymentMethods_retrieve: { method: "GET", path: "/v1/payment-methods/{id}" },
|
|
303
316
|
Payments_executeC2p: { method: "POST", path: "/v1/payments/c2p" },
|
|
304
317
|
Payments_executeVpos: { method: "POST", path: "/v1/payments/vpos" },
|
|
305
318
|
Payments_getBanks: { method: "GET", path: "/v1/banks" },
|
|
@@ -317,6 +330,10 @@ var ROUTES = {
|
|
|
317
330
|
Payouts_getById: { method: "GET", path: "/v1/payouts/{id}" },
|
|
318
331
|
Payouts_getByRef: { method: "GET", path: "/v1/payouts/by-ref/{externalRef}" },
|
|
319
332
|
Payouts_list: { method: "GET", path: "/v1/payouts" },
|
|
333
|
+
Prices_create: { method: "POST", path: "/v1/prices" },
|
|
334
|
+
Prices_list: { method: "GET", path: "/v1/prices" },
|
|
335
|
+
Prices_retrieve: { method: "GET", path: "/v1/prices/{id}" },
|
|
336
|
+
Prices_update: { method: "POST", path: "/v1/prices/{id}" },
|
|
320
337
|
Products_create: { method: "POST", path: "/v1/products" },
|
|
321
338
|
Products_createLink: { method: "POST", path: "/v1/products/{id}/links" },
|
|
322
339
|
Products_get: { method: "GET", path: "/v1/products/{id}" },
|
|
@@ -333,6 +350,13 @@ var ROUTES = {
|
|
|
333
350
|
R4Operations_ejecutarVuelto: { method: "POST", path: "/v1/payments/change" },
|
|
334
351
|
R4Operations_generarOtp: { method: "POST", path: "/v1/payments/debit/otp" },
|
|
335
352
|
R4Operations_pollOperation: { method: "POST", path: "/v1/payments/operations/poll" },
|
|
353
|
+
SetupSessions_create: { method: "POST", path: "/v1/setup-sessions" },
|
|
354
|
+
SetupSessions_retrieve: { method: "GET", path: "/v1/setup-sessions/{id}" },
|
|
355
|
+
Subscriptions_cancel: { method: "DELETE", path: "/v1/subscriptions/{id}" },
|
|
356
|
+
Subscriptions_create: { method: "POST", path: "/v1/subscriptions" },
|
|
357
|
+
Subscriptions_list: { method: "GET", path: "/v1/subscriptions" },
|
|
358
|
+
Subscriptions_retrieve: { method: "GET", path: "/v1/subscriptions/{id}" },
|
|
359
|
+
Subscriptions_update: { method: "POST", path: "/v1/subscriptions/{id}" },
|
|
336
360
|
TenantPayoutAccount_confirmVerify: { method: "POST", path: "/v1/tenant/payout-account/verify" },
|
|
337
361
|
TenantPayoutAccount_get: { method: "GET", path: "/v1/tenant/payout-account" },
|
|
338
362
|
TenantPayoutAccount_startVerify: { method: "POST", path: "/v1/tenant/payout-account/verify/start" },
|
|
@@ -459,6 +483,126 @@ var WebhookEndpoints = class extends APIResource {
|
|
|
459
483
|
}
|
|
460
484
|
};
|
|
461
485
|
|
|
486
|
+
// src/resources/billing.ts
|
|
487
|
+
var CustomerPaymentMethods = class extends APIResource {
|
|
488
|
+
/** Await for one page, or `for await` over every attached method (newest first). */
|
|
489
|
+
list(customerId, params = {}, options) {
|
|
490
|
+
return new PagePromise(
|
|
491
|
+
(cursor) => this.call("PaymentMethods_list", { path: { id: customerId }, query: { ...params, cursor } }, options),
|
|
492
|
+
params.cursor
|
|
493
|
+
);
|
|
494
|
+
}
|
|
495
|
+
};
|
|
496
|
+
var Customers = class extends APIResource {
|
|
497
|
+
paymentMethods = new CustomerPaymentMethods(this.http);
|
|
498
|
+
/** Pass `idempotencyKey` in options to retry safely. */
|
|
499
|
+
create(params = {}, options) {
|
|
500
|
+
return this.call("Customers_create", { body: params }, options);
|
|
501
|
+
}
|
|
502
|
+
/** Await for one page, or `for await` over every customer (newest first). Filter with `email`. */
|
|
503
|
+
list(params = {}, options) {
|
|
504
|
+
return new PagePromise(
|
|
505
|
+
(cursor) => this.call("Customers_list", { query: { ...params, cursor } }, options),
|
|
506
|
+
params.cursor
|
|
507
|
+
);
|
|
508
|
+
}
|
|
509
|
+
retrieve(id, options) {
|
|
510
|
+
return this.call("Customers_retrieve", { path: { id } }, options);
|
|
511
|
+
}
|
|
512
|
+
update(id, params, options) {
|
|
513
|
+
return this.call("Customers_update", { path: { id }, body: params }, options);
|
|
514
|
+
}
|
|
515
|
+
/** Refused with 409 while the customer has a live subscription. */
|
|
516
|
+
delete(id, options) {
|
|
517
|
+
return this.call("Customers_remove", { path: { id } }, options);
|
|
518
|
+
}
|
|
519
|
+
};
|
|
520
|
+
var Prices = class extends APIResource {
|
|
521
|
+
create(params, options) {
|
|
522
|
+
return this.call("Prices_create", { body: params }, options);
|
|
523
|
+
}
|
|
524
|
+
/** Await for one page, or `for await` over every price. Filter with `product` and `active`. */
|
|
525
|
+
list(params = {}, options) {
|
|
526
|
+
return new PagePromise(
|
|
527
|
+
(cursor) => this.call("Prices_list", { query: { ...params, cursor } }, options),
|
|
528
|
+
params.cursor
|
|
529
|
+
);
|
|
530
|
+
}
|
|
531
|
+
retrieve(id, options) {
|
|
532
|
+
return this.call("Prices_retrieve", { path: { id } }, options);
|
|
533
|
+
}
|
|
534
|
+
/** Only `active`, `nickname` and `metadata` can change; create a new price for a new amount. */
|
|
535
|
+
update(id, params, options) {
|
|
536
|
+
return this.call("Prices_update", { path: { id }, body: params }, options);
|
|
537
|
+
}
|
|
538
|
+
};
|
|
539
|
+
var Subscriptions = class extends APIResource {
|
|
540
|
+
/** Pass `idempotencyKey` in options to retry safely. */
|
|
541
|
+
create(params, options) {
|
|
542
|
+
return this.call("Subscriptions_create", { body: params }, options);
|
|
543
|
+
}
|
|
544
|
+
/** Await for one page, or `for await` over every subscription (newest first). Filter with `customer`, `price`, `status`. */
|
|
545
|
+
list(params = {}, options) {
|
|
546
|
+
return new PagePromise(
|
|
547
|
+
(cursor) => this.call("Subscriptions_list", { query: { ...params, cursor } }, options),
|
|
548
|
+
params.cursor
|
|
549
|
+
);
|
|
550
|
+
}
|
|
551
|
+
retrieve(id, options) {
|
|
552
|
+
return this.call("Subscriptions_retrieve", { path: { id } }, options);
|
|
553
|
+
}
|
|
554
|
+
/** Changes apply from the next invoice. Set `cancelAtPeriodEnd` to cancel when the period ends. */
|
|
555
|
+
update(id, params, options) {
|
|
556
|
+
return this.call("Subscriptions_update", { path: { id }, body: params }, options);
|
|
557
|
+
}
|
|
558
|
+
/** Cancel now; its open invoices are voided. */
|
|
559
|
+
cancel(id, options) {
|
|
560
|
+
return this.call("Subscriptions_cancel", { path: { id } }, options);
|
|
561
|
+
}
|
|
562
|
+
};
|
|
563
|
+
var Invoices = class extends APIResource {
|
|
564
|
+
/** Await for one page, or `for await` over every invoice (newest first). Filter with `customer`, `subscription`, `status`. */
|
|
565
|
+
list(params = {}, options) {
|
|
566
|
+
return new PagePromise(
|
|
567
|
+
(cursor) => this.call("Invoices_list", { query: { ...params, cursor } }, options),
|
|
568
|
+
params.cursor
|
|
569
|
+
);
|
|
570
|
+
}
|
|
571
|
+
retrieve(id, options) {
|
|
572
|
+
return this.call("Invoices_retrieve", { path: { id } }, options);
|
|
573
|
+
}
|
|
574
|
+
/** Void an open invoice. */
|
|
575
|
+
void(id, options) {
|
|
576
|
+
return this.call("Invoices_void", { path: { id } }, options);
|
|
577
|
+
}
|
|
578
|
+
/** Stop chasing an open invoice; it can still be paid. */
|
|
579
|
+
markUncollectible(id, options) {
|
|
580
|
+
return this.call("Invoices_markUncollectible", { path: { id } }, options);
|
|
581
|
+
}
|
|
582
|
+
/** Record an open invoice as paid outside VEXPay (`paidOutOfBand: true`); no money moves. */
|
|
583
|
+
pay(id, params, options) {
|
|
584
|
+
return this.call("Invoices_pay", { path: { id }, body: params }, options);
|
|
585
|
+
}
|
|
586
|
+
};
|
|
587
|
+
var SetupSessions = class extends APIResource {
|
|
588
|
+
/** `url` is returned only here — send it to the customer. */
|
|
589
|
+
create(params, options) {
|
|
590
|
+
return this.call("SetupSessions_create", { body: params }, options);
|
|
591
|
+
}
|
|
592
|
+
retrieve(id, options) {
|
|
593
|
+
return this.call("SetupSessions_retrieve", { path: { id } }, options);
|
|
594
|
+
}
|
|
595
|
+
};
|
|
596
|
+
var PaymentMethods = class extends APIResource {
|
|
597
|
+
retrieve(id, options) {
|
|
598
|
+
return this.call("PaymentMethods_retrieve", { path: { id } }, options);
|
|
599
|
+
}
|
|
600
|
+
/** The method is never charged again. */
|
|
601
|
+
detach(id, options) {
|
|
602
|
+
return this.call("PaymentMethods_detach", { path: { id } }, options);
|
|
603
|
+
}
|
|
604
|
+
};
|
|
605
|
+
|
|
462
606
|
// src/resources/commerce.ts
|
|
463
607
|
var CheckoutSessions = class extends APIResource {
|
|
464
608
|
/** `clientSecret` is returned only here — hand it to the browser, never store or log it. */
|
|
@@ -828,6 +972,25 @@ var WEBHOOK_EVENT_NAMES = [
|
|
|
828
972
|
"tenant.api_key.rotated",
|
|
829
973
|
"tenant.api_key.revoked",
|
|
830
974
|
"tenant.live_status_changed",
|
|
975
|
+
"customer.created",
|
|
976
|
+
"customer.updated",
|
|
977
|
+
"customer.deleted",
|
|
978
|
+
"customer.subscription.created",
|
|
979
|
+
"customer.subscription.updated",
|
|
980
|
+
"customer.subscription.deleted",
|
|
981
|
+
"customer.subscription.trial_will_end",
|
|
982
|
+
"customer.subscription.reactivated",
|
|
983
|
+
"invoice.created",
|
|
984
|
+
"invoice.upcoming",
|
|
985
|
+
"invoice.paid",
|
|
986
|
+
"invoice.payment_attempt",
|
|
987
|
+
"invoice.payment_failed",
|
|
988
|
+
"invoice.overdue",
|
|
989
|
+
"invoice.voided",
|
|
990
|
+
"invoice.marked_uncollectible",
|
|
991
|
+
"payment_method.attached",
|
|
992
|
+
"payment_method.updated",
|
|
993
|
+
"payment_method.detached",
|
|
831
994
|
"notification.test"
|
|
832
995
|
];
|
|
833
996
|
var SIGNATURE_HEADER = "VexPay-Signature";
|
|
@@ -929,6 +1092,17 @@ var VexPay = class {
|
|
|
929
1092
|
paymentLinks;
|
|
930
1093
|
tenantPayoutAccount;
|
|
931
1094
|
webhookEndpoints;
|
|
1095
|
+
/** Billing: who you bill. */
|
|
1096
|
+
customers;
|
|
1097
|
+
/** Billing: recurring prices on products. */
|
|
1098
|
+
prices;
|
|
1099
|
+
/** Billing: bill a customer on a price every interval. */
|
|
1100
|
+
subscriptions;
|
|
1101
|
+
invoices;
|
|
1102
|
+
/** Billing: hosted links where a customer authorizes domiciliación. */
|
|
1103
|
+
setupSessions;
|
|
1104
|
+
/** Billing: domiciliación payment methods (bolívar methods your account takes: `payments.methods()`). */
|
|
1105
|
+
paymentMethods;
|
|
932
1106
|
/** Offline helpers: `constructEvent` verifies deliveries; no API calls. */
|
|
933
1107
|
webhooks = new Webhooks();
|
|
934
1108
|
constructor(apiKey, options = {}) {
|
|
@@ -963,6 +1137,12 @@ var VexPay = class {
|
|
|
963
1137
|
this.paymentLinks = new PaymentLinks(this.http);
|
|
964
1138
|
this.tenantPayoutAccount = new TenantPayoutAccount(this.http);
|
|
965
1139
|
this.webhookEndpoints = new WebhookEndpoints(this.http);
|
|
1140
|
+
this.customers = new Customers(this.http);
|
|
1141
|
+
this.prices = new Prices(this.http);
|
|
1142
|
+
this.subscriptions = new Subscriptions(this.http);
|
|
1143
|
+
this.invoices = new Invoices(this.http);
|
|
1144
|
+
this.setupSessions = new SetupSessions(this.http);
|
|
1145
|
+
this.paymentMethods = new PaymentMethods(this.http);
|
|
966
1146
|
}
|
|
967
1147
|
};
|
|
968
1148
|
// Annotate the CommonJS export names for ESM import in node:
|