# White Label API Integration - BUY Flow

### Business Integration Manual — Buy Flow

**Prod Environment:** `https://api.coindisco.com`<br>

**Sandbox Environment:** `https://api-staging.coindisco.com`<br>

**API Key Example:** `YOUR_API_KEY`

All requests require your **partner API key** in the header:

```
partner-api-key: YOUR_API_KEY
```

***

## 1. Introduction

This guide explains how to integrate Coindisco’s **White-Label API** to enable a fully branded “Buy Crypto” experience within your own product. The integration allows partners to control user experience, while Coindisco handles provider connections, quotes, and purchase flows behind the scenes.

***

## 2. Flow Overview

The White-Label integration follows a straightforward flow from discovering available providers to completing the transaction with the selected service.

User → Select Region → Select Payment Method → Select Fiat Currency → Select Cryptocurrency → Enter Amount → Get Quotes → Choose Provider → Redirect to Purchase

{% stepper %}
{% step %}

### Provider Discovery

Retrieve and display the list of fiat-to-crypto providers so users can see available onramp providers.
{% endstep %}

{% step %}

### Region Selection

Detect or allow the user to choose their region (you can pre-select using IP or browser settings).
{% endstep %}

{% step %}

### Payment Method Selection

Show available payment methods for the selected region (e.g., card, bank transfer, Apple Pay).
{% endstep %}

{% step %}

### Currency and Crypto Selection

Display available fiat currencies and cryptocurrencies (and networks) for the user to choose.
{% endstep %}

{% step %}

### Quote Request

Request quotes to calculate estimated crypto amount and applicable fees.
{% endstep %}

{% step %}

### Offer Comparison

Present provider offers so users can choose the best option (compare fees, crypto amount, KYC requirements, etc.).
{% endstep %}

{% step %}

### Purchase Redirect

Generate a buy link and redirect the user to the provider to complete payment.
{% endstep %}
{% endstepper %}

***

## 3. Detailed Integration Flow

Each step below explains the **business logic** followed by the **API request** required to implement it.

{% stepper %}
{% step %}

### Retrieve Active Providers

Partners begin by fetching a list of currently active fiat-to-crypto providers supported by Coindisco. Display this list in your UI to allow users to see available onramp providers.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/active-providers/' --header 'partner-api-key: YOUR_API_KEY'
```

Response example:

```bash
[
    {
       "id": 1, // service_id
       "name": "MoonPay", // service name
       "slug_name": "moonpay", // service slug name
       "icon": "https://api-staging.coindisco.com/media/service_integration/Service/moonpay.png",
       "url_for_transaction_details": "https://buy-sandbox.moonpay.com/transaction_receipt?transactionId=", // service transaction details
       "url_for_support": "https://support.moonpay.com/hc/en-gb/requests/new", // service support link
       "domain": "buy.moonpay.io", // service domain
       "privacy": "https://www.moonpay.com/legal/privacy_policy", // service privacy page
       "terms": "https://www.moonpay.com/legal/terms_of_use", // service terms page
       "sell_available": true // service sell available
   }
]
```

{% endstep %}

{% step %}

### Retrieve Available Regions

Use this endpoint to display or automatically detect the user’s region. You can pre-select the region using the user’s IP or browser settings.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/regions/' --header 'partner-api-key: YOUR_API_KEY'
```

Response example:

```bash
[
   {
       "id": 264, // region id
       "letter_id": "aland-islands", // unique code
       "kind": "country", // region kind
       "name": "Åland Islands", // region name
       "alpha2_code": "AX", // ISO 3166-1 code for countries
       "alpha3_code": "ALA", // ISO 3166-1 code for countries
       "icon": "https://api-staging.coindisco.com/media/service_integration/Region/AX.png", // icon
       "parent_region": null, // parent region
       "child_exists": false, // nested regions exists
       "default": false, // is default
       "states": [] // nested regions
   }
]
```

{% endstep %}

{% step %}

### Retrieve Payment Methods

