Webhook events

The complete catalogue of events LB Pay sends, with the payload of each one.

Before implementing a handler, read Credit exactly once — every one of these events can be delivered more than once.

Events

Category	Event
Deposits	`pixChargePaid`
Deposits	`pixChargeExpired`
Deposits	`pixChargeRejected`
Withdrawals	`pixWithdrawSuccess`
Withdrawals	`pixWithdrawFailed`
Refunds	`pixRefundSuccess`
Refunds	`pixRefundFailed`

Deposit Events

Pix Charge Paid

Fired when a Pix charge is successfully paid.

Key fields

Field	Description
`chargeId`	Internal charge identifier
`externalId`	Your system's identifier for this charge
`status`	Always `"paid"` for this event
`amount`	Amount in cents
`paidAt`	Timestamp of payment confirmation
`debtor`	Bank account details of the payer
`pixTransaction.endToEndId`	Unique end-to-end Pix transaction ID

{
  "pixChargePaid": {
    "chargeId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "status": "paid",
    "createdAt": "2026-03-19T22:59:59.439Z",
    "expiresAt": "2026-03-19T23:16:39.439Z",
    "paidAt": "2026-03-19T23:00:37.491Z",
    "description": "Displayed to the customer in the payment app before confirmation. Up to 140 chars.",
    "amount": 1000,
    "debtor": {
      "bankCode": "00000000",
      "branchCode": "0001",
      "accountNumber": "3323200006",
      "personType": "NATURAL_PERSON",
      "accountType": "CACC",
      "taxId": "39424283008",
      "name": "PT1"
    },
    "pixTransaction": {
      "transactionId": "019d0854-5399-7500-a4bf-85e175e300f3",
      "endToEndId": "E183942282026031923007DP8OFYBk9a"
    },
    "metadata": {
      "additionalProp1": "1",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
} 

Pix Charge Expired

Fired when a Pix charge reaches its expiration time without being paid.

Key fields

Field	Description
`chargeId`	Internal charge identifier
`externalId`	Your system's identifier for this charge
`status`	Always `"expired"` for this event
`expiresAt`	Timestamp when the charge expired

{
  "pixChargeExpired": {
    "chargeId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "status": "expired",
    "createdAt": "2026-03-19T22:59:59.439Z",
    "expiresAt": "2026-03-19T23:16:39.439Z",
    "description": "Displayed to the customer in the payment app before confirmation. Up to 140 chars.",
    "amount": 1000,
    "metadata": {
      "additionalProp1": "1",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

Pix Charge Rejected

Fired when a Pix charge is rejected — for example, because the paying account does not match the expected payer.

Key fields

Field	Description
`chargeId`	Internal charge identifier
`externalId`	Your system's identifier for this charge
`status`	Always `"pending"` for this event (charge is not settled)
`rejectedReason`	Machine-readable rejection code (e.g. `ACCOUNT_MISMATCH`)
`rejectedDescription`	Human-readable explanation of the rejection

{
  "pixChargeRejected": {
    "chargeId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "status": "pending",
    "createdAt": "2026-03-19T22:59:59.439Z",
    "expiresAt": "2026-03-19T23:16:39.439Z",
    "description": "Displayed to the customer in the payment app before confirmation. Up to 140 chars.",
    "amount": 1000,
    "expectedPayer": {
      "taxId": "15276356213",
      "name": "Andre",
      "bankAccounts": [
        {
          "bankCode": "341",
          "branchCode": "0001",
          "accountNumber": "20262027",
          "personType": "NATURAL_PERSON",
          "accountType": "CACC"
        }
      ]
    },
    "debtor": {
      "bankCode": "00000000",
      "branchCode": "0001",
      "accountNumber": "3323200006",
      "personType": "NATURAL_PERSON",
      "accountType": "CACC",
      "taxId": "39424283008",
      "name": "PT1"
    },
    "rejectedReason": "ACCOUNT_MISMATCH",
    "rejectedDescription": "This payment account is not allowed for this QR Code.",
    "metadata": {
      "additionalProp1": "1",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

Withdrawal Events

Pix Withdraw Success

Fired when a Pix withdrawal is successfully processed.

Key fields

Field	Description
`transactionId`	Internal transaction identifier
`externalId`	Your system's identifier for this withdrawal
`endToEndId`	Unique end-to-end Pix transaction ID
`status`	Always `"success"` for this event
`initiationType`	How the withdrawal was initiated (e.g. `PIX_KEY`)
`creditor`	Resolved bank account that received the funds

{
  "pixWithdrawSuccess": {
    "transactionId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "endToEndId": "E183942282026031923007DP8OFYBk9a",
    "status": "success",
    "description": "Displayed to the customer in the payment app before confirmation. Up to 140 chars.",
    "initiationType": "DICT_KEY",
    "amount": 1000,
    "creditor": {
      "bankCode": "00000000",
      "branchCode": "0001",
      "accountNumber": "3323200006",
      "personType": "NATURAL_PERSON",
      "accountType": "CACC",
      "taxId": "39424283008",
      "name": "PT1"
    },
    "createdAt": "2026-03-19T22:59:59.439Z",
    "updatedAt": "2026-03-19T23:16:39.439Z",
    "metadata": {
      "additionalProp1": "1",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

Pix Withdraw Failed

Fired when a Pix withdrawal cannot be completed.

Key fields

Field	Description
`transactionId`	Internal transaction identifier
`externalId`	Your system's identifier for this withdrawal
`status`	Always `"failed"` for this event
`errorCode`	Machine-readable failure code (e.g. `ACCOUNT_MISMATCH`)
`errorDescription`	Human-readable explanation of the failure

{
  "pixWithdrawFailed": {
    "transactionId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "endToEndId": "E183942282026031923007DP8OFYBk9a",
    "status": "failed",
    "description": "Displayed to the customer in the payment app before confirmation. Up to 140 chars.",
    "initiationType": "DICT_KEY",
    "amount": 1000,
    "creditor": {
      "bankCode": "00000000",
      "branchCode": "0001",
      "accountNumber": "3323200006",
      "personType": "NATURAL_PERSON",
      "accountType": "CACC",
      "taxId": "39424283008",
      "name": "PT1"
    },
    "createdAt": "2026-03-19T22:59:59.439Z",
    "updatedAt": "2026-03-19T23:16:39.439Z",
    "errorCode": "ACCOUNT_MISMATCH",
    "errorDescription": "The destination account does not match the provided Pix key.",
    "metadata": {
      "additionalProp1": "1",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}

Refund Events

Pix Refund Success

Fired when a Pix refund is successfully processed.

Key fields

Field	Description
`refundId`	Internal refund identifier
`externalId`	Your system's identifier for this refund
`transactionId`	Internal transaction identifier
`originalEndToEndId`	End-to-end ID of the original charge being refunded
`refundEndToEndId`	End-to-end ID of the refund transaction itself
`status`	Always `"success"` for this event
`amount`	Refunded amount in cents
`originalAmount`	Original charge amount in cents
`leftAmount`	Remaining refundable amount in cents
`totalReversedAmount`	Total amount reversed so far in cents
`creditor`	Bank account that received the refund
`canBeReversedUntil`	Deadline after which the refund can no longer be reversed
`settlementDateTime`	Timestamp when the refund settled

{
  "pixRefundSuccess": {
    "refundId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "transactionId": "019d0854-5399-7500-a4bf-85e175e300f3",
    "originalEndToEndId": "E183942282026031923007DP8OFYBk9a",
    "refundEndToEndId": "E183942282026031923007DP8OFYBk9b",
    "status": "success",
    "amount": 1000,
    "originalAmount": 1000,
    "leftAmount": 0,
    "totalReversedAmount": 1000,
    "creditor": {
      "bankCode": "341",
      "branchCode": "0001",
      "accountNumber": "20262027",
      "accountType": "CACC",
      "personType": "NATURAL_PERSON",
      "taxId": "15276356213",
      "name": "Andre"
    },
    "canBeReversedUntil": "2026-03-26T22:59:59.439Z",
    "settlementDateTime": "2026-03-19T23:00:37.491Z",
    "createdAt": "2026-03-19T22:59:59.439Z",
    "updatedAt": "2026-03-19T23:16:39.439Z"
  }
}

Pix Refund Failed

Fired when a Pix refund cannot be completed.

Key fields

Field	Description
`refundId`	Internal refund identifier
`externalId`	Your system's identifier for this refund
`transactionId`	Internal transaction identifier
`originalEndToEndId`	End-to-end ID of the original charge being refunded
`status`	Always `"failed"` for this event
`amount`	Attempted refund amount in cents
`originalAmount`	Original charge amount in cents
`leftAmount`	Remaining refundable amount in cents
`totalReversedAmount`	Total amount reversed so far in cents
`errorCode`	Machine-readable failure code
`errorDescription`	Human-readable explanation of the failure

{
  "pixRefundFailed": {
    "refundId": "019d0853-bf54-7145-b463-df2d5566e894",
    "externalId": "8d231a73-80c0-4333-acea-abf9b55f8d53",
    "transactionId": "019d0854-5399-7500-a4bf-85e175e300f3",
    "originalEndToEndId": "E183942282026031923007DP8OFYBk9a",
    "refundEndToEndId": "E183942282026031923007DP8OFYBk9b",
    "status": "failed",
    "amount": 1000,
    "originalAmount": 1000,
    "leftAmount": 1000,
    "totalReversedAmount": 0,
    "creditor": {
      "bankCode": "341",
      "branchCode": "0001",
      "accountNumber": "20262027",
      "accountType": "CACC",
      "personType": "NATURAL_PERSON",
      "taxId": "15276356213",
      "name": "Andre"
    },
    "canBeReversedUntil": "2026-03-26T22:59:59.439Z",
    "errorCode": "REFUND_LIMIT_EXCEEDED",
    "errorDescription": "The refund amount exceeds the original charge amount.",
    "createdAt": "2026-03-19T22:59:59.439Z",
    "updatedAt": "2026-03-19T23:16:39.439Z"
  }
}

Pix Automático Events

Pix Automático events are delivered by the same webhook service as every other event in this catalogue: same registration, same authentication, same retry policy, same payload shape. Event names follow the same convention (pixAutomatic<Aggregate><Action>) and the payload carries the full resource.

Configuration

There is nothing specific to configure: Pix Automático events are delivered to the account webhook registered with PUT /v1/webhook (API Reference), using its URL and its authentication (Basic or Bearer).

With no events filter on the registration, every event in the catalogue below is delivered.
To receive only some of them, list the pixAutomatic… names you want in events, next to the Pix events you already use.

Delivery

Each event is an HTTP POST with:

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Event`	the event name, e.g. `pixAutomaticScheduleSettled`
`Authorization`	`Basic` or `Bearer`, as configured in the account webhook

Only a 2xx response counts as delivered. Network errors and 5xx are retried in place (3 attempts, 1s/2s/4s) and then again with backoff from 30 s up to 1 h, for up to 10 rounds. A 4xx other than 408 and 429 is final: it is not retried. Deliveries are at least once — deduplicate by eventId.

Payload

Same shape as the other Pix webhooks: the event name is the single top-level key and wraps the event fields (eventId, occurredAt, walletId), the resource and the event-specific fields.

{
  "pixAutomaticScheduleSettled": {
    "eventId": "evt_7f9c2a1d4e8b4c6f9a3d5e7b1c2f4a6d",
    "occurredAt": "2026-10-15T03:00:12.123456Z",
    "walletId": "wallet-id",
    "schedule": {
      "id": "019d0853-bf54-7145-b463-df2d5566e894",
      "recurrenceId": "RR12345678202609110000000001",
      "walletId": "wallet-id",
      "cycleNumber": 2,
      "txid": "txid",
      "amount": 15000,
      "originalDueDate": "2026-10-15",
      "dueDate": "2026-10-15",
      "purpose": "AGND",
      "status": "SUCCESS",
      "statusDetailed": "SETTLED",
      "endToEndId": "E12345678202610151200abcdefghijk",
      "attemptCount": 0,
      "metadata": {},
      "attempts": [],
      "createdAt": "2026-09-11T00:00:00.123456Z",
      "updatedAt": "2026-10-15T03:00:12.123456Z",
      "settledAt": "2026-10-15T03:00:12.123456Z"
    },
    "amount": 15000,
    "description": "Mensalidade"
  }
}

Field	Description
top-level key	Event name from the catalogue below (also sent in `X-Webhook-Event`)
`eventId`	Unique event id — the deduplication key
`occurredAt`	ISO 8601 timestamp of the event
`walletId`	Your wallet
`recurrence` / `schedule` / `refund`	The full resource, in the same shape returned by the corresponding `GET`
other keys	Event-specific fields listed in the tables below

Amounts are integers in centavos; field names are camelCase.

Recurrence events (resource in recurrence)

Event	Fired when	Extra fields
`pixAutomaticRecurrenceCreated`	Recurrence created	—
`pixAutomaticRecurrenceFirstPaymentSucceeded`	First Pix settled	`endToEndId`
`pixAutomaticRecurrenceAuthorized`	Payer PSP approved the recurrence	—
`pixAutomaticRecurrenceRejected`	Payer PSP rejected the recurrence	`reason`
`pixAutomaticRecurrenceCancelled`	Cancelled by you or by the payer	`source: "payer_psp"` when payer-initiated
`pixAutomaticRecurrenceExpired`	Journey expired unauthorized	—
`pixAutomaticRecurrenceFirstPaymentRefunded`	First payment refunded	`refundId`

Schedule events (resource in schedule)

Event	Fired when	Extra fields
`pixAutomaticScheduleCreated`	Charge scheduled	—
`pixAutomaticScheduleInstructionSent`	Charge instruction sent to the payer PSP	—
`pixAutomaticScheduleInstructionSendFailed`	Dispatch failed	—
`pixAutomaticSchedulePayerResponseTimeout`	Payer PSP never answered the instruction	—
`pixAutomaticScheduleAccepted`	Payer PSP accepted the charge	—
`pixAutomaticScheduleRejected`	Payer PSP rejected the charge	—
`pixAutomaticScheduleSettled`	Charge settled — funds received	`amount`, `description`
`pixAutomaticScheduleSettlementRejected`	Settlement rejected by the SPI	—
`pixAutomaticScheduleCancellationRequested`	You cancelled a charge already sent to the payer PSP; waiting for its answer	—
`pixAutomaticScheduleCancellationRejected`	Payer PSP refused the cancellation; the charge stays scheduled	`cancellationId`
`pixAutomaticScheduleCancellationResultReceived`	Late cancellation answer for a charge that already reached a final state	`cancellationId`
`pixAutomaticScheduleCancelled`	Cancelled by you, by the payer PSP or after a failed settlement	`reason`; `source: "payer_psp"` when payer-initiated; `cancellationId` when answered by the payer PSP

Reimbursement events (resource in refund)

Event	Fired when
`pixAutomaticReimbursementSent`	Refund sent to the SPI
`pixAutomaticReimbursementSettled`	Refund settled
`pixAutomaticReimbursementFailed`	Refund rejected by the SPI

pixAutomaticReimbursementSettled is accepted in filters as an alias of pixAutomaticReimbursementSettled.

The minimum integration is: react to recurrence.authorized (start scheduling), schedule.settled (reconcile funds) and recurrence.cancelled / schedule.rejected (stop or retry charges).

Events​

Deposit Events​

Pix Charge Paid​

Pix Charge Expired​

Pix Charge Rejected​

Withdrawal Events​

Pix Withdraw Success​

Pix Withdraw Failed​

Refund Events​

Pix Refund Success​

Pix Refund Failed​

Pix Automático Events​

Configuration​

Delivery​

Events

Deposit Events

Pix Charge Paid

Pix Charge Expired

Pix Charge Rejected

Withdrawal Events

Pix Withdraw Success

Pix Withdraw Failed

Refund Events

Pix Refund Success

Pix Refund Failed

Pix Automático Events

Configuration

Delivery