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.
- The customer chooses the amount and the recipient. A new recipient needs an external account first: see Find destinations and requirements.
- You create a quote, and the customer confirms it. See Quotes and exchange rates.
- You create the transfer, and you show the deposit instructions. See Create a transfer and Deposit instructions.
- The customer pays.
- Nodu reviews the transfer and pays the recipient. See What Nodu does after the funds arrive and Track and cancel a transfer.
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.
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
statusmust beactive: see How onboarding works, and customer statuses. - 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.
- A destination. For a payout outside Nodu, register an external account. For a Nodu wallet destination, send the wallet ID and currency. See External accounts and counterparties.
- 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. 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.
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 explains the calculation. The transfer keeps the quote's exchange rate for 15 minutes: see 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.
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. 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
paymentRailand thecurrencyof 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 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 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.
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"}'
- Retrieve the transfer and check that it is still
awaiting_fundsand the customer has not paid. - Send the update. It cannot change the source, destination or declared originator.
- 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. - 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. 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:
"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:
"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.
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:
- Nodu receives the payment. Nodu then matches it to the transfer.
- Nodu reviews the transfer for compliance. During this review, Nodu can ask the customer to complete an action, such as proving that they control a crypto wallet.
- Nodu converts the funds when the two currencies differ.
- 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 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 returns the currencies and rails on which the customer can pay in or be paid out.
- List external account destinations returns the countries and rails for which you can register an external account in a currency.
Next steps
- Payment channels: prepare the customer's channels for a transfer.
- Find destinations and requirements: find the fields of the external account that a transfer pays out to.
- Fees and how amounts are calculated: the fees and the amounts to show the customer.
- Simulate funding in the sandbox: test a transfer without real money.