Automatic retries
The plugin processes Pix events asynchronously. If it fails to process an event, the plugin retries in place, then captures the event to a dead-letter queue without loss. An operator replays a parked event, bounded to a maximum number of attempts. After the limit, the record stays parked for inspection and the plugin never drops it. The plugin retries outbound calls to the provider on 5xx responses and timeouts. Each retry uses exponential backoff with jitter.
Refund reconciliation
A refund can succeed at the provider but fail to record locally if the service crashes between the two steps. The refund reconciliation sweeper is a background safety net for this case. The sweeper runs on a timer and finds refunds still stuck in pending. For each one, it re-drives the idempotent steps — settle, confirm, or close — which the provider deduplicates by refund reference. It parks a row still at the create step for an operator, because a blind create replay could cause a double refund. Each failed attempt waits longer than the last, from one minute up to one hour. After a maximum number of attempts, the sweeper parks the record and raises an alert. It does not retry forever. The sweeper is optional and off by default.
Configuration
You can tune retry and reconciliation behavior with environment variables:
What you need to do
The plugin manages retries and reconciliation for you. The default settings fit most deployments. To keep operations healthy:
- Use unique, traceable IDs for your transactions and accounts.
- Monitor event delivery and transaction status.
- Contact Lerian for job visibility or event replay support.