API v1

Documentación

Integra recargas, facturas, remesas y Paso Rápido con una sola API REST. Peticiones y respuestas en JSON, sobre HTTPS.

Introducción

La URL base de producción es:

https://api.zenterapp.com/v1

Hay dos entornos, determinados por el prefijo de tu API key: zp_live_ para producción y zp_test_ para sandbox. El sandbox simula respuestas sin mover dinero real.

Todos los montos están en pesos dominicanos (DOP) con dos decimales.

Quickstart

Haz tu primera llamada en menos de un minuto. Con una key de sandbox, crea una recarga de prueba:

curl https://api.zenterapp.com/v1/recargas \
  -H "Authorization: Bearer zp_test_0c7d..." \
  -d carrier="Claro" -d account="8094128890" -d amount=100

Recibirás una transacción con status: "completed". Cambia tu key por una zp_live_ para procesar en producción.

Autenticación

Envía tu API key como Bearer token en el header Authorization de cada petición. Mantén tus keys en secreto y rótalas si se exponen.

curl https://api.zenterapp.com/v1/balance \
  -H "Authorization: Bearer zp_live_4f9a..."

Para evitar transacciones duplicadas ante reintentos de red, envía un header Idempotency-Key único por operación (un UUID). Si repites la misma key, la API devuelve el resultado de la primera petición sin volver a procesar.

curl https://api.zenterapp.com/v1/recargas \
  -H "Authorization: Bearer zp_live_4f9a..." \
  -H "Idempotency-Key: 9f1c2b7a-..." \
  -d carrier="Claro" -d account="8094128890" -d amount=200

Rate limits

El límite por defecto es de 100 peticiones por minuto por API key. Cada respuesta incluye los headers X-RateLimit-Remaining y X-RateLimit-Reset. Al excederlo recibirás un 429.

Listar operadores

GET/v1/operators

Devuelve los operadores disponibles y su categoría.

{
  "data": [
    { "id": "Claro", "category": "recarga", "group": "Telefonía móvil" },
    { "id": "Edenorte", "category": "factura", "group": "Electricidad" },
    { "id": "NATCASH", "category": "remesa", "group": "Remesas" }
  ]
}

Crear una recarga

POST/v1/recargas

Parámetros

`carrier`req	string	ID del operador (p. ej. Claro).
`account`req	string	Número de teléfono destino.
`amount`req	number	Monto en DOP.
`reference`	string	Referencia propia para conciliar.

curl https://api.zenterapp.com/v1/recargas \
  -H "Authorization: Bearer zp_live_4f9a..." \
  -d carrier="Claro" \
  -d account="8094128890" \
  -d amount=200 \
  -d reference="REF-1001"

Respuesta:

{
  "id": "txn_000174f3z",
  "status": "completed",
  "carrier": "Claro",
  "account": "8094128890",
  "amount": 200,
  "benefit": 8.00,
  "currency": "DOP",
  "created_at": "2026-06-18T15:00:00-04:00"
}

Pagar una factura

Primero consulta la cuenta para obtener el titular y el monto pendiente, luego confirma el pago.

GET/v1/facturas/lookup

POST/v1/facturas

Parámetros

`carrier`req	string	Operador de factura (p. ej. Edenorte).
`account`req	string	NIC, contrato o cuenta.
`amount`req	number	Monto a pagar en DOP.

# 1. Consultar
curl https://api.zenterapp.com/v1/facturas/lookup \
  -H "Authorization: Bearer zp_live_4f9a..." \
  -d carrier="Edenorte" -d account="7741203"

# 2. Pagar
curl https://api.zenterapp.com/v1/facturas \
  -H "Authorization: Bearer zp_live_4f9a..." \
  -d carrier="Edenorte" -d account="7741203" -d amount=1250

Enviar una remesa

POST/v1/remesas

Parámetros

