Obtener Link de Pago

Obtén los detalles completos de un link de pago específico usando su hashUrl.

Endpoint

GET /v1/payment-links/{hashUrl}

Parámetros de ruta

Parámetro	Tipo	Descripción
hashUrl	string	Hash único del link de pago (presente en la URL de pago)

Autenticación

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

Ejemplos de solicitud

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

Formato de respuesta

{
  "success": true,
  "data": {
    "paymentLink": {
      "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"
    }
  },
  "message": "Payment link retrieved successfully",
  "timestamp": "2026-03-13T10:30:00.000Z"
}

Campos de la respuesta

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

Códigos de estado

Código	Descripción
200	Link obtenido exitosamente
401	API key faltante
404	Link de pago no encontrado o API key inválida
429	Rate limit excedido

Respuestas de error

Link no encontrado

{
  "success": false,
  "error": {
    "code": "ERR_PAYMENT_LINK_NOT_FOUND",
    "message": "Payment link not found"
  },
  "timestamp": "2026-03-13T10:30:00.000Z"
}

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 un link con manejo de errores

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

    const result = await response.json();

    if (!result.success) {
      console.error('Error:', result.error.code, result.error.message);
      return null;
    }

    return result.data.paymentLink;
  } catch (error) {
    console.error('Error de red:', error.message);
    return null;
  }
}

const link = await getPaymentLink('abc123def456');
if (link) {
  console.log(`Estado: ${link.status}, Monto: $${(link.amount / 100).toFixed(2)}`);
}

Verificar estado de un link

async function checkPaymentStatus(hashUrl) {
  const link = await getPaymentLink(hashUrl);

  if (!link) {
    return { found: false };
  }

  return {
    found: true,
    status: link.status,
    isPaid: link.status === 'completed',
    isPending: link.status === 'pending',
    isExpired: link.status === 'expired',
    isCancelled: link.status === 'cancelled',
    amount: link.amount,
    customerName: link.customerName
  };
}

Verificar estado de una orden

async function checkOrderStatus(hashUrl) {
  const link = await getPaymentLink(hashUrl);

  if (!link) {
    return { error: 'Link de pago no encontrado' };
  }

  switch (link.status) {
    case 'completed':
      return {
        status: 'paid',
        message: `Pago completado por ${link.customerName}`,
        orderId: link.metadata?.orderId
      };
    case 'pending':
      return {
        status: 'awaiting_payment',
        message: 'Esperando pago del cliente',
        paymentUrl: link.paymentLinkUrl,
        expiresAt: link.expiresAt
      };
    case 'expired':
      return {
        status: 'expired',
        message: 'El link de pago expiró sin recibir pago'
      };
    case 'cancelled':
      return {
        status: 'cancelled',
        message: 'El link de pago fue cancelado'
      };
  }
}

Casos de uso

Página de estado de orden

Usa este endpoint para mostrar el estado actualizado de un pago en tu sitio web:

app.get('/ordenes/:hashUrl/estado', async (req, res) => {
  const link = await getPaymentLink(req.params.hashUrl);

  if (!link) {
    return res.status(404).json({ error: 'Orden no encontrada' });
  }

  res.json({
    orderId: link.metadata?.orderId,
    status: link.status,
    amount: `$${(link.amount / 100).toFixed(2)}`,
    customerName: link.customerName
  });
});

Verificación de pago

Verifica si un pago se completó antes de entregar un producto o servicio:

async function verifyPayment(hashUrl) {
  const link = await getPaymentLink(hashUrl);

  if (!link) {
    throw new Error('Link de pago no encontrado');
  }

  if (link.status !== 'completed') {
    throw new Error(`Pago no completado. Estado actual: ${link.status}`);
  }

  return {
    verified: true,
    amount: link.amount,
    customerName: link.customerName,
    metadata: link.metadata
  };
}

Atención al cliente

Consulta los detalles de un link de pago para resolver dudas de tus clientes:

async function getPaymentDetails(hashUrl) {
  const link = await getPaymentLink(hashUrl);

  if (!link) {
    return 'Link de pago no encontrado';
  }

  return {
    cliente: link.customerName,
    email: link.customerEmail || 'No proporcionado',
    concepto: link.concept,
    monto: `$${(link.amount / 100).toFixed(2)}`,
    estado: link.status,
    creado: link.createdAt,
    expira: link.expiresAt,
    urlPago: link.paymentLinkUrl,
    esPrueba: link.isTest
  };
}

Siguientes pasos

• — Obtén una lista de todos tus links
• — Crea un nuevo link de pago
• — Cancela un link pendiente
• — Recibe notificaciones automáticas de estado