Hook reference: invoice.payment_recorded

Trigger and payload

PaymentService dispatches invoice.payment_recorded after its ledger transaction commits, for both received funds and a recorded completed refund. Payload is invoice_id, payment_id and direction.

{"invoice_id": 123, "payment_id": 456, "direction": "received"}

direction is received or refund. Read the exact payment entry and invoice; do not assume every callback represents incoming money.

Correct deduplication

Use the durable payment ID, not just invoice ID, as the input identity for addon work. One invoice can receive partial receipts and later a refund. A repeated event must not repeat an irreversible external operation. Verify that the payment belongs to the referenced invoice and keep its owner, seller and currency intact.

Settlement and delivery boundary

The ledger entry records already settled external funds or a completed refund. This hook does not charge a card, initiate a refund or prove the invoice's current net balance is zero. A partial receipt can leave an invoice unpaid; a refund can require order review. Do not activate a service solely because a payment event arrived. Let the existing fulfilment workflow evaluate full payment and provider readiness.

Test cases

Cover received, partial receipt, repeated payment event, completed refund and an invoice whose status changed before the worker handled the event. Ensure logs omit bank/card secrets and copied customer details. If the handler fails, inspect its addon diagnostic; do not replay the payment provider callback or add a second ledger entry to recover your addon.