---
title: "Relays: deposit instructions you can reuse"
description: "Learn when to use a relay, how to create one, how to publish its deposit instructions, and what happens when funds arrive."
url: "/guides/relays/"
index: "/llms.txt"
---

# Relays: deposit instructions you can reuse

A relay gives one customer reusable deposit instructions that say where to send payments. Each time a payment follows these instructions, Nodu creates a transfer to the destination that you chose for the relay. Use a relay when a customer makes repeated payments to the same deposit instructions.

The availability of relays depends on your integration agreement with Nodu.

## When to use a relay

| What differs | A transfer for each payment | A relay |
|---|---|---|
| Deposit instructions | You create a transfer for each payment. Each transfer returns its own instructions. | You create the relay once. Every payment uses the same instructions. |
| Amount | You set `amount` in the request. | The amount that arrives. |
| Quote | Optional. A [quote](/guides/transfers/quotes-and-exchange-rates/index.md) fixes the fees and, for a limited time, the exchange rate. | None. |
| `developerFee`, the fee that you keep for yourself | You set it. | Zero. |
| Originator of incoming crypto | You can [declare the originator](/guides/transfers/external-accounts/declare-the-originator-of-a-crypto-funding/index.md). | Nodu treats the crypto as sent from the customer's own crypto wallet. |

Use a relay when payments for the same destination arrive repeatedly, and you do not know their amounts or times in advance.

## Before you start

- **A destination.** Register an external account for the customer: see [External accounts and counterparties](/guides/transfers/external-accounts/first-party-and-third-party-accounts/index.md). Or create a Nodu wallet, which is a balance held at Nodu: see [Nodu wallet balances and scopes](/guides/nodu-wallets/balances-and-wallet-scopes/index.md).
- **Payment channels.** The customer's [payment channels](/guides/transfers/payment-channels/index.md) must include the source rail and currency with the direction `payin`. They must also include the destination rail and currency with the direction `payout`. For a Nodu wallet, the destination rail is `wallet`. Without these channels, Nodu answers with the status `404`.

## Create a relay

1. Call [Create a relay](/api/tag/relays/post-v1-relays.md) with an `Idempotency-Key` header and these fields:
   - `customerId`.
   - `source`: the `paymentRail` and the `currency` on which the funds arrive. For example, `sepa` and `eur`. The rail cannot be `wallet`.
   - `destination`: either `externalAccountId` or `walletId`, not both. With `walletId`, also send `currency`. With `externalAccountId`, Nodu takes the rail and the currency from the external account.
2. Read `status` in the response. `active` means that the response contains `depositInstructions`. `pending` means that Nodu is still setting up the relay: wait for the event `v1.relay.activated`, or call [Retrieve a relay](/api/tag/relays/get-v1-relays-relayid.md) later.
3. Store the `id` of the relay with the customer in your system. The relay object does not contain `customerId`. You can also send your own identifier in `clientReferenceId` when you create the relay.

For example, a relay that receives EUR by SEPA and adds the funds to a Nodu wallet:

```bash
curl https://api.sandbox.nodu.fi/v1/relays \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "<customer-id>",
    "clientReferenceId": "client_relay_id_123",
    "source": {"paymentRail": "sepa", "currency": "eur"},
    "destination": {"walletId": "<wallet-id>", "currency": "eur"}
  }'
```

To send the funds to an external account instead, replace `destination` with `{"externalAccountId": "<external-account-id>"}`. Add `destination.message` when a third party receives the payout, following the [third-party payment-message rules](/guides/transfers/external-accounts/first-party-and-third-party-accounts/index.md#first-party-and-third-party-accounts). This is the outgoing payment reference; `depositInstructions.depositMessage` is the reference the sender must include on the incoming payment. Omit `destination.message` for a Nodu wallet destination.

The destination can differ from the source in rail and currency. Nodu converts the funds when they arrive. The rail and the currency in the request are examples. The ones that you can use depend on your integration agreement with Nodu.

## Find an existing relay

Use the relay ID stored with your customer to [retrieve it](/api/tag/relays/get-v1-relays-relayid.md). [List relays](/api/tag/relays/get-v1-relays.md) can also filter by `clientReferenceId` or `destinationWalletId`. Follow [Pagination](/guides/api-basics/pagination/index.md) when listing results. Check the relay's current status before reusing its instructions.

## Publish the deposit instructions

An `active` relay has `depositInstructions`. They have the same fields as the deposit instructions of a transfer: see [How transfers work](/guides/transfers/how-transfers-work/index.md#deposit-instructions). They stay the same while the relay exists. For example:

```json
"status": "active",
"depositInstructions": {
  "requisites": {
    "iban": "GB52NODU00000053201335",
    "bic": "NODUGB22",
    "bankName": "Nodu Bank UK",
    "bankCountry": "GB",
    "bankAddress": "1 Churchill Place, London E14 5HP"
  },
  "accountOwner": {
    "type": "business",
    "companyName": "Nodu Holdings Ltd",
    "address": {"country": "GB"}
  },
  "depositMessage": "K7P9X2M3N4"
}
```

Show the customer the instructions exactly as returned. Show only the fields that contain a value.

> **Warning**
>
> When `depositMessage` is present, every payment must include it, unchanged. Without it, Nodu cannot match the payment to the relay.

## When funds arrive

1. Nodu matches the payment to the relay.
2. Nodu creates a transfer for the relay's customer. The requirements in [How transfers work](/guides/transfers/how-transfers-work/index.md#what-a-transfer-needs) apply to this transfer. Its `amount` is the amount that arrived. Its `source` and `destination` are those of the relay.
3. Nodu sends the event `v1.transfer.created`. Nodu sends further events as the transfer changes state: see [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md). Nodu reviews the transfer like any other, so it can wait in `info_required`.

The transfer differs from a transfer that you create in three ways:

- The transfer object does not contain the `id` of the relay.
- The transfer is already funded. Do not show its `sourceDepositInstructions` to the customer.
- The transfer has no quote. Its `receipt` shows the fees and the exchange rate.

If the customer has paid and no transfer appears, contact Nodu.

## Relay statuses


| `status` | Meaning | What you do |
|---|---|---|
| `pending` | Nodu is setting up the relay. It has no deposit instructions yet. | Wait for the event `v1.relay.activated`. |
| `active` | The relay can receive funds. | Publish the deposit instructions. |
| `suspended` | The relay does not accept new funds at present. Nodu still processes the payments that it has already received. | Ask the customer not to pay. Retrieve the relay to read its current status. |

Nodu sends the events [`v1.relay.created`](/api/tag/webhooks/webhook/POST/v1.relay.created.md) and [`v1.relay.activated`](/api/tag/webhooks/webhook/POST/v1.relay.activated.md). Retrieve the relay before showing deposit instructions to check its current status.

## Next steps

- [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md): follow the transfers that a relay creates.
- [Fund and pay out from a Nodu wallet](/guides/nodu-wallets/transfers-funded-from-a-wallet/index.md): use the funds that a relay sends to a Nodu wallet.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): simulate a payment to a relay.
