Webhook Events

Events are structured and transmitted to your endpoint in JSON format. All payloads share the same root structure:

{
  "type": "<EVENT_TYPE>",
  "data": { ... }
}

Field	Type	Description
type	String	Identifies the event type. See the sections below.
data	Object	Event payload. Fields vary according to the event type.

Event Types Summary

Type	Category	Trigger
`QR_CODE_COPY_AND_PASTE_CREATED`	Cash In	A QR Code (Pix Copia e Cola) was generated
`QR_CODE_COPY_AND_PASTE_PAID`	Cash In	A QR Code was paid by the customer
`QR_CODE_COPY_AND_PASTE_REFUNDED`	Cash In	A QR Code payment was successfully refunded (chargeback)
`QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR`	Cash In	An attempted QR Code refund failed
`PIX_CASHIN_RECEIVED`	Cash In	A Pix transfer was received (key or manual)
`PIX_CASHIN_REFUNDED`	Cash In	A received Pix transfer was successfully refunded
`PIX_CASHIN_REFUNDED_ERROR`	Cash In	An attempted refund of a received Pix transfer failed
`MANUAL_CREDIT`	Transaction	A manual credit was added to the account
`MANUAL_DEBIT`	Transaction	A manual debit was subtracted from the account
`PIX_CASHOUT_CREATED`	Cash Out	A Pix transfer was created (pending or awaiting approval)
`PIX_CASHOUT_SUCCESS`	Cash Out	A Pix transfer was successfully completed
`PIX_CASHOUT_ERROR`	Cash Out	A Pix transfer failed
`PIX_CASHOUT_REFUND`	Cash Out	A Pix transfer was returned by the recipient's bank
`PIX_CASHOUT_CANCELED`	Cash Out	A Pix transfer was canceled
`MED_CREATED`	MED	A MED infraction report was received
`MED_APPROVED`	MED	A MED infraction report was approved (accepted)
`MED_REJECTED`	MED	A MED infraction report was rejected
`MED_CANCELLED`	MED	A MED infraction report was cancelled
`ONBOARDING_REQUISITION_APPROVED`	Onboarding	An account opening request was approved and the account created
`ONBOARDING_REQUISITION_REPROVED`	Onboarding	An account opening request was rejected
`ACCOUNT_CREDENTIALS_CREATED`	Onboarding	API credentials were generated for an existing account

Webhook type filter mapping: When registering a webhook with type_webhook = CASHIN, it will receive all events in the Cash In category. type_webhook = CASHOUT receives all Cash Out events. You can also register with a specific event type (e.g. PIX_CASHOUT_SUCCESS) to receive only that event.

Cash In Events

QR_CODE_COPY_AND_PASTE_CREATED

Fired when a Pix QR Code (Copia e Cola) is generated and is awaiting payment.

