Automatic Pix Webhooks
Webhook notifications are essential for the proper processing of asynchronous events related to Automatic Pix, especially including authorizations and executions of recurring payments in different journeys.
Attention!
QI Tech webhooks should not be mapped in a restrictive manner. Additional fields may be included in the webhook payloads returned by our APIs.
Recurrence Status Webhook
This webhook is intended to report status changes of authorizations and recurrence cycles of Automatic Pix, differentiating the types of journeys involved.
Webhook Request Body
Journey 1 – journey_one
Request Body: Journey 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"
}
}
Journey 2 – journey_two
Request Body: Journey 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
}
}
Journey 3 – journey_three
Request Body: Journey 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
}
}
}
Journey 4 – journey_four
Request Body: Journey 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
}
}
Attention
When the payer user receives the notification, they can choose to schedule the Pix or make the transfer at that moment. If the payer makes the payment instantly, the baas.automatic_pix.outgoing_recurrence.status_change webhook will be sent with the information filled in, in case of scheduling the values will be null.
Webhook Body Params
| Field | Type | Description | Characters |
|---|---|---|---|
event_type * | string | Type of reported event (example: baas.automatic_pix.outgoing_recurrence.status_change). | 100 |
origin_key * | string | Unique identifier of the event origin (UUID). | 36 |
data * | Object | Main object containing the automatic recurrence details. | Data Object |
Data Object
| Field | Type | Description | Characters |
|---|---|---|---|
request_control_key * | string | Unique request control key (UUID4). | 36 |
outgoing_recurrence_key * | string | Unique identifier of the automatic recurrence (UUID). | 36 |
outgoing_recurrence_status * | string | Status of the recurrence in question (ex: approved, pending, rejected, etc.) | 30 |
journey_type * | enumerator | Journey corresponding to the Automatic Pix authorization (journey_one, journey_two, etc.). | journey_type Enumerators |
outgoing_recurrence_data * | Object | Object containing specific recurrence and journey information. | outgoing_recurrence_data Object |
payment_conciliation_batch_key | string | Grouping identifier for payment conciliation. May be null. | 36 or null |
qr_code_initial_payment_data | Object | (Journey 3 and 4) Details of initial QR Code payment data, if any. | qr_code_initial_payment_data Object |
outgoing_recurrence_data Object
| Field | Type | Description | Characters |
|---|---|---|---|
minimum_recurrence_amount | number | Minimum amount of the authorized recurrence. | - |
recurrence_amount | number | Total amount of the recurrence (may be null if not applicable). | - |
qr_code_initial_payment_data | Object | (Journey 3) Detailed data of the initial payment if QR Code is used. | qr_code_initial_payment_data Object |
payment_conciliation_batch_key | string | Payment batch/conciliation identifier. | 36 |
qr_code_initial_payment_data Object
| Field | Type | Description | Characters |
|---|---|---|---|
receiver_conciliation_id | string | Unique identifier of the receiver's conciliation. | - |
transaction_data | Object | Transaction details associated with the initial QR code. | transaction_data Object |
transaction_data Object
| Field | Type | Description | Characters |
|---|---|---|---|
transaction_key | string | Unique transaction key. | 36 |
pix_transfer_key | string | Associated Pix transfer identifier. | 36 |
end_to_end_id | string | Pix end-to-end identifier. | 32 |
journey_type Enumerators
| Enumerator | Description |
|---|---|
journey_one | Direct notification in banking app |
journey_two | QR Code experience for recurring billing |
journey_three | Instant payment + QR Code recurrence |
journey_four | Recurring opt-in from Pix operation |
Payment Order Status Webhook
This webhook is intended to report status changes of Automatic Pix payment orders, informing about cancellations, completed payments, and rejections.
Webhook Request Body
Status: Cancelled (cancelled)
Request Body: Cancelled Payment Order
{
"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: Paid (paid)
Request Body: Paid Payment Order
{
"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: Rejected (rejected)
Request Body: Rejected Payment Order
{
"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"
}
}
Information
Rejected payment orders are sent after the maximum number of attempts has been exhausted (if the recurrence allows retries). In this case, the transaction_key and incoming_pix_transfer_key fields are not included in the payload.
Webhook Body Params - Payment Order
| Field | Type | Description | Characters |
|---|---|---|---|
event_type * | string | Type of reported event (baas.automatic_pix.payment_order.status_change). | 100 |
origin_key * | string | Unique identifier of the event origin (UUID of the payment order). | 36 |
data * | Object | Main object containing the payment order details. | Data Object |
Data Object (Payment Order)
| Field | Type | Description | Characters |
|---|---|---|---|
payment_order_key * | string | Unique payment order key (UUID). | 36 |
payment_order_spi_id * | string | SPI identifier of the payment order. | 29 |
outgoing_recurrence_key * | string | Unique identifier of the associated automatic recurrence (UUID). | 36 |
payment_order_status * | string | Payment order status (cancelled, paid, rejected). | 30 |
receiver_conciliation_id * | string | Receiver conciliation identifier (UUID). | 36 |
transaction_amount * | number | Payment order transaction amount. | - |
payment_order_conciliation_batch_key * | string | Associated conciliation batch identifier (UUID). | 36 |
transaction_key | string | Unique transaction key (present only in cancelled and paid status). | 36 |
incoming_pix_transfer_key | string | Incoming PIX transfer identifier (present only in cancelled and paid status). | 36 |
paid_at | string | Payment date and time (present only in paid status, ISO 8601 format). | - |
payment_order_status Enumerators
| Enumerator | Description |
|---|---|
cancelled | Payment order cancelled by payer or receiver |
paid | Payment order successfully executed |
rejected | Payment order rejected after exhausting retry attempts |
Payment Order Attempt Status Webhook
This webhook is intended to report status changes of payment order execution attempts for Automatic Pix, especially informing about rejected attempts and rejection reasons.
Webhook Request Body
Status: Rejected (rejected)
Request Body: Rejected Payment Order Attempt
{
"event_type": "baas.automatic_pix.payment_order_attempt.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"payment_order_attempt_status": "rejected",
"transaction_amount": 125.53,
"reason": "Conta de destino inexistente",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
Information
This webhook is sent whenever a payment order execution attempt is rejected by the SPI. The payment order may have new attempts depending on the recurrence configuration and the rejection reason. The reason field contains the description of the rejection reason based on the Bacen error code.
Webhook Body Params - Payment Order Attempt
| Field | Type | Description | Characters |
|---|---|---|---|
event_type * | string | Type of reported event (baas.automatic_pix.payment_order_attempt.status_change). | 100 |
origin_key * | string | Unique identifier of the event origin (UUID of the payment order). | 36 |
data * | Object | Main object containing the payment order attempt details. | Data Object |
Data Object (Payment Order Attempt)
| Field | Type | Description | Characters |
|---|---|---|---|
request_control_key * | string | Unique request control key (UUID of the payment order). | 36 |
payment_order_key * | string | Unique key of the associated payment order (UUID). | 36 |
payment_order_attempt_key * | string | Unique key of the payment attempt (UUID). | 36 |
payment_order_status * | string | Current status of the payment order (pending, accepted, cancelled, etc.). | 30 |
payment_order_attempt_status * | string | Payment attempt status (rejected). | 30 |
transaction_amount * | number | Payment attempt transaction amount. | - |
reason * | string | Reason for attempt rejection (error description based on Bacen code). | 200 |
outgoing_recurrence_key * | string | Unique identifier of the associated automatic recurrence (UUID). | 36 |
payment_order_attempt_status Enumerators
| Enumerator | Description |
|---|---|
rejected | Payment attempt rejected by SPI due to specific error |
Webhook for non-liquidated payment order attempt
Webhook intended to notify when a payment order attempt was accepted but was not liquidated within the expected timeframe.
Webhook Request Body
Request Body: Non-liquidated payment order attempt
{
"webhook_type": "baas.automatic_pix.payment_order_attempt.not_liquidated",
"webhook_datetime": "2025-10-22T21:15:00.000Z",
"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": "pending",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": "125.53",
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc83",
"payment_order_attempt_status": "not_liquidated",
"due_date": "2025-10-22",
"end_to_end_id": "E1234567890123456789012"
}
}
Webhook Body Params
| Field | Type | Description | Max. Characters |
|---|---|---|---|
webhook_type | string | An enumerator that defines the type of event being reported | 100 |
webhook_datetime | string | Date and time of webhook sending | 20 |
payment_order_key | uuid4 | Unique identifier of the payment order. | 36 |
payment_order_spi_id | string | Payment order identifier in the SPI. | 50 |
outgoing_recurrence_key | uuid4 | Unique identifier of the associated outgoing recurrence. | 36 |
payment_order_status | string | Current status of the payment order. | payment_order_status Enumerators |
receiver_conciliation_id | string | Receiver conciliation identification. | 36 |
transaction_amount | number | Payment order transaction amount. | - |
payment_order_conciliation_batch_key | uuid4 | Unique identifier of the associated conciliation batch. | 36 |
payment_order_attempt_key | uuid4 | Unique identifier of the payment order attempt. | 36 |
payment_order_attempt_status | string | Status of the payment order attempt. | payment_order_attempt_status Enumerators |
due_date | string | Due date of the payment order attempt (YYYY-MM-DD format). | 10 |
end_to_end_id | string | Idempotency key of a Pix transaction within the SPI. | 32 |
payment_order_status Enumerators
| Enumerator | Description |
|---|---|
pending_conciliation | Awaiting conciliation. |
pending | Pending and awaiting payment. |
paid | Successfully paid. |
rejected | Rejected and will not be processed. |
cancelled | Cancelled before payment. |
payment_order_attempt_status Enumerators
| Enumerator | Description |
|---|---|
sent | Payment attempt sent |
accepted | Payment attempt accepted |
rejected | Payment attempt rejected by SPI due to specific error |
not_liquidated | Payment attempt accepted but not liquidated within expected timeframe |