The Pix plugin includes internal jobs that run in the background to ensure data consistency, complete pending transactions, and recover from errors automatically.

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

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.

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:

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

👍

Best practice

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

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:

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.