Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

Bloobank emits webhook events on every relevant transition in the lifecycle of a Payment Order. These events allow your system to track payments in real time without polling. All events follow the standard envelope described in Webhooks Overview, with pathname equal to /topic/api-payments/payment/v1 for payment events.

​
Event catalog

EventDirectionWhen it fires
payment.createdIN / OUTOrder created and awaiting processing.
payment.processingIN / OUTOrder entered processing.
payment.confirmedIN / OUTOrder successfully confirmed. Final state.
payment.failedIN / OUTOrder failed. Final state.
payment.canceledIN / OUTOrder canceled before processing. Final state.
TODO (needs to be filled manually): The final event naming (payment.confirmed vs payment_order.confirmed vs another pattern), the granularity (separate events for Pix-In and Pix-Out, or a single namespace?), and the complete list of events published by Bloobank must be confirmed with the platform team. The catalog above reflects the lifecycle observed on the REST endpoints.

​
body structure

The body field of the envelope contains the full Payment Order resource, at the current state of the event. The shape is the same returned by GET /v1/pix-in/{id} or GET /v1/pix-out/{id}.

​
Example: payment.confirmed (Pix-In)

{
  "event": "payment.confirmed",
  "messageId": "msg_8H2kPqR9zT4xVm",
  "method": "POST",
  "pathname": "/topic/api-payments/payment/v1",
  "body": {
    "id": "pixin_123456789",
    "direction": "IN",
    "amount": 15000,
    "currency": "BRL",
    "status": "confirmed",
    "endToEndId": "E1234567820260506110000000012345",
    "payer": {
      "name": "John Doe",
      "document": "00000000000"
    },
    "createdAt": "2026-05-06T10:30:00Z",
    "confirmedAt": "2026-05-06T10:30:05Z"
  },
  "query": {}
}

​
Example: payment.failed (Pix-Out)

{
  "event": "payment.failed",
  "messageId": "msg_3F8jKlN1xC7Bz",
  "method": "POST",
  "pathname": "/topic/api-payments/payment/v1",
  "body": {
    "id": "pixout_987654321",
    "direction": "OUT",
    "amount": 5000,
    "currency": "BRL",
    "status": "failed",
    "externalId": "order-555",
    "errorCode": "INSUFFICIENT_FUNDS",
    "errorMessage": "Insufficient available balance for this operation.",
    "createdAt": "2026-05-06T11:00:00Z",
    "updatedAt": "2026-05-06T11:00:02Z"
  },
  "query": {}
}

​
Ordering and duplication

Events are not guaranteed to be in order. For example, you may receive payment.confirmed before payment.processing in retry scenarios. Use the state returned in body as the source of truth.
Events may be delivered more than once. Use the messageId to deduplicate — see Idempotency.

​
Event filtering on the integrator side

Recommendations for routing events on your server:
1

Route by pathname

Use the pathname field to distinguish event families (e.g. payments vs. balance vs. configuration webhooks).
2

Switch by event

Inside the payments handler, use a switch on the event field to separate logic by transition type.
3

Filter by direction when relevant

If you only process Pix-In or only Pix-Out, filter by the body.direction field before applying the logic.

​
Next steps

Webhooks Overview

How to configure, authenticate, and handle Bloobank webhooks.