A transfer (trf_*) moves money within one party: between its wallets, or between a wallet and a linked bank account. To learn more, see Deposit and withdraw and Transfer between wallets.
Natural’s limits or risk checks, or a Natural reviewer, denied the transfer before it was sent. failure says why, when available.
Final
PROCESSING
Sent to the payment rail and not finished yet.
COMPLETED, FAILED, RETURNED
IN_REVIEW
Held for review by Natural. Nothing is sent until it’s approved.
PROCESSING, FAILED, APPROVAL_DENIED, CANCELED
COMPLETED
The transfer finished and the funds are available. A bank can still return a completed transfer.
RETURNED
FAILED
The transfer didn’t go through. failure says why, when available.
Final
RETURNED
The bank sent the funds back. return says why, when available.
Final
CANCELED
Canceled before it was sent, for example when the key or permission that started it was removed. failure says why, when available.
Final
Internal transfers
Internal transfers send no webhook events. Read status on the response.
Events
deposit.created: The public deposit transfer resource became visible. API-initiated deposits emit with status “created” once they pass approval checks, before money movement submission. Deposits denied or canceled by those checks don’t emit it; deposits discovered from money movement may emit with the current status, such as “processing”. Deposits carry no fee, so fee is always null on deposit.* events.
deposit.canceled: A deposit was canceled before money movement processing.
deposit.approvalDenied: A deposit approval was explicitly denied before money movement processing.
withdrawal.created: A withdrawal was created and funds are being moved out of a wallet. Instant withdrawals carry a fee, assessed when the withdrawal is submitted, so it’s always null on withdrawal.created. Read it from withdrawal.completed.