Introducción a la API

Esta guía te ayudará a entender los conceptos básicos para integrar la API de GalioPay en tu aplicación.

URL Base

Todas las peticiones a la API deben dirigirse a:

https://pay.galio.app/api

Autenticacion

La API publica de GalioPay utiliza credenciales de cliente. Debes enviar API Key y Client ID en cada request autenticado.

Headers de autenticacion

Authorization: Bearer {TU_API_KEY}
x-client-id: {TU_CLIENT_ID}

Ejemplo de autenticación

const response = await fetch("https://pay.galio.app/api/payment-links", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer TU_API_KEY_AQUI",
    "x-client-id": "TU_CLIENT_ID_AQUI",
  },
  body: JSON.stringify({
    // ... datos de la petición
  }),
});

Formatos de datos

La API acepta y devuelve datos en formato JSON.

Content-Type

Todas las peticiones deben incluir:

Content-Type: application/json

Códigos de respuesta HTTP

Código	Significado	Descripción
200	OK	La petición fue exitosa
201	Created	Recurso creado exitosamente
400	Bad Request	Datos de entrada inválidos
401	Unauthorized	API Key inválida o faltante
404	Not Found	Recurso no encontrado
500	Internal Server Error	Error interno del servidor

Manejo de errores

Cuando ocurre un error, la API devuelve una respuesta con el siguiente formato:

{
  "error": "Descripción del error"
}

Webhooks

GalioPay envía webhooks con POST cuando cambia el estado del pago.

Destino del webhook (orden de prioridad):

1. notificationUrl del payment link (si fue enviado en POST /api/payment-links o PUT /api/payment-links/{id})
2. notificationUrl del cliente (fallback)

Si no hay URL configurada en ninguno de los dos niveles, no se envía webhook.

Los POST posibles que puedes recibir

Caso	status	Cuándo se envía
Pago aprobado	approved	Cuando un pago se acredita correctamente
Pago reembolsado	refunded	Cuando se completa un reembolso

Payload de pago (approved)

{
  "id": "67a8f1b2c3d4e5f6a7b8c9d0",
  "paymentMethodId": "TRANSFER",
  "amount": 15000,
  "netAmount": 14650,
  "moneyReleaseDate": "2026-02-12T00:00:00.000Z",
  "currency": "ARS",
  "status": "approved",
  "sandbox": false,
  "date": "2026-02-10T14:21:00.000Z",
  "referenceId": "orden-456"
}

Payload de reembolso (refunded)

{
  "id": "67a8f1b2c3d4e5f6a7b8c9d0",
  "paymentMethodId": "TRANSFER",
  "amount_refunded": 15000,
  "refund_type": "total",
  "refund_reason": "Cliente solicito devolucion",
  "status": "refunded",
  "currency": "ARS",
  "sandbox": false,
  "date": "2026-02-12T10:30:00.000Z",
  "referenceId": "orden-456"
}

Ejemplos de errores comunes

Error de validación (400):

{
  "error": "Items array is required"
}

API Key inválida (401):

{
  "error": "Unauthorized"
}

Recurso no encontrado (404):

{
  "error": "Payment link not found"
}

Ejemplo completo

Aquí tienes un ejemplo completo de cómo hacer una petición autenticada:

cURL

curl -X POST https://pay.galio.app/api/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY_AQUI" \
  -H "x-client-id: TU_CLIENT_ID_AQUI" \
  -d '{
    "items": [
      {
      "title": "Producto de ejemplo",
      "quantity": 1,
      "unitPrice": 1000,
      "currencyId": "ARS"
      }
    ],
    "referenceId": "orden-123",
    "backUrl": {
      "success": "https://tusitio.com/exito",
      "failure": "https://tusitio.com/error"
    }
  }'

JavaScript (Fetch)

async function crearLinkDePago() {
  const apiKey = "TU_API_KEY_AQUI";
  const clientId = "TU_CLIENT_ID_AQUI";

  const datos = {
    items: [
      {
        title: "Producto de ejemplo",
        quantity: 1,
        unitPrice: 1000,
        currencyId: "ARS",
      },
    ],
    referenceId: "orden-123",
    backUrl: {
      success: "https://tusitio.com/exito",
      failure: "https://tusitio.com/error",
    },
  };

  try {
    const response = await fetch("https://pay.galio.app/api/payment-links", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
        "x-client-id": clientId,
      },
      body: JSON.stringify(datos),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error);
    }

    const resultado = await response.json();
    console.log("Link creado:", resultado.url);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

Próximos pasos

• Aprende a crear links de pago
• Aprende a consultar y reembolsar pagos