@vexpay/node 0.12.0 → 0.13.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
@@ -177,13 +177,28 @@ await vexpay.conversions.settings.update({ autoConvert: { COP: { percent: 50 } }
177
177
 
178
178
  ## Colombian pesos (COP)
179
179
 
180
- Collect pesos from buyers in Colombia through Bre-B, Nequi or Daviplata. Amounts are whole pesos, payments complete asynchronously (`payment.completed` / `payment.failed`), and completed payments go to your COP balance net of the COP fee. COP must be enabled on your account — otherwise the calls fail with `method_not_allowed` (403).
180
+ Collect pesos from buyers in Colombia through PSE, Bancolombia (transfer or QR), Bre-B, Nequi or Daviplata — and cards on the hosted checkout. Amounts are whole pesos, payments complete asynchronously (`payment.completed` / `payment.failed`), and completed payments go to your COP balance net of the COP fee. COP must be enabled on your account — otherwise the calls fail with `method_not_allowed` (403).
181
181
 
182
182
  ```ts
183
183
  import VexPay from '@vexpay/node';
184
184
 
185
185
  const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
186
186
 
187
+ // What your account can use now, the PSE banks, and the terms links some channels need.
188
+ const { channels, pseBanks, terms } = await vexpay.cop.channels();
189
+
190
+ // PSE: send the buyer to their bank (next.url). On redirect_pending, retrieve again in a few seconds.
191
+ const pse = await vexpay.cop.payments.create({
192
+ amountCop: 80000,
193
+ channel: 'pse',
194
+ pse: { bankCode: pseBanks![0]!.code },
195
+ buyer: {
196
+ firstName: 'Juan', lastName: 'Pérez', personType: 'natural', email: 'juan@example.com', phone: '3001234567',
197
+ documentType: 'CC', documentNumber: '1234567890', termsAccepted: true, // the buyer accepted `terms`
198
+ },
199
+ });
200
+ if (pse.next?.type === 'redirect') console.log('Send the buyer to', pse.next.url);
201
+
187
202
  // Bre-B: no buyer data. Show next.qrPngBase64 as an image and next.transferKey as text.
188
203
  const breb = await vexpay.cop.payments.create(
189
204
  { amountCop: 100000, channel: 'breb', reference: 'order-1042' },
@@ -194,10 +209,10 @@ const breb = await vexpay.cop.payments.create(
194
209
  await vexpay.cop.payments.create({
195
210
  amountCop: 50000,
196
211
  channel: 'nequi',
197
- buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890' },
212
+ buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890', termsAccepted: true },
198
213
  });
199
214
 
200
- // Daviplata: the buyer reads you the SMS code; submit it.
215
+ // Daviplata: with next.type 'submit_otp' the buyer reads you the SMS code; submit it (otherwise follow next.url).
201
216
  const davi = await vexpay.cop.payments.create({
202
217
  amountCop: 50000,
203
218
  channel: 'daviplata',
@@ -209,15 +224,17 @@ const status = (await vexpay.cop.payments.retrieve(breb.id)).status; // pending
209
224
  const { availableCop } = await vexpay.cop.balance.retrieve();
210
225
  ```
211
226
 
212
- `cancel(id)` cancels a pending payment and `refund(id)` refunds a completed one in full within 96 hours. A webhook for a COP payment has `data.method === 'COP'`; read it as `CopPaymentWebhookData`.
227
+ `cancel(id)` cancels a pending payment and `refund(id)` refunds a completed one in full (cards within 24 hours, Bre-B within 96 hours; channels without API refunds fail with `refund_not_supported`). Send `buyer.termsAccepted: true` for channels whose catalog entry has `needsTermsAcceptance`. A webhook for a COP payment has `data.method === 'COP'`; read it as `CopPaymentWebhookData`.
213
228
 
214
229
  **Test mode** (test API keys use a sandbox):
215
230
 
216
231
  | Channel | What to use | Result |
217
232
  |---|---|---|
218
233
  | Bre-B | No buyer data | QR and key from the sandbox. **Never send real money to them** — sandbox keys are reachable from real banks and the money is not credited. |
219
- | Nequi | Any valid data, e.g. phone `3001234567`, `CC` `1234567890`, any email | Completes on its own within about a minute |
220
- | Daviplata | Same buyer data (`CC`, `CE` or `TI` only) | OTP `123456`, `000000` or `111111` completes it; any other code fails with `invalid_otp` |
234
+ | Nequi | Phone `3991111111`, any valid document and email | Completes on its own within about a minute; `3992222222` is declined |
235
+ | Daviplata | Same buyer data (`CC`, `CE` or `TI` only) | With `submit_otp`, OTP `123456`, `000000` or `111111` completes it; any other code fails with `invalid_otp`. With `redirect`, follow the test page |
236
+ | PSE | Any valid buyer data | Bank code `1` approves, `2` declines |
237
+ | Card (hosted checkout) | `4242 4242 4242 4242`, any future expiry and CVC | Approved; `4111 1111 1111 1111` is declined |
221
238
 
222
239
  ## Subscriptions
223
240
 
@@ -315,6 +332,32 @@ const page = await vexpay.balance.transactions.list({ paymentId: 'pay_…', type
315
332
  console.log(page.items.map((m) => [m.type, m.amountVes]));
316
333
  ```
317
334
 
335
+ ## Top up your balance
336
+
337
+ Load your own Bs balance by Pago Móvil — for money that is not a sale (for example advertising income). Send the exact `amountVes` from `payerPhone` to the returned `receiver` before `expiresAt` (15 minutes); the top-up completes on its own when the transfer arrives, and its fee is charged then. The credit is held like any other credit unless you release it early with `instant` (for `instantFeeVes`). Each top-up needs a `sourceNote` and counts against your monthly limit (`topup_cap_exceeded`, 422, with `remainingUsd`/`remainingVes` in the error body). Top-ups are enabled per account (`topups_not_enabled`, 403). In balance movements they appear as `topup`, `topup_fee`, `topup_instant_release` and `topup_instant_fee`.
338
+
339
+ ```ts
340
+ import VexPay from '@vexpay/node';
341
+
342
+ const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
343
+
344
+ const topup = await vexpay.balance.topups.create({
345
+ amountVes: '100000.00',
346
+ payerPhone: '04121234567',
347
+ payerCedula: 'V12345678',
348
+ sourceNote: 'Ingresos publicidad quincena 2',
349
+ });
350
+ console.log(topup.receiver, topup.expiresAt); // where and until when to send the Pago Móvil
351
+
352
+ const { data, monthRemainingUsd } = await vexpay.balance.topups.list({ limit: 20 });
353
+ console.log(data.length, monthRemainingUsd); // newest first, plus what is left of this month's limit (USD)
354
+ const latest = await vexpay.balance.topups.retrieve(topup.id);
355
+ if (latest.status === 'completed' && latest.heldVes !== '0.00') {
356
+ await vexpay.balance.topups.instant(topup.id); // idempotent; `not_held` (409) when nothing is held
357
+ }
358
+ // Test mode only: await vexpay.balance.topups.simulate(topup.id);
359
+ ```
360
+
318
361
  ## Errors
319
362
 
320
363
  Every error extends `VexPayError` and carries `status`, the API `code` (e.g. `insufficient_balance`), and the response `body`.
@@ -377,6 +420,32 @@ await vexpay.payments.c2p.execute(
377
420
  );
378
421
  ```
379
422
 
423
+ ## Seller balances
424
+
425
+ Credit a seller from your platform balance in bolívares, or in dollars converted at the official BCV rate, then read their movements and monthly statement:
426
+
427
+ ```ts
428
+ import VexPay from '@vexpay/node';
429
+
430
+ const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
431
+ const merchantId = '00000000-0000-4000-8000-000000000002';
432
+
433
+ const balance = await vexpay.merchants.transfer(merchantId, { amountUsd: '100.00', transferKey: 'payroll-2026-11-u1' });
434
+ console.log(balance.pendingVes, balance.transfer.amountVes, balance.transfer.rate);
435
+
436
+ for await (const movement of vexpay.merchants.listTransactions(merchantId, { from: '2026-11-01T00:00:00Z' })) {
437
+ console.log(movement.type, movement.amountVes);
438
+ }
439
+
440
+ const statement = await vexpay.merchants.retrieveStatement(merchantId, { month: '2026-11' });
441
+ console.log(statement.openingVes, statement.closingVes, statement.movements.length);
442
+
443
+ const csv = await vexpay.merchants.retrieveStatementCsv(merchantId, { month: '2026-11' });
444
+ console.log(csv.split('\n')[0]);
445
+ ```
446
+
447
+ A transfer with `amountUsd` fails with `rate_unavailable` (503) when no BCV rate can be read; nothing is recorded.
448
+
380
449
  ## Pagination
381
450
 
382
451
  `list()` methods on payouts, merchants, products, customers, prices, subscriptions and invoices return the first page when awaited, and every item when iterated:
@@ -434,6 +503,7 @@ console.log(describe, {} as NewPayout, {} as Session);
434
503
  | `quotes` | `retrieve` |
435
504
  | `balance` | `retrieve` |
436
505
  | `balance.transactions` | `list` |
506
+ | `balance.topups` | `create`, `list`, `retrieve`, `instant`, `simulate` |
437
507
  | `payments` | `retrieve`, `retrieveByRef`, `reverse` |
438
508
  | `payments.c2p` | `request`, `execute` |
439
509
  | `payments.vpos` | `create` |
@@ -449,8 +519,9 @@ console.log(describe, {} as NewPayout, {} as Session);
449
519
  | `conversions.quotes` | `create` |
450
520
  | `conversions.settings` | `retrieve`, `update` |
451
521
  | `cop.payments` | `create`, `retrieve`, `submitOtp`, `cancel`, `refund` |
522
+ | `cop` | `channels` |
452
523
  | `cop.balance` | `retrieve` |
453
- | `merchants` | `create`, `list`, `retrieve`, `retrieveByRef`, `update`, `delete`, `retrieveBalance`, `transfer`, `listAuditEvents`, `startVerification`, `confirmVerification` |
524
+ | `merchants` | `create`, `list`, `retrieve`, `retrieveByRef`, `update`, `delete`, `retrieveBalance`, `transfer`, `listTransactions`, `retrieveStatement`, `retrieveStatementCsv`, `listAuditEvents`, `startVerification`, `confirmVerification` |
454
525
  | `merchants.payoutMethods` | `list`, `create`, `setDefault`, `delete`, `startVerification`, `confirmVerification` |
455
526
  | `payouts` | `create`, `createInstant`, `createBatch`, `list`, `retrieve`, `retrieveByRef` |
456
527
  | `products` | `create`, `list`, `retrieve`, `update`, `delete`, `createLink`, `listLinks` |
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.12.0";
110
+ var VERSION = "0.13.0";
111
111
 
112
112
  // src/core.ts
113
113
  var INITIAL_RETRY_DELAY_MS = 500;
@@ -270,6 +270,7 @@ var ROUTES = {
270
270
  ConversionSettings_update: { method: "PATCH", path: "/v1/conversions/settings" },
271
271
  CopPayments_balance: { method: "GET", path: "/v1/cop/balance" },
272
272
  CopPayments_cancel: { method: "POST", path: "/v1/cop/payments/{id}/cancel" },
273
+ CopPayments_channels: { method: "GET", path: "/v1/cop/channels" },
273
274
  CopPayments_create: { method: "POST", path: "/v1/cop/payments" },
274
275
  CopPayments_get: { method: "GET", path: "/v1/cop/payments/{id}" },
275
276
  CopPayments_refund: { method: "POST", path: "/v1/cop/payments/{id}/refund" },
@@ -300,10 +301,12 @@ var ROUTES = {
300
301
  Merchants_listAuditEvents: { method: "GET", path: "/v1/merchants/{id}/audit-events" },
301
302
  Merchants_listOrGetByRef: { method: "GET", path: "/v1/merchants" },
302
303
  Merchants_listPayoutMethods: { method: "GET", path: "/v1/merchants/{id}/payout-methods" },
304
+ Merchants_listTransactions: { method: "GET", path: "/v1/merchants/{id}/transactions" },
303
305
  Merchants_remove: { method: "DELETE", path: "/v1/merchants/{id}" },
304
306
  Merchants_setDefaultPayoutMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods/{methodId}/default" },
305
307
  Merchants_startVerify: { method: "POST", path: "/v1/merchants/{id}/verify/start" },
306
308
  Merchants_startVerifyMethod: { method: "POST", path: "/v1/merchants/{id}/payout-methods/{methodId}/verify/start" },
309
+ Merchants_statement: { method: "GET", path: "/v1/merchants/{id}/statement" },
307
310
  Merchants_transfer: { method: "POST", path: "/v1/merchants/{id}/transfers" },
308
311
  Merchants_update: { method: "PATCH", path: "/v1/merchants/{id}" },
309
312
  Notifications_sendTest: { method: "POST", path: "/v1/notifications/test" },
@@ -362,6 +365,11 @@ var ROUTES = {
362
365
  TenantPayoutAccount_startVerify: { method: "POST", path: "/v1/tenant/payout-account/verify/start" },
363
366
  TenantPayoutAccount_upsert: { method: "PUT", path: "/v1/tenant/payout-account" },
364
367
  TenantPayoutAccount_upsertPost: { method: "POST", path: "/v1/tenant/payout-account" },
368
+ Topups_create: { method: "POST", path: "/v1/balance/topups" },
369
+ Topups_get: { method: "GET", path: "/v1/balance/topups/{id}" },
370
+ Topups_instant: { method: "POST", path: "/v1/balance/topups/{id}/instant" },
371
+ Topups_list: { method: "GET", path: "/v1/balance/topups" },
372
+ Topups_simulate: { method: "POST", path: "/v1/balance/topups/{id}/simulate" },
365
373
  Webhooks_createWebhook: { method: "POST", path: "/v1/webhooks" },
366
374
  Webhooks_deleteWebhook: { method: "DELETE", path: "/v1/webhooks/{id}" },
367
375
  Webhooks_listWebhooks: { method: "GET", path: "/v1/webhooks" },
@@ -412,8 +420,30 @@ var BalanceTransactions = class extends APIResource {
412
420
  );
413
421
  }
414
422
  };
423
+ var BalanceTopups = class extends APIResource {
424
+ /** Start a top-up. Over the monthly limit fails with `topup_cap_exceeded` (422). */
425
+ create(params, options) {
426
+ return this.call("Topups_create", { body: params }, options);
427
+ }
428
+ /** Your latest top-ups (newest first, `limit` 1–100) plus this month's limit usage. */
429
+ list(params = {}, options) {
430
+ return this.call("Topups_list", { query: params }, options);
431
+ }
432
+ retrieve(id, options) {
433
+ return this.call("Topups_get", { path: { id } }, options);
434
+ }
435
+ /** Release the still-held part of a completed top-up now, for `instantFeeVes`. Idempotent; `not_held` (409) if nothing is held. */
436
+ instant(id, options) {
437
+ return this.call("Topups_instant", { path: { id } }, options);
438
+ }
439
+ /** Test mode only: complete the top-up as if the Pago Móvil arrived. */
440
+ simulate(id, options) {
441
+ return this.call("Topups_simulate", { path: { id } }, options);
442
+ }
443
+ };
415
444
  var Balance = class extends APIResource {
416
445
  transactions = new BalanceTransactions(this.http);
446
+ topups = new BalanceTopups(this.http);
417
447
  retrieve(options) {
418
448
  return this.call("Balance_getBalance", {}, options);
419
449
  }
@@ -701,8 +731,10 @@ var Conversions = class extends APIResource {
701
731
  // src/resources/cop.ts
702
732
  var CopPayments = class extends APIResource {
703
733
  /**
704
- * Create a payment in whole pesos. `buyer` is required for `nequi` and `daviplata`. The response
705
- * `next` says what the buyer does: `show_qr`, `approve_in_app` or `submit_otp`.
734
+ * Create a payment in whole pesos. `buyer` is required for every channel except `breb`, with
735
+ * `termsAccepted: true` when {@link Cop.channels} says `needsTermsAcceptance`; `pse` also needs
736
+ * `pse.bankCode`. The response `next` says what the buyer does: `show_qr`, `approve_in_app`,
737
+ * `submit_otp`, `redirect` (send them to `next.url`) or `redirect_pending` (retrieve again shortly).
706
738
  * Pass `idempotencyKey` in options to retry safely.
707
739
  */
708
740
  create(params, options) {
@@ -711,7 +743,7 @@ var CopPayments = class extends APIResource {
711
743
  retrieve(id, options) {
712
744
  return this.call("CopPayments_get", { path: { id } }, options);
713
745
  }
714
- /** Daviplata: submit the code the buyer received by SMS. A wrong code fails with `invalid_otp`. */
746
+ /** Daviplata with `next.type: "submit_otp"`: submit the code the buyer received by SMS. A wrong code fails with `invalid_otp`. */
715
747
  submitOtp(id, params, options) {
716
748
  return this.call("CopPayments_submitOtp", { path: { id }, body: params }, options);
717
749
  }
@@ -719,7 +751,10 @@ var CopPayments = class extends APIResource {
719
751
  cancel(id, options) {
720
752
  return this.call("CopPayments_cancel", { path: { id } }, options);
721
753
  }
722
- /** Full refund of a completed payment, within 96 hours. */
754
+ /**
755
+ * Full refund of a completed payment, within the channel's window (card 24 h, Bre-B 96 h).
756
+ * Channels that cannot be refunded through the API fail with `refund_not_supported`.
757
+ */
723
758
  refund(id, options) {
724
759
  return this.call("CopPayments_refund", { path: { id } }, options);
725
760
  }
@@ -732,6 +767,10 @@ var CopBalance = class extends APIResource {
732
767
  var Cop = class extends APIResource {
733
768
  payments = new CopPayments(this.http);
734
769
  balance = new CopBalance(this.http);
770
+ /** Channels you can use right now, with what each needs, plus the PSE banks and terms links. */
771
+ channels(options) {
772
+ return this.call("CopPayments_channels", {}, options);
773
+ }
735
774
  };
736
775
 
737
776
  // src/resources/crypto.ts
@@ -828,10 +867,34 @@ var Merchants = class extends APIResource {
828
867
  retrieveBalance(id, options) {
829
868
  return this.call("Merchants_getBalance", { path: { id } }, options);
830
869
  }
831
- /** Move VES between this merchant's balance and another. */
870
+ /**
871
+ * Credit this seller's pending balance from your platform balance. Send `amountVes`, or
872
+ * `amountUsd` to convert at the official BCV rate; `transferKey` makes it idempotent.
873
+ * The response is the seller balance plus `transfer` (amounts and rate used).
874
+ */
832
875
  transfer(id, params, options) {
833
876
  return this.call("Merchants_transfer", { path: { id }, body: params }, options);
834
877
  }
878
+ /** Seller balance movements, newest first. Await for one page, or `for await` over every movement. */
879
+ listTransactions(id, params = {}, options) {
880
+ return new PagePromise(
881
+ (cursor) => this.call("Merchants_listTransactions", { path: { id }, query: { ...params, cursor } }, options),
882
+ params.cursor
883
+ );
884
+ }
885
+ /** Monthly statement (`month: 'YYYY-MM'`, America/Caracas): opening, movements, closing. */
886
+ retrieveStatement(id, params, options) {
887
+ return this.call("Merchants_statement", { path: { id }, query: { ...params, format: "json" } }, options);
888
+ }
889
+ /** The same monthly statement as CSV (with a running balance column), returned as a string. */
890
+ async retrieveStatementCsv(id, params, options) {
891
+ const body = await this.call(
892
+ "Merchants_statement",
893
+ { path: { id }, query: { ...params, format: "csv" } },
894
+ options
895
+ );
896
+ return typeof body === "string" ? body : "";
897
+ }
835
898
  listAuditEvents(id, options) {
836
899
  return this.call("Merchants_listAuditEvents", { path: { id } }, options);
837
900
  }