@vexpay/node 0.15.0 → 0.18.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 +17 -31
- package/dist/index.cjs +23 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +694 -462
- package/dist/index.d.ts +694 -462
- package/dist/index.js +23 -13
- 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';
|
|
@@ -180,27 +180,15 @@ await vexpay.conversions.settings.update({ autoConvert: { COP: { percent: 50 } }
|
|
|
180
180
|
|
|
181
181
|
## Colombian pesos (COP)
|
|
182
182
|
|
|
183
|
-
Collect pesos from buyers in Colombia through
|
|
183
|
+
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).
|
|
184
184
|
|
|
185
185
|
```ts
|
|
186
186
|
import VexPay from '@vexpay/node';
|
|
187
187
|
|
|
188
188
|
const vexpay = new VexPay(process.env.VEXPAY_API_KEY!);
|
|
189
189
|
|
|
190
|
-
// What your account can use now,
|
|
191
|
-
const { channels
|
|
192
|
-
|
|
193
|
-
// PSE: send the buyer to their bank (next.url). On redirect_pending, retrieve again in a few seconds.
|
|
194
|
-
const pse = await vexpay.cop.payments.create({
|
|
195
|
-
amountCop: 80000,
|
|
196
|
-
channel: 'pse',
|
|
197
|
-
pse: { bankCode: pseBanks![0]!.code },
|
|
198
|
-
buyer: {
|
|
199
|
-
firstName: 'Juan', lastName: 'Pérez', personType: 'natural', email: 'juan@example.com', phone: '3001234567',
|
|
200
|
-
documentType: 'CC', documentNumber: '1234567890', termsAccepted: true, // the buyer accepted `terms`
|
|
201
|
-
},
|
|
202
|
-
});
|
|
203
|
-
if (pse.next?.type === 'redirect') console.log('Send the buyer to', pse.next.url);
|
|
190
|
+
// What your account can use now (Bre-B, Nequi, Daviplata) and what each needs.
|
|
191
|
+
const { channels } = await vexpay.cop.channels();
|
|
204
192
|
|
|
205
193
|
// Bre-B: no buyer data. Show next.qrPngBase64 as an image and next.transferKey as text.
|
|
206
194
|
const breb = await vexpay.cop.payments.create(
|
|
@@ -212,10 +200,10 @@ const breb = await vexpay.cop.payments.create(
|
|
|
212
200
|
await vexpay.cop.payments.create({
|
|
213
201
|
amountCop: 50000,
|
|
214
202
|
channel: 'nequi',
|
|
215
|
-
buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890'
|
|
203
|
+
buyer: { email: 'juan@example.com', phone: '3001234567', documentType: 'CC', documentNumber: '1234567890' },
|
|
216
204
|
});
|
|
217
205
|
|
|
218
|
-
// Daviplata: with next.type 'submit_otp' the buyer reads you the SMS code; submit it
|
|
206
|
+
// Daviplata: with next.type 'submit_otp' the buyer reads you the SMS code; submit it.
|
|
219
207
|
const davi = await vexpay.cop.payments.create({
|
|
220
208
|
amountCop: 50000,
|
|
221
209
|
channel: 'daviplata',
|
|
@@ -227,7 +215,7 @@ const status = (await vexpay.cop.payments.retrieve(breb.id)).status; // pending
|
|
|
227
215
|
const { availableCop } = await vexpay.cop.balance.retrieve();
|
|
228
216
|
```
|
|
229
217
|
|
|
230
|
-
`cancel(id)` cancels a pending payment and `refund(id)` refunds a completed one in full
|
|
218
|
+
`cancel(id)` cancels a pending payment and `refund(id)` refunds a completed one in full within 96 hours (a payment that can no longer be refunded through the API fails with `refund_not_supported`). A webhook for a COP payment has `data.method === 'COP'`; read it as `CopPaymentWebhookData`.
|
|
231
219
|
|
|
232
220
|
**Test mode** (test API keys use a sandbox):
|
|
233
221
|
|
|
@@ -235,13 +223,11 @@ const { availableCop } = await vexpay.cop.balance.retrieve();
|
|
|
235
223
|
|---|---|---|
|
|
236
224
|
| 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. |
|
|
237
225
|
| Nequi | Phone `3991111111`, any valid document and email | Completes on its own within about a minute; `3992222222` is declined |
|
|
238
|
-
| 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
|
|
239
|
-
| PSE | Any valid buyer data | Bank code `1` approves, `2` declines |
|
|
240
|
-
| Card (hosted checkout) | `4242 4242 4242 4242`, any future expiry and CVC | Approved; `4111 1111 1111 1111` is declined |
|
|
226
|
+
| 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` |
|
|
241
227
|
|
|
242
228
|
## Subscriptions
|
|
243
229
|
|
|
244
|
-
Bill a customer on a recurring USD price. Each period
|
|
230
|
+
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
231
|
|
|
246
232
|
```ts
|
|
247
233
|
import VexPay from '@vexpay/node';
|
|
@@ -274,7 +260,7 @@ for await (const method of vexpay.customers.paymentMethods.list(customer.id)) {
|
|
|
274
260
|
await vexpay.subscriptions.update(subscription.id, { cancelAtPeriodEnd: true });
|
|
275
261
|
```
|
|
276
262
|
|
|
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
|
|
263
|
+
`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
264
|
|
|
279
265
|
## Testing card payments
|
|
280
266
|
|
|
@@ -282,7 +268,7 @@ With a test API key, VPOS test cards return a fixed outcome without reaching the
|
|
|
282
268
|
|
|
283
269
|
## Webhooks
|
|
284
270
|
|
|
285
|
-
|
|
271
|
+
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
272
|
|
|
287
273
|
```ts
|
|
288
274
|
import VexPay from '@vexpay/node';
|
|
@@ -403,7 +389,7 @@ try {
|
|
|
403
389
|
|
|
404
390
|
## Retries and idempotency
|
|
405
391
|
|
|
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
|
|
392
|
+
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
393
|
|
|
408
394
|
```ts
|
|
409
395
|
import VexPay from '@vexpay/node';
|
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.18.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" },
|
|
@@ -615,7 +617,7 @@ var Invoices = class extends APIResource {
|
|
|
615
617
|
markUncollectible(id, options) {
|
|
616
618
|
return this.call("Invoices_markUncollectible", { path: { id } }, options);
|
|
617
619
|
}
|
|
618
|
-
/** Record an open invoice as paid outside
|
|
620
|
+
/** Record an open invoice as paid outside VEX Pay (`paidOutOfBand: true`); no money moves. */
|
|
619
621
|
pay(id, params, options) {
|
|
620
622
|
return this.call("Invoices_pay", { path: { id }, body: params }, options);
|
|
621
623
|
}
|
|
@@ -764,10 +766,8 @@ var Conversions = class extends APIResource {
|
|
|
764
766
|
// src/resources/cop.ts
|
|
765
767
|
var CopPayments = class extends APIResource {
|
|
766
768
|
/**
|
|
767
|
-
* Create a payment in whole pesos. `buyer` is required for every channel except `breb
|
|
768
|
-
*
|
|
769
|
-
* `pse.bankCode`. The response `next` says what the buyer does: `show_qr`, `approve_in_app`,
|
|
770
|
-
* `submit_otp`, `redirect` (send them to `next.url`) or `redirect_pending` (retrieve again shortly).
|
|
769
|
+
* Create a payment in whole pesos. `buyer` is required for every channel except `breb`. The
|
|
770
|
+
* response `next` says what the buyer does: `show_qr`, `approve_in_app` or `submit_otp`.
|
|
771
771
|
* Pass `idempotencyKey` in options to retry safely.
|
|
772
772
|
*/
|
|
773
773
|
create(params, options) {
|
|
@@ -785,8 +785,8 @@ var CopPayments = class extends APIResource {
|
|
|
785
785
|
return this.call("CopPayments_cancel", { path: { id } }, options);
|
|
786
786
|
}
|
|
787
787
|
/**
|
|
788
|
-
* Full refund of a completed payment, within
|
|
789
|
-
*
|
|
788
|
+
* Full refund of a completed payment, within 96 hours of completion. A payment that can no
|
|
789
|
+
* longer be refunded through the API fails with `refund_not_supported`.
|
|
790
790
|
*/
|
|
791
791
|
refund(id, options) {
|
|
792
792
|
return this.call("CopPayments_refund", { path: { id } }, options);
|
|
@@ -800,7 +800,7 @@ var CopBalance = class extends APIResource {
|
|
|
800
800
|
var Cop = class extends APIResource {
|
|
801
801
|
payments = new CopPayments(this.http);
|
|
802
802
|
balance = new CopBalance(this.http);
|
|
803
|
-
/** Channels you can use right now, with what each needs
|
|
803
|
+
/** Channels you can use right now, with what each needs. */
|
|
804
804
|
channels(options) {
|
|
805
805
|
return this.call("CopPayments_channels", {}, options);
|
|
806
806
|
}
|
|
@@ -879,8 +879,18 @@ var PayoutMethods = class extends APIResource {
|
|
|
879
879
|
);
|
|
880
880
|
}
|
|
881
881
|
};
|
|
882
|
+
var MarketplaceSettings = class extends APIResource {
|
|
883
|
+
retrieve(options) {
|
|
884
|
+
return this.call("MarketplaceSettings_get", {}, options);
|
|
885
|
+
}
|
|
886
|
+
/** `merchantAutoPayoutDefault` and/or `merchantAutoPayoutMinUsd` (USD; null clears it). */
|
|
887
|
+
update(params, options) {
|
|
888
|
+
return this.call("MarketplaceSettings_update", { body: params }, options);
|
|
889
|
+
}
|
|
890
|
+
};
|
|
882
891
|
var Merchants = class extends APIResource {
|
|
883
892
|
payoutMethods = new PayoutMethods(this.http);
|
|
893
|
+
marketplaceSettings = new MarketplaceSettings(this.http);
|
|
884
894
|
/** `externalRef` is required and is the idempotency key for merchant creation. */
|
|
885
895
|
create(params, options) {
|
|
886
896
|
return this.call("Merchants_create", { body: params }, options);
|
|
@@ -1216,7 +1226,7 @@ var VexPay = class {
|
|
|
1216
1226
|
constructor(apiKey, options = {}) {
|
|
1217
1227
|
if (typeof apiKey !== "string" || apiKey.trim() === "") {
|
|
1218
1228
|
throw new VexPayConfigurationError(
|
|
1219
|
-
"A
|
|
1229
|
+
"A VEX Pay API key is required: new VexPay(process.env.VEXPAY_API_KEY)."
|
|
1220
1230
|
);
|
|
1221
1231
|
}
|
|
1222
1232
|
const fetchImpl = options.fetch ?? globalThis.fetch;
|