Skip to main content
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 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 page for details. You can also update the user later using the Update a User endpoint. Request and response examples: 
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"
  }
}'
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 endpoint. You must provide the user_id, which is the same id received in step 1.
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).

​
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 endpoint. The user will receive a verification code at their registered phone number. The 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 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 endpoint to create a Flow with the manage-payouts step. You must provide the user_id you received in Step 1. Request and response examples: 
  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"
  }'
From the response, use the link to embed the Flow into an iframe within your application or redirect the user.
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.
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: 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: 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 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. Request and response examples: 
  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"
    }'
After transferring the funds to the user’s wallet, you can create the payout using the 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 endpoint. Request and response examples: 
    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"
    }'

​
Single Step

To create the payout in a single step, use the 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.
  • 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: 
    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
    }'

​
What’s Next?

You can configure webhooks to receive updates about users, transfers, and payouts. See the Webhooks page for details. If you’re facing errors while using the Dots API, check the complete list of error codes you can receive.