Docs

Direct Debit · Reference

Webhook events

Configure your endpoint and handle the charge_result and instrument_ownership_verification_result events.

Monato notifies your systems when a charge reaches a final outcome or an instrument finishes penny validation. For how webhooks work across Monato products, see Webhooks.

Configure your endpoint

Set your endpoint in the Portal under Settings → Webhooks. You provide the URL and a header name and value that Monato includes in every delivery. In production the URL must use HTTPS.

Your endpoint must:

  • Accept POST requests with a Content-Type: application/json body.
  • Return 200, 201, 202 or 204 within 5 seconds on successful receipt.
  • Be reachable from the public internet over HTTPS.
Warning:

Respond as quickly as possible, before doing any processing. A response that takes longer than 5 seconds counts as a failed delivery and is retried.

Verify requests

Monato sends the header you configured with every webhook request. Check it to confirm the request comes from Monato. Webhook requests are not signed and do not use your API key.

Delivery and retries

If the first attempt fails, Monato retries once per hour for up to 10 hours (10 retries total). After the final retry, the event is not delivered again: query the API for the current state of the resource.

Event structure

All events share the same top-level structure.

Field Type Description
event string The event type identifier
timestamp string When the event was generated, as an ISO 8601 / RFC 3339 datetime in UTC with an explicit +00:00 offset (e.g. 2026-03-29T12:01:30.000000+00:00)
data object Event-specific payload

charge_result

Sent whenever a charge reaches a final outcome: confirmation, decline, cancellation or chargeback. There is no separate event type for chargebacks.

It is sent when:

  • The banking network returns a result for a charge.
  • Penny validation cancels a charge (runs before risk verification).
  • The risk engine cancels a charge (runs after penny validation).

The payload has two shapes. Bank results and risk engine cancellations carry the base fields. Penny validation cancellations carry the base fields plus three ownership fields.

{
  "event": "charge_result",
  "timestamp": "2026-01-15T12:01:30.000000+00:00",
  "data": {
    "charge_id": "22222222-2222-4222-8222-222222222222",
    "charge_result": "confirmed",
    "charge_reference": "subscription-0001",
    "amount": 250.0,
    "declined_reason": null,
    "risk_status": "ok",
    "risk_reasons": null,
    "client_debt_id": null,
    "instrument_identifier": null,
    "is_test": false
  }
}
Field Type Value
charge_id UUID The unique identifier of the charge
charge_result string confirmed, declined, canceled, or chargeback
charge_reference string / null The merchant-assigned reference, if one was provided on the charge
amount number The charge amount
declined_reason string / null Platform-level decline code. Set only when charge_result is declined; null otherwise. See Error Codes
risk_status string ok or cancelled_by_risk. Never null in webhooks
risk_reasons array / null List of risk rules that triggered cancellation when risk_status is cancelled_by_risk; null otherwise. Possible values: instrument_chargeback_history, bank_blacklist
client_debt_id string / null The debt identifier you sent when the charge belongs to a Collection as a Service portfolio. null for standard charges
instrument_identifier string / null The charged CLABE or card number for Collection as a Service charges. null for standard charges
is_test boolean true for test webhooks sent from the sandbox Portal

Penny validation cancellations add:

Field Type Value
ownership_verification_result string no_match, errored, account_canceled or account_does_not_exist
ownership_verification_result_at string ISO 8601 datetime when penny validation completed
ownership_information object / null Account holder data from the CEP, whatever the result. null when the validation transfer failed and no CEP exists
ownership_information.name string Account holder name as reported on the CEP
ownership_information.document_id string Account holder document ID as reported on the CEP

Charges whose ownership matched get no penny validation event; you receive their bank result later. For status meanings see Charge statuses. For chargebacks see Chargebacks.

instrument_ownership_verification_result

Sent when penny validation completes for an instrument and it moves to active or errored. It fires for every terminal outcome, whether validation succeeded or failed.

{
  "event": "instrument_ownership_verification_result",
  "timestamp": "2026-01-15T20:05:00.000000+00:00",
  "data": {
    "instrument_id": "66666666-6666-4666-8666-666666666666",
    "ownership_verification_result": "matched",
    "ownership_verification_result_at": "2026-01-15T20:04:58.200000+00:00",
    "ownership_information": {
      "name": "JANE DOE",
      "document_id": "XXXX000000XXX"
    },
    "is_test": false
  }
}
Field Type Description
instrument_id UUID The unique identifier of the instrument
ownership_verification_result string matched, no_match, errored, account_canceled or account_does_not_exist
ownership_verification_result_at string ISO 8601 datetime when the penny validation result was recorded
ownership_information object / null Account holder data from the CEP. null when no CEP is available
ownership_information.name string Account holder name as reported on the CEP
ownership_information.document_id string Account holder document ID as reported on the CEP
is_test boolean true for test webhooks sent from the sandbox Portal

See Penny validation for the full process.