> ## Documentation Index
> Fetch the complete documentation index at: https://dotsdev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# White-Labeled Payouts

White-labeled payouts give you complete control over the payout experience within your own application. By integrating directly with the Dots API, you can create a fully branded payout flow that minimizes payee friction and keeps users within your ecosystem.

This approach is ideal for businesses with developer teams who want to:

* Maintain full branding and user experience control
* Collect user information through their own UI
* Minimize direct payee interactions with Dots
* Customize the payout flow to match their product

This guide walks through the end-to-end implementation steps for creating white-labeled payouts using the Dots API.

## Requirements

Before creating a payout using the Dots API, you must have:

* A Dots developer dashboard account.
* An App that has been approved.

## 1. Create a User

The first step is to create a user. You must first capture user information through your system, including first name, last name, email, country code, and phone number.

After capturing the user information, you can create a user using the [Create a User](/apireference/users/create-a-user) endpoint. The required parameters are:

* `first_name`
* `last_name`
* `email`
* `country_code`
* `phone_number`

You can add additional information when creating the user or use metadata to store custom data, such as an internal `id`. See the [Metadata](/references/metadata) page for details. You can also update the user later using the [Update a User](/apireference/users/update-a-user) endpoint.

Request and response examples:

<CodeGroup>
  ```sh Request theme={null}
  curl --request POST \
    --url https://pls.senddotssandbox.com/api/v2/users \
    --header 'Authorization: Basic cGtfZGV2X3lpYXF0aXkwOGdIb3gzR3pvUEo2RlFsaURkSDRnOnNrX2Rldl9nUDBHQjZCd1FmZmt3S2FEVkh0UmdTd0NPT2RNVA==' \
    --header 'Content-Type: application/json' \
    --data '{
    "first_name": "Yizhuo",
    "last_name": "Ning",
    "email": "sample@dots.dev",
    "country_code": "86",
    "phone_number": "12345678901",
    "metadata": {
      "internal_id": "user_121344"
    }
  }'
  ```

  ```json Response theme={null}
  {
    "email": "sample@dots.dev",
    "first_name": "Yizhuo",
    "id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
    "last_name": "Ning",
    "metadata": {
      "internal_id": "user_121344"
    },
    "phone_number": {
      "country_code": "86",
      "phone_number": "12345678901"
    },
    "status": "unverified",
    "verified": false
  }
  ```
</CodeGroup>

The response includes the user `id`.

## 2. Submit Compliance Information

Depending on the user's location, you may need to capture and submit their compliance information:

* For users based in the United States, you must provide W-9 information.
* For international users, you must provide W-8BEN information.

To submit the compliance information to Dots, use the [Submit Compliance Information](/apireference/users/submit-compliance-information) endpoint. You must provide the `user_id`, which is the same `id` received in step 1.

<Note>
  While this step is not strictly required in all cases, we strongly recommend providing compliance information upfront to reduce your integration complexity and facilitate a frictionless, white-labeled payout experience. If this information is not provided upfront, it will need to be collected later if a user triggers a condition that requires collection (e.g., if a U.S.-based user exceeds the annual 1099 threshold for payouts).
</Note>

## 3. Verify the User

Next, you need to verify the user. First, send a verification code to the user's phone using the [Send a Verification Token](/apireference/users/send-a-verification-token) endpoint. The user will receive a verification code at their registered phone number. The [Send a Verification Token](/apireference/users/send-a-verification-token) endpoint will return a 202 HTTP response for successful requests.

After sending the verification code, you must provide a UI for the user to enter the verification code. Capture the code the user enters and use it to verify their account using the [Verify a User](/apireference/users/verify-a-user) endpoint. Successful requests will return a 200 HTTP response.

## 4. Add a Default Payout Method

To enable users to withdraw their transferred funds, they should set a default payout method. The API doesn't provide a way to determine which payout methods are available for a user to add based on their location. Therefore, before creating the first payout, you should use a Flow to enable the user to set a default payout method. Then you can use the API to create a payout using the default payout method chosen by the user.

To add a default payout method to the user's account, use the [Create a Flow](/apireference/flows/create-a-flow) endpoint to create a Flow with the `manage-payouts` step. You must provide the `user_id` you received in [Step 1](#1-create-a-user). Request and response examples:

<CodeGroup>
  ```sh Request theme={null}
    curl --request POST \
      --url https://pls.senddotssandbox.com/api/v2/flows/ \
      --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
      --header 'Content-Type: application/json' \
      --data '{
      "steps": [
        "manage-payouts"
      ],
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4"
    }'
  ```

  ```json Response theme={null}
    {
      "completed_steps": [],
      "created": "2024-07-30T13:19:09.438268",
      "id": "17f357c1-7f4d-4101-a2c0-8cb9c9947ac8",
      "link": "https://my-sandbox.dots.dev/flow/17f357c1-7f4d-4101-a2c0-8cb9c9947ac8",
      "metadata": null,
      "payout_link_id": null,
      "steps": [
        "manage-payouts"
      ],
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4"
    }
  ```
