Endpoints

URL base: https://api.zelta.dev/pay/v1

Todos los endpoints requieren autenticación mediante clave API en el header Authorization. Las respuestas usan formato JSON. Los montos se expresan en centavos (ej: $50.00 = 5000).

Links de pago (Payment Links)

Listar links de pago

http

GET /payment-links

Parámetros de consulta:

Parámetro	Tipo	Descripción
`status`	string	`active`, `paid`, `expired`, `disabled`
`from`	datetime	Fecha de inicio del rango (ISO 8601)
`to`	datetime	Fecha de fin del rango (ISO 8601)
`page`	integer	Número de página (default: 1)
`per_page`	integer	Resultados por página (default: 20, max: 100)

Respuesta exitosa (200):

json

{
  "data": [
    {
      "id": "pl_abc123",
      "amount": 15000,
      "currency": "USD",
      "description": "Consultoría de marketing digital - Sesión de 1 hora",
      "url": "pay.zelta.dev/link/abc123",
      "status": "active",
      "payment_methods": ["visa", "mastercard", "yappy", "nequi"],
      "logo_url": "https://storage.zelta.dev/logos/mi-negocio.png",
      "expires_at": "2026-03-18T23:59:59Z",
      "created_at": "2026-03-11T10:00:00Z",
      "paid_at": null
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 20
  }
}

Crear link de pago

http

POST /payment-links

Cuerpo de la petición:

json

{
  "amount": 15000,
  "currency": "USD",
  "description": "Consultoría de marketing digital - Sesión de 1 hora",
  "payment_methods": ["visa", "mastercard", "amex", "yappy", "nequi", "ach"],
  "expires_at": "2026-03-18T23:59:59Z",
  "max_payments": 1,
  "reference": "INV-2026-042",
  "metadata": {
    "client_name": "Empresa ABC",
    "project": "Campaña Q1"
  }
}

Campos del cuerpo:

Campo	Tipo	Obligatorio	Descripción
`amount`	integer	Sí*	Monto en centavos. Omitir para monto abierto
`currency`	string	Sí	Código de moneda: `USD`, `PAB`
`description`	string	Sí	Descripción visible para el cliente
`payment_methods`	array	Sí	Métodos aceptados: `visa`, `mastercard`, `amex`, `yappy`, `nequi`, `ach`
`expires_at`	datetime	No	Fecha de expiración (ISO 8601)
`max_payments`	integer	No	Número máximo de pagos que acepta el link
`reference`	string	No	Referencia interna para tu control
`metadata`	object	No	Datos adicionales en formato clave-valor

Respuesta exitosa (201):

json

{
  "data": {
    "id": "pl_def456",
    "amount": 15000,
    "currency": "USD",
    "description": "Consultoría de marketing digital - Sesión de 1 hora",
    "url": "pay.zelta.dev/link/def456",
    "status": "active",
    "payment_methods": ["visa", "mastercard", "amex", "yappy", "nequi", "ach"],
    "expires_at": "2026-03-18T23:59:59Z",
    "max_payments": 1,
    "reference": "INV-2026-042",
    "metadata": {
      "client_name": "Empresa ABC",
      "project": "Campaña Q1"
    },
    "created_at": "2026-03-11T10:00:00Z"
  }
}

Obtener link de pago

http

GET /payment-links/{link_id}

Desactivar link de pago

http

DELETE /payment-links/{link_id}

Desactiva el link para que no acepte más pagos. Los pagos ya completados no se ven afectados.

Transacciones (Transactions)

Listar transacciones

http

GET /transactions

Parámetros de consulta:

Parámetro	Tipo	Descripción
`status`	string	`completed`, `pending`, `failed`, `refunded`
`payment_method`	string	`visa`, `mastercard`, `amex`, `yappy`, `nequi`, `ach`
`link_id`	string	Filtrar por link de pago
`from`	datetime	Fecha de inicio del rango
`to`	datetime	Fecha de fin del rango
`min_amount`	integer	Monto mínimo (centavos)
`max_amount`	integer	Monto máximo (centavos)
`page`	integer	Número de página
`per_page`	integer	Resultados por página

Respuesta exitosa (200):

json

{
  "data": [
    {
      "id": "txn_xyz789",
      "link_id": "pl_abc123",
      "amount": 15000,
      "currency": "USD",
      "description": "Consultoría de marketing digital - Sesión de 1 hora",
      "status": "completed",
      "payment_method": "visa",
      "card_last_four": "4242",
      "customer": {
        "email": "cliente@ejemplo.com",
        "name": "Juan Pérez"
      },
      "receipt_url": "pay.zelta.dev/receipts/txn_xyz789",
      "created_at": "2026-03-11T14:30:00Z",
      "completed_at": "2026-03-11T14:30:05Z"
    }
  ],
  "meta": {
    "total": 89,
    "page": 1,
    "per_page": 20
  }
}

Obtener transacción

http

GET /transactions/{transaction_id}

Reembolsar transacción

http

POST /transactions/{transaction_id}/refund

Cuerpo de la petición:

json

{
  "amount": 15000,
  "reason": "Solicitud del cliente"
}

Campo	Tipo	Obligatorio	Descripción
`amount`	integer	No	Monto a reembolsar en centavos. Si se omite, se reembolsa el total
`reason`	string	No	Motivo del reembolso

Respuesta exitosa (200):

json

{
  "data": {
    "id": "ref_abc123",
    "transaction_id": "txn_xyz789",
    "amount": 15000,
    "status": "processing",
    "reason": "Solicitud del cliente",
    "created_at": "2026-03-12T09:00:00Z"
  }
}

Reportes (Reports)

Resumen de ingresos

http

GET /reports/revenue

Parámetros de consulta:

Parámetro	Tipo	Descripción
`from`	datetime	Fecha de inicio (obligatorio)
`to`	datetime	Fecha de fin (obligatorio)
`group_by`	string	`day`, `week`, `month` (default: `day`)

Respuesta exitosa (200):

json

{
  "data": {
    "total_revenue": 1245000,
    "total_transactions": 89,
    "average_amount": 13988,
    "currency": "USD",
    "by_period": [
      {
        "date": "2026-03-01",
        "revenue": 425000,
        "transactions": 28
      },
      {
        "date": "2026-03-02",
        "revenue": 380000,
        "transactions": 31
      }
    ],
    "by_payment_method": {
      "visa": { "revenue": 560000, "transactions": 38 },
      "mastercard": { "revenue": 310000, "transactions": 22 },
      "yappy": { "revenue": 225000, "transactions": 18 },
      "nequi": { "revenue": 100000, "transactions": 8 },
      "ach": { "revenue": 50000, "transactions": 3 }
    }
  }
}

Reporte de liquidaciones

http

GET /reports/settlements

Parámetros de consulta:

Parámetro	Tipo	Descripción
`from`	datetime	Fecha de inicio
`to`	datetime	Fecha de fin
`status`	string	`processing`, `deposited`
`page`	integer	Número de página
`per_page`	integer	Resultados por página

Respuesta exitosa (200):

json

{
  "data": [
    {
      "id": "stl_abc123",
      "amount": 425000,
      "fees": 12750,
      "net_amount": 412250,
      "currency": "USD",
      "transactions_count": 28,
      "status": "deposited",
      "bank_account_last_four": "7890",
      "deposited_at": "2026-03-03T06:00:00Z",
      "period_from": "2026-03-01T00:00:00Z",
      "period_to": "2026-03-01T23:59:59Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 20
  }
}

Webhooks

Listar webhooks

http

GET /webhooks

Crear webhook

http

POST /webhooks

Cuerpo de la petición:

json

{
  "url": "https://tu-servidor.com/webhooks/zelta-pay",
  "events": ["payment.completed", "payment.refunded", "settlement.completed"],
  "secret": "whsec_tu_secreto_de_firma"
}

Obtener webhook

http

GET /webhooks/{webhook_id}

Actualizar webhook

http

PATCH /webhooks/{webhook_id}

Cuerpo de la petición:

json

{
  "events": ["payment.completed", "payment.failed", "payment.refunded"],
  "active": true
}

Eliminar webhook

http

DELETE /webhooks/{webhook_id}

Ejemplo completo: Crear link, consultar pago y generar reporte

bash

# 1. Crear un link de pago
curl -X POST https://api.zelta.dev/pay/v1/payment-links \
  -H "Authorization: Bearer zp_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 7500,
    "currency": "USD",
    "description": "Diseño de logo - Paquete básico",
    "payment_methods": ["visa", "mastercard", "yappy"],
    "expires_at": "2026-03-18T23:59:59Z",
    "reference": "LOGO-001"
  }'

# 2. Consultar transacciones del link
curl https://api.zelta.dev/pay/v1/transactions?link_id=pl_def456 \
  -H "Authorization: Bearer zp_live_abc123def456"

# 3. Generar reporte de ingresos del mes
curl "https://api.zelta.dev/pay/v1/reports/revenue?from=2026-03-01&to=2026-03-31&group_by=week" \
  -H "Authorization: Bearer zp_live_abc123def456"

Códigos de error

Código	Significado
`400`	Petición malformada o parámetros inválidos
`401`	Clave API inválida o no proporcionada
`403`	Permisos insuficientes para esta operación
`404`	Recurso no encontrado
`409`	Conflicto (ej: reembolso duplicado)
`422`	Datos de la petición no procesables (ej: monto negativo)
`429`	Límite de tasa excedido
`500`	Error interno del servidor

Formato de error:

json

{
  "error": "invalid_amount",
  "message": "El monto debe ser un número entero positivo expresado en centavos.",
  "status": 422
}

INFO

Los montos se expresan en centavos. Por ejemplo, $75.00 USD se envía como 7500. Todos los endpoints soportan paginación con page y per_page. Las fechas usan formato ISO 8601 con zona horaria. Los IDs de recursos usan prefijos descriptivos (pl_, txn_, ref_, stl_).

Endpoints ​

Links de pago (Payment Links) ​

Listar links de pago ​

Crear link de pago ​

Obtener link de pago ​

Desactivar link de pago ​

Transacciones (Transactions) ​

Listar transacciones ​

Obtener transacción ​

Reembolsar transacción ​

Reportes (Reports) ​

Resumen de ingresos ​

Reporte de liquidaciones ​

Webhooks ​

Listar webhooks ​

Crear webhook ​

Obtener webhook ​

Actualizar webhook ​

Eliminar webhook ​

Ejemplo completo: Crear link, consultar pago y generar reporte ​

Códigos de error ​

Endpoints

Links de pago (Payment Links)

Listar links de pago

Crear link de pago

Obtener link de pago

Desactivar link de pago

Transacciones (Transactions)

Listar transacciones

Obtener transacción

Reembolsar transacción

Reportes (Reports)

Resumen de ingresos

Reporte de liquidaciones

Webhooks

Listar webhooks

Crear webhook

Obtener webhook

Actualizar webhook

Eliminar webhook

Ejemplo completo: Crear link, consultar pago y generar reporte

Códigos de error