Webhooks

Atenção!

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

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

Webhook de pagamentos

Webhook Request Body

Request Body: Pagamento executado

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "executed",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}

Request Body: Pagamento pendente de execução

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "pending_execution",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}

Request Body: Pagamento rejeitado

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": null,
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "rejected",
    "payment_type":"bank_slip",
    "error_code": "BIP000023",
    "error_message": "The source account has insufficient balance. Payment cannot be made."
  }
}

Request Body: Pagamento revertido

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "reverted",
    "payment_type":"bank_slip",
    "error_code": "BIP000029",
    "error_message": "Bank slip payment write off rejected."
  }
}

Webhook Body Params

Campo	Tipo	Descrição
webhook_type	string	Um enumerador que define o tipo de evento sendo reportado
webhook_datetime	string	Data e hora do envio do webhook
request_control_key	uuid4	Chave única de identificação da request do cliente.
source_account_key *	uuid4	Chave da conta debitada.
payment_key	uuid4	Chave única de identificação do pagamento.
payment_schedule_key	uuid4	Chave única de identificação do agendamento (somente para pagamentos gerados a partir de um agendamento).
barcode	string	Código de barras.
digitable_line	string	Linha digitável.
payment_type	enum	Tipo do pagamento.
payment_status	enum	Status do pagamento.
error_code	string	Código de erro.
error_message	string	Mensagem de erro.

Enumeradores payment_type

Enumerador	Tipo	Descrição
bank_slip	string	Boleto bancário
collection_slip	string	Fatura de recolhimento

Enumeradores payment_status

Enumerador	Tipo	Descrição
executed	string	Executado
rejected	string	rejeitado
reverted	string	Revertido

Código HTTP	Código QI	Título	Descrição (eng)	Descrição (pt-br)
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000014	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
400	BIP000023	Bad Request	The source account has insufficient balance. Payment cannot be made.	A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado.
400	BIP000025	Bad Request	It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance.	Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência.
400	BIP000029	Bad Request	Bank slip payment write off rejected.	Baixa de pagamento de boleto rejeitada.
400	BIP000034	Bad Request	Collection slip already paid.	Fatura de recolhimento já paga.
400	BIP000036	Bad Request	Covenant slip overdue.	Fatura de recolhimento vencida.
400	BIP000038	Bad Request	Outside of covenant payment hours.	Fora do horário de pagamento do convênio.
400	BIP000044	Bad Request	It was not possible to pay the collection slip at this time. Please verify your

Webhook de agendamento de pagamento

Fluxo de Webhooks para Agendamentos de Pagamentos

O processo de agendamento e execução de pagamentos envolve a utilização de diferentes webhooks, cada um desempenhando um papel específico na notificação e no acompanhamento do status do pagamento.

Quando o agendamento é executado na data solicitada, ele pode seguir para o status executed e será disparado um webhook de payment_schedule com o status executed, a execução do agendamento resulta na criação de um payment com o status pending e será enviado o webhook do mesmo. Alternativamente, o agendamento pode seguir para o status rejected, sem que o payment seja criado, em situações como o fechamento da conta ou alteração do valor do boleto, por exemplo. Nesse caso somente o webhook de payment_schedule com o status rejected é enviado, acompanhado dos devidos códigos de erro.

• Inicialmente, o status do pagamento será pending, pois o processo de pagamento está em andamento. Quando o pagamento é concluído, um novo webhook de payment é enviado, agora com o status executed.
• Se o pagamento não puder ser concluído, por exemplo, devido à falta de saldo na conta, um webhook de payment com o status rejected será enviado, acompanhado dos devidos códigos de erro.
• Em casos de insuficiência de saldo na conta, o sistema realizará até 3 tentativas de pagamento, com um intervalo de 30 minutos entre cada uma. Nessa situação, poderão ser gerados múltiplos registros de pagamento para um mesmo agendamento executado. Por exemplo, se o saldo suficiente estiver disponível apenas na terceira tentativa, serão disparados os webhooks dos dois primeiros pagamentos com os status payment e rejected, seguidos pelos webhooks do terceiro pagamento com os status payment e executed.

Webhook Request Body

Request Body: Agendamento de pagamento executado

{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "executed",
    "error_code": null,
    "error_message": null
  }
}

Request Body: Agendamento de pagamento rejeitado

{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "rejected",
    "error_code": "BIP000007",
    "error_message": "Bank slip blocked for payment"
  }
}

Webhook Body Params

Campo	Tipo	Descrição
webhook_type	string	Um enumerador que define o tipo de evento sendo reportado
webhook_datetime	string	Data e hora do envio do webhook
request_control_key	uuid4	Chave única de identificação da request do cliente.
source_account_key *	uuid4	Chave da conta debitada.
payment_key	uuid4	Chave única de identificação do pagamento.
payment_schedule_key	uuid4	Chave única de identificação do agendamento pagamento.
barcode	string	Código de barras.
digitable_line	string	Linha digitável.
payment_type	enum	Tipo do agendamento de pagamento.
payment_schedule_status	enum	Status do agendamento de pagamento.
error_code	string	Código de erro.
error_message	string	Mensagem de erro.

Enumeradores payment_type

Enumerador	Tipo	Descrição
bank_slip	string	Boleto bancário
collection_slip	string	Fatura de recolhimento

Enumeradores payment_schedule_status

Enumerador	Tipo	Descrição
executed	string	Executado
rejected	string	Rejeitado

Código HTTP	Código QI	Título	Descrição (eng)	Descrição (pt-br)
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000014	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
400	BIP000006	Bad Request	Bank slip already written off	Boleto já baixado
400	BIP000007	Bad Request	Bank slip blocked for payment	Boleto bloqueado para pagamento
400	BIP000008	Bad Request	Bank slip already paid	Boleto já pago
400	BIP000009	Bad Request	Invalid bank slip. Please consult issuing bank	Boleto inválido. Favor consultar banco emissor
400	BIP000034	Bad Request	Collection slip already paid.	Fatura de recolhimento já paga.