Picture it: you're wiring up payouts. Your code calls POST /accounts/{accountID}/transfers, gets back a 2xx, marks the payout as done, and moves on. Then a slow response makes your retry logic fire, and you start wondering whether you just sent the money twice. The Moov Transfers API is built for exactly this moment, and a post on APIs.io walks through what the contract actually says.
The API moves money between Moov accounts across ACH, RTP and card rails. According to the post, its most important design decision sits in one optional header. If you call the create endpoint without x-wait-for, you get the asynchronous response by default. If you send x-wait-for: rail-response, you get full rail-specific details, with a timeout at 15 seconds. The post is blunt about the consequence: an integrator who treats a success code as "the money moved" has misread the contract.
The create operation documents three different success codes, and they aren't interchangeable. A 200 returns a CreatedTransfer, the synchronous result. A 201 means the transfer was created, but an error occurred while generating the synchronous response, so you get the asynchronous object instead. A 202 means the transfer was created, but rail details may not be available within the 15-second window. So 201 and 202 both mean the transfer exists and you don't have the full details yet. If your code branches only on "2xx", it loses that distinction. If it treats a slow response as a failure, it can retry a transfer that already exists.
The contract guards against that retry. x-idempotency-key is a required header on transfer creation, and a duplicate key returns a 409 whose documented body is a Transfer. The status code reads like an error, but the payload is the transfer you already created. Reversals and refund creation also take the key. Cancellation creation does not declare it, so the post says to check that path before you automate retries.
There's a second half to the design. The post notes that the AsyncAPI file for Moov's webhooks names transfer.created and transfer.updated, and describes the first as the start of the transfer lifecycle. You start a transfer over REST, then follow its status through events or by polling. Version handling matters too: X-Moov-Version is optional, and omitting it defaults you to v2024.01.00, while the document the post describes is v2026.01.00. The refund operation's own description also points you to the reversal endpoint for more complete cancel and refund options.
For scale, the post reports that Moov scores 74.2 on the Kin Score (exemplar) and 56.8 on Agent Readiness (agent-native). Its page lists 42 API contracts, though its header counts 3 published, and this one has 16 operations: four for transfers, one each for metadata, options and reversals, three each for cancellations, refunds and transfer configuration. The API page carries an OpenAPI contract, documentation, an AsyncAPI definition, a JSON-LD context and two JSON Schemas.
Here is where the post turns on its own record. Three of the transfer-config operations don't match the other thirteen. They declare bearer auth where the others declare Basic, they have no descriptions, and each documents only a 200. The post says the contract is assembled from three of Moov's published definitions, and these three paths carry a different server entry from the rest, which points to a different source. The catalog has not verified them against Moov's live API, so you should treat them as lower confidence. The post also says the four refund and reversal operations appear again under the separate Moov Refunds API, which inflates any operation count that adds the two together.
So what do you take away? Build on this API as an event-driven system. Pin X-Moov-Version instead of letting it default. Store your idempotency key before the first attempt. And treat 201, 202 and 409 as states to handle, not outcomes to log. When you read the three transfer-config operations, remember the catalog itself says they're the part it hasn't checked.
Read the original: https://apis.io/2026/11/08/moov-transfers-api-answers-async-unless-you-ask-it-to-wait-15-seconds/