Once the region is known, retrieve payment methods available in that region. Optionally, filter methods by a specific provider using `service_id`.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/regions/{{region_id}}/payment-methods/?service_id={{service_id}}' --header 'partner-api-key: YOUR_API_KEY'
```

Display these methods to the user (e.g., card, bank transfer, Apple Pay).

Response example:

```bash
[
   {
       "id": 147, // payment method id
       "letter_id": "bank_transfer", // payment method unique alphabetical code
       "code": "bank_transfer", // payment method code
       "name": "Bank Transfer", // payment method name
       "icon": "https://api-staging.coindisco.com/media/service_integration/PaymentMethod/bank_transfer.png",
       "sell_available": true // is payment method available for sell
   }
]
```

{% endstep %}

{% step %}

### Retrieve Fiat Currencies

Get the list of supported fiat currencies for the selected region and provider. This determines what base currencies (USD, EUR, GBP, etc.) the user can use.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/regions/{{region_id}}/currencies/?service_id={{service_id}}' --header 'partner-api-key: YOUR_API_KEY'
```

Response example:

```bash
[
   {
       "id": 1,
       "name": "EUR",
       "symbol": "€",
       "icon": "https://api-staging.coindisco.com/media/currencies/icons/EUR.png",
       "is_popular": true,
       "full_name": "Euro",
       "rate": 0.8574000865,
       "default": false
   }
]
```

{% endstep %}

{% step %}

### Retrieve Cryptocurrencies

Fetch the list of cryptocurrencies available for purchase and their supported networks. Display them as user options in your Buy screen.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/cryptocurrency/?service_id={{service_id}}' --header 'partner-api-key: YOUR_API_KEY'
```

Response example:

```bash
{
   "next": "https://api-staging.coindisco.com/api/white-label/v1/cryptocurrency/?cursor=cD0xMA==&favorites=false&ordering=rank&service_id=1", // link for the next page
   "previous": null, // link for the prev page
   "results": [
       {
            "id": 1, // cryptocurrency id
            "letter_id": "bitcoin", // cryptocurrency unique alphabetical code
            "name": "Bitcoin", // cryptocurrency name
            "symbol": "BTC", // cryptocurrency symbol
            "code": "btc", // cryptocurrency code
            "rank": 1, // cryptocurrency rank
            "logo": "https://s3.amazonaws.com/cdn-staging.coindisco.com/currencies/logo/btc_bitcoin.png",
            "issuer": null, // cryptocurrency issuer or smart contract
            "home_domain": null, // cryptocurrency home domain
            "networks": [] // available networks
        }
    ]
}
```

{% endstep %}

{% step %}

### Request Buy Quotes

Once the user selects all parameters (region, payment method, currency, crypto, amount), request a quote to calculate estimated crypto amount and fees.

Case A — User Selected a Specific Provider

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/search-buy-quotes/' --header 'partner-api-key: YOUR_API_KEY' --header 'Content-Type: application/json' --data '{
  "service": 23,
  "region": 156,
  "payment_method": 27,
  "cryptocurrency": 5,
  "currency": 3,
  "network": 26,
  "currency_amount": 400
}'
```

Case B — Without Provider Preselection

If no provider is chosen, Coindisco searches across all connected providers and returns a `search_id` to poll for results.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/search-buy-quotes/' --header 'partner-api-key: YOUR_API_KEY' --header 'Content-Type: application/json' --data '{
  "region": 156,
  "payment_method": 27,
  "cryptocurrency": 5,
  "currency": 3,
  "network": 26,
  "currency_amount": 400
}'
```

Response example:

```json
{ "search_id": "7e038ab6-3c65-41cb-a364-2d47471b00de" }
```

{% endstep %}

{% step %}

### Retrieve Search Results and Display Offers

Poll for search results every few seconds using the `search_id`. When the status becomes `completed`, present the list of available offers to the user for comparison.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/search-buy-quotes/{{search_id}}/' --header 'partner-api-key: YOUR_API_KEY' --header 'Content-Type: application/json'
```

Response example:

```json
{
  "status": "completed",
  "data": [
    {
      "cryptocurrency_amount": "392.2",
      "total_fee": "7.8",
      "service": { "id": 16, "name": "Banxa" }
    },
    {
      "cryptocurrency_amount": "380.98",
      "total_fee": "18.96",
      "service": { "id": 6, "name": "Transak" }
    }
  ]
}
```

