CLI

La CLI de Onflay (onflay) es la forma más rápida de arrancar un proyecto de integración sin tocar el dashboard. Define tu catálogo en un archivo TypeScript, aplícalo al entorno y genera tipos listos para usar en tu backend, todo desde la terminal.

Instalación y autenticación

No necesitas instalar nada de forma global. Usa npx directamente o agrégala como devDependency:

# Sin instalación
npx onflay --help

# Como devDependency (recomendado para proyectos)
pnpm add -D onflay

Autentica exportando tu API key de sandbox:

export ONFLAY_API_KEY=sk_test_...

Agrega ONFLAY_API_KEY a tu archivo .env y cárgalo con dotenv-cli o el mecanismo de tu framework. La CLI lo detecta automáticamente. También puedes usar onflay whoami para validar entorno y base URL resuelta.

Flujo CLI-first para un proyecto nuevo

Puedes configurar toda tu integración sin abrir el dashboard:

Scaffold inicial (opcional)

Ejecuta npx onflay init para crear pricing.onflay.ts, webhook route y .env.example automáticamente.

Crea el archivo de catálogo

Define tus productos, precios o listings en pricing.onflay.ts.

Revisa el plan

Ejecuta catalog plan para ver qué se creará o modificará sin aplicar nada.

Aplica el catálogo

Ejecuta catalog apply para sincronizar el archivo con tu entorno sandbox.

Genera los tipos

Ejecuta catalog sync para aplicar + generar tipos en un solo comando (o catalog codegen si ya aplicaste antes).

Levanta el túnel de webhooks

Ejecuta onflay listen para recibir eventos en tu servidor local.

Dispara un evento de prueba

Ejecuta onflay trigger para simular un pago completado y probar tu handler.

Catálogo declarativo

El catálogo es un archivo .ts que exporta la definición de lo que vendes. La CLI lo lee, calcula la diferencia con el entorno y aplica solo los cambios necesarios — similar a Terraform para tu catálogo de Onflay.

Estructura del archivo

// pricing.onflay.ts
import { defineCatalog } from 'onflay/catalog';

export default defineCatalog({
  products: [
    {
      nickname: 'pro_plan',
      name: 'Plan Pro',
      description: 'Acceso completo a todas las funciones.',
      prices: [
        {
          nickname: 'pro_monthly',
          amount: 2900,
          currency: 'usd',
          interval: 'month',
        },
        {
          nickname: 'pro_annual',
          amount: 29000,
          currency: 'usd',
          interval: 'year',
        },
      ],
    },
    {
      nickname: 'starter_plan',
      name: 'Plan Starter',
      description: 'Para proyectos personales y pruebas.',
      prices: [
        {
          nickname: 'starter_monthly',
          amount: 900,
          currency: 'usd',
          interval: 'month',
        },
      ],
    },
  ],
});

El campo nickname es tu identificador local estable. No lo cambies sin usar antes onflay catalog mv, o la CLI lo tratará como un objeto nuevo.

Pagos únicos

Para productos sin recurrencia, omite interval:

prices: [
  {
    nickname: 'ebook_usd',
    amount: 1500,
    currency: 'usd',
  },
],

Comandos del catálogo

`catalog plan` — previsualizar cambios

Muestra qué se creará, actualizará o archivará sin modificar nada en el entorno.

npx onflay catalog plan pricing.onflay.ts

Salida de ejemplo:

~ Plan Pro               (actualizar descripción)
+ Plan Starter           (crear)
+ Starter mensual        (crear price)
  Pro mensual            (sin cambios)
  Pro anual              (sin cambios)

Úsalo en CI para detectar drift entre el archivo y el entorno. Con --exit-code, la CLI termina con código 2 cuando detecta drift:

npx onflay catalog plan pricing.onflay.ts --exit-code

`catalog apply` — aplicar cambios

Sincroniza el archivo con el entorno activo según la API key configurada.

npx onflay catalog apply pricing.onflay.ts

apply modifica objetos en el entorno apuntado por ONFLAY_API_KEY. Con sk_test_ toca sandbox; con sk_live_ toca producción. Revisa siempre el plan antes.

`catalog codegen` — generar tipos TypeScript

Genera un archivo con los IDs reales de Onflay mapeados a tus keys, listo para importar en tu backend:

npx onflay catalog codegen pricing.onflay.ts --out src/onflay-catalog.ts

Archivo generado (src/onflay-catalog.ts):

// Archivo generado automáticamente — no editar manualmente
export const catalog = {
  products: {
    pro_plan: 'cmpulbdci00004moh85qpsd6k',
    starter_plan: 'cmpuql04c000p4mn3iumpcaxf',
  },
  prices: {
    pro_monthly: 'cmpulbdci00004moh85qpsd6k:cmpulbdcm00014mohsjolsvoq',
    pro_annual: 'cmpulbdci00004moh85qpsd6k:cmpulbdcn00024mohsjolsvoq',
    starter_monthly: 'cmpuql04c000p4mn3iumpcaxf:cmpuql04f000q4mn3w0iz64m1',
  },
} as const;

Úsalo directamente al crear sesiones de checkout (modo compatibilidad lineItems):

