Events
Event format
Every event has anid, a type, a created_at time and the object in data. The objects and their fields are described in the API Reference.
Event examples in these guides are excerpts: data shows only the fields used in the step.
Event (excerpt)
Where to check amount, currency and reference
For
settlement.completed, data.amount is the amount of the collection and data.settlement.gross_amount is the amount deposited and settled. They are equal for a complete deposit.
Handling events
In this diagram, light blue steps are validations and dashed yellow steps are notifications.1
Verify the signature
Each event is signed by Broco. Verify the signature before you trust the content. Reject events that fail verification.
2
Ignore duplicates
Look up the event
id. If you already stored it, respond with a 2xx status and do nothing else. A repeated event never means a second payment or a second credit.3
Store the event before you respond
Save the whole event and the work it requires in durable storage, marked as received. Then respond with a
2xx status. A 2xx response means you received the event, not that you processed it. If processing is short, you can also finish it before responding.4
Process stored events
Process each stored event once. Lock the event or the order while it is processed, so two workers never handle it at the same time. Mark the event as processed only after your update succeeds. If processing fails, keep the event pending and resume it from your storage.
5
Match your records
Compare the event with the attempt you are tracking: the Broco object
id you stored when you created it, the connection of the account involved, the amount, the currency and the reference. Use the fields in the table above. If they differ, do not update the order: flag it for review and retrieve the object to check its status.Repeated, late or out-of-order events
Treat events as independent notices that can arrive more than once and in any order.- Apply an event only if it concerns the attempt you are tracking and moves your record forward.
- Never move an order or invoice back from paid to unpaid because of an event about an earlier attempt or an older status. Flag the difference for review instead.
- When in doubt, retrieve the object and use its current status.
When an event is late
Retrieve the object to read its current status:
For events that credit funds (
payment.succeeded, cash_payment.succeeded, supplier_payment.succeeded and settlement.completed), the credit happens when Broco records the operation, not when your server receives the event. cash_payment.expired and collection.collected do not credit anyone.