Skip to main content

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:

FieldMeaning
idThe identifier that you send to activate the channel.
directionspayin: the customer can pay in on this channel. payout: the customer can be paid out on it. A channel has one direction or both.
statusWhether 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 status is not active. The error is a business rule violation with rule=payment_channel_not_active.
  • The currency and rail are not in the customer's list for that direction. The error has the status 404 and the code resource_missing.

Channel statuses​

statusMeaningWhat you do
inactiveThe channel is available to the customer, but it is not activated.Activate the channel if the customer needs it.
pendingNodu is setting the channel up.Wait for the event v1.payment_channel.activated. Do not offer transfers on this channel yet.
activeThe customer can use the channel for quotes and transfers.Nothing.
suspendedThe 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.

  1. Check that the customer has status=active. Otherwise, Nodu refuses the activation with rule=customer_not_active.
  2. Call List payment channels. Find the channel by currency, paymentRail and directions. Read its id.
  3. Call Activate a payment channel with that id. The request has no body.
  4. Read status in the response. pending means that Nodu is still setting up the channel. Wait for the event v1.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 status returns to active. Nodu then sends the event v1.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​