Question 1

What happens if some payouts in a run fail?

Accepted Answer

Only the failed lines are affected. A halfin mass payout is a fan-out of independent single-payout calls (POST /api/v1/payouts, one per recipient), so a bad address, a dust-threshold amount, an unsupported currency, or a downstream send failure stops that one line while every other line proceeds. You re-submit the failed lines with the same idempotency_key they already carried — the lines that already succeeded return as no-ops, and only the corrected ones execute. You reconcile per line against the payout.completed and payout.failed webhook events.

Question 2

How do I retry a failed payout without paying someone twice?

Accepted Answer

Re-submit the line with the same idempotency_key it carried the first time. halfin deduplicates on that key: if the payout already exists it returns the original instead of sending a second transaction, and if the line genuinely never succeeded it executes now. The key must be deterministic — derive it from your own ledger, for example the recipient's account id joined with the payout period — so a retry reproduces it. A random UUID generated per attempt defeats the deduplication and is what causes double-pays.

Question 3

How do I tell which lines failed versus succeeded?

Accepted Answer

halfin emits a payout.completed webhook when a line settles on-chain and a payout.failed webhook when one cannot. Verify the HMAC signature over the raw webhook bytes with a constant-time comparison before acting, then record the outcome against the idempotency_key you supplied for that line. Because each payout is tracked independently, you reconcile a run line by line: a line with a terminal completed or failed event is done, and a line with neither is still pending approval, queued, or awaiting on-chain confirmation.

What happens if some payouts in a run fail?

Keep reading across the cluster.