Pix Indirect via BTG events

Pix Indirect via BTG publishes 63 JSON business facts as CloudEvents 1.0 in binary content mode over Kafka. These events are available on BYOC deployments. Streaming is optional and off by default. To turn it on, set STREAMING_ENABLED=true and the other business event variables in the API component. The event streaming overview describes the shared envelope.

Transport contract

Field	Value
`ce-source`	The value of `STREAMING_CLOUDEVENTS_SOURCE`. The default is `plugin-br-pix-indirect-btg`.
Topic	`lerian.streaming.<ce-source>`
`ce-type`	`studio.lerian.<ce-source>.<event-key>`
`ce-tenantid`	The value of `STREAMING_TENANT_ID`. The default is `default`.
Schema version	`1.0.0` for every event
Content type	`application/json`
Delivery	Set per event. See Delivery.
Command topic	None
Runtime manifest	`GET /v1/streaming/manifest`

If you change STREAMING_CLOUDEVENTS_SOURCE, the topic and every ce-type change with it. When streaming is on, the API serves the event catalog at GET /v1/streaming/manifest. The route requires the Access Manager resource streaming with the action get.

Delivery

Each event has one of three delivery modes:

Outbox: the API writes the event to its PostgreSQL outbox, and a relay publishes it to Kafka.
Direct, outbox fallback: the API publishes the event to Kafka. If the brokers are unavailable or slow, the API writes the event to the outbox.
Best effort: the API publishes the event to Kafka, with no outbox.

Publishing an event never fails the business operation that produced it. An event can arrive more than once: deduplicate on (ce-source, ce-id) and keep consumers idempotent. Do not rely on arrival order.

Event catalog

Charges

Event key	Fires when	Delivery
`collection.created`	BTG registers a Pix charge, and the API stores it as `ACTIVE`. It fires for immediate and due-date charges. The `type` field tells them apart.	Direct, outbox fallback
`collection.updated`	BTG accepts a change to an `ACTIVE` charge, and the API stores the charge with a new revision.	Direct, outbox fallback
`collection.deleted`	BTG accepts the deletion of an `ACTIVE` immediate charge, and the API stores it as `DELETED`.	Direct, outbox fallback
`collection.completed`	A charge moves from `ACTIVE` to `COMPLETED`: its payment settles, or the operator endpoint completes it.	Outbox

DICT keys and claims

Event key	Fires when	Delivery
`dict_entry.created`	A Pix key is stored as `ACTIVE` for one of your accounts: through the API, through reconciliation, or when a claim completes in your favor.	Direct, outbox fallback
`dict_entry.updated`	DICT accepts a change to the account or owner data of a key, and the API stores it.	Direct, outbox fallback
`dict_entry.deleted`	A key leaves your account: you delete it, reconciliation removes it, or the donor confirms a claim on it.	Direct, outbox fallback
`claim.created`	A portability or ownership claim exists for a key: you open it as the claimer, or BTG reports a claim that another participant opened on your key.	Outbox
`claim.acknowledged`	The donor acknowledges the claim, and the claim moves to `WAITING_RESOLUTION`.	Direct, outbox fallback
`claim.confirmed`	The donor confirms the claim.	Outbox
`claim.completed`	The claim reaches `COMPLETED`, and the key belongs to the claimer in DICT.	Outbox
`claim.cancelled`	The claim reaches `CANCELLED`, and the key stays with the donor.	Outbox

MED 2.0 funds recovery

Event key	Fires when	Delivery
`funds_recovery.created`	A funds recovery exists: you create it, or BTG reports one that the API did not have.	Outbox
`funds_recovery.tracked`	The funds recovery moves to `TRACKED`, and its tracking graph is available.	Direct, outbox fallback
`funds_recovery.awaiting_analysis`	The funds recovery moves to `AWAITING_ANALYSIS`.	Outbox
`funds_recovery.analysed`	The funds recovery moves to `ANALYSED`.	Outbox
`funds_recovery.refund_requested`	The funds recovery moves to `REFUNDING`.	Outbox
`funds_recovery.completed`	BTG reports the funds recovery as `COMPLETED`.	Outbox
`funds_recovery.cancelled`	The funds recovery moves to `CANCELLED`.	Outbox

MED infraction reports and refund requests

Event key	Fires when	Delivery
`infraction.created`	An infraction report exists: you open it, or BTG delivers one that a counterparty opened against your customer.	Outbox
`infraction.acknowledged`	An infraction report moves from `OPEN` to `ACKNOWLEDGED`.	Direct, outbox fallback
`infraction.closed`	An infraction report reaches `CLOSED` with its analysis result.	Outbox
`infraction.cancelled`	An infraction report reaches `CANCELLED`.	Outbox
`refund_request.created`	A MED refund request exists: you create it, or BTG delivers one that a counterparty created.	Outbox
`refund_request.closed`	A refund request reaches `CLOSED` with its result and the refunded amount.	Outbox
`refund_request.cancelled`	A refund request reaches `CANCELLED`.	Outbox

Cash-in and refunds

