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

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

Webhook de Status de Ordem de Pagamento

Este webhook é destinado ao reporte de alterações de status de ordens de pagamento do Pix Automático, informando sobre cancelamentos, pagamentos realizados e rejeições.

Webhook Request Body

Status: Cancelado (cancelled)

Request Body: Payment Order Cancelada

{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "cancelled",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56"
  }
}

Status: Pago (paid)

Request Body: Payment Order Paga

{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "paid",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "paid_at": "2021-10-22T20:30:23.459Z"
  }
}

Status: Rejeitado (rejected)

Request Body: Payment Order Rejeitada

{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "rejected",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}

Informação

As ordens de pagamento rejeitadas são enviadas após o esgotamento do número máximo de tentativas (caso a recorrência permita retentativas). Neste caso, os campos transaction_key e incoming_pix_transfer_key não são incluídos no payload.

Webhook Body Params - Payment Order

Campo	Tipo	Descrição	Caracteres
event_type *	string	Tipo do evento reportado (baas.automatic_pix.payment_order.status_change).	100
origin_key *	string	Identificador único de origem do evento (UUID da payment order).	36
data *	Object	Objeto principal contendo os detalhes da ordem de pagamento.	Objeto data

---

Objeto data (Payment Order)

Campo	Tipo	Descrição	Caracteres
payment_order_key *	string	Chave única da ordem de pagamento (UUID).	36
payment_order_spi_id *	string	Identificador SPI da ordem de pagamento.	29
outgoing_recurrence_key *	string	Identificador único da recorrência automática associada (UUID).	36
payment_order_status *	string	Status da ordem de pagamento (cancelled, paid, rejected).	30
receiver_conciliation_id *	string	Identificador de conciliação do recebedor (UUID).	36
transaction_amount *	number	Valor da transação da ordem de pagamento.	-
payment_order_conciliation_batch_key *	string	Identificador do lote de conciliação associado (UUID).	36
transaction_key	string	Chave única da transação (presente apenas em status cancelled e paid).	36
incoming_pix_transfer_key	string	Identificador da transferência PIX de entrada (presente apenas em status cancelled e paid).	36
paid_at	string	Data e hora do pagamento (presente apenas em status paid, formato ISO 8601).	-

---

Enumeradores payment_order_status

Enumerador	Descrição
cancelled	Ordem de pagamento cancelada pelo pagador ou recebedor
paid	Ordem de pagamento executada com sucesso
rejected	Ordem de pagamento rejeitada após esgotamento de tentativas