Transaction verification job
Every Pix transaction starts as pending. In most cases, it’s quickly confirmed or rejected by the PSTI, but sometimes that confirmation gets delayed or lost. The transaction verification job periodically scans for transactions stuck in pending and asks the PSTI for an update.Workflow: Status Verification
How it works:- After a short delay (30 seconds), the job checks for any transactions still marked as pending.
- If the transaction is confirmed, it’s marked as confirmed.
- If it fails, the system reverses the debit and updates the status to failed.
- If it’s still pending, the job schedules another check.
These jobs are idempotent and transactional, so they can run safely in parallel across environments.
Webhook retry queue
If your system fails to process a webhook, for example, due to a timeout or server error, the Pix plugin doesn’t give up. Failed webhook deliveries are added to a retry queue with exponential backoff:| Attempt | Delay before retry |
|---|---|
| 1st | Immediate |
| 2nd | 10 seconds |
| 3rd | 1 minute |
| 4th | 5 minutes |
| … | Up to 24 hours |
Always respond to webhooks quickly (within 5s). If you need to run heavy logic, do it asynchronously after responding with
200.Reversal recovery
In rare edge cases, reversal attempts may partially succeed, for example:- The value is credited back to the sender.
- But the confirmation step is lost
- Or a webhook delivery fails
What makes this reliable?
- Stateful by design: Every Pix transaction includes a complete audit trail and lifecycle status.
- Built-in compensation logic: If something breaks, the system knows how to complete or safely undo it.
- Idempotency-respecting: Retries and repeated jobs won’t produce duplicate results.
Configurable parameters
You can adjust job behavior using the following environment variables:| Variable | Description | Default |
|---|---|---|
PENDING_JOB_INTERVAL | How often to check for pending txns. | 30 seconds |
MAX_TRANSACTION_RETRIES | Max attempts before marking as failed. | 5 |
RETRY_BACKOFF_BASE | Base delay for webhook retries | 10 seconds |
MAX_RETRY_TTL | Max duration for webhook retries | 24 hours |
What you need to do
You don’t need to configure anything; jobs are fully managed by the Pix plugin. To ensure things run smoothly:- Use unique, traceable IDs for your transactions and accounts.
- Monitor webhook delivery and transaction statuses.
- Let us know if you need support for webhook replay or visibility into job execution.