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

Campo	Tipo	Descrição	Max. Caracteres
webhook_type	string	Um enumerador que define o tipo de evento sendo reportado	23
webhook_datetime	string	Data e hora do envio do webhook	20
request_control_key	string	UUID4 para fins de consulta sobre a requisição feita.	36
pix_transfer_key	string	Chave de identificação da transferência Pix no sistema QI	36
pix_transfer_status	string	Status da transação.	200
created_at	string	Data 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

Campo	Tipo	Descrição	Max. Caracteres
webhook_type	string	Um enumerador que define o tipo de evento sendo reportado	23
webhook_datetime	string	Data e hora do envio do webhook	20
pix_transfer_type	enumerator	Tipo do pix realizado	Enumerador pix_transfer_type
target_pix_key	string	Chave pix da conta a ser enviada a transação	100
source_account	Object	Conta destino - Só deve ser enviada em transações do tipo "manual"	Objeto source_account
transfer_amount	number	Valor da transferencia	10
receiver_conciliation_id	string	Identicação de conciliação do recebedor	35
end_to_end_id	string	Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key"	32
pix_message	string	Mensagem a ser enviada junto à transferência Pix	140
fee_amount	number	Valor da transferencia	10
pix_transfer_status	string	Status da transação pix	10
account_key	string	Chave única de identificação da conta QI	36
pix_transfer_key	string	Chave única de identificação da transferência Pix	36

Enumerador pix_transfer_type

Enumerador	Descrição
manual	Pix utilizando os dados da conta destino
key	Pix utilizando uma chave pix
static_qr_code	Pix utilizando um QR code estático
dynamic_qr_code	Pix utilizando um QR code dinâmico
reversal	Devolução Pix

Objeto source_account

Campo	Tipo	Descrição	Caracteres
account_branch *	string	Agência da conta	6
account_digit *	string	Dígito da conta	1
account_number *	string	Número da conta	20
owner_document_number *	string	CPF ou CNPJ (apenas números) do titular da conta	14
owner_name	string	Nome do titular da conta	150
account_type*	enumerator	Tipo da conta	Enumerador account_type
ispb *	string	Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central	8

Enumerador account_type

Enumerador	Descrição
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta 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

Campo	Tipo	Descrição	Max. Caracteres
webhook_type	string	Um enumerador que define o tipo de evento sendo reportado	23
webhook_datetime	string	Data e hora do envio do webhook	20
pix_transfer_type	enumerator	Tipo do pix realizado	Enumerador pix_transfer_type
target_pix_key	string	Chave pix da conta a ser enviada a transação	100
source_account	Object	Conta destino - Só deve ser enviada em transações do tipo "manual"	Objeto source_account
transfer_amount	number	Valor da transferencia	10
receiver_conciliation_id	string	Identicação de conciliação do recebedor	35
end_to_end_id	string	Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key"	32
pix_message	string	Mensagem a ser enviada junto à transferência Pix	140
fee_amount	number	Valor da transferencia	10
pix_transfer_status	string	Status da transação pix	10
account_key	string	Chave única de identificação da conta QI	36
pix_transfer_key	string	Chave única de identificação da transferência Pix	36
original_outgoing_pix_transfer	string	Chave única de identificação da transferência Pix de saída Original	36
original_end_to_end_id	string	End to end da transferência Pix de saída Original	36

Enumerador pix_transfer_type

Enumerador	Descrição
manual	Pix utilizando os dados da conta destino
key	Pix utilizando uma chave pix
static_qr_code	Pix utilizando um QR code estático
dynamic_qr_code	Pix utilizando um QR code dinâmico
reversal	Devolução Pix

Objeto source_account

Campo	Tipo	Descrição	Caracteres
account_branch	string	Agência da conta	6
account_digit	string	Dígito da conta	1
account_number	string	Número da conta	20
owner_document_number	string	CPF ou CNPJ (apenas números) do titular da conta	14
owner_name	string	Nome do titular da conta	150
account_type	enumerator	Tipo da conta	Enumerador account_type
ispb	string	Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central	8

Enumerador account_type

Enumerador	Descrição
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta de Pagamentos