---
title: "Quickstart: your first sandbox transfer"
description: "Go from a sandbox API key to a completed test transfer: create and verify a customer, create a quote and a transfer, simulate the funding and the proof of ownership, and read the result."
url: "/guides/get-started/quickstart/"
index: "/llms.txt"
---

# 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](/guides/get-started/environments-and-api-keys/index.md#get-a-key).
- **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](/guides/customers/api-onboarding/create-a-customer-with-a-full-application/index.md) for steps 1–2, then return here with an active customer.

## 1. Create a customer

Call [Create a customer](/api/tag/customers/post-v1-customers.md):

```bash
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](/guides/api-basics/idempotency/index.md).

An illustrative response excerpt (other customer fields omitted):

```json
{"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](/guides/customers/hosted-onboarding/index.md): you take the place of the customer in a browser.

1. Call [Retrieve a link to ToS acceptance page for a customer](/api/tag/customers/get-v1-customers-customerid-tos-acceptance-link.md). Open the returned `link`. Accept the terms.
2. Call [Retrieve a link to verification page for a customer](/api/tag/customers/get-v1-customers-customerid-verification-link.md). 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](/guides/sandbox/test-onboarding/index.md) says where you get the test document.
3. Call [Retrieve a customer](/api/tag/customers/get-v1-customers-customerid.md). Repeat the call until `status=active`.

```bash
# 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](/guides/customers/resubmission-and-rejection/index.md). 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](/api/tag/customers/get-v1-customers-customerid-payment-channels.md):

```bash
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:

```json
[
  {
    "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](/api/tag/customers/post-v1-customers-customerid-payment-channels-channelid-activate.md). In this example, activate the EUR/SEPA channel. Replace `<channel-id>` with its returned `id`; the request has no body:

```bash
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](/guides/transfers/payment-channels/index.md#activate-a-channel).

## 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](/api/tag/external-accounts/post-v1-external-accounts.md). `selfOwned=true` says that the crypto wallet belongs to the customer:

```bash
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](/guides/transfers/travel-rule/self-custody-wallets/index.md).

Store the `id` from the response. To find the fields that a rail needs, see [destinations and requirements](/guides/transfers/external-accounts/destinations-and-requirements/index.md).

## 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](/api/tag/quotes/post-v1-quotes.md):

```bash
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](/guides/transfers/quotes-and-exchange-rates/index.md).

## 6. Create the transfer

Call [Create a transfer](/api/tag/transfers/post-v1-transfers.md). The `amount` equals the `source.amount` of the quote:

```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": "<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:

```json
{
  "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](/guides/transfers/how-transfers-work/index.md#deposit-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](/api/tag/transfers/post-v1-transfers-transferid-simulate-funding.md):

```bash
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](/guides/sandbox/simulate-funding/index.md).

## 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](/guides/transfers/handle-a-transfer-that-needs-action/index.md).

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](/api/tag/transfers/get-v1-transfers-transferid.md). 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](/guides/transfers/track-a-transfer/index.md):

```bash
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:

```json
{
  "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](/api/tag/transfers/post-v1-transfers-transferid-simulate-wallet-verification.md) with the `side` of the requirement:

```bash
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](/guides/sandbox/simulate-wallet-verification/index.md).

## 9. Read the result

Call [Retrieve a transfer](/api/tag/transfers/get-v1-transfers-transferid.md) 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](/guides/transfers/track-a-transfer/index.md). 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:

```json
{
  "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](/guides/transfers/fees-and-amounts/index.md) explains each field.

If the transfer reaches another state, see [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md).

## Next steps

- [Receive and verify webhooks](/guides/api-basics/webhooks/index.md): receive notifications about customer and transfer changes.
- [Onboarding models](/guides/customers/onboarding-models/index.md): choose how you onboard real customers.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): test incoming payments.