Event key	Fires when	Delivery
`cashin.received`	The API accepts an incoming Pix and stores it as `CREATED`. No credit happens at this step.	Direct, outbox fallback
`cashin.completed`	An incoming Pix settles, and the API credits it to the account in Midaz.	Outbox
`cashin.failed`	BTG reports an error for an accepted incoming Pix, and the API stores it as `REJECTED`. Nothing is credited.	Outbox
`refund.created`	A refund exists for one of your accounts. The `type` field (`CASHOUT` or `CASHIN`) gives its direction.	Direct, outbox fallback
`refund.processing`	A refund that you send (`CASHOUT`) moves to `PROCESSING`.	Direct, outbox fallback
`refund.completed`	A refund settles and moves to `COMPLETED`.	Outbox
`refund.rejected`	BTG or the intra-PSP settlement rejects a refund in progress, and the API stores it as `REJECTED`.	Outbox
`refund.failed`	A refund that you send (`CASHOUT`) cannot run, and the API stores it as `FAILED`.	Outbox

Cash-out, payment initiation, and schedules

Event key	Fires when	Delivery
`payment_initiation.created`	A payment initiation (`MANUAL`, `KEY`, or `QR_CODE`) passes validation, and the API stores it as `PENDING`.	Direct, outbox fallback
`cashout.created`	The API stores a cash-out as `CREATED`.	Direct, outbox fallback
`cashout.processing`	The provider accepts the cash-out, and the API stores it as `PROCESSING`.	Direct, outbox fallback
`cashout.completed`	The cash-out settles, and the API stores it as `COMPLETED`.	Outbox
`cashout.rejected`	BTG or the intra-PSP settlement rejects a cash-out that reached the provider, and the API stores it as `REJECTED`.	Outbox
`cashout.failed`	The cash-out fails before the provider accepts it, and the API stores it as `FAILED`.	Outbox
`schedule.created`	The API stores a scheduled Pix as `SCHEDULED`.	Direct, outbox fallback
`schedule.cancelled`	A `SCHEDULED` schedule is cancelled.	Direct, outbox fallback
`schedule.attempt_failed`	An attempt fails for insufficient funds, and the schedule waits for a retry on the same day.	Best effort
`schedule.executed`	A scheduled Pix runs and settles.	Outbox
`schedule.failed`	A scheduled Pix reaches `FAILED` after its last attempt.	Outbox

Pix Automático authorizations

Event key	Fires when	Delivery
`authorization_request.created`	The API stores an authorization request for a payer account: BTG delivers it, or you confirm a Pix Automático QR code for the payer.	Direct, outbox fallback
`authorization_request.approved`	BTG acknowledges the payer’s approval, and the request moves to `APPROVING`. The mandate does not exist at this step.	Direct, outbox fallback
`authorization_request.confirmed`	BTG confirms the approval, and the request reaches `CONFIRMED`.	Outbox
`authorization_request.rejected`	The request reaches `REJECTED`: the payer rejects it, or BTG reports a rejection.	Outbox
`authorization_request.cancelled`	BTG reports the cancellation of a request before its confirmation.	Outbox
`authorization_request.expired`	The request reaches `EXPIRED` with no decision.	Outbox
`authorization_request.reply_failed`	The API cannot deliver the payer’s decision to BTG, and the request reaches `REPLY_FAILED`.	Direct, outbox fallback
`authorization_request.payment_failed`	The immediate Pix of a pay-and-confirm request does not settle, and the request reaches `PAYMENT_FAILED`. No mandate is created.	Outbox
`recurring_authorization.authorized`	A Pix Automático mandate becomes effective for a payer account.	Outbox
`recurring_authorization.cancelled`	A mandate is cancelled through the API, and its future scheduled charges are cancelled with it.	Outbox
`recurrence.completed`	The last permitted charge of a recurrence runs, and the recurrence ends.	Outbox
`recurrence.expired`	A recurrence reaches its end date, and it ends.	Outbox

Pix Automático charges

Event key	Fires when	Delivery
`recurring_charge.received`	A Pix Automático charge arrives from BTG, and the API stores it as `RECEIVED`.	Direct, outbox fallback
`recurring_charge.scheduled`	The API schedules a debit attempt for a charge: the charge passes the acceptance checks, or a failed attempt has retries left.	Direct, outbox fallback
`recurring_charge.rejected`	The acceptance checks refuse a received charge. The payer is not debited.	Outbox
`recurring_charge.executed`	The payer is debited for a charge.	Outbox
`recurring_charge.failed`	The last permitted debit attempt fails. The payer is not debited.	Outbox
`recurring_charge.cancelled`	A scheduled charge is cancelled: its mandate is cancelled, or its schedule is cancelled.	Direct, outbox fallback

DICT API

Claims API

MED · Infractions

MED · Fraud markers

MED · Refund requests

MED · Statistics

Transactions API

QR Codes API

Collections API

Funds Recovery API

Reconciliation API

Pix Automático API

Schedules API

Transaction Reports API

Transaction times

Webhooks API

Error handling

Events

Pix Indirect via BTG events

Transport contract

Delivery

Event catalog

Charges

DICT keys and claims

MED 2.0 funds recovery

MED infraction reports and refund requests

Cash-in and refunds

Cash-out, payment initiation, and schedules

Pix Automático authorizations

Pix Automático charges

​Transport contract

​Delivery

​Event catalog

​Charges

​DICT keys and claims

​MED 2.0 funds recovery

​MED infraction reports and refund requests

​Cash-in and refunds

​Cash-out, payment initiation, and schedules

​Pix Automático authorizations

​Pix Automático charges

Transport contract

Delivery

Event catalog

Charges

DICT keys and claims

MED 2.0 funds recovery

MED infraction reports and refund requests

Cash-in and refunds

Cash-out, payment initiation, and schedules

Pix Automático authorizations

Pix Automático charges