Webhook Events

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

{
  "type": "<EVENT_TYPE>",
  "data": { ... }
}
FieldTypeDescription
typeStringIdentifies the event type. See the sections below.
dataObjectEvent payload. Fields vary according to the event type.

Event Types Summary

TypeCategoryTrigger
QR_CODE_COPY_AND_PASTE_CREATEDCash InA QR Code (Pix Copia e Cola) was generated
QR_CODE_COPY_AND_PASTE_PAIDCash InA QR Code was paid by the customer
QR_CODE_COPY_AND_PASTE_REFUNDEDCash InA QR Code payment was successfully refunded (chargeback)
QR_CODE_COPY_AND_PASTE_REFUNDED_ERRORCash InAn attempted QR Code refund failed
PIX_CASHIN_RECEIVEDCash InA Pix transfer was received (key or manual)
PIX_CASHIN_REFUNDEDCash InA received Pix transfer was successfully refunded
PIX_CASHIN_REFUNDED_ERRORCash InAn attempted refund of a received Pix transfer failed
PIX_CASHOUT_CREATEDCash OutA Pix transfer was created (pending or awaiting approval)
PIX_CASHOUT_SUCCESSCash OutA Pix transfer was successfully completed
PIX_CASHOUT_ERRORCash OutA Pix transfer failed
PIX_CASHOUT_REFUNDCash OutA Pix transfer was returned by the recipient's bank
PIX_CASHOUT_CANCELEDCash OutA Pix transfer was canceled
MED_CREATEDMEDA MED infraction report was received
MED_APPROVEDMEDA MED infraction report was approved (accepted)
MED_REJECTEDMEDA MED infraction report was rejected
MED_CANCELLEDMEDA MED infraction report was cancelled
ONBOARDING_REQUISITION_APPROVEDOnboardingAn onboarding requisition was fully approved

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-v3.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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
qr_code_idIntegerUnique internal identifier of the QR Code.
tx_idStringConciliation ID (txId) of the QR Code, used for bank reconciliation.
pix_copy_and_pasteStringFull Pix Copia e Cola code that the customer can paste in their banking app to pay.
statusStringNEW — QR Code generated, awaiting payment.
amountDecimalCharged amount in BRL.
amount_chargebackDecimalRefunded amount. 0.00 while the payment has not been refunded.
feeDecimalFee charged to the customer (if applicable).
base_64_imageStringQR Code image in base64 format. Deprecated — use base_64_image_url instead.
base_64_image_urlStringURL to the QR Code image.
account_numberStringAccount number of the recipient (payee).
agency_numberStringAgency (branch) number of the recipient.
debtor_documentStringCPF or CNPJ of the payer.
debtor_nameStringFull name or company name of the payer.
type_documentStringDocument type of the payer: CPF or CNPJ.
due_dateDatetimeDue date for scheduled charges. null for immediate QR Codes.
expiration_dateDatetimeDate and time when the QR Code expires.
fineDecimalFine value applied after the due date (if any).
fine_dateDatetimeDate from which the fine is applied.
type_fineStringFine type: NONE, FIXED, or PERCENT.
tagStringCustom 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-v3.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": "Simpay 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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
qr_code_idIntegerUnique internal identifier of the QR Code.
tx_idStringConciliation ID (txId) of the QR Code.
end_to_endStringEnd-to-end identifier (E2E ID) of the Pix payment.
pix_copy_and_pasteStringThe original Copia e Cola code that was paid.
statusStringPAID — payment confirmed.
payment_dateDatetimeDate and time when the payment was confirmed.
amountDecimalPaid amount in BRL.
amount_chargebackDecimalRefunded amount. 0.00 when no refund has occurred.
feeDecimalFee charged to the customer (if applicable).
base_64_imageStringQR Code image in base64 format. Deprecated.
base_64_image_urlStringURL to the QR Code image.
account_numberStringAccount number of the recipient.
agency_numberStringAgency (branch) number of the recipient.
debtor_documentStringCPF or CNPJ of the payer.
debtor_nameStringFull name or company name of the payer.
debtor_institutionStringName of the payer's financial institution.
debtor_institution_numberStringISPB number of the payer's financial institution.
type_documentStringDocument type of the payer: CPF or CNPJ.
due_dateDatetimeDue date of the charge. null for immediate QR Codes.
expiration_dateDatetimeExpiration date of the QR Code.
fineDecimalFine value (if applicable).
fine_dateDatetimeDate from which the fine is applied.
type_fineStringFine type: NONE, FIXED, or PERCENT.
tagStringCustom 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"
  }
}
FieldTypeDescription
workedBooleantrue when the refund was successfully dispatched.
end_to_endStringE2E ID of the refund transaction.
chargeback_idIntegerUnique identifier of the chargeback record.
origin_chargeback_idIntegerID of the original QR Code that was refunded.
origin_end_to_endStringE2E ID of the original payment.
tx_idStringConciliation ID of the original QR Code.
statusStringCHARGEBACK — refund successfully completed.
amountDecimalOriginal payment amount in BRL.
amount_chargebackDecimalAmount effectively refunded in BRL.
feeDecimalFee charged (if applicable).
account_numberStringAccount number of the original recipient.
agency_numberStringAgency number of the original recipient.
debtor_documentStringCPF or CNPJ of the original payer.
debtor_nameStringName of the original payer.
type_documentStringDocument type: CPF or CNPJ.
fineDecimalFine value (if applicable).
fine_dateDatetimeDate from which the fine is applied.
type_fineStringFine type: NONE, FIXED, or PERCENT.
tagStringCustom 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"
  }
}
FieldTypeDescription
workedBooleanfalse — the refund attempt failed.
qr_code_idIntegerUnique internal identifier of the QR Code.
tx_idStringConciliation ID of the QR Code.
pix_copy_and_pasteStringThe original Copia e Cola code.
statusStringCHARGEBACK — indicates a chargeback was attempted.
amountDecimalOriginal payment amount in BRL.
amount_chargebackDecimalAmount for which the refund was attempted.
feeDecimalFee (if applicable).
account_numberStringAccount number of the recipient.
agency_numberStringAgency number of the recipient.
debtor_documentStringCPF or CNPJ of the original payer.
debtor_nameStringName of the original payer.
type_documentStringDocument type: CPF or CNPJ.
due_dateDatetimeDue date of the original charge.
expiration_dateDatetimeExpiration date of the QR Code.
fineDecimalFine value (if applicable).
fine_dateDatetimeFine date (if applicable).
type_fineStringFine type: NONE, FIXED, or PERCENT.
tagStringCustom 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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
end_to_endStringEnd-to-end identifier (E2E ID) of the received Pix.
type_transferStringHow the transfer was received: key (via Pix key) or manual (via account number).
amountDecimalReceived amount in BRL.
payment_dateDatetimeDate and time the payment was received.
feeDecimalFee charged (if applicable).
from_accountStringAccount number where the transfer was received.
from_agencyStringAgency number where the transfer was received.
from_account_keyStringPix key of the receiving account. null if the transfer was made manually without a key.
debtor_nameStringName of the sender (payer).
debtor_institutionStringISPB number of the sender's financial institution.
debtor_branch_identifierStringBranch (agency) of the sender's account.
debtor_accountStringAccount number of the sender.
debtor_legal_idStringCPF or CNPJ of the sender.
debtor_account_typeStringAccount 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"
  }
}
FieldTypeDescription
workedBooleantrue when the refund was successfully completed.
end_to_endStringE2E ID of the refund transaction.
chargeback_idIntegerUnique identifier of the chargeback record.
origin_chargeback_idIntegerID of the original AccountBankTransaction that was refunded.
origin_end_to_endStringE2E ID of the original received Pix.
statusStringSUCCESS — refund successfully completed.
amountDecimalOriginal received amount in BRL.
amount_chargebackDecimalAmount effectively refunded in BRL.
feeDecimalFee (if applicable).
account_numberStringAccount number that originally received the Pix.
agency_numberStringAgency number of the account that received the Pix.
debtor_documentStringCPF or CNPJ of the original sender.
debtor_nameStringName of the original sender.
type_documentStringDocument type: CPF or CNPJ.
tagStringCustom 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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched (even though the refund failed).
end_to_endStringE2E ID of the failed refund attempt.
chargeback_idIntegerUnique identifier of the chargeback record.
origin_chargeback_idIntegerID of the original AccountBankTransaction.
origin_end_to_endStringE2E ID of the original received Pix.
statusStringREJECTED — refund was rejected.
amountDecimalOriginal received amount in BRL.
amount_chargebackDecimalAmount for which the refund was attempted.
feeDecimalFee (if applicable).
account_numberStringAccount number that originally received the Pix.
agency_numberStringAgency of the account that received the Pix.
debtor_documentStringCPF or CNPJ of the original sender.
debtor_nameStringName of the original sender.
type_documentStringDocument type: CPF or CNPJ.
tagStringCustom tag (if applicable).

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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
transaction_idIntegerUnique identifier of the transaction. Use this to query the transfer status via other endpoints.
statusStringNEW — transfer created and queued for processing.
amountDecimalTransfer amount in BRL.
feeDecimalFee charged (if applicable).
keyStringPix key used as the destination. null if the transfer was made to a bank account manually.
tagStringCustom tag (if applicable).
from_accoutStringAccount 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"
  }
}
FieldTypeDescription
workedBooleantrue when the transfer was successfully completed.
transaction_idIntegerUnique identifier of the transaction.
end_to_endStringEnd-to-end identifier (E2E ID) of the completed Pix.
statusStringSUCCESS — transfer completed.
amountDecimalTransfer amount in BRL.
payment_dateDatetimeDate and time when the transfer was completed.
feeDecimalFee charged (if applicable).
keyStringPix key used as the destination.
tagStringCustom tag (if applicable).
from_accoutStringAccount number that originated the transfer. (Typo kept for backward compatibility.)
recipient_nameStringFull name of the recipient.
recipient_instutionStringISPB number of the recipient's financial institution. (Typo kept for backward compatibility.)
recipient_branch_identifierStringBranch (agency) of the recipient's account.
recipient_account_idStringAccount number of the recipient.
recipient_legal_idStringCPF 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
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched (even though the transfer failed).
transaction_idIntegerUnique identifier of the transaction.
end_to_endStringE2E ID. null when the error occurred before the transfer reached the bank.
statusStringERROR — transfer failed.
amountDecimalTransfer amount in BRL.
feeDecimalFee (if applicable).
keyStringPix key that was used as the destination.
tagStringCustom tag (if applicable).
from_accoutStringAccount number that originated the transfer. (Typo kept for backward compatibility.)
errorStringDescription of the error (e.g. "PIX key not found", "Insufficient balance").
recipient_nameStringRecipient name. null when data was not retrieved before the error.
recipient_instutionStringRecipient institution ISPB. null when not retrieved.
recipient_branch_identifierStringRecipient branch. null when not retrieved.
recipient_account_idStringRecipient account. null when not retrieved.
recipient_legal_idStringRecipient 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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
transaction_idIntegerID of the refund transaction.
end_to_endStringE2E ID of the refund (devolution) transaction.
origin_end_to_endStringE2E ID of the original outgoing transfer that was returned.
origin_transaction_idIntegerID of the original outgoing transaction.
statusStringREFUNDED — the transfer has been returned.
amountDecimalRefunded amount in BRL.
feeDecimalFee (if applicable).
keyStringPix key associated with the original transfer.
tagStringCustom tag (if applicable).
from_accoutStringAccount that originated the original transfer. (Typo kept for backward compatibility.)
recipient_nameStringName of the recipient in the original transfer.
recipient_instutionStringISPB of the recipient's institution.
recipient_branch_identifierStringBranch of the recipient's account.
recipient_account_idStringAccount number of the recipient.
recipient_legal_idStringCPF 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"
  }
}
FieldTypeDescription
workedBooleantrue when the event was dispatched successfully.
transaction_idIntegerUnique identifier of the transaction.
end_to_endStringE2E ID. null when the transfer was canceled before reaching the bank.
statusStringCANCELLED — transfer was canceled.
amountDecimalTransfer amount in BRL.
feeDecimalFee (if applicable).
keyStringPix key used as destination.
tagStringCustom tag (if applicable).
from_accoutStringAccount that originated the transfer. (Typo kept for backward compatibility.)
cancel_descriptionStringReason for cancellation (e.g. "Insufficient balance"). null if no description is available.
recipient_nameStringName of the intended recipient.
recipient_instutionStringISPB of the recipient's institution.
recipient_branch_identifierStringBranch of the recipient's account.
recipient_account_idStringAccount number of the intended recipient.
recipient_legal_idStringCPF or CNPJ of the intended recipient.


Webhook Type Filter Reference

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

type_webhook valueEvents delivered
CASHINQR_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
CASHOUTPIX_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_CREATEDPIX_CASHOUT_CREATED only
PIX_CASHOUT_SUCCESSPIX_CASHOUT_SUCCESS only
ALLAll event types
Any other specific typeOnly that specific event type