This is the base method used to request a payout. Please note each country may have its own additional requirements and will have their own payment schedules, see below for more detailed examples.
Request
Response
Request
Body Parameters
login
required
string
Your merchant ID in dLocal platform
- Length 32 chars -
pass
required
string
Your merchant password in dLocal platform
- Length 32 chars -
Payouts metadata in json format
-Length 500 chars-
document_id
optional
string
Beneficiary's personal identification number
-Max. 100 chars-
document_type
optional
string
Beneficiary's personal identification type
-Max. 10 chars-
beneficiary_name
required
string
Beneficiary's name or company
-Max. 100 chars-
beneficiary_lastname
optional
string
Beneficiary's surname
-Max. 100 chars-
country
required
string
The user's country. ISO 3166-1 alpha-2 code
-Length: 2 chars-
bank_code
optional
integer
Beneficiary's bank code. See Bank codes
bank_name
optional
string
Beneficiary's bank name. See bank names
-Max. 40 chars-
bank_province
optional
string
Beneficiary's bank province name
-Max. 40 chars-
bank_city
optional
string
Beneficiary's bank city name
-Max. 40 chars-
bank_branch_name
optional
string
Beneficiary's bank branch name
-Max. 40 chars-
bank_branch
optional
string
Beneficiary's bank branch number
-Max. 45 chars-
bank_account
required
string
Beneficiary's bank account number
-Max. 45 chars-
account_type
optional
string
The type of the account.
C for checking accounts, S for savings accounts, M for Maestra accounts (only Peru)
-Length: 1 chars-
amount
required
number
Payout amount (in the currency entered in the field 'currency')
-Max. 2 decimal numbers-
control
optional
string
Control string.I should be used only if using API version < 2
address
optional
string
Address of the beneficiary
-Max. 200 chars-
birthday
optional
string
Beneficiary's birth date
-Format: 'YYYYMMDD'-
city
optional
string
City of the beneficiary
-Max. 100 chars-
comments
optional
string
A commentary for this payout
-Max. 200 chars-
currency
required
string
Each country accepts USD and local currency.
Default: USD
-Length: 3 chars-
email
optional
string
Email of the beneficiary
-Max. 100 chars-
phone
optional
string
Phone number of the beneficiary
-Max. 20 chars-
extra_info
optional
string
Extra info of the beneficiary in json format
-Max. 500 chars-
notification_url
optional
string
To be provided if the notification URL is different from the notification URL defined by default. See the Notifications section below.
-Max. 100 chars-
on_hold
optional
boolean
If the merchant wants to hold the payout and set it to process later through the merchants panel. This functionality is not available for instant payouts flow such as Nigeria.
Default: 0
-Boolean 1 or 0-
postal_code
optional
string
Postal code of the beneficiary
-Max. 20 chars-
type
optional
string
Response type xml or json.
Default: json
remitter_address
optional
string
Remitter's address
-Max. 200 chars-
remitter_bank_account
optional
string
Remitter's bank account
-Max. 45 chars-
remitter_full_name
optional
string
Remitter's full name
-Max. 200 chars-
remitter_document
optional
string
Remitter's document
-Max. 45 chars-
remitter_city
optional
string
Remitter's bank city name
-Max. 40 chars-
remitter_country
optional
string
The remitter's country. ISO 3166-1 alpha-2 code
-Max. 2 chars-
remitter_postal_code
optional
string
Postal code of the remitter
-Max. 20 chars-
remitter_birth_date
optional
string
Remitter's birthdate
-Format: 'YYYYMMDD'-
purpose
optional
string
Payout purpose code. See the Purpose codes section below.
-Length: 6 chars-
Response
200: OK
Request OK
{
“status”:0,
“cashout_id”:123456,
“desc”:“OK”
}
Depending on each country's bank compliance requirements, some additional fields might be mandatory when sending payouts.
Response
If the status is 0 then the payout was ok submitted.
http code:200
{
"status":0,
"desc":"OK",
"cashout_id":206766
}
If the status is 1 the payout could not be created.
Example 1:
http code:200
{
"status":1,
"desc":"External ID already used",
"error_code":"511",
"cashout_id":206766
}
Example 2:
http code:200
{
"status":1,
"desc":"Empty param login"
"error_code":"301"
}
Country requirements
Please see each country below for specific country requirements and example requests:
x_login and x_trans_key are your credentials. Remember to find them in the Merchant Panel, under the Integration > Credentials & Settings section.
Notifications
Once the transfer is confirmed by the bank, dLocal will send a notification to your merchant notification URL informing you of the result code of the transaction. This URL can be overridden using the notification parameter for individual payout requests, however note this new URL will only be active for that particular payout.
