Lifecycle
Tesouro tracks accepted transfers through two states:
Hard failures at initial submission return a
4xx and no transfer record is created — the caller never sees a “failed transfer” object in the list.
A transfer’s state is what Tesouro has observed from the upstream banking core. Because ACH returns can land days after a transfer first appears COMPLETED, surface SUBMITTED rather than COMPLETED to the business customer until the return window for ACH has closed. Tesouro does not currently surface ACH returns as a separate status — partners that need return-level visibility must reconcile against statements externally.
Reading transfer state
Read transfer state by listing the source account’s transfers:PENDING transfer is checked against the upstream banking core, and ACH transfers the core reports as settled are updated to COMPLETED as part of the read. RTP and FedNow transfers go through the same check, but the upstream source has no record of them, so they stay in the state they were written at acceptance. Poll the list endpoint on a cadence appropriate to the rail — same-day for ACH; every few minutes is more than enough for the real-time rails.
Idempotency
Every money-movement endpoint accepts anidempotencyKey. Submitting the same key twice with the same parameters returns the original transfer (201 Created with the original body) — useful for retrying a request after a timeout without creating a duplicate. Submitting the same key with different parameters returns 409 Conflict with errorCode: MONEY_MOVEMENT_IDEMPOTENCY_KEY_CONFLICT.
Generate the key once per logical transfer attempt and reuse it across any retries for the same attempt.