How do I keep invoice status and payments in sync across systems?

To keep invoice status and payments in sync across systems, use a single source of truth + event-driven updates + reconciliation approach.

1) Define one system as the source of truth

Pick one system to own each concept:

• Invoicing system: invoice creation, due dates, invoice status
• Payment system / processor: payment attempts, captures, refunds, chargebacks

Then map how status should flow between them.

2) Use an event-driven sync pattern

When something changes in one system, publish an event and update the others.

Typical events:

• InvoiceCreated
• PaymentInitiated
• PaymentSucceeded
• PaymentFailed
• InvoicePartiallyPaid
• InvoicePaid
• RefundIssued
• ChargebackOpened

Best practices:

• Include a unique invoice ID and payment transaction ID
• Make events idempotent so duplicates don’t cause problems
• Use at-least-once delivery and handle retries safely

3) Keep a status mapping table

Systems often use different status vocabularies. Create a canonical mapping.

Example:

• Invoice system: open, sent, paid, void, overdue
• Payment system: pending, authorized, captured, failed, refunded

Canonical internal statuses:

• draft
• open
• partially_paid
• paid
• overdue
• void
• refunded
• disputed

Then map each system into this shared model.

4) Reconcile regularly

Even good sync systems drift. Run a scheduled reconciliation job:

• Compare invoice balances across systems
• Compare payment records with processor settlement reports
• Detect missing events or mismatched totals
• Auto-correct if possible, otherwise flag for review

This is especially important for:

• failed webhooks
• network retries
• partial refunds
• chargebacks
• manual adjustments

5) Make updates atomic where possible

If you control both systems or a middleware layer:

• Write the invoice/payment record
• Persist an outbox event in the same transaction
• Publish the event asynchronously

This is the transactional outbox pattern, which helps avoid “DB updated but event not sent” problems.

6) Handle edge cases explicitly

Common edge cases to design for:

• Partial payment
• Overpayment
• Refund after invoice is paid
• Payment reversal/chargeback
• Manual invoice write-off
• Currency mismatches
• Duplicate payment notifications

Define the business rule for each case ahead of time.

7) Log and trace everything

For each invoice/payment sync operation, store:

• invoice ID
• payment ID
• source system
• target system
• event type
• timestamp
• outcome/error

This makes debugging much easier.

8) Prefer webhooks + polling backup

Use:

• Webhooks for fast updates
• Periodic polling as a fallback in case webhooks fail

9) Example flow

1. Invoice created in billing system → emit InvoiceCreated
2. Payment made in processor → emit PaymentSucceeded
3. Sync service receives event → updates invoice balance/status
4. Billing system marks invoice as paid
5. Reconciliation job confirms both systems match

Recommended architecture

If you’re integrating multiple systems, the most reliable setup is:

• Canonical billing service
• Event bus / message queue
• Sync worker / integration service
• Scheduled reconciliation job
• Audit log

If you want, I can also give you:

• a sample status mapping
• an event schema
• or a reference architecture diagram for syncing invoices and payments.