Question 1

How do I retry failed lines?

Accepted Answer

Re-POST each failed line to POST /api/v1/payouts with the same idempotency_key it carried the first time. A mass payout is the single-payout endpoint called once per recipient, so retrying is line-level: a line that previously succeeded returns its existing payout as a no-op and moves no money, while a line that never went through executes now. The simplest safe approach is to resend the whole file unchanged — already-paid recipients are untouched and only the lines that still need to run do. The key must be deterministic so a retry reproduces it; a fresh UUID per attempt is what causes double-pays.

Question 2

Will retrying pay a recipient who already succeeded?

Accepted Answer

No, as long as the idempotency_key is unchanged. halfin deduplicates on that key: if a payout already exists for it, the call returns the existing payout instead of sending a second transaction, so succeeded lines short-circuit to a no-op. That is what makes resending the whole file safe — you do not have to track which rows made it through. The only way to double-pay on a retry is to change the key, which makes halfin treat an already-paid recipient as a brand-new request.

Question 3

A line failed after it was accepted — can I reuse the same key to retry it?

Accepted Answer

No. A line that failed asynchronously is reported via the payout.failed webhook, and its idempotency_key is now tied to that terminal failed payout — resending the same key returns the failed record rather than executing. Fix the underlying problem and resend under a new but equally deterministic key, such as the same identity-plus-period key with an attempt suffix. A line rejected at submit time is different: it never created a payout, so once you correct the row you can keep the original key.

How do I retry failed lines?

Keep reading across the cluster.