Quickstart: your first sandbox transfer
Nine steps take you from a sandbox API key to a completed test transfer. The sandbox is Nodu's test environment: no real money moves. The example is an on-ramp: fiat in, stablecoin out.
Before you start
- A sandbox API key. Nodu gives it to you during the integration: see Environments and API keys.
- A terminal with
curl, and a browser. In step 2, you take the place of the customer on two pages that Nodu hosts. - Your own values. In the commands, replace each placeholder in angle brackets, such as
<customer-id>.
In this transfer, a customer pays euros by SEPA. Nodu pays USDC on Ethereum to the customer's own crypto wallet. A rail is a bank payment scheme or blockchain network that carries the money.
Before following this example, agree the sandbox configuration with Nodu: hosted onboarding, eur on sepa for pay-in, and usdc on ethereum for payout. Step 3 checks that these channels are available to your customer. If your agreed integration uses API onboarding, follow API onboarding for steps 1–2, then return here with an active customer.
1. Create a customer
Call Create a customer:
curl https://api.sandbox.nodu.fi/v1/customers \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"type": "individual",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com"
}'
Store the id from the response. The customer starts with status=pending. Use a new Idempotency-Key value for each object that you create in this quickstart. If you send the same request again, reuse its value: see Idempotency.
An illustrative response excerpt (other customer fields omitted):
{"id": "019634b8-f479-7001-84ce-2e15ced821e2", "status": "pending"}
Use the returned ID as <customer-id> throughout the remaining steps.
2. Get the customer verified
A customer can transact when the customer has status=active. Before the customer can transact, they must accept Nodu's Terms of Service. Nodu must also approve the customer's verification. This step uses hosted onboarding: you take the place of the customer in a browser.
- Call Retrieve a link to ToS acceptance page for a customer. Open the returned
link. Accept the terms. - Call Retrieve a link to verification page for a customer. Open the returned
link. When the page asks for a document, upload the test document that produces an approval. Complete the other steps of the page. Test onboarding in the sandbox says where you get the test document. - Call Retrieve a customer. Repeat the call until
status=active.
# 1. The link to the terms page
curl 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>/tos-acceptance-link' \
--header 'Authorization: Bearer <your-api-key>'
# 2. The link to the verification page
curl 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>/verification-link' \
--header 'Authorization: Bearer <your-api-key>'
# 3. The customer
curl 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>' \
--header 'Authorization: Bearer <your-api-key>'
If the customer needs corrections or receives a final rejection, stop polling and follow Resubmission and rejection. Poll with a delay between requests and a timeout in your own integration; a timeout does not mean rejection.
3. Check the payment channels
A payment channel is a currency and rail on which a customer can pay in or be paid out. Call List payment channels:
curl 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>/payment-channels' \
--header 'Authorization: Bearer <your-api-key>'
An example response with the two channels used in this quickstart:
[
{
"id": "01973a82-de63-71d8-932b-73c11c888e9e",
"currency": "eur",
"paymentRail": "sepa",
"status": "inactive",
"directions": ["payin"]
},
{
"id": "01973a82-de63-71d8-932b-73c11c888e9f",
"currency": "usdc",
"paymentRail": "ethereum",
"status": "active",
"directions": ["payout"]
}
]
This transfer needs both channels with status=active: eur on sepa with payin in its directions, and usdc on ethereum with payout in its directions. Your response may contain other channels or statuses.
For each required channel with status=inactive, call Activate a payment channel. In this example, activate the EUR/SEPA channel. Replace <channel-id> with its returned id; the request has no body:
curl --request POST 'https://api.sandbox.nodu.fi/v1/customers/<customer-id>/payment-channels/<channel-id>/activate' \
--header 'Authorization: Bearer <your-api-key>'
The response has HTTP status 202 and contains the channel object. If its status is pending, list the channels again after a delay until both required channels are active. If a required channel is missing or suspended, stop this example and check the agreed configuration. See Payment channels.
4. Register the crypto wallet
An external account is a bank account or crypto wallet outside Nodu that you register for transfers. Call Create an external account. selfOwned=true says that the crypto wallet belongs to the customer:
curl https://api.sandbox.nodu.fi/v1/external-accounts \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "<customer-id>",
"selfOwned": true,
"paymentRail": "ethereum",
"currency": "usdc",
"accountRequisites": {
"wallet": "<ethereum-address>"
}
}'
Replace <ethereum-address> with the address of a crypto wallet on Ethereum. Step 8 simulates the proof of ownership, so you do not need to control the address. The request does not declare an exchange or custodian, so Nodu treats the crypto wallet as a self-custody wallet.
Store the id from the response. To find the fields that a rail needs, see destinations and requirements.
5. Create a quote
A quote fixes the amounts, the fees and the exchange rate of one transfer for a limited time. Call Create a quote:
curl https://api.sandbox.nodu.fi/v1/quotes \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "<customer-id>",
"source": {"amount": "100", "currency": "eur", "paymentRail": "sepa"},
"destination": {"currency": "usdc", "paymentRail": "ethereum"}
}'
The response contains the fees, the exchange rate and destination.amount, the amount that the crypto wallet receives. Store the id. Create the transfer before the time in expiresAt, 2 minutes after the quote. The transfer then keeps the quoted exchange rate for 15 minutes: see Quotes and exchange rates.
6. Create the transfer
Call Create a transfer. The amount equals the source.amount of the quote:
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>",
"quoteId": "<quote-id>",
"amount": "100",
"source": {"paymentRail": "sepa", "currency": "eur"},
"destination": {"externalAccountId": "<external-account-id>"}
}'
The transfer starts in awaiting_funds. Here is a full example response for this request, with illustrative IDs, bank details, fees and exchange rate. Use the values returned by your own requests:
{
"id": "019ab6e1-4c2a-7d3e-9f10-6b7c8d9e0a12",
"state": "awaiting_funds",
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"amount": "100",
"developerFee": "0",
"source": {
"currency": "eur",
"paymentRail": "sepa"
},
"destination": {
"currency": "usdc",
"paymentRail": "ethereum",
"externalAccountId": "019ab6df-64a7-73da-93fd-66e2c4ea34b5",
"beneficiaryId": "019ab6df-64a7-73da-93fd-66e2c4ea34b5"
},
"sourceDepositInstructions": {
"requisites": {
"iban": "GB52NODU00000053201335",
"bic": "NODUGB22",
"bankName": "Example Bank",
"bankCountry": "GB",
"bankAddress": "1 Example Street, London"
},
"accountOwner": {
"type": "business",
"companyName": "Example Account Holder",
"address": {
"addressLine1": "1 Example Street",
"city": "Riga",
"postalCode": "LV-1001",
"country": "LV"
}
},
"depositMessage": "7QKMZZ8T"
},
"receipt": {
"initialAmount": "100",
"developerFee": "0",
"serviceFee": "0.50",
"subtotalAmount": "99.50",
"exchangeRate": "1.08350000",
"networkFee": "0.02",
"finalAmount": "107.78825"
},
"createdAt": "2026-10-16T10:00:00+00:00",
"updatedAt": "2026-10-16T10:00:00+00:00"
}
Store the returned id as <transfer-id> to track the transfer. To fund it, the customer uses the bank account details in sourceDepositInstructions.
7. Fund the transfer
In production, show these instructions to the customer so they can send the euros from their bank.
In the sandbox, you simulate the customer's SEPA payment. Call Simulate funding for a transfer:
curl --request POST 'https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>/simulate-funding' \
--header 'Authorization: Bearer <your-api-key>'
Nodu answers with the status 204 and no body. Nodu then processes the transfer as it does after a real payment: see Simulate funding in the sandbox.
8. Complete the proof of ownership
In production, when Nodu requests proof of ownership, direct the customer to the verification page in the transfer's requirements so they can prove control of the crypto wallet: see Handle a transfer that needs action.
In the sandbox, Nodu asks for this proof whatever the amount, so a first transfer to a new crypto wallet always needs it. The transfer waits in the state info_required.
Call Retrieve a transfer. Poll with a delay until state=info_required. If the address is already verified, the transfer can continue without this state; go to step 9. For an error or return state, follow Track a transfer:
curl 'https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>' \
--header 'Authorization: Bearer <your-api-key>'
In the response, the requirements list says which crypto wallet needs the proof. An excerpt:
{
"state": "info_required",
"requirements": [
{
"id": "0196a1f2-7c3e-7b10-9d4e-5a2b8c6f1e03",
"action": "verify_wallet_ownership",
"side": "destination",
"url": "https://customer.nodu.fi/wallet-verification/019657d0-c6c4-7947-94ec-42c4164cd51e"
}
]
}
To simulate the proof in the sandbox, call Simulate a wallet verification with the side of the requirement:
curl https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>/simulate-wallet-verification \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{"side": "destination"}'
Nodu answers with the status 204 and no body. Nodu records the proof and continues the transfer: see Simulate crypto wallet verification in the sandbox.
9. Read the result
Call Retrieve a transfer again. Poll with a delay until state=payment_processed: the test transfer is complete. Stop and handle any action, error or return state using Track a transfer. If your polling timeout expires, retain the transfer ID and retrieve it later rather than creating a replacement. Read the receipt for the fees, the exchange rate and the final amount. An excerpt, with illustrative fees and rate:
{
"state": "payment_processed",
"receipt": {
"initialAmount": "100",
"developerFee": "0",
"serviceFee": "0.50",
"subtotalAmount": "99.50",
"exchangeRate": "1.08350000",
"networkFee": "0.02",
"finalAmount": "107.78825"
}
}
finalAmount is the amount in USDC that the crypto wallet receives. A payout to a crypto wallet has a network fee: Nodu deducts networkFee, in USDC, from the converted amount. Fees and how amounts are calculated explains each field.
If the transfer reaches another state, see Track and cancel a transfer.
Next steps
- Receive and verify webhooks: receive notifications about customer and transfer changes.
- Onboarding models: choose how you onboard real customers.
- Simulate funding in the sandbox: test incoming payments.