Payment channels
A payment channel is a currency and rail on which a customer can pay in or be paid out. A rail is a bank payment scheme or blockchain network that carries the money. Before you offer a transfer, check that the customer has an active payment channel on each side.
What a channel contains
List payment channels returns every channel available to one customer. The available channels depend on your integration agreement with Nodu. The response contains all channels in one array and is not paginated.
Each channel has a currency, a paymentRail and these fields:
| Field | Meaning |
|---|---|
id | The identifier that you send to activate the channel. |
directions | payin: the customer can pay in on this channel. payout: the customer can be paid out on it. A channel has one direction or both. |
status | Whether the customer can use the channel now. See Channel statuses. |
The list can also contain channels on the rail wallet. These channels are for Nodu wallets, which are balances held at Nodu. They are active from the start and need no activation: see Nodu wallet balances and scopes.
The channels a transfer needs
Transfers and quotes require a payin channel for the source. They require a payout channel for the destination.
The flows that you can use depend on your integration agreement with Nodu: see How transfers work.
For example, an EUR/SEPA → USDC/Ethereum transfer needs payin on the EUR/SEPA channel and payout on the USDC/Ethereum channel. For the reverse flow, check the reverse directions; the same currency and rail do not imply both directions are enabled.
Nodu refuses a quote or a transfer in two cases:
- The channel is in the customer's list, but its
statusis notactive. The error is a business rule violation withrule=payment_channel_not_active. - The currency and rail are not in the customer's list for that direction. The error has the status
404and the coderesource_missing.
Channel statuses
status | Meaning | What you do |
|---|---|---|
inactive | The channel is available to the customer, but it is not activated. | Activate the channel if the customer needs it. |
pending | Nodu is setting the channel up. | Wait for the event v1.payment_channel.activated. Do not offer transfers on this channel yet. |
active | The customer can use the channel for quotes and transfers. | Nothing. |
suspended | The customer cannot use the channel at present. | Stop offering new transfers on this channel. See When a channel is suspended. |
Activate a channel
Depending on your integration agreement with Nodu, Nodu automatically activates some channels after approving the customer. List the channels first. Activate only channels whose status is still inactive.
- Check that the customer has
status=active. Otherwise, Nodu refuses the activation withrule=customer_not_active. - Call List payment channels. Find the channel by
currency,paymentRailanddirections. Read itsid. - Call Activate a payment channel with that
id. The request has no body. - Read
statusin the response.pendingmeans that Nodu is still setting up the channel. Wait for the eventv1.payment_channel.activated, or call List payment channels again later.
The response status 202 means that Nodu accepted the request, not that the channel is active. A request for a channel that is not inactive changes nothing: the response returns the channel as it is.
Follow channel changes
Nodu sends a webhook event when a channel changes: v1.payment_channel.pending, v1.payment_channel.activated and v1.payment_channel.suspended. Each event carries the customer and the paymentChannel. Receive and verify webhooks describes the events.
An event is a notification, not the current state. For the current state, call List payment channels.
When a channel is suspended
Nodu sends v1.payment_channel.suspended when a customer can no longer use a channel.
- Nodu refuses new quotes and new transfers that use the channel.
- Existing transfers keep their deposit instructions.
- Activate a payment channel does not change a suspended channel.
- When the channel is usable again, its
statusreturns toactive. Nodu then sends the eventv1.payment_channel.activated.
Channels and deposit instructions
Depending on the source channel, the customer sends money using deposit details assigned to that customer or details for a shared account. With a shared account, each transfer has a payment reference in depositMessage. The customer must include it in the payment.
The channel object does not say which of the two applies. Read sourceDepositInstructions on each transfer.
Next steps
- External accounts and counterparties: register where a transfer pays out.
- Quotes and exchange rates: show the customer the amounts and fees before a transfer.
- Simulate funding in the sandbox: test a transfer on an
activechannel.