---
title: "Track and cancel a transfer"
description: "Learn what each transfer state means, what to show the customer, and how to handle cancellation, failed payouts, refunds, errors and reconciliation."
url: "/guides/transfers/track-a-transfer/"
index: "/llms.txt"
---

# Track and cancel a transfer

After you create a transfer, you follow it through its states to an outcome. For each state, the table below gives its meaning, what to show the customer and what you do. Cancellation, failed payouts, refunds, errors and reconciliation follow the table.

## Follow a transfer

- **Events.** Nodu sends a webhook event when the state of a transfer changes. The event type ends with the name of the new state: for example, `v1.transfer.payment_processed`. Each event carries the `transfer` as it was at that moment. See [Receive and verify webhooks](/guides/api-basics/webhooks/index.md).
- **The current state.** [Retrieve a transfer](/api/tag/transfers/get-v1-transfers-transferid.md) returns the `state`, the `sourceDepositInstructions`, the `receipt` and any `requirements`.

An event is a notification, not the current state. Process each event once. When an event conflicts with what you know, retrieve the transfer.

## The order of the states

```mermaid
stateDiagram-v2
    direction TB
    [*] --> awaiting_funds : Create a transfer
    awaiting_funds --> canceled : Cancel a transfer
    awaiting_funds --> in_review : The funds arrive
    in_review --> info_required : The customer must act
    info_required --> in_review : The customer has acted
    in_review --> funds_received : The review passes
    funds_received --> payment_submitted : Nodu sends the payout
    funds_received --> payment_processed : The destination is a Nodu wallet
    payment_submitted --> payment_processed : The payout arrives
    payment_submitted --> undeliverable : The payout fails
    payment_processed --> returned : The payout comes back
    undeliverable --> refunded : Nodu refunds the sender
    returned --> refunded : Nodu refunds the sender
    state "error" as error
    error --> undeliverable : Nodu resolves the error
    error --> returned : Nodu resolves the error
    error --> refunded : Nodu resolves the error
    note left of error
        Processing has stopped.
        It can follow in_review,
        info_required, funds_received
        or payment_submitted.
    end note
    class canceled,refunded final
    class error,undeliverable,returned problem
```

In the diagram, the green states are final. The red states mean that the payout failed or that processing stopped. A transfer in `error` moves on when Nodu resolves the error: to `undeliverable`, `returned` or `refunded`.

A transfer usually moves through these states in order:

1. `awaiting_funds`
2. `in_review`
3. `funds_received`
4. `payment_submitted`
5. `payment_processed`

During the review, a transfer can wait in `info_required`. A transfer whose destination is a [Nodu wallet](/guides/nodu-wallets/balances-and-wallet-scopes/index.md) goes from `funds_received` straight to `payment_processed`.

- Only `canceled` and `refunded` are sure to be final. A transfer in `payment_processed` can still move to `returned`, if the payout comes back later.
- Nodu can fill some `receipt` fields after the event `v1.transfer.payment_processed`. Use `sourceTxHash` to reconcile incoming crypto and `destinationTxHash` to reconcile a blockchain payout. If a field is missing, retrieve the transfer again.

## Transfer states

The column "What to show the customer" is a suggestion for your interface. The API does not require it.


