Saltar al contenido principal

Catálogo de eventos

Lista exhaustiva de eventos que Max Pay emite. Cada evento tiene un type estable (en minúsculas con puntos como separador) y una estructura de data documentada.

Convenciones​

Todos los eventos comparten la estructura:

{
  "id": "evt_b3f8a1c2d4e5f6789012345678901234",
  "type": "<event-type>",
  "createdAt": "2026-05-15T14:30:05-03:00",
  "data": { ... }
}

Los data.* incluyen el recurso completo en su estado al momento del evento. Datos derivados (stats, balances, etc.) no se incluyen para evitar discrepancias con el state actual.

Receivable accounts​

receivable-account.created​

Dispara al crear una cuenta recaudadora. La cuenta está en PROVISIONING, sin CVU aún.

{
  "type": "receivable-account.created",
  "data": {
    "receivableAccount": {
      "id": 4242,
      "status": "PROVISIONING",
      "cvu": null,
      "owner": { "type": "CLIENT", "id": 1042 },
      ...
    }
  }
}

receivable-account.activated​

Dispara cuando el CVU se asigna y la cuenta pasa a ACTIVE. Este es el evento que el integrador debe esperar para saber que la cuenta está lista para operar.

{
  "type": "receivable-account.activated",
  "data": {
    "receivableAccount": {
      "id": 4242,
      "status": "ACTIVE",
      "cvu": "0000000099887766554433",
      "alias": "distribuidora.demo.kiosco.central",
      "owner": { "type": "CLIENT", "id": 1042 },
      ...
    }
  }
}

receivable-account.disabled​

{ "type": "receivable-account.disabled", "data": { "receivableAccount": { ... } } }

receivable-account.owner-changed​

Dispara al vincular un associate post-hoc (A → C) o al reasignar el operador (C → C con otro associate).

{
  "type": "receivable-account.owner-changed",
  "data": {
    "receivableAccount": { "id": 4242, ... },
    "previousOwner": { "type": "CLIENT", "id": 1042 },
    "newOwner": { "type": "CLIENT_AND_ASSOCIATE", "clientId": 1042, "associateId": 88 }
  }
}

receivable-account.cvu-failed​

Dispara después de que Max Pay agota los reintentos automáticos contra el proveedor bancario sin lograr provisionar el CVU. La cuenta queda en DISABLED y el integrador puede reintentar la provisión con POST /v1/receivable-accounts/{id}/activations, o crear una cuenta nueva si los datos del owner necesitan ajustes.

Recomendado suscribirse a este evento en el setup mínimo para detectar cuentas trabadas (ver Setup mínimo recomendado).

{
  "type": "receivable-account.cvu-failed",
  "data": {
    "receivableAccount": { "id": 4242, "status": "DISABLED", ... },
    "error": { "code": "external-provider-unavailable", "detail": "..." }
  }
}

receivable-account.batch.completed​

Dispara cuando termina un alta masiva de cuentas recaudadoras (POST /v1/receivable-accounts/batches).

{
  "type": "receivable-account.batch.completed",
  "data": {
    "batchId": 1203,
    "totalItems": 250,
    "successCount": 248,
    "failureCount": 2,
    "reportUrl": "https://files.maxpay.com.ar/batches/1203/report.csv?token=..."
  }
}

El reporte CSV trae una fila por cuenta con su receivableAccountId, status final, y el error.code en caso de falla.

Comprobantes​

receivable.created​

{ "type": "receivable.created", "data": { "receivable": { ... } } }

receivable.updated​

Cambios a campos editables del comprobante (description, dueDate, etc.).

receivable.paid​

Dispara cuando un comprobante transiciona a PAID.

receivable.expired​

Dispara cuando un comprobante transiciona a EXPIRED (típicamente por job nocturno).

receivable.settled​

Dispara cuando un comprobante transiciona a SETTLED durante un ciclo de liquidación. Esperar muchos eventos juntos cuando se liquida una cuenta con muchos pendientes.

{
  "type": "receivable.settled",
  "data": {
    "receivable": { ... },
    "settlementId": 9001
  }
}

receivable.disabled​

Dispara al anular un comprobante.

receivable.batch.completed​

Dispara cuando termina un alta masiva de comprobantes.

{
  "type": "receivable.batch.completed",
  "data": {
    "batchId": 902,
    "totalItems": 500,
    "successCount": 498,
    "failureCount": 2,
    "reportUrl": "https://files.maxpay.com.ar/batches/902/report.csv?token=..."
  }
}

Movements (cobros y rollbacks)​

movement.created​

Dispara para cada movement nuevo, sea crédito o débito. Es el evento principal para conciliación de cobros. Particularmente importante porque el sistema no vincula automáticamente estos movements a comprobantes específicos.

{
  "type": "movement.created",
  "data": {
    "movement": {
      "id": 88123,
      "receivableAccountId": 4242,
      "movementType": "CREDIT",
      "operationType": "DEPOSIT",
      "amount": 45000.00,
      "counterParty": { "name": "Kiosco Central", "taxId": "30998888887" }
    }
  }
}

Rollbacks​

Cuando un movement entrante se revierte (por ejemplo, rechazo COELSA luego de acreditarse), se emite un nuevo movement.created con operationType: ROLLBACK que referencia al movement original. No hay un evento separado para rollbacks: tu handler de movement.created debe ramificar por operationType.

Settlements​

settlement.scheduled​

Dispara cuando una liquidación se programa para ejecución.

settlement.completed​

Dispara al finalizar exitosamente una liquidación. Incluye el resumen completo.

{
  "type": "settlement.completed",
  "data": { "settlement": { ... el objeto completo ... } }
}

settlement.failed​

Dispara si una liquidación falla. Escalable a soporte.

{
  "type": "settlement.failed",
  "data": {
    "settlement": { "id": 9001, "status": "FAILED", ... },
    "error": { "code": "...", "detail": "..." }
  }
}

Clients y associates​

client.created​

client.updated​

associate.created​

associate.updated​

associate.disabled​

associate.activated​

Route settlements​

route-settlement.created​

route-settlement.updated​

Webhooks (meta)​

webhook.test​

Evento de prueba enviado por POST /v1/webhooks/{id}/deliveries. Útil para validar conectividad y verificación de firma desde el ERP.

{
  "id": "evt_test_...",
  "type": "webhook.test",
  "createdAt": "...",
  "data": {
    "message": "Test delivery from Max Pay",
    "webhookId": 301
  }
}

Recomendación: a qué eventos suscribirse en un setup mínimo​

Para un setup mínimo viable de un integrador típico:

{
  "events": [
    "receivable-account.activated",
    "receivable-account.cvu-failed",
    "receivable.settled",
    "movement.created",
    "settlement.completed",
    "receivable.batch.completed",
    "receivable-account.batch.completed"
  ]
}

Suscribirte a receivable-account.cvu-failed te permite reaccionar cuando una cuenta no logra obtener CVU tras los reintentos automáticos. Si además marcás receivables como PAID desde el ERP, agregá receivable.paid para confirmar el cambio.