API Reference

Webhooks

Los webhooks de iPagos son notificaciones HTTP POST firmadas que envíamos a tu endpoint cada vez que ocurre un evento relevante en tu cuenta.

Eventos soportados

payment.created

payment.approved

payment.declined

payment.refunded

payment.disputed

subscription.renewed

subscription.payment_failed

subscription.canceled

Estructura del evento

{
  "id": "evt_9F1aL3Yw2Pq",
  "object": "event",
  "type": "payment.approved",
  "livemode": false,
  "created_at": "2026-06-04T17:42:11Z",
  "data": {
    "object": {
      "id": "pay_3K9aB2X7QvLm",
      "object": "payment",
      "amount": 25000,
      "currency": "MXN",
      "status": "approved"
    }
  },
  "request_id": "req_8B2nM1Q9TfYr"
}

Verificación de firma (HMAC-SHA256)

Cada webhook llega con el encabezado iPagos-Signature, calculado como:

signature = HMAC_SHA256(secret = whsec_xxx, payload = "{timestamp}.{raw_body}")
header   = "t={timestamp},v1={signature}"

Ejemplo de verificación en PHP:

<?php
$payload   = file_get_contents('php://input');
$header    = $_SERVER['HTTP_IPAGOS_SIGNATURE'] ?? '';
$secret    = getenv('IPAGOS_WEBHOOK_SECRET');

parse_str(str_replace(',', '&', $header), $parts);
$timestamp = $parts['t'] ?? '';
$received  = $parts['v1'] ?? '';

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (!hash_equals($expected, $received) || abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit('Firma inválida o expirada');
}

http_response_code(200);
echo 'OK';

Reintentos

Si tu endpoint no responde 2xx en menos de 10 segundos, iPagos reintenta hasta 8 veces con backoff exponencial durante 72 horas. Después de eso, el evento se marca como fallido y se notifica por correo a los administradores de la cuenta.

Responde 200 OK tan pronto valides la firma. Procesa el evento en una cola asíncrona para no exceder el timeout de 10 segundos.

Desarrolladores

Eventos soportados

Estructura del evento

Verificación de firma (HMAC-SHA256)

Reintentos