Paying each reference once

SET Direct Deposit API · Live since 2026-11-10

The problem

USDC payouts are final. A bounty platform that retries after a timeout, a user who double-clicks "Pay", or two workers that pick up the same job can each send the payout, and the payee is paid twice. Stablecoin transfers cannot be pulled back.

The answer: a payout intent

Reserve the payout under your own reference before you send anything:

POST /api/partner/payout_intents
{ "reference": "bounty-4471", "amountUsdc": "250.00", "chain": "base", "payeeId": "pye_…" }

The answer (201) is the intent, with the address to pay and its destination (bank, wallet or threshold). Send the address as address instead of payeeId for a Cash-Out or Threshold Address you already checked.

A second intent for the same reference is refused, with the first one in the answer:

Answer	Means	Do
`409 already_intended`	An open intent exists for this reference	Pay the address in `intent`, once, or nothing
`409 already_paid`	A payment already carries this reference	Pay nothing

Two calls at the same moment get the same treatment: one wins, the other gets 409 already_intended with the winner.

Marking it paid

Pay the intent's address.
Set the reference on that payment: POST /api/partner/references {chain, txHash, to?, reference}. A Payable Email batch item's reference counts too, once its payment is reported.
The intent becomes paid, with txHash and paidAt, and you get payout_intent.paid.

Other calls

GET /api/partner/payout_intents?reference=bounty-4471: the intent for a reference.
GET /api/partner/payout_intents/{id}: one intent.
POST /api/partner/payout_intents/{id}/cancel: cancel while it is open. The reference can then be used again. A paid intent cannot be canceled (409 already_paid).

Things to know

A reference is 1–64 visible ASCII characters: your own id, never a person's name or email. SET keeps it as a keyed hash (to find it) and sealed (to show it back), never in clear.
An intent is marked paid only when a payment carries its reference. A payment without the reference leaves the intent open.
An amount that would not reach the bank after SET's fee is 422 below_minimum; see Amounts below the minimum.
A payee who cannot be paid yet (setup_required, invited) is 409 payee_not_payable. Resolve them again later.