Skip to main content

Charge events (charge.*)

Facts from the charge lifecycle. In entity events, data is the charge serialized in the v1 API format, with the full person and collectionRule embedded. In fact events (paid, overdue, promise_*), data is a lean reference object.

charge.created​

Fires when a charge is created (API, import, ERP/gateway sync).

{
  "event": "charge.created",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "publicId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
    "companyId": null,
    "businessUnitId": null,
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "collectionRuleId": "8f6a4c2e-1b3d-4e5f-a7c9-2d4f6b8a0e1c",
    "documentNumber": "NF-2026-0451",
    "description": "Mensalidade julho/2026",
    "originalAmount": "1500.00",
    "interestAmount": "0.00",
    "fineAmount": "0.00",
    "discountAmount": "0.00",
    "paidAmount": null,
    "currentAmount": "1500.00",
    "issueDate": "2026-07-01T00:00:00.000Z",
    "dueDate": "2026-07-31T00:00:00.000Z",
    "paidAt": null,
    "daysOverdue": 0,
    "status": "pending",
    "paymentMethod": null,
    "barcode": null,
    "pixEmv": null,
    "paymentUrl": "https://pay.example.com/b2c3d4e5",
    "externalId": "ERP-TIT-2026-0451",
    "customData": null,
    "tags": ["mensalidade"],
    "currentStep": null,
    "lastNotificationAt": null,
    "negativedAt": null,
    "protestedAt": null,
    "source": "api",
    "lastVerifiedAt": null,
    "paymentClaimed": false,
    "legalHold": false,
    "legalHoldReason": null,
    "deletedAt": null,
    "metadata": {},
    "createdAt": "2026-07-23T12:00:00.000Z",
    "updatedAt": "2026-07-23T12:00:00.000Z",
    "person": { "id": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60", "name": "Padaria Pão Quente Ltda", "documentNumber": "12345678000190", "...": "full customer (same shape as person.created)" },
    "collectionRule": { "id": "8f6a4c2e-1b3d-4e5f-a7c9-2d4f6b8a0e1c", "name": "Régua padrão B2B", "...": "full collection rule (same shape as collection_rule.created, without steps)" }
  }
}

status values: pending · paid · overdue · cancelled · negotiated · protested · negatived · written_off. source values: kobana · erp · api · spreadsheet · manual.

charge.updated​

Fires when the charge is changed via API/dashboard. Same shape as charge.created — note that currentAmount, daysOverdue and status are recalculated on every update (an overdue charge may already arrive with status: "overdue").

charge.deleted​

Fires on (logical) deletion. Blocked if the charge has notifications, interactions, negativations or protests — in those cases the event does not occur.

{
  "event": "charge.deleted",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": { "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d" }
}

charge.paid​

Fires when a payment is identified (PSP/gateway webhook, reconciliation). The collection rule is halted and pending sends are suppressed before the event.

{
  "event": "charge.paid",
  "timestamp": "2026-07-23T14:32:08.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "chargeId": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "amount": 1500.0,
    "paidAt": "2026-07-23T14:31:55.000Z"
  }
}

amount and paidAt reflect what the payment provider reported. For the charge's full state after settlement, fetch GET /api/v1/charges/{chargeId}.

charge.overdue​

Fires once per transition: on the day the charge falls due without payment (daily job), not on every day of delay.

{
  "event": "charge.overdue",
  "timestamp": "2026-07-23T06:00:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "chargeId": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "daysOverdue": 1,
    "currentAmount": 1512.5
  }
}

currentAmount already includes the interest and fine calculated at the turn of the day.

charge.promise_registered​

Fires when a promise to pay is registered: an interaction with the promise_to_pay outcome and a future promiseDate (civil day in the organization's timezone). The collection rule is paused and pending sends are cancelled until promiseDate plus the grace period (2 civil days by default) — if the interaction is linked to a charge, only that one; otherwise, every enrolled charge of the customer (one event per paused charge).

{
  "event": "charge.promise_registered",
  "timestamp": "2026-08-04T15:20:33.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "interactionId": "5d3e7f9a-2b4c-4d6e-8f0a-3c5e7a9b1d2f",
    "promiseDate": "2026-08-10T00:00:00.000Z",
    "promisedAmount": "1512.50"
  }
}

Here id is the id of the charge covered by the promise; interactionId points to the interaction that registered it. promiseDate is a civil date (midnight UTC) and promisedAmount is a decimal string or null (promise with no stated amount). A new promise supersedes previous open ones in the same scope — the new deadline takes over.

charge.promise_broken​

Fires when the daily check finds a promise past its deadline plus the grace period with the charge still open (not paid, not negotiated, not cancelled). The collection rule resumes from where it stopped, once per still-open charge in the promise's scope. A kept promise emits no event of its own — the payment already emitted charge.paid.

{
  "event": "charge.promise_broken",
  "timestamp": "2026-08-13T04:30:00.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "id": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
    "interactionId": "5d3e7f9a-2b4c-4d6e-8f0a-3c5e7a9b1d2f",
    "promiseDate": "2026-08-10T00:00:00.000Z",
    "promisedAmount": "1512.50"
  }
}

Same shape as the registration event. With the default grace period, a promise for Friday can be paid until Sunday — on Monday it resolves (kept or broken).