</CodeGroup>

From the response, use the `link` to embed the Flow into an iframe within your application or redirect the user.

<Note>
  To start the Flow, Dots will send a verification code to the user's phone to confirm their identity. Once verified, all available payout methods will be displayed. The user can then select their preferred payout method and provide the necessary information. At the end of the process, there is an option to set this as the default payment method, which is selected by default. If the user has a default payout method in their account, funds can be transferred automatically using this method.
</Note>

After the user has set a default payout method, you can proceed to the next step.

## 5. Create a Payout

You can create the payout using one of two methods:

* [Two Steps](#two-steps): Create a transfer from the app wallet to a user wallet, and then create a payout from the user wallet using the default payment method.
* [Single Step](#single-step): Create a payout with `fund: true` to transfer the funds from the app wallet to the user wallet and automatically create a payout from the user wallet using the default payment method.

### Two Steps

For a two-step process, first use the [Create a Transfer](/apireference/transfers/create-a-transfer) endpoint to transfer funds from your app wallet to the user's wallet. You need to provide the `amount` and the `user_id` you received in [Step 1](#1-create-a-user). Request and response examples:

<CodeGroup>
  ```sh Request theme={null}
    curl --request POST \
      --url https://api.dots.dev/api/v2/transfers  \
      --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
      --header 'Content-Type: application/json' \
        --data '{
        "amount": -1000,
        "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4"
      }'
  ```

  ```json Response theme={null}
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
      "status": "created",
      "type": "refill",
      "amount": 1000,
      "external_data": {
        "account_id": "<string>",
        "external_id": "<string>",
        "platform": "ach"
      },
      "transactions": [
        {
          "id": 123,
          "amount": 1000,
          "created": "2023-11-07T05:31:56Z",
          "source_name": "<string>",
          "destination_name": "<string>",
          "type": "balance",
          "metadata": "<string>"
        }
      ],
    }
  ```
</CodeGroup>

After transferring the funds to the user's wallet, you can create the payout using the [Create a Payout](/apireference/payouts/create-a-payout) endpoint. You must provide the `amount`, `user_id`, and `platform`. For the `amount`, you can specify a different value than the one used when creating the transfer. However, if the user doesn't have enough funds, the transaction will fail. For the `platform`, if the user has a default payout method, you can set `platform: default`. If the user hasn't defined a default payout method, you must collect their preferences and payout information and include the information in the request to the [Create a Payout](/apireference/payouts/create-a-payout) endpoint. Request and response examples:

<CodeGroup>
  ```sh Request theme={null}
      curl --request POST \
        --url https://api.dots.dev/api/v2/payouts \
        --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
        --header 'Content-Type: application/json' \
        --data '{
        "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
        "amount": 1000,
        "platform": "default"
      }'
  ```

  ```json Response theme={null}
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
      "status": "created",
      "type": "refill",
      "amount": 1000,
      "external_data": {
        "account_id": "<string>",
        "external_id": "<string>",
        "platform": "ach"
      },
      "transactions": [
        {
          "id": 123,
          "amount": 1000,
          "created": "2023-11-07T05:31:56Z",
          "source_name": "<string>",
          "destination_name": "<string>",
          "type": "balance",
          "metadata": "<string>"
        }
      ],
    }
  ```
</CodeGroup>

### Single Step

To create the payout in a single step, use the [Create a Payout](/apireference/payouts/create-a-payout) endpoint. Provide the following parameters:

* `amount`: The payout amount the user will receive.
* `user_id`: The user ID you received in [Step 1](#1-create-a-user).
* `platform`: If the user has a default payout method, you can set `platform: default`. If the user hasn't defined a default payout method, you must collect their preferences and payout information.
* `fund`: Set to `true` to enable Dots to create a transfer for the amount to the user before creating the payout. The funds are returned if the payout does not succeed.

Request and response examples:

<CodeGroup>
  ```sh Request theme={null}
      curl --request POST \
        --url https://api.dots.dev/api/v2/payouts \
        --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
        --header 'Content-Type: application/json' \
        --data '{
        "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
        "amount": 1000,
        "platform": "default",
        "fund": true
      }'
  ```

  ```json Response theme={null}
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
      "status": "created",
      "type": "refill",
      "amount": 1000,
      "external_data": {
        "account_id": "<string>",
        "external_id": "<string>",
        "platform": "ach"
      },
      "transactions": [
        {
          "id": 123,
          "amount": 1000,
          "created": "2023-11-07T05:31:56Z",
          "source_name": "<string>",
          "destination_name": "<string>",
          "type": "balance",
          "metadata": "<string>"
        }
      ],
    }
  ```
</CodeGroup>

## What's Next?

You can configure webhooks to receive updates about users, transfers, and payouts. See the [Webhooks](/references/webhooks) page for details.

If you're facing errors while using the Dots API, check the complete list of [error codes](/references/error-codes) you can receive.