---
title: "How transfers work"
description: "Learn how transfer sources, destinations, deposit instructions and states fit together, with a full Create a transfer request."
url: "/guides/transfers/how-transfers-work/"
index: "/llms.txt"
---

# How transfers work

A transfer moves money for one customer from a source to a destination. In the pay-as-you-go flow below, you create it with one request. The customer then pays, and Nodu reviews the transfer, converts the funds and pays the recipient. Learn these parts before you build a transfer flow.

```mermaid
sequenceDiagram
    participant Customer
    participant You as Your system
    participant Nodu
    Note over Customer,Nodu: The customer is active, and the payment channels are active.
    Customer->>You: 1. Choose the amount and the recipient
    opt New recipient
        You->>Nodu: Find the requirements<br/>GET /v1/external-accounts/destinations<br/>GET /v1/external-accounts/requirements
        You->>Nodu: Register the recipient<br/>POST /v1/external-accounts
        Nodu-->>You: External account id
    end
    You->>Nodu: 2. Create a quote<br/>POST /v1/quotes
    You->>Customer: Show the amounts and the fees
    Customer->>You: Confirm
    You->>Nodu: 3. Create the transfer<br/>POST /v1/transfers
    Nodu-->>You: Transfer id and deposit instructions
    You->>Customer: Show the deposit instructions
    Customer->>Nodu: 4. Pay: a bank payment or crypto
    Note over Customer,Nodu: 5. Nodu reviews the transfer and pays the recipient.<br/>You show any action that the customer must take.
    Nodu-->>You: Webhook events for the transfer
    You->>Nodu: Read the transfer and its receipt<br/>GET /v1/transfers/{transferId}
    You->>Customer: Show the outcome
```

1. **The customer chooses the amount and the recipient.** A new recipient needs an external account first: see [Find destinations and requirements](/guides/transfers/external-accounts/destinations-and-requirements/index.md).
2. **You create a quote, and the customer confirms it.** See [Quotes and exchange rates](/guides/transfers/quotes-and-exchange-rates/index.md).
3. **You create the transfer, and you show the deposit instructions.** See [Create a transfer](#create-a-transfer) and [Deposit instructions](#deposit-instructions).
4. **The customer pays.**
5. **Nodu reviews the transfer and pays the recipient.** See [What Nodu does after the funds arrive](#what-nodu-does-after-the-funds-arrive) and [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md).

## A source and a destination

A transfer request names the customer, an `amount`, a `source` and a `destination`. The `source` is where the money comes from. The `destination` is where Nodu sends it.

| Part | What it can be | What you send |
|---|---|---|
| `source` | A payment that the customer makes on a rail. A rail is a bank payment scheme or blockchain network that carries the money. | A `paymentRail` and a `currency`. For example, the rail `sepa` with the currency `eur`. |
| `source` | A Nodu wallet\* | The `paymentRail` `wallet`, a `currency` and the `walletId`. |
| `destination` | An external account: a bank account or crypto wallet outside Nodu that you registered for transfers. | The `externalAccountId`. The external account has a rail and a currency of its own. |
| `destination` | A Nodu wallet\* | The `walletId` and a `currency`. |

\* A Nodu wallet is a balance held at Nodu. A transfer with a Nodu wallet is a separate flow: see [Fund and pay out from a Nodu wallet](/guides/nodu-wallets/transfers-funded-from-a-wallet/index.md).

The currencies of the source and the destination decide the flow:

| Flow | Money in | Money out |
|---|---|---|
| On-ramp | Fiat money, by bank payment. | A stablecoin, to a crypto wallet. |
| Off-ramp | A stablecoin. | Fiat money, to a bank account. |
| Crypto swap | Crypto. | Crypto, to a crypto wallet. For example, `usdc` in and `eurc` out. |
| Fiat cross-border | Fiat money, by bank payment. | Fiat money, to a bank account. For example, `eur` in and `gbp` out. |

The flows, currencies and rails that you can use depend on your integration agreement with Nodu.

## What a transfer needs

- **An active customer.** The customer's `status` must be `active`: see [How onboarding works, and customer statuses](/guides/customers/how-onboarding-works/index.md).
- **An active payment channel on each side.** A payment channel is a currency and rail on which a customer can pay in or be paid out: see [Payment channels](/guides/transfers/payment-channels/index.md).
- **A destination.** For a payout outside Nodu, register an external account. For a [Nodu wallet destination](/guides/nodu-wallets/transfers-funded-from-a-wallet/index.md#move-funds-into-a-nodu-wallet), send the wallet ID and currency. See [External accounts and counterparties](/guides/transfers/external-accounts/first-party-and-third-party-accounts/index.md).
- **The customer on at least one side.** A third party is someone other than the customer. Nodu refuses a transfer that has a third party on both sides.

## Create a transfer

Call [Create a transfer](/api/tag/transfers/post-v1-transfers.md). This example is an on-ramp: the customer pays euros by SEPA, and Nodu pays a stablecoin to a recipient's crypto wallet. It uses a quote that the customer has confirmed.

```bash
curl https://api.sandbox.nodu.fi/v1/transfers \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
    "quoteId": "01963a52-6c1e-7b4f-a2d9-3e5c8f0b1a77",
    "clientReferenceId": "order-10045",
    "amount": "1000.00",
    "developerFee": "5.00",
    "source": {
      "paymentRail": "sepa",
      "currency": "eur"
    },
    "destination": {
      "externalAccountId": "019ab6d8-dd85-777f-9d40-247ba54388f5",
      "message": "Invoice 10045"
    }
  }'
```

Use the quote the customer confirmed: its source amount, currencies, rails and developer fee must match the transfer. You can omit `developerFee` to use the quote's fee. [Fees and amounts](/guides/transfers/fees-and-amounts/index.md) explains the calculation. The transfer keeps the quote's exchange rate for 15 minutes: see [How long a transfer keeps the quoted rate](/guides/transfers/quotes-and-exchange-rates/index.md#how-long-a-transfer-keeps-the-quoted-rate).

`clientReferenceId` helps connect this transfer to your own records. When a third party takes part on either side, include `destination.message`, the payment message shown to a bank recipient. Exact field constraints are in [Create a transfer](/api/tag/transfers/post-v1-transfers.md).

For an off-ramp, set `source` to the stablecoin and blockchain rail, and use a bank external account for `destination.externalAccountId`. For example, `source={"paymentRail":"ethereum","currency":"usdc"}` with an EUR/SEPA destination. Obtain a quote for those currencies and rails, and use its `source.amount` as `amount`.

When the crypto comes from a third party, or from the customer's own wallet at an exchange or custodian, also send `source.externalAccountId`: see [Declare who sends incoming crypto](/guides/transfers/external-accounts/declare-the-originator-of-a-crypto-funding/index.md). When the customer sends crypto from their own self-custody wallet, leave it out. Nodu refuses the transfer unless the external account in `source.externalAccountId` meets all of these conditions:

- The source of the transfer is on a blockchain rail.
- The external account belongs to the customer of the transfer, and it has `status=active`.
- The external account has the `paymentRail` and the `currency` of the source.
- The external account meets the requirements of the originator side. To check this in advance, call [Validate an external account for a transfer side](/api/tag/external-accounts/get-v1-external-accounts-externalaccountid-validation.md) with `side=originator`.

Store the `id` of the transfer from the response. The response also contains the `sourceDepositInstructions`.

## Update a transfer before funding

While a transfer is `awaiting_funds`, [Update a transfer](/api/tag/transfers/put-v1-transfers-transferid.md) can change `amount` and `developerFee`. The amount and fee are decimal strings in the source currency. Omit either field to keep its current value. The customer must still be active, and the updated amount must satisfy the limits and cover the fees.

```bash
curl --request PUT 'https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>' \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"amount": "125.00", "developerFee": "1.00"}'
```

1. Retrieve the transfer and check that it is still `awaiting_funds` and the customer has not paid.
2. Send the update. It cannot change the source, destination or declared originator.
3. Read the returned amount and `receipt`. Nodu recalculates the service fee and replaces the receipt; the original quote's rate and final amount are not preserved by this update. Show the revised figures and funding amount before the customer pays.
4. If the customer needs a new quote, cancel the unfunded transfer and create a new one with a new quote after cancellation succeeds.

Funds can arrive between your check and the update. If the update fails because the transfer has moved on, retrieve it and continue [tracking](/guides/transfers/track-a-transfer/index.md). Do not ask the customer to pay a changed amount until the update succeeds. After a timeout, retrieve the transfer to check the result before retrying.

## Deposit instructions

The `sourceDepositInstructions` of a transfer say where the customer sends the money. This example is for a SEPA payment:

```json
"sourceDepositInstructions": {
  "requisites": {
    "iban": "GB52NODU00000053201335",
    "bic": "NODUGB22",
    "bankName": "Nodu Bank UK",
    "bankCountry": "GB",
    "bankAddress": "1 Churchill Place, London E14 5HP"
  },
  "accountOwner": {
    "type": "business",
    "companyName": "Company Name",
    "address": {
      "addressLine1": "Test st.",
      "city": "Riga",
      "postalCode": "LV-1001",
      "country": "LV"
    }
  },
  "depositMessage": "7QKMZZ8T"
}
```

For a payment in crypto, `requisites` holds the deposit address in `wallet`. This example is for `usdc` on `base`:

```json
"sourceDepositInstructions": {
  "requisites": {
    "wallet": "0xc0ffee254729296a45a3885639AC7E10F9d54979"
  },
  "accountOwner": {
    "type": "business",
    "companyName": "Company Name",
    "address": {
      "country": "GB"
    }
  }
}
```

| Field | Meaning |
|---|---|
| `requisites` | The bank details for a bank rail, such as the IBAN and the BIC. For a blockchain rail, the deposit address in `wallet`. |
| `accountOwner` | The holder of the deposit account: its name and address. |
| `depositMessage` | A payment reference. It is present only when the payment needs one. |

Show the customer every field that has a value. A field without a value is absent from the response. The customer then makes the payment from their bank account or crypto wallet. The deposit instructions are not the details of the recipient.

> **Warning**
>
> When `depositMessage` is present, the customer must include it in the payment, unchanged. On a bank payment, it goes in the reference text. Nodu uses it to match the payment to the transfer.

A transfer whose source is a Nodu wallet has no deposit instructions.

## What Nodu does after the funds arrive

You make no further API calls for these steps:

1. Nodu receives the payment. Nodu then matches it to the transfer.
2. Nodu reviews the transfer for compliance. During this review, Nodu can ask the customer to [complete an action](/guides/transfers/handle-a-transfer-that-needs-action/index.md), such as proving that they control a crypto wallet.
3. Nodu converts the funds when the two currencies differ.
4. Nodu sends the payout to the destination.

## The lifecycle

A transfer that the customer funds starts in `awaiting_funds`. Nodu sends a `v1.transfer.*` webhook event when its state changes. See [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md) for each state's meaning and your next action.

## Which rails and currencies you can use

The rails and currencies that you can use depend on your integration agreement with Nodu. Two operations return what is available to a customer:

- [List payment channels](/api/tag/customers/get-v1-customers-customerid-payment-channels.md) returns the currencies and rails on which the customer can pay in or be paid out.
- [List external account destinations](/api/tag/external-accounts/get-v1-external-accounts-destinations.md) returns the countries and rails for which you can register an external account in a currency.

## Next steps

- [Payment channels](/guides/transfers/payment-channels/index.md): prepare the customer's channels for a transfer.
- [Find destinations and requirements](/guides/transfers/external-accounts/destinations-and-requirements/index.md): find the fields of the external account that a transfer pays out to.
- [Fees and how amounts are calculated](/guides/transfers/fees-and-amounts/index.md): the fees and the amounts to show the customer.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): test a transfer without real money.