import { catalog } from '@/onflay-catalog';
import { Onflay } from '@onflay/node';

const onflay = new Onflay(process.env.ONFLAY_API_KEY!);

const session = await onflay.checkoutSessions.create({
  lineItems: [{ priceId: catalog.prices['pro-monthly'].id, quantity: 1 }],
  successUrl: 'https://tu-app.com/gracias',
  cancelUrl: 'https://tu-app.com/precios',
});

`catalog sync` — apply + codegen en un solo paso

npx onflay catalog sync pricing.onflay.ts --out src/onflay-catalog.ts --yes

`catalog mv` — renombrar claves sin recrear objetos

Si quieres renombrar un nickname sin que el siguiente apply lo trate como “borrado + creado”, usa:

npx onflay catalog mv pricing.onflay.ts pro_plan pro_plus_plan

Webhooks locales

Levanta un túnel para recibir eventos de Onflay en tu servidor local durante el desarrollo:

npx onflay listen --forward-to http://localhost:3000/api/webhooks/onflay

La CLI imprime un secret temporal que expira al cerrar el proceso:

  connected to https://sandbox-api.onflay.com (sandbox)

  ready
    Webhook secret: whsec_dev_...
    Forwarding events ▸ http://localhost:3000/api/webhooks/onflay
    Press Ctrl+C to stop.

La CLI también intenta guardarlo automáticamente en .env.local en el directorio actual. Si prefieres configurarlo manualmente, expórtalo para que tu handler lo use:

export ONFLAY_WEBHOOK_SECRET=whsec_dev_...

O agrégalo a tu .env.local si tu framework lo carga automáticamente.

En producción usa el secret permanente del dashboard, no el whsec_dev_... que genera listen.

Disparar eventos de prueba

Simula un evento sin necesitar un pago real:

npx onflay trigger payment.completed

Eventos disponibles para trigger:

Evento	Descripción
`payment.completed`	Pago exitoso procesado
`payment.refunded`	Reembolso emitido
`payout.scheduled`	Payout en cola
`payout.completed`	Payout completado
`payout.failed`	Payout fallido
`dispute.opened`	Disputa abierta
`dispute.resolved`	Disputa resuelta
`subscription.created`	Nueva suscripción (primer pago exitoso)
`subscription.renewed`	Renovación de suscripción
`subscription.canceled`	Suscripción cancelada
`subscription.expired`	Suscripción expirada
`subscription.dunning`	Reintento de cobro
`invoice.created`	Invoice creada
`invoice.finalized`	Invoice finalizada
`invoice.paid`	Invoice pagada

trigger solo funciona en sandbox. No lo uses con sk_live_.

Gestión de eventos

Consulta y reenvía eventos pasados del entorno:

# Listar eventos recientes
npx onflay events list

# Ver detalle de un evento
npx onflay events show evt_...

# Reenviar un evento al webhook configurado
npx onflay events resend evt_...

events resend es útil para reprobar un handler sin crear una transacción nueva.

Scripts recomendados en `package.json`

{
  "scripts": {
    "catalog:plan": "onflay catalog plan pricing.onflay.ts",
    "catalog:apply": "onflay catalog apply pricing.onflay.ts",
    "catalog:sync": "onflay catalog sync pricing.onflay.ts --out src/onflay-catalog.ts --yes",
    "webhooks:dev": "onflay listen --forward-to http://localhost:3000/api/webhooks/onflay"
  }
}

Con esto puedes correr pnpm catalog:plan antes de cada deploy para verificar que el catálogo esté sincronizado.

Empezar

Para creadores

Desarrolladores

Conceptos operativos

Instalación y autenticación

Flujo CLI-first para un proyecto nuevo

Catálogo declarativo

Estructura del archivo

Pagos únicos

Comandos del catálogo

`catalog plan` — previsualizar cambios

`catalog apply` — aplicar cambios

`catalog codegen` — generar tipos TypeScript

`catalog sync` — apply + codegen en un solo paso

`catalog mv` — renombrar claves sin recrear objetos

Webhooks locales

Disparar eventos de prueba

Gestión de eventos

Scripts recomendados en `package.json`

​Instalación y autenticación

​Flujo CLI-first para un proyecto nuevo

​Catálogo declarativo

​Estructura del archivo

​Pagos únicos

​Comandos del catálogo

​catalog plan — previsualizar cambios

​catalog apply — aplicar cambios

​catalog codegen — generar tipos TypeScript

​catalog sync — apply + codegen en un solo paso

​catalog mv — renombrar claves sin recrear objetos

​Webhooks locales

​Disparar eventos de prueba

​Gestión de eventos

​Scripts recomendados en package.json

Instalación y autenticación

Flujo CLI-first para un proyecto nuevo

Catálogo declarativo

Estructura del archivo

Pagos únicos

Comandos del catálogo

`catalog plan` — previsualizar cambios

`catalog apply` — aplicar cambios

`catalog codegen` — generar tipos TypeScript

`catalog sync` — apply + codegen en un solo paso

`catalog mv` — renombrar claves sin recrear objetos

Webhooks locales

Disparar eventos de prueba

Gestión de eventos

Scripts recomendados en `package.json`