All Dots solutions are available through its API. If you’re a business with a developer team who want full control over the payout process and prefer to use your UI, the white-label approach based on the Dots API is the best option. This page presents a guide with all the steps to create payouts using the Dots API.

​
Requirements

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

  • A Dots account.
  • Created an App.

If you still need to complete one of these steps, access the Getting Started before continuing.

​
1. Create a User

The first step to create a payout is to create a user in Dots. To create a user, you must first capture user information through your system. This will include details such as first name, last name, email, country code, and phone number.

After capturing the user information, you can create a user in Dots using the Create a User endpoint. Following, you will find the list of required parameters:

  • first_name
  • last_name
  • email
  • country_code
  • phone_number

You can add additional information when creating the user or use metadata to provide complementary information that may be useful for your system, such as an internal id. For additional information, see the Metadata documentation page. In addition, you can later update the user account using the Update a User endpoint.

The following code block presents request and response examples of creating a user.

curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/users \
  --header 'Authorization: Basic cGtfZGV2X3lpYXF0aXkwOGdIb3gzR3pvUEo2RlFsaURkSDRnOnNrX2Rldl9nUDBHQjZCd1FmZmt3S2FEVkh0UmdTd0NPT2RNVA==' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Bob",
  "last_name": "Loblaw",
  "email": "bob@bobloblaw.com",
  "country_code": "1",
  "phone_number": "4154332334",
  "metadata": {
    "internal_id": "user_121344"
  }
}'

You will receive the user id in the response upon successful creation.

​
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 the W-9 equivalent form.
  • For foreign payees, you must provide the W8-BEN form.

To submit the compliance information to Dots, use the Submit Compliance Information endpoint. You must inform the user_id, which is the same id received in step 1.

​
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 in the registered phone number used to create their account in step 1. The Send a Verification Token endpoint will return a 202 HTTP response for successful requests.

After sending the verification code, you have to provide a UI for the user to enter the verification code they receive. Capture the code and use the code shared by the user 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. However, Dots doesn’t provide a way to tell you what payout methods are available for a user via the API. Therefore, before performing 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 execute a payout using the default payout method chosen by the user.

To add a default payout method to your user account, use the Create a Flow endpoint to create a Flow with the manage-payouts step. In addition, you must inform the user_id you received in Step 1. The following code block presents request and response examples of creating a Flow with the described configurations.

  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 defined a default payout method, you can proceed to the next step.

​
5. Create a Payout

As the final step, you can now create the payout. There are two options you can use to execute this action:

  • 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 informing 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

If you prefer to execute the process in two steps, first you need to use the Create a Transfer endpoint to transfer funds from your app wallet to the user app wallet. You need to inform the amount and the user_id, which you received in Step 1. The following code block presents request and response examples of creating a transfer.

  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 moving the funds to the user’s wallet, you can create the payout using the Create a Payout endpoint. You must inform the amount, user_id, and platform. For the amount, you can inform a value different from the one used when creating the transfer, however, if the user doesn’t have enough funds the transaction will fail. Regarding 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. The following code block presents request and response examples of creating a payout.

    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 execute the payout in a single step, you need to use the Create a Payout endpoint. You must inform:

  • amount: Inform the payout amount the user will receive.
  • user_id: The user identification 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: It must be set equal 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.

The following code block presents request and response examples of creating a payout.

    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 stay up to date with all updates related to users, transfers, and payouts. To do so, access the Webhooks documentation page in Dots.

If you’re facing errors while using the Dots API, check the complete list of error codes you can receive.