> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs and retry logic

> Recover Pix transactions automatically with background jobs that resolve pending status, retry webhooks, and keep data consistent.

These jobs give your system resilience without requiring manual intervention. Even if a webhook fails or a PSTI call times out, the plugin keeps working behind the scenes to fix it.

## 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

```mermaid mermaid theme={null}
sequenceDiagram
  participant Job
  participant PixPlugin as Pix Plugin
  Job->>PixPlugin: Check transaction status
  alt Status = confirmed
    PixPlugin-->>Job: confirmed
    Job->>DB: Mark as confirmed
  else Status = failed
    PixPlugin-->>Job: failed
    Job->>PixPlugin: Reverse funds
    Job->>DB: Mark as failed
  else Status = still pending
    PixPlugin-->>Job: pending
    Job-->>Job: Wait and retry later
  end
```

**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.

<Tip>
  These jobs are idempotent and transactional, so they can run safely in parallel across environments.
</Tip>

## 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     |

If the event is still not acknowledged after all retries, it’s marked as undeliverable and logged.

<Tip>
  Always respond to webhooks quickly (within 5s). If you need to run heavy logic, do it **asynchronously** after responding with `200`.
</Tip>

## 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

The Pix plugin detects these situations during its routine scans and re-triggers any missing actions (e.g., notify → persist).

### 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.