Transfers overview

A transfer moves value out of one of your accounts to a destination. It is the only object in the API that debits a balance, and it is deliberately the last step in a sequence — by the time you create one, the destination has been resolved and verified, the rate has been locked if the currencies differ, and the amounts have been previewed.

​

The sequence

Only the transfer is required. Preview is optional but cheap, and a quote is mandatory whenever the source and destination currencies differ.

​

Statuses

Seven, and only some of them are ones you will see in a response.

​

Amounts change form

This catches nearly everyone. The request and the response are not in the same units. Never feed a response amount back into a request. totalDebit — sourceAmount plus fee — is what actually leaves the account, and is the figure to put in front of whoever approves the payment.

​

externalReference is the idempotency key

You choose it, it is unique within your business, and reusing it returns the existing transfer without looking at the rest of your payload. Two consequences worth internalising now:

• A different payment under a used reference returns the old transfer and moves nothing.
• A failed transfer keeps its reference. Retrying with it returns the failure, not a new attempt.

​

FX quotes

A quote locks a rate for exactly one transfer. It is bound to five things — source account, destination, both currencies, and the side with its amount — and spending it on anything that differs is refused. Its expiry comes from the FX provider rather than a fixed Sakawave window, so read expiresAt instead of assuming a duration. Like a destination, it is single use.

​

Events

Transfers reach your endpoint as fiat.withdrawal.* events. There are no transfer.* events. The payload is the posted ledger transaction, with the transfer described inside relatedOperation. See webhook events.

​

Next