{
  "type": "QR_CODE_COPY_AND_PASTE_CREATED",
  "data": {
    "worked": true,
    "qr_code_id": 1,
    "tx_id": "978e3d40d3******e88b558f4",
    "pix_copy_and_paste": "00020101021226880014br.gov.bcb.pix...",
    "status": "NEW",
    "amount": 10.00,
    "amount_chargeback": 0.00,
    "fee": 0.00,
    "base_64_image": null,
    "base_64_image_url": "https://api.somossimpay.com.br/v2/finance/image/qrcode/978e3d40***.png",
    "account_number": "00001",
    "agency_number": "0001",
    "debtor_document": "0******32",
    "debtor_name": "Fulano de tal",
    "type_document": "CPF",
    "due_date": null,
    "expiration_date": "2024-01-01 00:00:00.000000+00:00",
    "fine": null,
    "fine_date": null,
    "type_fine": "NONE",
    "tag": "NONE"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
qr_code_id	Integer	Unique internal identifier of the QR Code.
tx_id	String	Conciliation ID (txId) of the QR Code, used for bank reconciliation.
pix_copy_and_paste	String	Full Pix Copia e Cola code that the customer can paste in their banking app to pay.
status	String	`NEW` — QR Code generated, awaiting payment.
amount	Decimal	Charged amount in BRL.
amount_chargeback	Decimal	Refunded amount. `0.00` while the payment has not been refunded.
fee	Decimal	Fee charged to the customer (if applicable).
base_64_image	String	QR Code image in base64 format. Deprecated — use `base_64_image_url` instead.
base_64_image_url	String	URL to the QR Code image.
account_number	String	Account number of the recipient (payee).
agency_number	String	Agency (branch) number of the recipient.
debtor_document	String	CPF or CNPJ of the payer.
debtor_name	String	Full name or company name of the payer.
type_document	String	Document type of the payer: `CPF` or `CNPJ`.
due_date	Datetime	Due date for scheduled charges. `null` for immediate QR Codes.
expiration_date	Datetime	Date and time when the QR Code expires.
fine	Decimal	Fine value applied after the due date (if any).
fine_date	Datetime	Date from which the fine is applied.
type_fine	String	Fine type: `NONE`, `FIXED`, or `PERCENT`.
tag	String	Custom tag (description) associated with the QR Code. `NONE` if not set.

QR_CODE_COPY_AND_PASTE_PAID

Fired when a QR Code is successfully paid by the customer.

{
  "type": "QR_CODE_COPY_AND_PASTE_PAID",
  "data": {
    "worked": true,
    "qr_code_id": 1,
    "tx_id": "431c561f7******d8cac7bc",
    "end_to_end": "E18236120******02eb560ffa",
    "pix_copy_and_paste": "00020101021226880014br.gov.bcb.pix...",
    "status": "PAID",
    "payment_date": "2024-01-01 12:00:00.000000+00:00",
    "amount": 100.00,
    "amount_chargeback": 0.00,
    "fee": 0.00,
    "base_64_image": null,
    "base_64_image_url": "https://api.somossimpay.com.br/v2/finance/image/qrcode/431c561f79***.png",
    "account_number": "0001",
    "agency_number": "0001",
    "debtor_document": "75******20",
    "debtor_name": "Fulano de tal",
    "debtor_institution": "EXAMPLE BANK",
    "debtor_institution_number": "000001",
    "type_document": "CPF",
    "due_date": null,
    "expiration_date": "2024-01-01 12:00:00.000000+00:00",
    "fine": null,
    "fine_date": null,
    "type_fine": "NONE",
    "tag": "NONE"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
qr_code_id	Integer	Unique internal identifier of the QR Code.
tx_id	String	Conciliation ID (txId) of the QR Code.
end_to_end	String	End-to-end identifier (E2E ID) of the Pix payment.
pix_copy_and_paste	String	The original Copia e Cola code that was paid.
status	String	`PAID` — payment confirmed.
payment_date	Datetime	Date and time when the payment was confirmed.
amount	Decimal	Paid amount in BRL.
amount_chargeback	Decimal	Refunded amount. `0.00` when no refund has occurred.
fee	Decimal	Fee charged to the customer (if applicable).
base_64_image	String	QR Code image in base64 format. Deprecated.
base_64_image_url	String	URL to the QR Code image.
account_number	String	Account number of the recipient.
agency_number	String	Agency (branch) number of the recipient.
debtor_document	String	CPF or CNPJ of the payer.
debtor_name	String	Full name or company name of the payer.
debtor_institution	String	Name of the payer's financial institution.
debtor_institution_number	String	ISPB number of the payer's financial institution.
type_document	String	Document type of the payer: `CPF` or `CNPJ`.
due_date	Datetime	Due date of the charge. `null` for immediate QR Codes.
expiration_date	Datetime	Expiration date of the QR Code.
fine	Decimal	Fine value (if applicable).
fine_date	Datetime	Date from which the fine is applied.
type_fine	String	Fine type: `NONE`, `FIXED`, or `PERCENT`.
tag	String	Custom tag associated with the QR Code.

QR_CODE_COPY_AND_PASTE_REFUNDED

Fired when a QR Code payment is successfully refunded (chargeback completed).

{
  "type": "QR_CODE_COPY_AND_PASTE_REFUNDED",
  "data": {
    "worked": true,
    "end_to_end": "D35535240******MG3VDK2N",
    "chargeback_id": 1,
    "origin_chargeback_id": 1,
    "origin_end_to_end": "E00360305******2c56b47a3c6",
    "tx_id": "05b85cd026******631e62f4",
    "status": "CHARGEBACK",
    "amount": 100.00,
    "amount_chargeback": 100.00,
    "fee": 0.00,
    "account_number": "0001",
    "agency_number": "0001",
    "debtor_document": "58******87",
    "debtor_name": "ROSA MARIA DA SILVA",
    "type_document": "CPF",
    "fine": null,
    "fine_date": null,
    "type_fine": "NONE",
    "tag": "description"
  }
}

Field	Type	Description
worked	Boolean	`true` when the refund was successfully dispatched.
end_to_end	String	E2E ID of the refund transaction.
chargeback_id	Integer	Unique identifier of the chargeback record.
origin_chargeback_id	Integer	ID of the original QR Code that was refunded.
origin_end_to_end	String	E2E ID of the original payment.
tx_id	String	Conciliation ID of the original QR Code.
status	String	`CHARGEBACK` — refund successfully completed.
amount	Decimal	Original payment amount in BRL.
amount_chargeback	Decimal	Amount effectively refunded in BRL.
fee	Decimal	Fee charged (if applicable).
account_number	String	Account number of the original recipient.
agency_number	String	Agency number of the original recipient.
debtor_document	String	CPF or CNPJ of the original payer.
debtor_name	String	Name of the original payer.
type_document	String	Document type: `CPF` or `CNPJ`.
fine	Decimal	Fine value (if applicable).
fine_date	Datetime	Date from which the fine is applied.
type_fine	String	Fine type: `NONE`, `FIXED`, or `PERCENT`.
tag	String	Custom tag associated with the original QR Code.

QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR

Fired when an attempt to refund a QR Code payment fails.

{
  "type": "QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR",
  "data": {
    "worked": false,
    "qr_code_id": 10,
    "tx_id": "05b85cd026******631e62f4",
    "pix_copy_and_paste": "00020101021226880014br.gov.bcb.pix...",
    "status": "CHARGEBACK",
    "amount": 0.01,
    "amount_chargeback": 0.01,
    "fee": 0.00,
    "account_number": "00001",
    "agency_number": "0001",
    "debtor_document": "12******11",
    "debtor_name": "Fulano de tal",
    "type_document": "CPF",
    "due_date": null,
    "expiration_date": "2024-01-01 00:00:00.000000+00:00",
    "fine": null,
    "fine_date": null,
    "type_fine": "NONE",
    "tag": "NONE"
  }
}

Field	Type	Description
worked	Boolean	`false` — the refund attempt failed.
qr_code_id	Integer	Unique internal identifier of the QR Code.
tx_id	String	Conciliation ID of the QR Code.
pix_copy_and_paste	String	The original Copia e Cola code.
status	String	`CHARGEBACK` — indicates a chargeback was attempted.
amount	Decimal	Original payment amount in BRL.
amount_chargeback	Decimal	Amount for which the refund was attempted.
fee	Decimal	Fee (if applicable).
account_number	String	Account number of the recipient.
agency_number	String	Agency number of the recipient.
debtor_document	String	CPF or CNPJ of the original payer.
debtor_name	String	Name of the original payer.
type_document	String	Document type: `CPF` or `CNPJ`.
due_date	Datetime	Due date of the original charge.
expiration_date	Datetime	Expiration date of the QR Code.
fine	Decimal	Fine value (if applicable).
fine_date	Datetime	Fine date (if applicable).
type_fine	String	Fine type: `NONE`, `FIXED`, or `PERCENT`.
tag	String	Custom tag associated with the QR Code.

PIX_CASHIN_RECEIVED

Fired when a Pix transfer is received in the account, either via Pix key or manual bank transfer.

{
  "type": "PIX_CASHIN_RECEIVED",
  "data": {
    "worked": true,
    "end_to_end": "E3030629******422000020aeJxs",
    "type_transfer": "key",
    "amount": 0.01,
    "payment_date": "2024-01-01 12:00:00.000000+00:00",
    "fee": 0.00,
    "from_account": "000001",
    "from_agency": "0001",
    "from_account_key": "6efc7203-b4b9-4009-ced9-2d89951427ee",
    "debtor_name": "Fulano de tal",
    "debtor_institution": "000001",
    "debtor_branch_identifier": "1",
    "debtor_account": "0001",
    "debtor_legal_id": "12******11",
    "debtor_account_type": "CURRENT_ACCOUNT"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
end_to_end	String	End-to-end identifier (E2E ID) of the received Pix.
type_transfer	String	How the transfer was received: `key` (via Pix key) or `manual` (via account number).
amount	Decimal	Received amount in BRL.
payment_date	Datetime	Date and time the payment was received.
fee	Decimal	Fee charged (if applicable).
from_account	String	Account number where the transfer was received.
from_agency	String	Agency number where the transfer was received.
from_account_key	String	Pix key of the receiving account. `null` if the transfer was made manually without a key.
debtor_name	String	Name of the sender (payer).
debtor_institution	String	ISPB number of the sender's financial institution.
debtor_branch_identifier	String	Branch (agency) of the sender's account.
debtor_account	String	Account number of the sender.
debtor_legal_id	String	CPF or CNPJ of the sender.
debtor_account_type	String	Account type of the sender. Possible values: `CURRENT_ACCOUNT`, `SALARY_ACCOUNT`, `SAVINGS_ACCOUNT`, `PAYMENT_ACCOUNT`.

PIX_CASHIN_REFUNDED

Fired when a received Pix (cash in) is successfully refunded back to the original sender.

{
  "type": "PIX_CASHIN_REFUNDED",
  "data": {
    "worked": true,
    "end_to_end": "D35535240******MG3VDK2N",
    "chargeback_id": 1,
    "origin_chargeback_id": 1,
    "origin_end_to_end": "E00360305******2c56b47a3c6",
    "status": "SUCCESS",
    "amount": 100.00,
    "amount_chargeback": 100.00,
    "fee": 0.00,
    "account_number": "0001",
    "agency_number": "0001",
    "debtor_document": "58******87",
    "debtor_name": "ROSA MARIA DA SILVA",
    "type_document": "CPF",
    "tag": "description"
  }
}

Field	Type	Description
worked	Boolean	`true` when the refund was successfully completed.
end_to_end	String	E2E ID of the refund transaction.
chargeback_id	Integer	Unique identifier of the chargeback record.
origin_chargeback_id	Integer	ID of the original `AccountBankTransaction` that was refunded.
origin_end_to_end	String	E2E ID of the original received Pix.
status	String	`SUCCESS` — refund successfully completed.
amount	Decimal	Original received amount in BRL.
amount_chargeback	Decimal	Amount effectively refunded in BRL.
fee	Decimal	Fee (if applicable).
account_number	String	Account number that originally received the Pix.
agency_number	String	Agency number of the account that received the Pix.
debtor_document	String	CPF or CNPJ of the original sender.
debtor_name	String	Name of the original sender.
type_document	String	Document type: `CPF` or `CNPJ`.
tag	String	Custom tag (if applicable).

PIX_CASHIN_REFUNDED_ERROR

Fired when an attempt to refund a received Pix fails.

{
  "type": "PIX_CASHIN_REFUNDED_ERROR",
  "data": {
    "worked": true,
    "end_to_end": "D35535240******60PSEEHRSVDQ",
    "chargeback_id": 10,
    "origin_chargeback_id": 1,
    "origin_end_to_end": "E30306294******4500000000000",
    "status": "REJECTED",
    "amount": 0.01,
    "amount_chargeback": 0.01,
    "fee": 0.00,
    "account_number": "00001",
    "agency_number": "0001",
    "debtor_document": "12******11",
    "debtor_name": "Fulano de tal",
    "type_document": "CPF",
    "tag": "description"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched (even though the refund failed).
end_to_end	String	E2E ID of the failed refund attempt.
chargeback_id	Integer	Unique identifier of the chargeback record.
origin_chargeback_id	Integer	ID of the original `AccountBankTransaction`.
origin_end_to_end	String	E2E ID of the original received Pix.
status	String	`REJECTED` — refund was rejected.
amount	Decimal	Original received amount in BRL.
amount_chargeback	Decimal	Amount for which the refund was attempted.
fee	Decimal	Fee (if applicable).
account_number	String	Account number that originally received the Pix.
agency_number	String	Agency of the account that received the Pix.
debtor_document	String	CPF or CNPJ of the original sender.
debtor_name	String	Name of the original sender.
type_document	String	Document type: `CPF` or `CNPJ`.
tag	String	Custom tag (if applicable).

Transaction Events

MANUAL_CREDIT

Fired when a manual credit is added to an account. This is typically used for operational credits, adjustments, or refunds processed manually.

{
  "type": "MANUAL_CREDIT",
  "data": {
    "transaction_id": 123456,
    "amount": 100.50,
    "description": "Refund for service issue",
    "created_at": "2024-01-15 14:30:00.000000+00:00",
    "account": {
      "id": 101,
      "account": "123456",
      "agency": "0001"
    },
    "counterparty": {
      "name": "System Admin",
      "document": "12******90",
      "ispb": "00000000",
      "agency": "0001",
      "account": "000001"
    }
  }
}

Field	Type	Description
transaction_id	Integer	Unique identifier of the manual credit transaction.
amount	Decimal	Credit amount in BRL.
description	String	Description or reason for the manual credit.
created_at	Datetime	Date and time when the credit was created.
account	Object	Account that received the credit. Contains `id`, `account` (number), and `agency` (branch).
counterparty	Object	Information about the counterparty (originator). `null` if not available. Contains `name`, `document`, `ispb`, `agency`, and `account`.

MANUAL_DEBIT

Fired when a manual debit is subtracted from an account. This is typically used for operational debits, adjustments, or fees processed manually.

{
  "type": "MANUAL_DEBIT",
  "data": {
    "transaction_id": 123457,
    "amount": 50.25,
    "description": "Administrative fee adjustment",
    "created_at": "2024-01-15 15:45:00.000000+00:00",
    "account": {
      "id": 101,
      "account": "123456",
      "agency": "0001"
    },
    "counterparty": {
      "name": "System Admin",
      "document": "12******90",
      "ispb": "00000000",
      "agency": "0001",
      "account": "000001"
    }
  }
}

Field	Type	Description
transaction_id	Integer	Unique identifier of the manual debit transaction.
amount	Decimal	Debit amount in BRL.
description	String	Description or reason for the manual debit.
created_at	Datetime	Date and time when the debit was created.
account	Object	Account that was debited. Contains `id`, `account` (number), and `agency` (branch).
counterparty	Object	Information about the counterparty (recipient). `null` if not available. Contains `name`, `document`, `ispb`, `agency`, and `account`.

Cash Out Events

PIX_CASHOUT_CREATED

Fired when a Pix outgoing transfer is created. The transfer may be pending approval or already submitted.

{
  "type": "PIX_CASHOUT_CREATED",
  "data": {
    "worked": true,
    "transaction_id": 961588700187,
    "status": "NEW",
    "amount": 100.00,
    "fee": 0.00,
    "key": "05967095101",
    "tag": "2509161025357691309986",
    "from_accout": "463339"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
transaction_id	Integer	Unique identifier of the transaction. Use this to query the transfer status via other endpoints.
status	String	`NEW` — transfer created and queued for processing.
amount	Decimal	Transfer amount in BRL.
fee	Decimal	Fee charged (if applicable).
key	String	Pix key used as the destination. `null` if the transfer was made to a bank account manually.
tag	String	Custom tag (if applicable).
from_accout	String	Account number that originated the transfer. (Note: field name has a typo — `from_accout` — kept for backward compatibility.)

PIX_CASHOUT_SUCCESS

Fired when a Pix outgoing transfer is successfully completed.

{
  "type": "PIX_CASHOUT_SUCCESS",
  "data": {
    "worked": true,
    "transaction_id": 1,
    "end_to_end": "E355352402****840W36G858B7",
    "status": "SUCCESS",
    "amount": 100.00,
    "payment_date": "2024-01-01 12:00:00.000000+00:00",
    "fee": 0.00,
    "key": "05967095101",
    "tag": "description",
    "from_accout": "463339",
    "recipient_name": "Fulano de tal",
    "recipient_instution": "000000",
    "recipient_branch_identifier": "1",
    "recipient_account_id": "0000001",
    "recipient_legal_id": "05******01"
  }
}

Field	Type	Description
worked	Boolean	`true` when the transfer was successfully completed.
transaction_id	Integer	Unique identifier of the transaction.
end_to_end	String	End-to-end identifier (E2E ID) of the completed Pix.
status	String	`SUCCESS` — transfer completed.
amount	Decimal	Transfer amount in BRL.
payment_date	Datetime	Date and time when the transfer was completed.
fee	Decimal	Fee charged (if applicable).
key	String	Pix key used as the destination.
tag	String	Custom tag (if applicable).
from_accout	String	Account number that originated the transfer. (Typo kept for backward compatibility.)
recipient_name	String	Full name of the recipient.
recipient_instution	String	ISPB number of the recipient's financial institution. (Typo kept for backward compatibility.)
recipient_branch_identifier	String	Branch (agency) of the recipient's account.
recipient_account_id	String	Account number of the recipient.
recipient_legal_id	String	CPF or CNPJ of the recipient.

PIX_CASHOUT_ERROR

Fired when a Pix outgoing transfer fails.

{
  "type": "PIX_CASHOUT_ERROR",
  "data": {
    "worked": true,
    "transaction_id": 1,
    "end_to_end": null,
    "status": "ERROR",
    "amount": 100.00,
    "fee": 0.00,
    "key": "+55********75",
    "tag": "description",
    "from_accout": "00001",
    "error": "PIX key not found",
    "recipient_name": null,
    "recipient_instution": null,
    "recipient_branch_identifier": null,
    "recipient_account_id": null,
    "recipient_legal_id": null
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched (even though the transfer failed).
transaction_id	Integer	Unique identifier of the transaction.
end_to_end	String	E2E ID. `null` when the error occurred before the transfer reached the bank.
status	String	`ERROR` — transfer failed.
amount	Decimal	Transfer amount in BRL.
fee	Decimal	Fee (if applicable).
key	String	Pix key that was used as the destination.
tag	String	Custom tag (if applicable).
from_accout	String	Account number that originated the transfer. (Typo kept for backward compatibility.)
error	String	Description of the error (e.g. `"PIX key not found"`, `"Insufficient balance"`).
recipient_name	String	Recipient name. `null` when data was not retrieved before the error.
recipient_instution	String	Recipient institution ISPB. `null` when not retrieved.
recipient_branch_identifier	String	Recipient branch. `null` when not retrieved.
recipient_account_id	String	Recipient account. `null` when not retrieved.
recipient_legal_id	String	Recipient document. `null` when not retrieved.

PIX_CASHOUT_REFUND

Fired when a sent Pix transfer is returned by the recipient's bank (devolution).

{
  "type": "PIX_CASHOUT_REFUND",
  "data": {
    "worked": true,
    "transaction_id": 1,
    "end_to_end": "D30306294******60000002Pjdp",
    "origin_end_to_end": "E35535240******GRGBGLAIRDN",
    "origin_transaction_id": 1,
    "status": "REFUNDED",
    "amount": 0.01,
    "fee": 0.00,
    "key": "14******47",
    "tag": null,
    "from_accout": "900002",
    "recipient_name": "Fulano de tal",
    "recipient_instution": "30306294",
    "recipient_branch_identifier": "20",
    "recipient_account_id": "8044331",
    "recipient_legal_id": "14******47"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
transaction_id	Integer	ID of the refund transaction.
end_to_end	String	E2E ID of the refund (devolution) transaction.
origin_end_to_end	String	E2E ID of the original outgoing transfer that was returned.
origin_transaction_id	Integer	ID of the original outgoing transaction.
status	String	`REFUNDED` — the transfer has been returned.
amount	Decimal	Refunded amount in BRL.
fee	Decimal	Fee (if applicable).
key	String	Pix key associated with the original transfer.
tag	String	Custom tag (if applicable).
from_accout	String	Account that originated the original transfer. (Typo kept for backward compatibility.)
recipient_name	String	Name of the recipient in the original transfer.
recipient_instution	String	ISPB of the recipient's institution.
recipient_branch_identifier	String	Branch of the recipient's account.
recipient_account_id	String	Account number of the recipient.
recipient_legal_id	String	CPF or CNPJ of the recipient.

PIX_CASHOUT_CANCELED

Fired when a Pix outgoing transfer is canceled (e.g. due to insufficient balance or manual cancellation).

{
  "type": "PIX_CASHOUT_CANCELED",
  "data": {
    "worked": true,
    "transaction_id": 1,
    "end_to_end": null,
    "status": "CANCELLED",
    "amount": 0.01,
    "fee": 0.00,
    "key": "14******47",
    "tag": null,
    "from_accout": "900002",
    "cancel_description": "Insufficient balance",
    "recipient_name": "Fulano de tal",
    "recipient_instution": "30306294",
    "recipient_branch_identifier": "20",
    "recipient_account_id": "8044331",
    "recipient_legal_id": "14******47"
  }
}

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
transaction_id	Integer	Unique identifier of the transaction.
end_to_end	String	E2E ID. `null` when the transfer was canceled before reaching the bank.
status	String	`CANCELLED` — transfer was canceled.
amount	Decimal	Transfer amount in BRL.
fee	Decimal	Fee (if applicable).
key	String	Pix key used as destination.
tag	String	Custom tag (if applicable).
from_accout	String	Account that originated the transfer. (Typo kept for backward compatibility.)
cancel_description	String	Reason for cancellation (e.g. `"Insufficient balance"`). `null` if no description is available.
recipient_name	String	Name of the intended recipient.
recipient_instution	String	ISPB of the recipient's institution.
recipient_branch_identifier	String	Branch of the recipient's account.
recipient_account_id	String	Account number of the intended recipient.
recipient_legal_id	String	CPF or CNPJ of the intended recipient.

MED Events

MED (Mecanismo Especial de Devolução) is the Pix fraud return mechanism regulated by Banco Central do Brasil.

MED_CREATED

Fired when a MED infraction report is received and registered.

{
  "type": "MED_CREATED",
  "data": {
    "worked": true,
    "id": "med-uuid-123",
    "end_to_end": "E35535240******GRGBGLAIRDN",
    "infraction_report_id": "bcb-infraction-id-456",
    "infraction_report_status": "RECEIVED",
    "amount": 500.00,
    "reason": "FRAUD",
    "analysis_result": null,
    "analysis_details": null,
    "created_at": "2024-01-01 10:00:00.000000+00:00",
    "updated_at": "2024-01-01 10:00:00.000000+00:00",
    "user_name": "Fulano de tal",
    "user_document": "12345678901"
  }
}

MED_APPROVED

Fired when a MED infraction report is approved (the refund request is accepted).

{
  "type": "MED_APPROVED",
  "data": {
    "worked": true,
    "id": "med-uuid-123",
    "end_to_end": "E35535240******GRGBGLAIRDN",
    "infraction_report_id": "bcb-infraction-id-456",
    "infraction_report_status": "ANALYZED",
    "amount": 500.00,
    "reason": "FRAUD",
    "analysis_result": "ACCEPTED",
    "analysis_details": "Confirmed fraudulent transaction",
    "created_at": "2024-01-01 10:00:00.000000+00:00",
    "updated_at": "2024-01-02 09:00:00.000000+00:00",
    "user_name": "Fulano de tal",
    "user_document": "12345678901"
  }
}

MED_REJECTED

Fired when a MED infraction report is rejected.

{
  "type": "MED_REJECTED",
  "data": {
    "worked": true,
    "id": "med-uuid-123",
    "end_to_end": "E35535240******GRGBGLAIRDN",
    "infraction_report_id": "bcb-infraction-id-456",
    "infraction_report_status": "ANALYZED",
    "amount": 500.00,
    "reason": "FRAUD",
    "analysis_result": "REJECTED",
    "analysis_details": "Transaction could not be confirmed as fraud",
    "created_at": "2024-01-01 10:00:00.000000+00:00",
    "updated_at": "2024-01-02 09:00:00.000000+00:00",
    "user_name": "Fulano de tal",
    "user_document": "12345678901"
  }
}

MED_CANCELLED

Fired when a MED infraction report is cancelled.

{
  "type": "MED_CANCELLED",
  "data": {
    "worked": true,
    "id": "med-uuid-123",
    "end_to_end": "E35535240******GRGBGLAIRDN",
    "infraction_report_id": "bcb-infraction-id-456",
    "infraction_report_status": "CANCELLED",
    "amount": 500.00,
    "reason": "FRAUD",
    "analysis_result": null,
    "analysis_details": null,
    "created_at": "2024-01-01 10:00:00.000000+00:00",
    "updated_at": "2024-01-03 08:00:00.000000+00:00",
    "user_name": "Fulano de tal",
    "user_document": "12345678901"
  }
}

MED event fields (all four types share the same structure):

Field	Type	Description
worked	Boolean	`true` when the event was dispatched successfully.
id	String	Internal unique identifier of the MED record.
end_to_end	String	E2E ID of the original Pix transaction related to the infraction.
infraction_report_id	String	Identifier of the infraction report issued by Banco Central.
infraction_report_status	String	Current status: `RECEIVED` (created), `ANALYZED` (approved or rejected), `CANCELLED`.
amount	Decimal	Amount involved in the infraction in BRL.
reason	String	Reason for the infraction report (e.g. `FRAUD`, `OPERATIONAL_FLAW`).
analysis_result	String	Result of the analysis: `ACCEPTED` (MED_APPROVED), `REJECTED` (MED_REJECTED), or `null` (other statuses).
analysis_details	String	Explanation of the analysis decision. `null` when not yet analyzed or cancelled.
created_at	Datetime	When the infraction report was originally created.
updated_at	Datetime	When the MED record was last updated.
user_name	String	Name of the user associated with the transaction.
user_document	String	CPF or CNPJ of the user associated with the transaction.

Onboarding Events

Onboarding events report the outcome of an account opening request, and the creation of API credentials for an account.

ONBOARDING_REQUISITION_APPROVED

Fired when an account opening request is approved and the account has been created.

When the account was provisioned with an API user, the user_api_* fields carry the credentials. When it was not, the three fields are null — they are never omitted.

With API credentials (legal entity):

{
  "type": "ONBOARDING_REQUISITION_APPROVED",
  "data": {
    "account_agency": "0001",
    "account_created_at": "2024-01-01 10:00:00.000000+00:00",
    "account_id": 90217,
    "account_number": "3391204",
    "document_legal_id": "34028316000103",
    "fantasy_name": "Mercado Sao Joao",
    "hmac": "b7f3c1d9e2a84f6b95c0d7e1a3f5b8c2d4e6f7a9b1c3d5e7f9a0b2c4d6e8f0a1",
    "official_name": "COMERCIO DE ALIMENTOS SAO JOAO LTDA",
    "onboarding_approved_at": "2024-01-01 09:59:58.000000+00:00",
    "onboarding_created_at": "2023-12-27 13:02:44.918273+00:00",
    "onboarding_id": 48211,
    "onboarding_status": "APPROVED",
    "onboarding_status_internal": "APPROVED",
    "onboarding_type": "PJ",
    "user_api_email": "api.mercadosaojoao@example.com.br",
    "user_api_name": "API Mercado Sao Joao",
    "user_api_password": "8rT2qL9xVb4Kd7Mw"
  }
}

Without API credentials (natural person):

{
  "type": "ONBOARDING_REQUISITION_APPROVED",
  "data": {
    "account_agency": "0001",
    "account_created_at": "2024-01-02 11:05:39.110447+00:00",
    "account_id": 90223,
    "account_number": "3391218",
    "document_legal_id": "52998224725",
    "fantasy_name": "Maria Aparecida de Souza",
    "hmac": "4a9d2e7f1b6c3a8d5e0f2b7c4a9d1e6f3b8c5a0d7e2f4b9c1a6d3e8f5b0c7a2d",
    "official_name": "MARIA APARECIDA DE SOUZA",
    "onboarding_approved_at": "2024-01-02 11:05:38.772190+00:00",
    "onboarding_created_at": "2023-12-28 09:15:20.441002+00:00",
    "onboarding_id": 48215,
    "onboarding_status": "APPROVED",
    "onboarding_status_internal": "APPROVED",
    "onboarding_type": "PF",
    "user_api_email": null,
    "user_api_name": null,
    "user_api_password": null
  }
}

ONBOARDING_REQUISITION_REPROVED

Fired when an account opening request is rejected. No account was created, so the payload carries no account and no credential fields.

{
  "type": "ONBOARDING_REQUISITION_REPROVED",
  "data": {
    "document_legal_id": "11222333000181",
    "fantasy_name": "Rapido Leste",
    "official_name": "TRANSPORTES RAPIDO LESTE LTDA",
    "onboarding_created_at": "2023-12-29 16:41:07.558210+00:00",
    "onboarding_id": 48230,
    "onboarding_status": "REPROVED",
    "onboarding_status_internal": "REJECTED",
    "onboarding_status_updated_at": "2024-01-03 09:12:55.203718+00:00",
    "onboarding_type": "PJ"
  }
}

The event reports that the request was rejected, not why. The reason is handled outside this channel.

ACCOUNT_CREDENTIALS_CREATED

Fired when API credentials are generated for an account that already exists, outside the account opening flow.

It carries no onboarding_id and no status fields: the event is about the account, not about a request. Correlate it by account_id.

{
  "type": "ACCOUNT_CREDENTIALS_CREATED",
  "data": {
    "account_agency": "0001",
    "account_created_at": "2024-01-01 10:00:00.000000+00:00",
    "account_id": 90217,
    "account_number": "3391204",
    "document_legal_id": "34028316000103",
    "fantasy_name": "Mercado Sao Joao",
    "hmac": "b7f3c1d9e2a84f6b95c0d7e1a3f5b8c2d4e6f7a9b1c3d5e7f9a0b2c4d6e8f0a1",
    "official_name": "COMERCIO DE ALIMENTOS SAO JOAO LTDA",
    "user_api_email": "api.mercadosaojoao@example.com.br",
    "user_api_name": "API Mercado Sao Joao",
    "user_api_password": "8rT2qL9xVb4Kd7Mw"
  }
}

Onboarding event fields:

Field	Type	Description
onboarding_id	Integer	Unique identifier of the account opening request. Absent in `ACCOUNT_CREDENTIALS_CREATED`.
onboarding_type	String	`PF` (natural person) or `PJ` (legal entity).
onboarding_status	String	`APPROVED` on approval, `REPROVED` on rejection.
onboarding_status_internal	String	`APPROVED` on approval, `REJECTED` on rejection.
onboarding_created_at	Datetime	When the request was submitted.
onboarding_approved_at	Datetime	When the approval was recorded. Only in `ONBOARDING_REQUISITION_APPROVED`.
onboarding_status_updated_at	Datetime	When the rejection was recorded. Only in `ONBOARDING_REQUISITION_REPROVED`.
document_legal_id	String	CPF or CNPJ, digits only — no dots, slashes or dashes.
official_name	String	Corporate name (PJ) or full legal name (PF).
fantasy_name	String	Trade name.
account_id	Integer	Unique identifier of the account. Absent in `ONBOARDING_REQUISITION_REPROVED`.
account_agency	String	Branch code. String — may carry leading zeros.
account_number	String	Account number. String — may carry leading zeros.
account_created_at	Datetime	When the account was opened.
hmac	String	Secret key of the account, used to sign its API requests.
user_api_email	String	Login of the API user. `null` when no API user was created.
user_api_name	String	Name of the API user. `null` when no API user was created.
user_api_password	String	Password of the API user, in plain text. `null` when no API user was created.

These payloads carry secrets. hmac and user_api_password are credentials in plain text. Accept them over HTTPS only, keep the request body out of your logs, and store the values in a secret manager. The API password is not recoverable afterwards — if it is lost, a new one has to be generated.

Webhook Type Filter Reference

When registering a webhook, the type_webhook field determines which events will be delivered to your endpoint.

`type_webhook` value	Events delivered
`CASHIN`	`QR_CODE_COPY_AND_PASTE_CREATED`, `QR_CODE_COPY_AND_PASTE_PAID`, `PIX_CASHIN_RECEIVED`, `QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR`, `PIX_CASHIN_REFUNDED_ERROR`
`CASHOUT`	`PIX_CASHOUT_CREATED`, `PIX_CASHOUT_SUCCESS`, `PIX_CASHOUT_ERROR`, `PIX_CASHOUT_CANCELED`, `PIX_CASHOUT_REFUND`, `QR_CODE_COPY_AND_PASTE_REFUNDED`, `PIX_CASHIN_REFUNDED`
`PIX_CASHOUT_CREATED`	`PIX_CASHOUT_CREATED` only
`PIX_CASHOUT_SUCCESS`	`PIX_CASHOUT_SUCCESS` only
`MANUAL_CREDIT`	`MANUAL_CREDIT` only
`MANUAL_DEBIT`	`MANUAL_DEBIT` only
`ONBOARDING_REQUISITION_APPROVED`	`ONBOARDING_REQUISITION_APPROVED` only
`ONBOARDING_REQUISITION_REPROVED`	`ONBOARDING_REQUISITION_REPROVED` only
`ALL`	All event types
Any other specific type	Only that specific event type

ACCOUNT_CREDENTIALS_CREATED cannot be registered as a specific filter. It is not a valid type_webhook value, so it is delivered only to endpoints registered with ALL.