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 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. | 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 directionpayout. For a Nodu wallet, the destination rail iswallet. Without these channels, Nodu answers with the status404.
Create a relay
- Call Create a relay with an
Idempotency-Keyheader and these fields:customerId.source: thepaymentRailand thecurrencyon which the funds arrive. For example,sepaandeur. The rail cannot bewallet.destination: eitherexternalAccountIdorwalletId, not both. WithwalletId, also sendcurrency. WithexternalAccountId, Nodu takes the rail and the currency from the external account.
- Read
statusin the response.activemeans that the response containsdepositInstructions.pendingmeans that Nodu is still setting up the relay: wait for the eventv1.relay.activated, or call Retrieve a relay later. - Store the
idof the relay with the customer in your system. The relay object does not containcustomerId. You can also send your own identifier inclientReferenceIdwhen 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.
When depositMessage is present, every payment must include it, unchanged. Without it, Nodu cannot match the payment to the relay.
When funds arrive
- Nodu matches the payment to the relay.
- Nodu creates a transfer for the relay's customer. The requirements in How transfers work apply to this transfer. Its
amountis the amount that arrived. Itssourceanddestinationare those of the relay. - 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 ininfo_required.
The transfer differs from a transfer that you create in three ways:
- The transfer object does not contain the
idof the relay. - The transfer is already funded. Do not show its
sourceDepositInstructionsto the customer. - The transfer has no quote. Its
receiptshows 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 and v1.relay.activated. Retrieve the relay before showing deposit instructions to check its current status.
Next steps
- Track and cancel a transfer: follow the transfers that a relay creates.
- Fund and pay out from a Nodu wallet: use the funds that a relay sends to a Nodu wallet.
- Simulate funding in the sandbox: simulate a payment to a relay.