Transfers Docs — Mozaca Labs

ReferenceUpdated May 28, 2026

Lifecycle

A transfer is an instruction to move value across a configured source, destination, asset, amount, and rail.

Transfers do not become production movements until identity, funding, rail, compliance, and approval requirements are satisfied.

Status	Meaning	Terminal
created	Instruction accepted by Mozaca	No
review_required	Policy or compliance review is needed	No
submitted	Instruction sent to the configured rail	No
settled	Movement completed and ledger matched	Yes
failed	Movement did not complete	Yes

Create transfer

Use idempotency keys for every transfer create request. Your backend can safely retry the same request when the network is uncertain.

POST /transfersjson

{
  "source": "wallet_kes_184250",
  "destination": {
    "type": "bank_account",
    "accountId": "bank_acct_442"
  },
  "amount": "50000.00",
  "currency": "KES",
  "railPreference": "fastest_available",
  "metadata": {
    "customerReference": "order_9001"
  }
}

Check status

Poll status only when webhooks are unavailable. Webhooks should be the primary way to receive settlement, failure, and review events.