@vexpay/node 0.11.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 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).
@@ -342,7 +379,7 @@ await vexpay.payments.c2p.execute(
342
379
 
343
380
  ## Pagination
344
381
 
345
- `list()` methods on payouts, merchants, and products return the first page when awaited, and every item when iterated:
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.11.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: