@vexpay/node 0.5.0 → 0.7.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
@@ -87,6 +87,8 @@ if (current.status === 'paid') {
87
87
  }
88
88
  ```
89
89
 
90
+ The hosted page lets the buyer pick the currency — bolívares, stablecoins or Colombian pesos — and offers every method your account accepts. Limit it with `methods` (`c2p`, `vpos`, `usdt`, `usdc`, `cop`).
91
+
90
92
  ## USDT
91
93
 
92
94
  USDT settles in USDT, into your VEXPay 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()`.
@@ -144,9 +146,9 @@ await vexpay.crypto.payouts.create({
144
146
 
145
147
  Responses and events include `currency`, `amount` and `fee` for both coins (`amountUsdt` / `feeUsdt` stay on USDT only). Credit your customer in the `currency` the webhook reports.
146
148
 
147
- ## Convert VES to USDT
149
+ ## Convert VES or COP to USDT
148
150
 
149
- Turn available VES into your USDT balance. A quote locks the rate (market USDT/VES rate plus your spread) for 60 seconds; accepting it debits the VES at once and returns a `PENDING` conversion. VEXPay then delivers the USDT and sends `conversion.completed` (or `conversion.canceled`, with the VES returned). Conversions are on for every account that has USDT enabled — otherwise the calls fail with `conversions_not_enabled` (403). In test mode they complete immediately.
151
+ 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. VEXPay 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.
150
152
 
151
153
  ```ts
152
154
  import VexPay from '@vexpay/node';
@@ -162,11 +164,65 @@ const conversion = await vexpay.conversions.create(
162
164
  );
163
165
 
164
166
  for await (const c of vexpay.conversions.list({ status: 'PENDING' })) {
165
- console.log(c.id, c.sourceAmountVes, '→', c.targetAmountUsdt);
167
+ console.log(c.id, c.sourceAmount, c.sourceCurrency, '→', c.targetAmountUsdt);
166
168
  }
167
169
  await vexpay.conversions.cancel(conversion.id); // only while PENDING
170
+
171
+ // Colombian pesos: same flow with sourceCurrency 'COP'.
172
+ const copQuote = await vexpay.conversions.quotes.create({ sourceCurrency: 'COP', sourceAmount: '1000000' });
173
+
174
+ // Auto-convert 50% of each completed COP payment (after the fee) to USDT; 0 turns it off.
175
+ await vexpay.conversions.settings.update({ autoConvert: { COP: { percent: 50 } } });
168
176
  ```
169
177
 
178
+ ## Colombian pesos (COP)
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).
181
+
182
+ ```ts
183
+ import VexPay from '@vexpay/node';
184
+
185
+ const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
186
+
187
+ // Bre-B: no buyer data. Show next.qrPngBase64 as an image and next.transferKey as text.
188
+ const breb = await vexpay.cop.payments.create(
189
+ { amountCop: 100000, channel: 'breb', reference: 'order-1042' },
190
+ { idempotencyKey: 'order-1042-cop' },
191
+ );
192
+
193
+ // Nequi: the buyer approves a push in the Nequi app.
194
+ await vexpay.cop.payments.create({
195
+ amountCop: 50000,
196
+ channel: 'nequi',
197
+ buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890' },
198
+ });
199
+
200
+ // Daviplata: the buyer reads you the SMS code; submit it.
201
+ const davi = await vexpay.cop.payments.create({
202
+ amountCop: 50000,
203
+ channel: 'daviplata',
204
+ buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890' },
205
+ });
206
+ await vexpay.cop.payments.submitOtp(davi.id, { otp: '123456' });
207
+
208
+ const status = (await vexpay.cop.payments.retrieve(breb.id)).status; // pending | completed | failed | canceled | refunded
209
+ const { availableCop } = await vexpay.cop.balance.retrieve();
210
+ ```
211
+
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`.
213
+
214
+ **Test mode** (test API keys use a sandbox):
215
+
216
+ | Channel | What to use | Result |
217
+ |---|---|---|
218
+ | 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` |
221
+
222
+ ## Testing card payments
223
+
224
+ 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).
225
+
170
226
  ## Webhooks
