Fund and pay out from a Nodu wallet
A Nodu wallet, which is a balance held at Nodu, can be the destination or the source of a transfer. A payout from a Nodu wallet differs from a transfer that the customer funds: Nodu takes the funds from the balance instead of waiting for the customer's payment. To create a Nodu wallet, see Nodu wallet balances and scopes.
Before you start
A transfer with a Nodu wallet names a customer in customerId, like every transfer. How transfers work lists what every transfer needs. This transfer also needs the following:
- A Nodu wallet whose scope includes the customer. A developer-scoped Nodu wallet serves any of your customers. A customer-scoped Nodu wallet serves its own customer only. For another customer, Nodu answers with the status
404. - A payment channel on the rail
wallet. The customer's payment channels must include a channel with the railwalletand the currency that you use with the Nodu wallet. When the Nodu wallet is the source, the payment channel direction ispayin. When it is the destination, the direction ispayout. Without this channel, Nodu answers with the status404.
Move funds into a Nodu wallet
Call Create a transfer with the Nodu wallet as the destination:
source: the rail and the currency of the incoming payment, as in any transfer.destination.walletId: theidof the Nodu wallet.destination.currency: the currency to add to the Nodu wallet. It is required, because a Nodu wallet can hold several currencies.
For example, a customer sends USDC on Base, and Nodu adds it to the Nodu wallet:
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": "<customer-id>",
"amount": "100.00",
"source": {"paymentRail": "base", "currency": "usdc"},
"destination": {"walletId": "<wallet-id>", "currency": "usdc"}
}'
The transfer starts in awaiting_funds. The response includes sourceDepositInstructions. The customer pays as in any other transfer. When the transfer reaches payment_processed, the funds are in the Nodu wallet. A transfer into a Nodu wallet does not pass through payment_submitted.
Pay out from a Nodu wallet
Call Create a transfer with the Nodu wallet as the source:
source.paymentRail:wallet.source.walletId: theidof the Nodu wallet.source.currency: the currency to take from the Nodu wallet.destination.externalAccountId: the external account that receives the payout, as in any transfer.
For example, Nodu takes EUR from the Nodu wallet and pays USDC to the customer's crypto wallet:
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": "<customer-id>",
"amount": "100.00",
"source": {"paymentRail": "wallet", "currency": "eur", "walletId": "<wallet-id>"},
"destination": {"externalAccountId": "<external-account-id>"}
}'
The rails and the currencies in both requests are examples. The ones that you can use depend on your integration agreement with Nodu.
To show the customer the amounts and the fees first, call Create a quote with wallet as the paymentRail of the source: see Quotes and exchange rates.
How a payout from a Nodu wallet differs
| What differs | A transfer that the customer funds | A transfer funded from a Nodu wallet |
|---|---|---|
| Deposit instructions | sourceDepositInstructions says where to pay. | None. The customer does not send a payment to fund the transfer. |
| Funding | Nodu waits for the payment to arrive. | Nodu takes amount from the available balance in the source currency. |
Meaning of awaiting_funds | The payment has not arrived yet. | Nodu has not taken the funds yet. |
After Nodu takes the funds, follow the transfer's state as described in Track and cancel a transfer. The transfer can enter info_required.
When the balance is too low
Nodu does not refuse a transfer because the balance is too low. The transfer waits in awaiting_funds until the available balance in the source currency covers amount, or until you cancel the transfer.
- Add funds and keep the same transfer. Do not create a second transfer for the same payout. Creating a second transfer can result in two payouts once enough funds are available.
- Expect waiting transfers to continue in order. Transfers that wait on the same Nodu wallet continue oldest first. A large waiting transfer can delay later transfers.
- Cancel a payout you no longer need. Call Cancel a transfer and check the response: see Track and cancel a transfer.
Read the balance afterward
Retrieve a wallet returns the balances of the Nodu wallet: see Nodu wallet balances and scopes.
- While a payout is in progress, Nodu holds its amount in
reserved. - Use transfer events to trigger a fresh wallet retrieval and read the current balance.
- After a failed payout, read the balance before you use the funds for another payout.
- To list the transfers that use one Nodu wallet as their source or destination, call List all transfers with
walletId.
Next steps
- Track and cancel a transfer: follow a transfer to its outcome.
- Relays: deposit instructions you can reuse: send repeated incoming payments to a Nodu wallet.
- Simulate funding in the sandbox: simulate the payment for a transfer into a Nodu wallet. A transfer that a Nodu wallet funds has no payment to simulate.