| `state` | Meaning | What to show the customer | What you do |
|---|---|---|---|
| `awaiting_funds` | Nodu is waiting for the payment that funds the transfer. For a transfer funded from a Nodu wallet, Nodu is waiting for enough balance. | Deposit instructions for an external payment; a balance-wait message for a Nodu wallet source. | Wait for funding. You can [update the amount or fee](/guides/transfers/how-transfers-work/index.md#update-a-transfer-before-funding), or [cancel the transfer](#cancel-a-transfer). |
| `in_review` | The funds have arrived. Nodu is reviewing the transfer. | The payment has arrived and the transfer is being checked. | Nothing. Wait for the next event. |
| `info_required` | The customer must complete an action before Nodu continues. | The action, and where the customer completes it. | See [Handle the `info_required` state](/guides/transfers/handle-a-transfer-that-needs-action/index.md#handle-the-info_required-state). |
| `funds_received` | The review is complete. Nodu is preparing the payout. | The transfer is in progress. | Nothing. |
| `payment_submitted` | Nodu has sent the payout. Its arrival is not confirmed yet. | The payout is on its way. | Nothing. |
| `payment_processed` | The payout has arrived at the destination. | The result and the details of the `receipt`. | Record the outcome. |
| `undeliverable` | Nodu could not deliver the payout. For example, the destination is not valid. The state can also follow `error`. | The payout failed. A refund to the payer is pending. | See [Failed payouts and refunds](#failed-payouts-and-refunds). |
| `returned` | The payout came back to Nodu after Nodu sent it. The state can also follow `error`. | The payout failed. A refund to the payer is pending. | See [Failed payouts and refunds](#failed-payouts-and-refunds). |
| `refunded` | The funds are back with the payer: the party that funded the transfer. The state can also follow `error`. | The funds were refunded. | Record the outcome. |
| `canceled` | The transfer was canceled before it was funded. | The transfer is canceled. The customer must not pay. | Record the outcome. |
| `error` | Processing stopped. Nodu must handle the transfer manually. | The transfer is on hold. | See [Errors](#errors). |

## Cancel a transfer

[Cancel a transfer](/api/tag/transfers/delete-v1-transfers-transferid.md) works only while the transfer is `awaiting_funds`. After a successful request, the transfer is `canceled`.

- **Check the response.** Funds can arrive while you cancel. The transfer is then no longer `awaiting_funds`. Nodu refuses the request with a [business rule violation](/guides/api-basics/errors-and-rule-codes/index.md#business-rule-violations), which has `rule=transfer_cannot_be_cancelled`. Retrieve the transfer and continue to track it.
- **Tell the customer not to pay.** A canceled transfer must not be funded.
- **If the customer has already paid, contact Nodu.** Cancellation does not reverse a payment that the customer has made.

## Failed payouts and refunds

`undeliverable` and `returned` both mean that the payout did not reach the recipient. In both states, Nodu holds the funds. A refund to the payer follows.

- Only `refunded` confirms that the payer has the funds back.
- Do not promise the customer a time for the refund.
- Do not ask the customer to pay again before the first transfer is resolved.
- When the destination was not valid, register a new external account with the correct details. Use it for the next transfer.

## Errors

`error` means that processing has stopped. Nodu must handle the transfer manually. Contact Nodu if Nodu has not contacted you. When Nodu resolves the error, the transfer moves to `undeliverable`, `returned` or `refunded`: see [Failed payouts and refunds](#failed-payouts-and-refunds).

Also contact Nodu in these cases:

- The customer paid an amount that differs from the amount of the transfer.
- The customer paid, and the transfer stays `awaiting_funds`.

Keep the `id` of the transfer and the evidence of the payment.

## A create request that timed out

Recover the result with the same `Idempotency-Key` and exact request body. See [Idempotency](/guides/api-basics/idempotency/index.md#retry-a-request-that-timed-out).

## Reconcile with the list

Do not depend on webhooks alone. Periodically compare your records with the results of [List all transfers](/api/tag/transfers/get-v1-transfers.md).

- The list returns the most recent transfers first. It is paginated: see [Pagination](/guides/api-basics/pagination/index.md).
- Filter with `customerId`, with `clientReferenceId`, or with one or more `states[]` values.
- Send your own identifier as `clientReferenceId` when you create a transfer. You can then find the transfer by that identifier.

Record a transfer as complete in your system when its outcome is confirmed, not when you create it.

## Next steps

- [Handle the `info_required` state](/guides/transfers/handle-a-transfer-that-needs-action/index.md#handle-the-info_required-state): what you do when a transfer is waiting for the customer.
- [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md): the errors that a request can return.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): move a test transfer through its states.
