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

http

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`, `completed`, `expired`, `cancelled`
`isTest`	`boolean`	—	Filtrar por modo de prueba: `true` o `false`
`paymentProvider`	`string`	—	Filtrar por proveedor de pago: `yappy`, `card`

Ejemplos de solicitud

Solicitud básica

:: tab cURL

bash

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

:: tab Node.js

javascript

const response = await fetch('https://api-pay.zelta.dev/v1/payment-links', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ZELTA_API_KEY,
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

:: tab Python

python

import requests

response = requests.get(
    'https://api-pay.zelta.dev/v1/payment-links',
    headers={
        'X-API-Key': 'tu-api-key-aqui',
        'Content-Type': 'application/json'
    }
)

result = response.json()
print(result)

Con paginación

:: tab cURL

bash

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"

:: tab Node.js

javascript

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

const result = await response.json();
console.log(`Mostrando ${result.data.paymentLinks.length} de ${result.data.total}`);

:: tab Python

python

import requests

response = requests.get(
    'https://api-pay.zelta.dev/v1/payment-links',
    params={'lim': 20, 'off': 40},
    headers={
        'X-API-Key': 'tu-api-key-aqui',
        'Content-Type': 'application/json'
    }
)

result = response.json()
print(f"Mostrando {len(result['data']['paymentLinks'])} de {result['data']['total']}")

Con filtros

:: tab cURL

bash

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"

:: tab Node.js

javascript

const params = new URLSearchParams({
  status: 'pending',
  isTest: 'false',
  lim: '10'
});

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

const result = await response.json();
console.log(result);

:: tab Python

python

import requests

response = requests.get(
    'https://api-pay.zelta.dev/v1/payment-links',
    params={
        'status': 'pending',
        'isTest': 'false',
        'lim': 10
    },
    headers={
        'X-API-Key': 'tu-api-key-aqui',
        'Content-Type': 'application/json'
    }
)

result = response.json()
print(result)

Formato de respuesta

json

{
  "success": true,
  "data": {
    "paymentLinks": [
      {
        "id": "pl_1234567890abcdef",
        "hashUrl": "abc123def456",
        "paymentLinkUrl": "https://pay.zelta.dev/abc123def456",
        "customerName": "Maria Garcia",
        "customerEmail": "[email protected]",
        "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`, `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

json

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

API key inválida

json

{
  "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

:: tab Node.js

javascript

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;
}

:: tab Python

python

import requests

def get_all_payment_links():
    all_links = []
    offset = 0
    limit = 50

    while True:
        response = requests.get(
            'https://api-pay.zelta.dev/v1/payment-links',
            params={'lim': limit, 'off': offset},
            headers={
                'X-API-Key': 'tu-api-key-aqui',
                'Content-Type': 'application/json'
            }
        )

        result = response.json()

        if not result.get('success'):
            raise Exception(f"Error: {result['error']['code']}")

        all_links.extend(result['data']['paymentLinks'])

        if len(all_links) >= result['data']['total']:
            break

        offset += limit

    return all_links

Filtrar links por estado

javascript

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:

javascript

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:

javascript

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:

javascript

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) 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

Listar Links de Pago ​

Endpoint ​

Autenticación ​

Parámetros de consulta ​

Ejemplos de solicitud ​

Solicitud básica ​

Con paginación ​

Con filtros ​

Formato de respuesta ​

Campos de la respuesta ​

Códigos de estado ​

Respuestas de error ​

API key faltante ​

API key inválida ​

Ejemplos de implementación ​

Obtener todos los links con paginación ​

Filtrar links por estado ​

Casos de uso ​

Vista general del dashboard ​

Gestión de órdenes ​

Análisis de pagos ​

Buenas prácticas ​

Siguientes pasos ​

Listar Links de Pago

Endpoint

Autenticación

Parámetros de consulta

Ejemplos de solicitud

Solicitud básica

Con paginación

Con filtros

Formato de respuesta

Campos de la respuesta

Códigos de estado

Respuestas de error

API key faltante

API key inválida

Ejemplos de implementación

Obtener todos los links con paginación

Filtrar links por estado

Casos de uso

Vista general del dashboard

Gestión de órdenes

Análisis de pagos

Buenas prácticas

Siguientes pasos