Each offer includes details about provider, total amount, fee, and whether KYC is required.
{% endstep %}

{% step %}

### Generate the Purchase Link

Once the user chooses a provider, request a buy link to redirect them to the provider’s payment flow. You must include all previously selected parameters in the request.

```bash
curl --location 'https://api.coindisco.com/api/white-label/v1/retrieve-buy-link/' --header 'partner-api-key: YOUR_API_KEY' --header 'Content-Type: application/json' --data '{
  "service": 1,
  "wallet_address": "0x8a3D3eA3E8AEb9E5eF2Ba0cE1e695D8A17ad5fA2",
  "region": 156,
  "payment_method": 27,
  "cryptocurrency": 5,
  "currency": 3,
  "network": 26,
  "currency_amount": 400
}'
```

Response example:

```json
{
  "link": "https://buy.moonpay.io/?paymentMethod=credit_debit_card&apiKey=YOUR_API_KEY&currencyCode=USDC_POLYGON...",
  "transaction_id": "638a68f8-111d-4d0c-b6ab-da6a805c419f"
}
```

Redirect the user to this link to complete the transaction.
{% endstep %}
{% endstepper %}

***

## 4. End-to-End Example

Scenario: A user from the United States wants to buy 400 USD worth of USDC using a debit card.

{% stepper %}
{% step %}

### Display Providers

Call `/active-providers/` to display available providers.
{% endstep %}

{% step %}

### Determine Region

Retrieve region ID for the U.S. via `/regions/`.
{% endstep %}

{% step %}

### Get Payment Methods

Get payment methods (e.g., debit card).
{% endstep %}

{% step %}

### Fetch Currencies and Cryptos

Fetch supported fiat currencies (USD) and cryptos (USDC).
{% endstep %}

{% step %}

### Request a Quote

Request a quote for $400.
{% endstep %}

{% step %}

### Show Provider Offers

Display provider offers with fees and estimated crypto amount.
{% endstep %}

{% step %}

### Generate Buy Link

Generate buy link for the selected provider (e.g., MoonPay).
{% endstep %}

{% step %}

### Redirect to Provider

Redirect user to complete payment securely on provider’s site.
{% endstep %}
{% endstepper %}

***

## 5. Best Practices

* Always validate user inputs before calling API.
* Cache provider and region data for faster UI loading.
* Detect region automatically when possible.
* Poll quote results until `status = completed`.
* Use official provider URLs only — never construct links manually.
* For production, ensure secure key storage and HTTPS communication.

***

## 6. Summary of Endpoints

<table><thead><tr><th width="65">#</th><th>Purpose</th><th width="375">Endpoint</th><th>Method</th></tr></thead><tbody><tr><td>1</td><td>Get active providers</td><td><code>/api/white-label/v1/active-providers/</code></td><td>GET</td></tr><tr><td>2</td><td>Get regions</td><td><code>/api/white-label/v1/regions/</code></td><td>GET</td></tr><tr><td>3</td><td>Get payment methods</td><td><code>/api/white-label/v1/regions/{region_id}/payment-methods/</code></td><td>GET</td></tr><tr><td>4</td><td>Get currencies</td><td><code>/api/white-label/v1/regions/{region_id}/currencies/</code></td><td>GET</td></tr><tr><td>5</td><td>Get cryptocurrencies</td><td><code>/api/white-label/v1/cryptocurrency/</code></td><td>GET</td></tr><tr><td>6</td><td>Search buy quotes</td><td><code>/api/white-label/v1/search-buy-quotes/</code></td><td>POST</td></tr><tr><td>7</td><td>Retrieve search results</td><td><code>/api/white-label/v1/search-buy-quotes/{search_id}/</code></td><td>GET</td></tr><tr><td>8</td><td>Retrieve buy link</td><td><code>/api/white-label/v1/retrieve-buy-link/</code></td><td>POST</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coindisco.gitbook.io/coindisco/api-integration/white-label-api-integration-buy-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.