Skip to main content

Channels

Overview​

Channels represent a payment route with specific characteristics for processing transactions.

A Channel can be seen as a type of contract where the details are fixed, including fees and transaction limits.

Each Channel is defined by:

  • Country
  • Fiat Currency
  • Payment Method Type

Important note: the Country code XX is used for Channels with multiple compatible countries, these Channels are available internationally.

Using Channels​

Get Available Countries​

To retrieve the list of supported countries and their available fiat currencies, use the GET /channels/sell/countries endpoint in the Business API.

curl -L 'https://api.sandbox.noah.com/v1/channels/sell/countries' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>'

Get Available Channels​

Query available channels for a specific country or currency:

To retrieve the list of available channels for a specific country or currency, use the GET /channels/sell endpoint in the Business API.

curl -L 'https://api.sandbox.noah.com/v1/channels/sell
        ?Country=GB // Provide country (optional if currency is specified)
        &CryptoCurrency=USDC_TEST
        &FiatCurrency=EUR // Provide currency (optional if country is specified)
        &FiatAmount=1000' // Optional - includes price calculation \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>'
tip

For details on the USDC_TEST token, used above, see Sandbox Testnet Currencies.

For each channel returned by the call above, the response body is as follows.

{
  "Calculated": {
    "TotalFee": "2"
  },
  "Country": "DE",
  "FiatCurrency": "EUR",
  "FormSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "BankDetails": {
        "properties": {
          "AccountType": {
            "enum": [
              "Checking",
              "Savings"
            ],
            "title": "Account Type",
            "type": "string"
          },
          "AccountNumber": {
            "maxLength": 22,
            "minLength": 22,
            "pattern": "^DE[0-9]{2}[A-Z0-9]{18}$",
            "title": "IBAN",
            "type": "string"
          }
        },
        "required": [
          "AccountType",
          "AccountNumber"
        ],
        "title": "Bank Details",
        "type": "object"
      }
    },
    "required": [
      "BankDetails"
    ]
  },
  "ID": "ebb9736b-08b3-599d-886b-10ee8aea82b5",
  "Limits": {
    "MinLimit": "1"
  },
  "PaymentMethodCategory": "Bank",
  "PaymentMethodType": "BankSepa",
  "ProcessingSeconds": 60,
  "Rate": "0.86"
}
tip

Looking at the above payload, consider the following when you select a channel.

  • Transaction limits (Limits object).
  • Processing time (ProcessingSeconds).
  • Payment method requirements, some channels may require a Dynamic Form to submit a transaction.

Get Dynamic Forms​

You can retrieve the required form fields for a given channel through two means:

  1. Directly from the Supported Channels Endpoint. When you query available channels using the GET /channels/sell endpoint, the response includes the form schema needed for the selected payment method, as shown above. This method simplifies the process by reducing the number of API calls.

  2. Using the Dynamic Form Endpoint. After selecting a channel, you can retrieve the required form fields by calling the GET /channels/:ChannelID/form endpoint. This endpoint provides a JSON Form schema specifying the required fields for the selected payment method.

Code Example​

Basic channel retrieval and selection:

// 1. Get available countries
const countries = await api.get('/v1/channels/sell/countries');

// 2. Get channels for selected country
const channels = await api.get('/v1/channels/sell', {
  params: {
    Country: 'GB',
    CryptoCurrency: 'BTC',
    FiatCurrency: 'GBP',
    FiatAmount: '1000',
    PageSize: 20,
  },
});

// 3. Get form schema for selected channel
const formSchema = await api.get(`/channels/${channelId}/form`);
tip

Best Practice 1: Regular Updates

  • Query the available payment channels immediately before displaying them to end users.
  • Avoid relying on stale or cached data for prolonged periods—channels and their limits (e.g., max/min transaction amounts) can change frequently.

Best Practice 2: Error Handling

  • Handle channel disablement gracefully, by attempting to retrieve an equivalent channel.
  • Validate transaction amounts against channel limits, before allowing a customer to select a channel.
  • Verify all required form fields are available, before allowing a customer to select a channel.

Best Practice 3: Performance

  • Implement pagination or filtering when listing multiple channels to reduce payload size and improve response times.
  • If pricing calculations are required, pass any needed parameters (like FiatAmount) in the API request.