Webhooks Pix Automático

As notificações via webhook são fundamentais para o correto processamento de eventos assíncronos relacionados ao Pix Automático, incluindo especialmente as autorizações e execuções de pagamentos recorrentes em diferentes jornadas.

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 de Status de Recorrência (Pix Automático)

Este webhook é destinado ao reporte de alterações de status de autorizações e ciclos de recorrência do Pix Automático, diferenciando os tipos de jornadas envolvidas.

Webhook Request Body

Jornada 1 – journey_one

Request Body: Jornada 1

{
  "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "approved",
    "journey_type": "journey_one",
    "outgoing_recurrence_data": {
      "minimum_recurrence_amount": 123.45,
      "recurrence_amount": null
    },
    "payment_conciliation_batch_key": "uuid"
  }
}

Jornada 2 – journey_two

Request Body: Jornada 2

{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_two",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}

Jornada 3 – journey_three

Request Body: Jornada 3

{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_three",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null,
            "qr_code_initial_payment_data": {
                "receiver_conciliation_id": "id",
                "transaction_data": {
                    "transaction_key": "uuid",
                    "pix_transfer_key": "uuid",
                    "end_to_end_id": "end_to_end"
                }
            },
            "payment_conciliation_batch_key": "uuid" or null
        }
    }
}

Jornada 4 – journey_four

Request Body: Jornada 4

{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_four",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "qr_code_initial_payment_data": {
            "receiver_conciliation_id": "id",
            "transaction_data": {
                "transaction_key": "uuid" or null,
                "pix_transfer_key": "uuid" or null,
                "end_to_end_id": "end_to_end" or null
            }
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}

Atenção

Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo baas.automatic_pix.outgoing_recurrence.status_change com as informações preenchidas, em caso de agendamento os valores serão null.

Webhook Body Params

Campo	Tipo	Descrição	Caracteres
event_type *	string	Tipo do evento reportado (exemplo: baas.automatic_pix.outgoing_recurrence.status_change).	100
origin_key *	string	Identificador único de origem do evento (UUID).	36
data *	Object	Objeto principal contendo os detalhes da recorrência automática.	Objeto data

---

Objeto data

Campo	Tipo	Descrição	Caracteres
request_control_key *	string	Chave de controle única da requisição (UUID4).	36
outgoing_recurrence_key *	string	Identificador único da recorrência automática (UUID).	36
outgoing_recurrence_status *	string	Status da recorrência em questão (ex: approved, pending, rejected, etc.)	30
journey_type *	enumerator	Jornada correspondente à autorização do Pix Automático (journey_one, journey_two, etc.).	Enumeradores journey_type
outgoing_recurrence_data *	Object	Objeto contendo informações específicas da recorrência e da jornada.	Objeto outgoing_recurrence_data
payment_conciliation_batch_key	string	Identificador de agrupamento para conciliação de pagamentos. Pode ser null.	36 ou null
qr_code_initial_payment_data	Object	(Jornada 3 e 4) Detalhamento de dados do pagamento via QR Code inicial, se houver.	Objeto qr_code_initial_payment_data

---

Objeto outgoing_recurrence_data

Campo	Tipo	Descrição	Caracteres
minimum_recurrence_amount	number	Valor mínimo da recorrência autorizada.	-
recurrence_amount	number	Valor total da recorrência (pode ser null se não aplicável).	-
qr_code_initial_payment_data	Object	(Jornada 3) Dados detalhados do pagamento inicial caso QR Code seja utilizado.	Objeto qr_code_initial_payment_data
payment_conciliation_batch_key	string	Identificador de lote/conciliação do pagamento.	36

---

Objeto qr_code_initial_payment_data

Campo	Tipo	Descrição	Caracteres
receiver_conciliation_id	string	Identificador único da conciliação do recebedor.	-
transaction_data	Object	Detalhes da transação associada ao QR code inicial.	Objeto transaction_data

---

Objeto transaction_data

Campo	Tipo	Descrição	Caracteres
transaction_key	string	Chave única da transação.	36
pix_transfer_key	string	Identificador da transferência Pix associada.	36
end_to_end_id	string	Identificador end-to-end do Pix.	32

---

Enumeradores journey_type

Enumerador	Descrição
journey_one	Notificação direta no aplicativo bancário
journey_two	Experiência QR Code para cobrança recorrente
journey_three	Pagamento instantâneo + recorrência QR Code
journey_four	Opt-in recorrente a partir de operação Pix