Webhooks

Since transfers occur asynchronously, it is highly important to correctly map and handle the webhooks sent.

Attention!

QI Tech webhooks should not be mapped restrictively. Additional fields may be included in the webhook payloads returned from our APIs.

Webhook for Pending Transactions

Webhook intended to update the status of transfers that remained pending (status 202) in the Pix transfer request.

Webhook Request Body

Request Body: Transaction Sent

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}

Request Body: Transaction Rejected

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "rejected",
    "created_at": "2021-10-22T20:30:23.459Z",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}

Webhook Body Param

Field	Type	Description	Max. Characters
webhook_type	string	An enumerator that defines the type of event being reported	23
webhook_datetime	string	Date and time the webhook was sent	20
request_control_key	string	UUID4 for query purposes about the request made.	36
pix_transfer_key	string	Identification key of the Pix transfer in the QI system	36
pix_transfer_status	string	Transaction status	200
created_at	string	Date and time the transaction was created	20

Webhook for incoming Pix

A webhook that will notify about Pix transactions that have arrived in an account.

Webhook Request Body

Request Body: Pix Received

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}

Webhook Body Param

Field	Type	Description	Max. Characters
webhook_type	string	An enumerator that defines the type of event being reported	23
webhook_datetime	string	Date and time the webhook was sent	20
pix_transfer_type	enumerator	Type of pix performed	Enumerator pix_transfer_type
target_pix_key	string	Pix key of the account to which the transaction will be sent	100
source_account	Object	Destination account - Should only be sent in transactions of type "manual"	Object source_account
transfer_amount	number	Transfer amount	10
receiver_conciliation_id	string	Receiver's conciliation identification	35
end_to_end_id	string	Idempotency key of a Pix transaction - should only be sent if the transfer type is "key"	32
pix_message	string	Message to be sent along with the Pix transfer	140
fee_amount	number	Transfer amount	10
pix_transfer_status	string	Pix transaction status	10
account_key	string	Unique identification key of the QI account	36
pix_transfer_key	string	Unique identification key of the Pix transfer	36

Enumerator pix_transfer_type

Enumerator	Description
manual	Pix using the destination account details
key	Pix using a pix key
static_qr_code	Pix using a static QR code
dynamic_qr_code	Pix using a dynamic QR code
reversal	Pix refund

Object source_account

Field	Type	Description	Characters
account_branch *	string	Branch of the account	6
account_digit *	string	Account digit	1
account_number *	string	Account number	20
owner_document_number *	string	CPF or CNPJ (numbers only) of the account holder	14
owner_name	string	Name of the account holder	150
account_type *	enumerator	Type of account	Enumerator account_type
ispb *	string	Eight-digit code that identifies banks in the Central Bank's reserve transfer system	8

Enumerator account_type

Enumerator	Description
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta de Pagamentos

Webhook for Pix Refunds

A webhook that will notify about Pix refunds that have arrived in an account.

Webhook Request Body

Request Body: Pix Received

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494"
  }
}

Webhook Body Param

Field	Type	Description	Max. Characters
webhook_type	string	An enumerator that defines the type of event being reported	23
webhook_datetime	string	Date and time the webhook was sent	20
pix_transfer_type	enumerator	Type of pix performed	Enumerator pix_transfer_type
target_pix_key	string	Pix key of the account to which the transaction will be sent	100
source_account	Object	Destination account - Should only be sent in transactions of type "manual"	Object source_account
transfer_amount	number	Transfer amount	10
receiver_conciliation_id	string	Receiver's conciliation identification	35
end_to_end_id	string	Idempotency key of a Pix transaction - should only be sent if the transfer type is "key"	32
pix_message	string	Message to be sent along with the Pix transfer	140
fee_amount	number	Transfer amount	10
pix_transfer_status	string	Pix transaction status	10
account_key	string	Unique identification key of the QI account	36
pix_transfer_key	string	Unique identification key of the Pix transfer	36
original_outgoing_pix_transfer	string	Unique identification key of the original outbound Pix transfer	36

Enumerator pix_transfer_type

Enumerator	Description
manual	Pix using the destination account details
key	Pix using a pix key
static_qr_code	Pix using a static QR code
dynamic_qr_code	Pix using a dynamic QR code
reversal	Pix refund

Object source_account

Field	Type	Description	Characters
account_branch	string	Branch of the account	6
account_digit	string	Account digit	1
account_number	string	Account number	20
owner_document_number	string	CPF or CNPJ (numbers only) of the account holder	14
owner_name	string	Name of the account holder	150
account_type	enumerator	Type of account	Enumerator account_type
ispb	string	Eight-digit code that identifies banks in the Central Bank's reserve transfer system	8

Enumerator account_type

Enumerator	Description
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta de Pagamentos