Question 1

How does idempotency work for a mass payout run?

Accepted Answer

It works per line. A mass payout is the single-payout endpoint, POST /api/v1/payouts, called once per recipient, and each call carries its own idempotency key. If you derive each key deterministically from your own ledger — for example the recipient's account id joined with the payout period — then re-running the same file reproduces the same keys, and halfin returns the payout it already created for each line instead of sending a second transaction. There is no batch-level key; the dedup boundary is the individual recipient line, which is what makes the whole file safe to retry from the top.

Question 2

What should I use as the idempotency key for each line?

Accepted Answer

Use a stable, deterministic value tied to your own records — typically the recipient's account id joined with the payout period, like "affiliate-8842:2026-W23". When you rebuild the file from the same source data, that line must produce the same key so halfin can match it to the payout it already made. Avoid random UUIDs generated at send time or keys based on a timestamp or shifting row number: a retry would produce a new key for an already-paid recipient and create a duplicate.

Question 3

If a request times out, will resubmitting the file pay someone twice?

Accepted Answer

No, as long as the keys are reproducible. A timed-out request may have landed even though your client never saw the response. When you resubmit with the same per-line keys, the lines that already succeeded return their existing payout and move nothing, and only lines that were never accepted execute. That is the intended recovery path: on any failure, rebuild the file and resubmit from the top rather than trying to track which rows made it through.

How does idempotency work for a mass payout run?

Keep reading across the cluster.