Pular para o conteúdo principal

Webhooks

Uma vez que as transferências ocorrem de forma assíncrona, é de suma importância o mapeamento e o tratamento corretos dos webhooks enviados.

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Webhook para Transações Pendentes

Webhook destinado para atualizar o status das transferências que ficaram pendentes (status 202) na requisição de envio do Pix.

Webhook Request Body

Request Body: Transação Enviada
{
"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: Transação Rejeitada
{
"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

CampoTipoDescriçãoMax. Caracteres
webhook_typestringUm enumerador que define o tipo de evento sendo reportado23
webhook_datetimestringData e hora do envio do webhook20
request_control_keystringUUID4 para fins de consulta sobre a requisição feita.36
pix_transfer_keystringChave de identificação da transferência Pix no sistema QI36
pix_transfer_statusstringStatus da transação.200
created_atstringData e hora de criação da transação.20

Webhook para Pix de Entrada

Webhook que servirá para avisar sobre transações Pix que chegaram para uma conta.

Webhook Request Body

Request Body: Pix Recebido
{
"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

CampoTipoDescriçãoMax. Caracteres
webhook_typestringUm enumerador que define o tipo de evento sendo reportado23
webhook_datetimestringData e hora do envio do webhook20
pix_transfer_typeenumeratorTipo do pix realizadoEnumerador pix_transfer_type
target_pix_keystringChave pix da conta a ser enviada a transação100
source_accountObjectConta destino - Só deve ser enviada em transações do tipo "manual"Objeto source_account
transfer_amountnumberValor da transferencia10
receiver_conciliation_idstringIdenticação de conciliação do recebedor35
end_to_end_idstringChave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key"32
pix_messagestringMensagem a ser enviada junto à transferência Pix140
fee_amountnumberValor da transferencia10
pix_transfer_statusstringStatus da transação pix10
account_keystringChave única de identificação da conta QI36
pix_transfer_keystringChave única de identificação da transferência Pix36

Enumerador pix_transfer_type

EnumeradorDescrição
manualPix utilizando os dados da conta destino
keyPix utilizando uma chave pix
static_qr_codePix utilizando um QR code estático
dynamic_qr_codePix utilizando um QR code dinâmico
reversalDevolução Pix

Objeto source_account

CampoTipoDescriçãoCaracteres
account_branch *stringAgência da conta6
account_digit *stringDígito da conta1
account_number *stringNúmero da conta20
owner_document_number *stringCPF ou CNPJ (apenas números) do titular da conta14
owner_namestringNome do titular da conta150
account_type*enumeratorTipo da contaEnumerador account_type
ispb *stringCódigo de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central8

Enumerador account_type

EnumeradorDescrição
checking_accountConta Corrente
salary_accountConta Salário
saving_accountConta Poupança
payment_accountConta de Pagamentos

Webhook para Devoluções de Pix

Webhook que servirá para avisar sobre devoluções Pix que chegaram para uma conta.

Webhook Request Body

Request Body: Pix Recebido
{
"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": "D18236120202308111235s14fddf2801",
"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",
"original_end_to_end_id": "E18236120202308111235s14fddf2801"
}
}

Webhook Body Param

CampoTipoDescriçãoMax. Caracteres
webhook_typestringUm enumerador que define o tipo de evento sendo reportado23
webhook_datetimestringData e hora do envio do webhook20
pix_transfer_typeenumeratorTipo do pix realizadoEnumerador pix_transfer_type
target_pix_keystringChave pix da conta a ser enviada a transação100
source_accountObjectConta destino - Só deve ser enviada em transações do tipo "manual"Objeto source_account
transfer_amountnumberValor da transferencia10
receiver_conciliation_idstringIdenticação de conciliação do recebedor35
end_to_end_idstringChave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key"32
pix_messagestringMensagem a ser enviada junto à transferência Pix140
fee_amountnumberValor da transferencia10
pix_transfer_statusstringStatus da transação pix10
account_keystringChave única de identificação da conta QI36
pix_transfer_keystringChave única de identificação da transferência Pix36
original_outgoing_pix_transferstringChave única de identificação da transferência Pix de saída Original36
original_end_to_end_idstringEnd to end da transferência Pix de saída Original36

Enumerador pix_transfer_type

EnumeradorDescrição
manualPix utilizando os dados da conta destino
keyPix utilizando uma chave pix
static_qr_codePix utilizando um QR code estático
dynamic_qr_codePix utilizando um QR code dinâmico
reversalDevolução Pix

Objeto source_account

CampoTipoDescriçãoCaracteres
account_branchstringAgência da conta6
account_digitstringDígito da conta1
account_numberstringNúmero da conta20
owner_document_numberstringCPF ou CNPJ (apenas números) do titular da conta14
owner_namestringNome do titular da conta150
account_typeenumeratorTipo da contaEnumerador account_type
ispbstringCódigo de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central8

Enumerador account_type

EnumeradorDescrição
checking_accountConta Corrente
salary_accountConta Salário
saving_accountConta Poupança
payment_accountConta de Pagamentos