Librería oficial de VentiPay para Node.js

Esta librería provee un acceso conveniente a la API REST de VentiPay para aplicaciones Node.js.

Instalación

Instala la librería utilizando tu package manager favorito.

npm install @ventipay/ventipay
# o
yarn add @ventipay/ventipay

Nota: La librería requiere Node.js 12+.

Uso

La idea de esta librería es reflejar lo más posible el diseño de nuestra API para que, sólo leyendo su documentación, puedas entenderla y utilizarla de manera rápida y simple.

Por cada recurso disponible en la API encontrarás un recurso en esta librería y por cada uno de estos recursos encontrarás acciones a ejecutar sobre ellos.

Inicio

El primer paso es requerir la librería y pasarle tu API Key. Puedes obtener una API Key en el Dashboard de VentiPay y recuerda que esta puede ser usada en modo live o test.

// Requiere la librería y crea el cliente de VentiPay
const ventipay = require('@ventipay/ventipay')('key_test_...'); // Provee tu API Key de modo live o test como primer parámetro del cliente

Ya puedes utilizar la librería y ejecutar acciones sobre los recursos de la API.

Recursos y acciones

La librería ahora te entrega un listado de recursos de la API con sus respectivas acciones. Un recurso se ve reflejado como una propiedad del cliente recién creado y cada acción como un método asociado a esta propiedad.

Ejemplo

// Llamando al método retrieve del recurso checkouts y pasando 2 parámetros.
const checkout = ventipay.checkouts.retrieve('chk_KaIq81HaHvaPq91c8FaK1ua6R', {
    expand: ['customer'],
});

// Imprimiendo el atributo id
console.log(checkout.id);

En este ejemplo se accede al recurso checkouts y al método retrieve. El método recibe 2 parámetros: el ID del recurso a obtener y el atributo opcional expand. Finalmente, se imprime el atributo id del recurso obtenido.

Usualmente los métodos que obtienen o actualizan un recurso (create, update, etc.) reciben un ID como primer parámetro y opciones como segundo parámetro, en cambio los métodos que listan recursos (list) reciben opciones como primer parámetro.

Estas opciones corresponden a los query params o body params encontrados en la documentación de la API.

Listado de recursos

API Pagos

| Recurso | Métodos | | ------ | ------ | | checkouts | retrieve, list, create, refund | | payments | retrieve, list, create, update, refund, capture | | refunds | retrieve, list |

API Suscripciones

| Recurso | Métodos | | ------ | ------ | | subscriptions | retrieve, list, create, update, cancel, suspend, unsuspend | | invoices | retrieve, list, create, update, finalize, pay, send, markUncollectible, void | | products | retrieve, list, create, update |

API Clientes

| Recurso | Métodos | | ------ | ------ | | customers | retrieve, list, create, update |

API Métodos de pago

| Recurso | Métodos | | ------ | ------ | | payment_methods | retrieve, list | | setup_intents | retrieve, create, update, del |

API Eventos

| Recurso | Métodos | | ------ | ------ | | events | retrieve, list |

API Finanzas

| Recurso | Métodos | | ------ | ------ | | balance_transactions | retrieve, list | | payouts | retrieve, list |

Promesas

Los métodos provistos por la librería retornan siempre una Promesa (Promise), por lo que puedes utilizar async/await o then/catch según tu preferencia.

Versionamiento

Utilizamos SemVer para el versionamiento, por lo que puedes actualizar de manera segura cambios a nivel minor y patch.

Changelog

Utilizamos la página de releases de GitHub para documentar cada release.

License

MIT