@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 +62 -3
- package/dist/index.cjs +65 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1142 -128
- package/dist/index.d.ts +1142 -128
- package/dist/index.js +65 -4
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
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.
|
|
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.
|
|
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
|
-
/**
|
|
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);
|