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 criação da recorrência de Pix Automático

Webhook destinado com as informações de criação de recorrência do cliente

Webhook Request Body

Request Body: Criação de recorrência

{
    "webhook_type": "baas.automatic_pix.incoming_recurrence",
    "webhook_datetime": "2025-10-22T20:30:23.459Z",
    "data": {
        "account_key": "13385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_status": "pending_confirmation",
        "transaction_amount": "150.00",
        "periodicity": "monthly",
        "journey_type": "j1_in_app_only_recurrence",
        "pix_transfer_type": "key",
        "end_to_end_id": "E1234567890123456789012",
        "start_date": "2025-06-01",
        "end_date": "2026-06-01",
        "receiver_conciliation_id": "rec-conc-789",
        "target_pix_key": "receiver@bank.com.br",
        "payer_document_number": "12345678900",
        "pix_message": "Pagamento mensal de serviço",
        "created_at": "2025-05-22T10:00:00Z",
        "updated_at": "2025-05-22T12:00:00Z"
    }
}

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
account_key	uuid4	Chave única de identificação da conta.	36
incoming_recurrence_key	uuid4	Chave única de identificação da autorização	36
incoming_recurrence_status	string	Identificador de status da recorrência Pix.	Enumeradores incoming_recurrence_status
transaction_amount	number	Valor da transferência para ocorrência de valor fixo.	10
minimum_transaction_amount	number	Valor mínimo da transferência para ocorrência de valor variável.	10
maximum_transaction_amount	number	Valor máximo da transferência para ocorrência de valor variável.	10
periodicity	enum	Tipo da periodicidade associada ao pagamento	Enumeradores periodicity
journey_type	enum	Tipo da jornada de solicitação	Enumeradores journey_type
pix_transfer_type	enum	Tipo do Pix a ser realizado	Enumeradores pix_transfer_type
end_to_end_id	string	Chave de idempotência de uma transação Pix dentro do SPI.	32
start_date	string	Data de início da recorrência	-
end_date	string	Data de término da recorrência, para os casos de tempo indeterminado, enviar como null	-
receiver_conciliation_id	string	Identificação de conciliação do recebedor.	35
target_pix_key	string	Chave Pix da conta da transação.	100
payer_document_number	string	Número de documento do pagador da transação	14
pix_message	string	Mensagem a ser enviada junto à transferência Pix.	140
created_at	string	Horário da criação da solicitação de recorrência	-
updated_at	string	Horário de atualização da solicitação de recorrência	-

Enumerador incoming_recurrence_status

Enumerador	Descrição
pending_confirmation	Recorrência pendente de confirmação
active	Recorrência ativa
cancelled	Recorrência cancelada
suspended	Recorrência suspensa
expired	Recorrência expirada

Enumeradores periodicity

Enumerador	Descrição
weekly	Recorrência semanal
monthly	Recorrência mensal
quarterly	Recorrência trimestral
semiannual	Recorrência semestral
annual	Recorrência anual

Enumeradores journey_type

Enumerador	Descrição
j1_in_app_only_recurrence	Solicitação de autorização mediante uma notificação no aplicativo
j2_recurrence_only_qrcode	Solicitação de autorização mediante a leitura de um QR Code
j3_payment_and_recurrence_qrcode	Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code
j4_recurrence_offer_post_payment	Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência

Enumeradores 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