Requirements
Before creating a payout using Dots API, you must have:- A Dots account.
- Created an App.
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
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.
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.
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 themanage-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.
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.
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 theamount
and the user_id
, which you received in Step 1. The following code block presents request and response examples of creating a transfer.
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.
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 setplatform: 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 totrue
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.