Skip to main content

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 differsA transfer for each paymentA relay
Deposit instructionsYou create a transfer for each payment. Each transfer returns its own instructions.You create the relay once. Every payment uses the same instructions.
AmountYou set amount in the request.The amount that arrives.
QuoteOptional. A quote fixes the fees and, for a limited time, the exchange rate.None.
developerFee, the fee that you keep for yourselfYou set it.Zero.
Originator of incoming cryptoYou can declare the originator.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. Or create a Nodu wallet, which is a balance held at Nodu: see Nodu wallet balances and scopes.
  • Payment channels. The customer's payment channels 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 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 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:

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. 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. List relays can also filter by clientReferenceId or destinationWalletId. Follow Pagination 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. They stay the same while the relay exists. For example:

"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 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. 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​

statusMeaningWhat you do
pendingNodu is setting up the relay. It has no deposit instructions yet.Wait for the event v1.relay.activated.
activeThe relay can receive funds.Publish the deposit instructions.
suspendedThe 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 and v1.relay.activated. Retrieve the relay before showing deposit instructions to check its current status.

Next steps​