Integrá cobros y pagos con la API de Gallo Pay.

Quick start

Base URL de producción: https://api.gallo-pay.com. Sandbox: https://sandbox.api.gallo-pay.com.

Todas las llamadas requieren el header x-api-key. Las operaciones de escritura críticas también piden Idempotency-Key.

Playground

Simulación en el browser — elegí operación e idioma, ejecutá y mirá request / response.

curl -X POST https://api.gallo-pay.com/v1/accounts \
  -H "x-api-key: gpk_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "cuit": "20370994049",
    "titular": "JUAN PEREZ",
    "tipoPersona": "F",
    "alias": "gallo.juan.perez"
  }'

Ejecutá para ver la respuesta.

Autenticación

El acceso se autentica con una API key enviada en el header:

x-api-key: gpk_live_…

• Prefijo gpk_live_ en producción y gpk_test_ en sandbox.
• Una key inválida o ausente responde 401.
• Custodiá las keys como secretos; no las embeds en apps cliente ni repos públicos.

Para obtener una key de sandbox o producción escribinos a infogallopay@estudiogallo.com.ar.

Webhooks

Configuramos junto a vos una URL HTTPS a la que hacemos POST por cada evento. Cada request incluye:

• X-Gallo-Signature — HMAC-SHA256 en hex de ${timestamp}.${body}
• X-Gallo-Timestamp — Unix time en segundos
• X-Gallo-Event-Id — ID único del evento
• X-Gallo-Event-Type — tipo de evento

{
  "eventId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "type": "transfer.confirmed",
  "version": "1",
  "occurredAt": "2026-07-30T12:00:00.000Z",
  "tenantId": "3f6d9c1e-8b2a-4a1f-9c3e-6b7a1d2e5f40",
  "data": {}
}

Verificar la firma (Node.js)

const crypto = require('crypto');

function verify(req, secret) {
  const ts = req.headers['x-gallo-timestamp'];
  const sig = req.headers['x-gallo-signature'];
  const body = req.rawBody; // body crudo, sin re-serializar
  const expected = crypto
    .createHmac('sha256', secret) // whsec_...
    .update(ts + '.' + body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig),
  );
}

Respondé 2xx rápido. Ante error o timeout reintentamos con backoff. Tipos principales: account.created, account.credited, transfer.confirmed, transfer.failed, transfer.reversed.

Modelo de errores

Los errores siguen un envelope JSON consistente:

{
  "statusCode": 400,
  "message": "Idempotency-Key header is required",
  "timestamp": "2026-07-30T12:00:00.000Z",
  "bankStatus": 400,
  "bankBody": {}
}

• 400 — request inválido o validación fallida
• 401 — API key ausente o inválida
• 404 — recurso inexistente
• 409 — conflicto (p. ej. alias ya tomado)
• bankStatus / bankBody — eco del banco cuando el error proviene de la red de pagos

Estados de transferencia

Una transferencia de salida (cash-out) atraviesa estados internos mientras se envía a la red y se reconcilia:

• PENDING / SENT — aceptada y enviada al banco; aún no confirmada en forma definitiva.
• COMPLETED — acreditada / confirmada.
• FAILED / REVERSED — rechazada o revertida; el ledger refleja la liberación o compensación correspondiente.

Consultá el estado con GET /v1/transfers/:id. El detalle de campos está en la referencia.