Listar Links de Pago

Obtén una lista paginada de tus links de pago con opciones de filtrado por estado, modo de prueba y proveedor de pago.

Endpoint

GET /v1/payment-links

Autenticación

Requiere el header X-API-Key. Consulta la .

Parámetros de consulta

Parámetro	Tipo	Default	Descripción
lim	integer	10	Cantidad de resultados por página (máx. 100)
off	integer	0	Número de resultados a saltar
status	string	—	Filtrar por estado: pending, processing, completed, expired, cancelled
isTest	boolean	—	Filtrar por modo de prueba: true o false
paymentProvider	string	—	Filtrar por proveedor de pago: yappy, card
linkType	string	—	Filtrar por tipo de link: one_time, customer_collection, customer_payment
search	string	—	Buscar por nombre del cliente

Ejemplos de solicitud

Solicitud básica

curl -X GET "https://api-pay.zelta.dev/v1/payment-links" \
  -H "X-API-Key: tu-api-key-aqui" \
  -H "Content-Type: application/json"

Con paginación

curl -X GET "https://api-pay.zelta.dev/v1/payment-links?lim=20&off=40" \
  -H "X-API-Key: tu-api-key-aqui" \
  -H "Content-Type: application/json"

Con filtros

curl -X GET "https://api-pay.zelta.dev/v1/payment-links?status=pending&isTest=false&lim=10" \
  -H "X-API-Key: tu-api-key-aqui" \
  -H "Content-Type: application/json"

Formato de respuesta

{
  "success": true,
  "data": {
    "paymentLinks": [
      {
        "id": "pl_1234567890abcdef",
        "hashUrl": "abc123def456",
        "paymentLinkUrl": "https://pay.zelta.dev/abc123def456",
        "customerName": "Maria Garcia",
        "customerEmail": "maria@ejemplo.com",
        "concept": "Pago de servicio mensual",
        "amount": 5000,
        "status": "pending",
        "isTest": false,
        "paymentMethods": ["card", "yappy"],
        "requestCustomerEmail": false,
        "redirectUrl": "https://mitienda.com/confirmacion",
        "metadata": {
          "orderId": "ORD-2026-0042"
        },
        "createdAt": "2026-03-13T10:30:00.000Z",
        "expiresAt": "2026-03-16T10:30:00.000Z"
      }
    ],
    "total": 1
  },
  "message": "Payment links retrieved successfully",
  "timestamp": "2026-03-13T10:30:00.000Z"
}

Campos de la respuesta

Campo	Tipo	Descripción
paymentLinks	array	Lista de links de pago
total	integer	Total de links que coinciden con los filtros
paymentLinks[].id	string	Identificador único del link
paymentLinks[].hashUrl	string	Hash único usado en la URL de pago
paymentLinks[].paymentLinkUrl	string	URL completa de la página de pago
paymentLinks[].customerName	string	Nombre del cliente
paymentLinks[].customerEmail	string	Email del cliente (si fue proporcionado)
paymentLinks[].concept	string	Concepto o descripción del cobro
paymentLinks[].amount	integer	Monto en centavos
paymentLinks[].status	string	Estado: pending, processing, completed, expired, cancelled
paymentLinks[].isTest	boolean	Si es un link de prueba
paymentLinks[].paymentMethods	array	Métodos de pago habilitados ("yappy", "card")
paymentLinks[].requestCustomerEmail	boolean	Si se solicita email al cliente en la página de pago
paymentLinks[].redirectUrl	string	URL de redirección después del pago
paymentLinks[].metadata	object	Datos personalizados asociados al link
paymentLinks[].createdAt	string	Fecha de creación (ISO 8601)
paymentLinks[].expiresAt	string	Fecha de expiración (ISO 8601)

Códigos de estado

Código	Descripción
200	Lista obtenida exitosamente
401	API key faltante o inválida
404	API key no encontrada
429	Rate limit excedido

Respuestas de error

API key faltante

{
  "success": false,
  "error": {
    "code": "ERR_MISSING_API_KEY",
    "message": "API key is required"
  },
  "timestamp": "2026-03-13T10:30:00.000Z"
}

API key inválida

{
  "success": false,
  "error": {
    "code": "ERR_API_KEY_NOT_FOUND",
    "message": "API key not found"
  },
  "timestamp": "2026-03-13T10:30:00.000Z"
}

Ejemplos de implementación

Obtener todos los links con paginación

async function getAllPaymentLinks() {
  const allLinks = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api-pay.zelta.dev/v1/payment-links?lim=${limit}&off=${offset}`,
      {
        headers: {
          'X-API-Key': process.env.ZELTA_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    const result = await response.json();

    if (!result.success) {
      throw new Error(`Error: ${result.error.code}`);
    }

    allLinks.push(...result.data.paymentLinks);

    if (allLinks.length >= result.data.total) {
      break;
    }

    offset += limit;
  }

  return allLinks;
}

Filtrar links por estado

async function getPaymentLinksByStatus(status) {
  const response = await fetch(
    `https://api-pay.zelta.dev/v1/payment-links?status=${status}`,
    {
      headers: {
        'X-API-Key': process.env.ZELTA_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();

  if (!result.success) {
    throw new Error(`Error: ${result.error.code}`);
  }

  return result.data;
}

// Obtener solo links pendientes
const pending = await getPaymentLinksByStatus('pending');

// Obtener solo links completados
const completed = await getPaymentLinksByStatus('completed');

Casos de uso

Vista general del dashboard

Usa la paginación para mostrar links de pago en una tabla con navegación por páginas:

async function getDashboardPage(page, perPage = 20) {
  const offset = (page - 1) * perPage;

  const response = await fetch(
    `https://api-pay.zelta.dev/v1/payment-links?lim=${perPage}&off=${offset}`,
    {
      headers: {
        'X-API-Key': process.env.ZELTA_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();
  const totalPages = Math.ceil(result.data.total / perPage);

  return {
    links: result.data.paymentLinks,
    total: result.data.total,
    currentPage: page,
    totalPages
  };
}

Gestión de órdenes

Filtra links pendientes para hacer seguimiento a pagos no completados:

async function getPendingOrders() {
  const response = await fetch(
    'https://api-pay.zelta.dev/v1/payment-links?status=pending&isTest=false',
    {
      headers: {
        'X-API-Key': process.env.ZELTA_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();
  return result.data.paymentLinks;
}

Análisis de pagos

Obtén links completados para generar reportes:

async function getCompletedPayments() {
  const response = await fetch(
    'https://api-pay.zelta.dev/v1/payment-links?status=completed&isTest=false',
    {
      headers: {
        'X-API-Key': process.env.ZELTA_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();
  const totalAmount = result.data.paymentLinks.reduce(
    (sum, link) => sum + link.amount, 0
  );

  return {
    count: result.data.total,
    totalAmountCents: totalAmount,
    totalAmountDollars: (totalAmount / 100).toFixed(2)
  };
}

Buenas prácticas

• Usa paginación: no intentes obtener todos los links en una sola solicitud. Usa lim y off para paginar.
• Filtra en el servidor: usa los parámetros de consulta (status, isTest, paymentProvider, linkType, search) en lugar de filtrar en tu aplicación.
• Respeta el rate limit: si necesitas obtener muchos links, espacia las solicitudes para no exceder las 60 por minuto.
• Maneja errores: siempre verifica el campo success antes de procesar los datos.

Siguientes pasos

• — Crea un nuevo link de pago
• — Consulta un link específico
• — Cancela un link pendiente
• — Recibe notificaciones de pago en tiempo real