--- title: "Submit a payout" method: POST path: "/payouts/v3" tags: ["Manage payouts"] --- # Submit a payout `POST /payouts/v3` ## Request - Base URL: `https://api.dlocal.com` - URL: `https://api.dlocal.com/payouts/v3` - Auth: API key in header `X-Date` and API key in header `X-Version` and API key in header `Authorization` Learn how to start making payouts. --- 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.
ⓘ Country requirements

Depending on each country's bank compliance requirements, some additional fields might be mandatory when sending payouts.
## Request body - SubmitPayoutRequest - `external_id` string, required: Payout identification at the merchant's end. - `payment_method_id` 'BANK_TRANSFER' | 'INSTANT_PAYMENT' | 'CARD' | 'CASH_PICK_UP', required: Payment method. - `flow_type` 'B2C' | 'B2B' | 'P2P', required: Payout flow type. - `country` string, required: Country where the payout will be processed and where the beneficiary's account exists. - `quote_id` string: Quote ID (only when previously created). - `currency` string, required: Payout currency. Each country accepts USD and local currency. - `currency_to_pay` string: Currency in which the payment has to be paid. Local currency assumed if not informed. - `amount` number, required: Payout amount (in the currency set in the `currency_to_pay` field). - `purpose` 'FAMILY_MAINTENANCE' | 'MEDICAL_CARE' | 'TUITION_COSTS' | 'CHARITY_DONATION' | 'PROPERTY_PURCHASE' | 'SHARES' | 'INVESTMENT' | 'UTILITY_PROVIDER' | 'TAXES' | 'TOURISM_EXPENSE' | 'TRAVEL' | 'SAVINGS_RETIREMENT' | 'PENSION' | 'PAYROLL' | 'PHYSICAL_GOODS' | 'DIGITAL_GOODS' | 'SUPPLIER' | 'OTHER_SERVICES' | 'CAPITAL_CONTRIBUTION' | 'PROPERTY_RENTAL' | 'LOGISTICS' | 'INVESTMENT_INTEREST' | 'AVAILABILITY' | 'DISPONIBILIDADES' | 'INSURANCE' | 'REWARDS' | 'ENTERTAINMENT' | 'PUBLIC_SERVICES' | 'AFFILIATION_PROGRAMS' | 'REMITTANCES', required: Payout purpose code. - `statement_descriptor` string: The text to be shown on the user payment statement. - `description` string: Payout description or comments. - `on_hold` boolean: Set to true to create the payout without processing it. The merchant can later request the payout to be processed (release) or canceled (cancel). - `notification_url` string: To be provided if the notification URL is different from the notification URL defined by default. - `beneficiary` object, required: Beneficiary's information. - `first_name` string: Beneficiary's first name. - `last_name` string: Beneficiary's last name. Only applies when the beneficiary is an individual. - `phone` string: Beneficiary's phone number. - `email` string: Beneficiary's email. - `bank_account` object: Beneficiary's bank account information. - `code` string: Beneficiary's bank account code. - `branch` string: Beneficiary's bank account branch. - `type` string: Beneficiary's bank account type. - `account` string: Beneficiary's bank account. - `document` object: Beneficiary's identification document. - `type` string: Beneficiary's document type. - `id` string: Beneficiary's document ID or number. - `birth_info` object: Beneficiary's birth information. - `date` string: Beneficiary's birth date in ISO 8601 format (YYYY-MM-DD). - `country` string: Beneficiary's place of birth (country). ISO 3166-1 alpha-2 code. - `city` string: Beneficiary's city of birth. - `address` object: Beneficiary's address information. - `street` string: Beneficiary's address street. - `number` string: Beneficiary's address street number. - `city` string: Beneficiary's address city. - `state` string: Beneficiary's address state. - `country` string: Beneficiary's address country. ISO 3166-1 alpha-2 code. - `postal_code` string: Beneficiary's address postal code. - `cash_pick_up` object: Cash pick-up information. Required when payment_method_id is "CASH_PICK_UP". Must not be used together with bank_account, instant_payment or card. - `location` string: Cash pick-up location. - `instant_payment` object: Beneficiary's wallet information for instant payment methods (e.g., PIX, mobile wallets). Required when payment_method_id is "INSTANT_PAYMENT". Must not be used together with bank_account or card. - `type` string: Beneficiary's wallet or instant payment type. - `id` string: Beneficiary's wallet id or instant payment identifier. - `card` object: Beneficiary's card information. Required when payment_method_id is "CARD". Must not be used together with bank_account or instant_payment. - `number` string: Beneficiary's card number. - `remitter` Remitter: Remitter information. - `first_name` string: Remitter's first name. - `last_name` string: Remitter's last name. - `nationality` string: Remitter's nationality. ISO 3166-1 alpha-2 code. - `phone` string: Remitter's phone number. - `email` string: Remitter's email. - `funds_source` string: Source of the funds for the remittance. - `document` object: Remitter identification document. - `type` string: Remitter's document type. - `id` string: Remitter's document ID or number. - `issue_date` string: Remitter's document issue date in ISO 8601 format (YYYY-MM-DD). - `expiration_date` string: Remitter's document expiration date in ISO 8601 format (YYYY-MM-DD). - `birth_info` object: Remitter birth information. - `date` string: Remitter's birth date in ISO 8601 format (YYYY-MM-DD). - `country` string: Remitter's place of birth (country). ISO 3166-1 alpha-2 code. - `city` string: Remitter's city of birth. - `address` object: Remitter address information. - `street` string: Remitter's address street. - `number` string: Remitter's address street number. - `city` string: Remitter's address city. - `state` string: Remitter's address state. - `country` string: Remitter's address country. ISO 3166-1 alpha-2 code. - `postal_code` string: Remitter's address postal code. ## Response `200` Payout created - ResponseGetPayout: The standard schema for all Payout responses (Submit, Get, Cancel, Release). - `id` string: Payout ID generated by dLocal - `external_id` string: External ID provided by the merchant - `status` string: Status of the payout (e.g., PENDING, CANCELLED) - `status_code` string: Status code of the payout - `status_detail` string: Detailed status message - `created_date` string, date-time: Creation date of the payout - `last_updated` string, date-time: Last update date of the payout - `payment_method_id` string: Payout method - `flow_type` string: Indicates payout flow - `country` string: Country code of the payout - `currency` string: Currency in which the FX conversion was based on - `currency_to_pay` string: Currency in which the payment was paid - `amount` number: Amount paid out - `purpose` string: Purpose of the payout - `statement_descriptor` string: Statement descriptor - `description` string: Payment description - `on_hold` boolean: Indicates if the payout is on hold - `notification_url` string: Notification callback URL - `amount_details` object: Details about the payout amount (present on GET endpoint) - `amount_to_pay` number: Final amount paid to the beneficiary. - `exchange` object - `source_amount` number: Amount in source currency. - `source_currency` string, ISO-4217 currency code: Source currency. - `destination_amount` number: Amount in destination currency. - `destination_currency` string, ISO-4217 currency code: Destination currency. - `exchange_rate` number: Exchange rate applied. - `fees` Fees - `amount` number: Total fees amount applicable to the transaction. - `currency` string, ISO-4217 currency code: Currency for the total processing fees. - `taxes` Taxes - `amount` number: Total tax amount applicable to the transaction. - `currency` string, ISO-4217 currency code: Currency for the total taxes applied. - `debit` Debit - `amount` number: Total amount that would be debited from the merchant's balance. - `currency` string, ISO-4217 currency code: Currency for the debit to the merchant's balance. - `beneficiary` object: Beneficiary information - `first_name` string: Beneficiary first name. - `last_name` string: Beneficiary last name. Only applies when the beneficiary is an individual. - `phone` string: Beneficiary's phone number. - `email` string: Beneficiary's email. - `bank_account` object: Beneficiary bank account information. - `code` string: Beneficiary's bank account code. - `branch` string: Beneficiary's bank account branch. - `type` string: Beneficiary's bank account type. - `account` string: Beneficiary's bank account. - `document` object: Beneficiary identification document. - `type` string: Beneficiary's document type. Possible values: PASS - Passport, DNI - National ID, RUC, or other values fixed by country. - `id` string: Beneficiary's document ID or number. - `birth_info` object: Beneficiary birth information. - `date` string: Beneficiary's birth date in ISO 8601 format (YYYY-MM-DD). - `country` string: Beneficiary's place of birth (country). ISO 3166-1 alpha-2 code. - `city` string: Beneficiary's city of birth. - `address` object: Beneficiary address information. - `street` string: Beneficiary's address street. - `number` string: Beneficiary's address street number. - `city` string: Beneficiary's address city. - `state` string: Beneficiary's address state. - `country` string: Beneficiary's address country. ISO 3166-1 alpha-2 code. - `postal_code` string: Beneficiary's address postal code. - `remitter` Remitter: Remitter information. - `first_name` string: Remitter's first name. - `last_name` string: Remitter's last name. - `nationality` string: Remitter's nationality. ISO 3166-1 alpha-2 code. - `phone` string: Remitter's phone number. - `email` string: Remitter's email. - `funds_source` string: Source of the funds for the remittance. - `document` object: Remitter identification document. - `type` string: Remitter's document type. - `id` string: Remitter's document ID or number. - `issue_date` string: Remitter's document issue date in ISO 8601 format (YYYY-MM-DD). - `expiration_date` string: Remitter's document expiration date in ISO 8601 format (YYYY-MM-DD). - `birth_info` object: Remitter birth information. - `date` string: Remitter's birth date in ISO 8601 format (YYYY-MM-DD). - `country` string: Remitter's place of birth (country). ISO 3166-1 alpha-2 code. - `city` string: Remitter's city of birth. - `address` object: Remitter address information. - `street` string: Remitter's address street. - `number` string: Remitter's address street number. - `city` string: Remitter's address city. - `state` string: Remitter's address state. - `country` string: Remitter's address country. ISO 3166-1 alpha-2 code. - `postal_code` string: Remitter's address postal code. ## Other responses - `400`: Bad Request - `403`: Forbidden --- [API](https://skmtc.dev/dlocal/apis/payouts-v3.md) - [All operations](https://skmtc.dev/dlocal/apis/payouts-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/dlocal/apis/payouts-v3/revisions/02c74e9e986e?raw)