Skip to main content

Event catalog

Exhaustive list of events emitted by Max Pay. Each event has a stable type (lowercase with dots as separators) and a documented data structure.

Conventions​

All events share the structure:

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

data.* includes the full resource in its state at the moment of the event. Derived data (stats, balances, etc.) is not included to avoid discrepancies with the current state.

Receivable accounts​

receivable-account.created​

Fires when a receivable account is created. The account is in PROVISIONING, with no CVU yet.

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

receivable-account.activated​

Fires when the CVU is assigned and the account moves to ACTIVE. This is the event the integrator should wait for to know the account is ready to operate.

{
  "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​

Fires when an associate is post-hoc bound (A → C) or when the operator is reassigned (C → C with a different 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​

Fires after Max Pay exhausts the automatic retries against the banking provider without provisioning the CVU. The account ends up in DISABLED and the integrator can retry provisioning with POST /v1/receivable-accounts/{id}/activations, or create a new account if the owner data needs adjustments.

Subscribing to this event is recommended in the minimum setup to detect stuck accounts (see Minimum recommended setup).

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

receivable-account.batch.completed​

Fires when a bulk creation of receivable accounts (POST /v1/receivable-accounts/batches) finishes.

{
  "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=..."
  }
}

The CSV report contains one row per account with its receivableAccountId, final status, and error.code on failure.

Receivables​

receivable.created​

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

receivable.updated​

Changes to editable fields of the receivable (description, dueDate, etc.).

receivable.paid​

Fires when a receivable transitions to PAID.

receivable.expired​

Fires when a receivable transitions to EXPIRED (typically via the nightly job).

receivable.settled​

Fires when a receivable transitions to SETTLED during a settlement cycle. Expect many events together when an account with many pending receivables is settled.

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

receivable.disabled​

Fires when a receivable is cancelled.

receivable.batch.completed​

Fires when a bulk receivable creation finishes.

{
  "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 (collections and rollbacks)​

movement.created​

Fires for every new movement, whether credit or debit. It is the primary event for collection reconciliation. Particularly important because the system does not automatically link these movements to specific receivables.

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

Rollbacks​

When an incoming movement is reversed (for example, a COELSA rejection after the funds were credited), a new movement.created is emitted with operationType: ROLLBACK referencing the original movement. There is no separate event for rollbacks: your movement.created handler must branch on operationType.

Settlements​

settlement.scheduled​

Fires when a settlement is scheduled for execution.

settlement.completed​

Fires when a settlement completes successfully. Includes the full summary.

{
  "type": "settlement.completed",
  "data": { "settlement": { ... full object ... } }
}

settlement.failed​

Fires when a settlement fails. Escalate to support.

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

Clients and 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​

Test event sent by POST /v1/webhooks/{id}/deliveries. Useful for validating connectivity and signature verification from the ERP.

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

Recommendation: which events to subscribe to in a minimum setup​

For a minimum viable setup of a typical integrator:

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

Subscribing to receivable-account.cvu-failed lets you react when an account fails to obtain a CVU after the automatic retries. If you also mark receivables as PAID from the ERP, add receivable.paid to confirm the change.