171
227
 
172
228
  VEXPay 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.
@@ -354,6 +410,9 @@ console.log(describe, {} as NewPayout, {} as Session);
354
410
  | `crypto.payouts` | `create`, `retrieve` |
355
411
  | `conversions` | `create`, `list`, `retrieve`, `cancel` |
356
412
  | `conversions.quotes` | `create` |
413
+ | `conversions.settings` | `retrieve`, `update` |
414
+ | `cop.payments` | `create`, `retrieve`, `submitOtp`, `cancel`, `refund` |
415
+ | `cop.balance` | `retrieve` |
357
416
  | `merchants` | `create`, `list`, `retrieve`, `retrieveByRef`, `update`, `delete`, `retrieveBalance`, `transfer`, `listAuditEvents`, `startVerification`, `confirmVerification` |
358
417
  | `merchants.payoutMethods` | `list`, `create`, `setDefault`, `delete`, `startVerification`, `confirmVerification` |
359
418
  | `payouts` | `create`, `createInstant`, `createBatch`, `list`, `retrieve`, `retrieveByRef` |
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.5.0";
110
+ var VERSION = "0.7.0";
111
111
 
112
112
  // src/core.ts
113
113
  var INITIAL_RETRY_DELAY_MS = 500;
@@ -266,6 +266,14 @@ var ROUTES = {
266
266
  Conversions_createQuote: { method: "POST", path: "/v1/conversions/quotes" },
267
267
  Conversions_get: { method: "GET", path: "/v1/conversions/{id}" },
268
268
  Conversions_list: { method: "GET", path: "/v1/conversions" },
269
+ ConversionSettings_get: { method: "GET", path: "/v1/conversions/settings" },
270
+ ConversionSettings_update: { method: "PATCH", path: "/v1/conversions/settings" },
271
+ CopPayments_balance: { method: "GET", path: "/v1/cop/balance" },
272
+ CopPayments_cancel: { method: "POST", path: "/v1/cop/payments/{id}/cancel" },
273
+ CopPayments_create: { method: "POST", path: "/v1/cop/payments" },
274
+ CopPayments_get: { method: "GET", path: "/v1/cop/payments/{id}" },
275
+ CopPayments_refund: { method: "POST", path: "/v1/cop/payments/{id}/refund" },
276
+ CopPayments_submitOtp: { method: "POST", path: "/v1/cop/payments/{id}/otp" },
269
277
  Crypto_createDepositAddress: { method: "POST", path: "/v1/crypto/deposit-addresses" },
270
278
  Crypto_createPayout: { method: "POST", path: "/v1/crypto/payouts" },
271
279
  Crypto_getBalance: { method: "GET", path: "/v1/crypto/balance" },
@@ -505,13 +513,26 @@ var PaymentLinks = class extends APIResource {
505
513
 
506
514
  // src/resources/conversions.ts
507
515
  var ConversionQuotes = class extends APIResource {
508
- /** Send `sourceAmountVes` (VES to spend) or `targetAmountUsdt` (USDT to receive) — exactly one. */
516
+ /**
517
+ * `sourceCurrency` is `'VES'` (default) or `'COP'`. Send `sourceAmount` (to spend; COP in whole pesos)
518
+ * or `targetAmountUsdt` (USDT to receive) — exactly one. VES may still use `sourceAmountVes`.
519
+ */
509
520
  create(params, options) {
510
521
  return this.call("Conversions_createQuote", { body: params }, options);
511
522
  }
512
523
  };
524
+ var ConversionSettings = class extends APIResource {
525
+ retrieve(options) {
526
+ return this.call("ConversionSettings_get", {}, options);
527
+ }
528
+ /** Only `autoConvert.COP.percent` (0–100, whole number; 0 = off) can be changed. */
529
+ update(params, options) {
530
+ return this.call("ConversionSettings_update", { body: params }, options);
531
+ }
532
+ };
513
533
  var Conversions = class extends APIResource {
514
534
  quotes = new ConversionQuotes(this.http);
535
+ settings = new ConversionSettings(this.http);
515
536
  /** Accept a quote (`quoteId`). Pass `idempotencyKey` in options to retry safely. */
516
537
  create(params, options) {
517
538
  return this.call("Conversions_create", { body: params }, options);
@@ -519,19 +540,55 @@ var Conversions = class extends APIResource {
519
540
  retrieve(id, options) {
520
541
  return this.call("Conversions_get", { path: { id } }, options);
521
542
  }
522
- /** Await for one page, or `for await` over every conversion (newest first). */
543
+ /** Await for one page, or `for await` over every conversion (newest first). Filter with `sourceCurrency`. */
523
544
  list(params = {}, options) {
524
545
  return new PagePromise(
525
546
  (cursor) => this.call("Conversions_list", { query: { ...params, cursor } }, options),
526
547
  params.cursor
527
548
  );
528
549
  }
529
- /** Cancel a `PENDING` conversion; the VES returns to your available balance. */
550
+ /** Cancel a `PENDING` conversion; the VES or COP returns to your available balance. */
530
551
  cancel(id, options) {
531
552
  return this.call("Conversions_cancel", { path: { id } }, options);
532
553
  }
533
554
  };
534
555
 
556
+ // src/resources/cop.ts
557
+ var CopPayments = class extends APIResource {
558
+ /**
559
+ * Create a payment in whole pesos. `buyer` is required for `nequi` and `daviplata`. The response
560
+ * `next` says what the buyer does: `show_qr`, `approve_in_app` or `submit_otp`.
561
+ * Pass `idempotencyKey` in options to retry safely.
562
+ */
563
+ create(params, options) {
564
+ return this.call("CopPayments_create", { body: params }, options);
565
+ }
566
+ retrieve(id, options) {
567
+ return this.call("CopPayments_get", { path: { id } }, options);
568
+ }
569
+ /** Daviplata: submit the code the buyer received by SMS. A wrong code fails with `invalid_otp`. */
570
+ submitOtp(id, params, options) {
571
+ return this.call("CopPayments_submitOtp", { path: { id }, body: params }, options);
572
+ }
573
+ /** Cancel a pending payment. */
574
+ cancel(id, options) {
575
+ return this.call("CopPayments_cancel", { path: { id } }, options);
576
+ }
577
+ /** Full refund of a completed payment, within 96 hours. */
578
+ refund(id, options) {
579
+ return this.call("CopPayments_refund", { path: { id } }, options);
580
+ }
581
+ };
582
+ var CopBalance = class extends APIResource {
583
+ retrieve(options) {
584
+ return this.call("CopPayments_balance", {}, options);
585
+ }
586
+ };
587
+ var Cop = class extends APIResource {
588
+ payments = new CopPayments(this.http);
589
+ balance = new CopBalance(this.http);
590
+ };
591
+
535
592
  // src/resources/crypto.ts
536
593
  var CryptoBalance = class extends APIResource {
537
594
  retrieve(params = {}, options) {
@@ -757,6 +814,7 @@ var WEBHOOK_EVENT_NAMES = [
757
814
  "merchant.wallet_credit",
758
815
  "payout.completed",
759
816
  "payout.failed",
817
+ "conversion.created",
760
818
  "conversion.completed",
761
819
  "conversion.canceled",
762
820
  "tenant.status_changed",
@@ -859,6 +917,8 @@ var VexPay = class {
859
917
  crypto;
860
918
  /** Convert available VES to USDT (enabled per account). */
861
919
  conversions;
920
+ /** Colombian pesos: Bre-B, Nequi and Daviplata payments and the COP balance. */
921
+ cop;
862
922
  products;
863
923
  paymentLinks;
864
924
  tenantPayoutAccount;
@@ -892,6 +952,7 @@ var VexPay = class {
892
952
  this.payouts = new Payouts(this.http);
893
953
  this.crypto = new Crypto(this.http);
894
954
  this.conversions = new Conversions(this.http);
955
+ this.cop = new Cop(this.http);
895
956
  this.products = new Products(this.http);
896
957
  this.paymentLinks = new PaymentLinks(this.http);
897
958
  this.tenantPayoutAccount = new TenantPayoutAccount(this.http);