`provider`req	string	NATCASH o MONCASH.
`account`req	string	Teléfono o billetera destino.
`amount`req	number	Monto en DOP.

curl https://api.zenterapp.com/v1/remesas \
  -H "Authorization: Bearer zp_live_4f9a..." \
  -d provider="NATCASH" \
  -d account="+50933441290" \
  -d amount=2500

Consultar balance

GET/v1/balance

Devuelve el balance disponible de tu wallet.

{
  "balance": 184350.75,
  "currency": "DOP"
}

Transacciones

GET/v1/transactions

GET/v1/transactions/:id

Query params

`category`	string	Filtra por recarga, factura, remesa o pasorapido.
`status`	string	Filtra por estado (completed, failed, …).
`limit`	number	Máximo de resultados (1–100, por defecto 25).
`starting_after`	string	Cursor de paginación (id de transacción).

curl "https://api.zenterapp.com/v1/transactions?category=recarga&limit=10" \
  -H "Authorization: Bearer zp_live_4f9a..."

Paginación

Los endpoints de listado usan paginación basada en cursor. Pasa el último id recibido en starting_after para obtener la siguiente página. La respuesta incluye has_more.

{
  "data": [ /* ... */ ],
  "has_more": true
}

Webhooks

Registra un endpoint para recibir eventos firmados cuando cambia el estado de una transacción. Verifica la firma con el secreto whsec_... usando el header X-Zenter-Signature.

{
  "event": "transaction.completed",
  "data": {
    "id": "txn_000174f3z",
    "status": "completed",
    "amount": 200
  }
}

Verificar la firma en Node.js:

import crypto from "crypto";

function verify(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Eventos: transaction.completed, transaction.failed, transaction.reversed, balance.low.

Objetos

Estos son los recursos principales que devuelve la API. Los mismos modelos se usan en el panel y en los webhooks.

El objeto Transaction

Campos

`id`	string	Identificador único (txn_…).
`reference`	string	Referencia del comercio.
`category`	enum	recarga · factura · remesa · pasorapido.
`carrier`	string	ID del operador.
`account`	string	Cuenta destino (teléfono, NIC…).
`amount`	number	Monto en DOP.
`benefit`	number	Ganancia del comercio (4% en recargas; 0 en facturas).
`currency`	string	Siempre “DOP”.
`status`	enum	pending · processing · completed · failed · reversed.
`channel`	enum	api · dashboard.
`created_at`	string	Fecha de creación (ISO 8601).
`updated_at`	string	Última actualización (ISO 8601).

El objeto Webhook

Campos

`id`	string	Identificador único (wh_…).
`url`	string	Endpoint HTTPS de destino.
`events`	array	Eventos suscritos.
`status`	enum	active · disabled.
`secret`	string	Secreto de firma (whsec_…).
`created_at`	string	Fecha de creación (ISO 8601).

Errores

Los errores devuelven un código HTTP y un cuerpo JSON con code y message.

{
  "error": {
    "code": "transaction_failed",
    "message": "El operador rechazó la transacción."
  }
}

Código	HTTP	Descripción
invalid_request	400	Faltan parámetros o son inválidos.
unauthorized	401	API key ausente o inválida.
insufficient_funds	402	Balance insuficiente en el wallet.
not_found	404	El recurso no existe.
transaction_failed	422	El operador rechazó la transacción.
rate_limited	429	Demasiadas peticiones.
carrier_unavailable	503	El operador no está disponible.

SDKs

Usa nuestras librerías oficiales para integrar más rápido. También puedes llamar la API directamente con cualquier cliente HTTP.

npm install @zenterpay/node

Documentación

Introducción

Quickstart

Autenticación

Idempotencia

Rate limits

Listar operadores

Crear una recarga

Pagar una factura

Enviar una remesa

Consultar balance

Transacciones

Paginación

Webhooks

Objetos

El objeto Transaction

El objeto Webhook

Errores

SDKs