Obtener Link de Pago

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

Endpoint

http

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

:: tab cURL

bash

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"

:: tab Node.js

javascript

const hashUrl = 'abc123def456';

const response = await fetch(
  `https://api-pay.zelta.dev/v1/payment-links/${hashUrl}`,
  {
    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

hash_url = 'abc123def456'

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

result = response.json()
print(result)

:: tab PHP

php

<?php

$hashUrl = 'abc123def456';
$apiKey = getenv('ZELTA_API_KEY');

$ch = curl_init("https://api-pay.zelta.dev/v1/payment-links/{$hashUrl}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

Formato de respuesta

json

{
  "success": true,
  "data": {
    "paymentLink": {
      "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"
    }
  },
  "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

json

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

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

:: tab Node.js

javascript

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

:: tab Python

python

import requests

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

        result = response.json()

        if not result.get('success'):
            print(f"Error: {result['error']['code']} - {result['error']['message']}")
            return None

        return result['data']['paymentLink']
    except requests.exceptions.RequestException as e:
        print(f"Error de red: {e}")
        return None

link = get_payment_link('abc123def456')
if link:
    print(f"Estado: {link['status']}, Monto: ${link['amount'] / 100:.2f}")

Verificar estado de un link

javascript

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

javascript

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:

javascript

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:

javascript

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:

javascript

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

Obtener Link de Pago ​

Endpoint ​

Parámetros de ruta ​

Autenticación ​

Ejemplos de solicitud ​

Formato de respuesta ​

Campos de la respuesta ​

Códigos de estado ​

Respuestas de error ​

Link no encontrado ​

API key faltante ​

API key inválida ​

Ejemplos de implementación ​

Obtener un link con manejo de errores ​

Verificar estado de un link ​

Verificar estado de una orden ​

Casos de uso ​

Página de estado de orden ​

Verificación de pago ​

Atención al cliente ​

Siguientes pasos ​

Obtener Link de Pago

Endpoint

Parámetros de ruta

Autenticación

Ejemplos de solicitud

Formato de respuesta

Campos de la respuesta

Códigos de estado

Respuestas de error

Link no encontrado

API key faltante

API key inválida

Ejemplos de implementación

Obtener un link con manejo de errores

Verificar estado de un link

Verificar estado de una orden

Casos de uso

Página de estado de orden

Verificación de pago

Atención al cliente

Siguientes pasos