@ventipay/ventipay NPM

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.