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​

List Available Countries​

Retrieve supported countries and their available fiat currencies:

GET /v1/channels/sell/countries

// Response example
{
  "GB": ["GBP", "EUR"],
  "US": ["USD"],
  "SG": ["SGD"]
}

Get Available Channels​

Query available channels for a specific country or currency:

GET /v1/channels/sell
  ?Country=GB // Provide country (optional if currency is specified)
  ?CryptoCurrency=BTC
  ?FiatCurrency=GBP // Provide currency (optional if country is specified)
  ?FiatAmount=1000  // Optional - includes price calculation

Channel Selection​

When selecting a channel, consider:

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

Dynamic Forms​

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

  1. Directly from the /v1/channels/sell Response:

    • When you query available channels using the /v1/channels/sell endpoint, the response includes the form schema needed for the selected payment method. This method simplifies the process by reducing the number of API calls.

  2. Using the /channels/{channelID}/form Endpoint:

    • After selecting a channel, you can retrieve the required form fields by calling the specific form endpoint:
    GET / channels / { channelID } / form;

    This endpoint provides a JSONForm schema specifying the required fields for the selected payment method.

Best Practices​

  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

  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

  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

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`);
  • Dynamic Forms
    Retrieve and display a channel's required payment details dynamically.
  • Payment Methods
    Understand the various fiat and crypto payment methods supported across different channels.
  • Webhook Configuration
    Set up notifications to receive updates on transactional activity.
  • Request Signing
    Ensure your API requests are secure in production.