Create a Mass Payout
Mass Payout lets you send up to 10,000 payments at once by uploading a properly formatted CSV file.
This feature supports payouts to Brazilian accounts (BR) in BRL currency, using either PagBank or Pix as payment methods.
Required Fields
To use the Mass Payout, your CSV file must have the fields described in the following table:
| Field | Accepted Values | Description |
|---|---|---|
| country | BR | Destination country (ISO 3166). |
| currency | BRL | Payment currency (ISO 4217). |
| amount | 0.01 to 20,000.00 | Transfer amount per payee. |
| paymentMethod | Pix or PagBank | Payment method. |
| paymentKey | See Payment Key Rules | Unique identifier for payee (key type varies by method). |
| payeeName | String (max 64 characters) | Recipient’s full name. |
| payeeDocumentType | CPF or CNPJ | Document type (individual or legal entity). |
| payeeDocumentValue | CPF: 11 digits CNPJ: 14 digits | Recipient’s document number. |
Step 1: Prepare Your CSV File
Your CSV file must:
- Use semicolon (;) as the field separator.
- Have one payment per line.
- Include a header row in the following order:
country;currency;amount;paymentMethod;paymentKey;payeeName;payeeDocumentType;payeeDocumentValue
Use a dot (.) as the decimal separator for the
amountfield.
The following code blocks shows an example of CSV file.
country;currency;amount;paymentMethod;paymentKey;payeeName;payeeDocumentType;payeeDocumentValue
BR;BRL;250.00;Pix;12345678901;Maria da Silva;CPF;12345678901
BR;BRL;1250.55;PagBank;[email protected];João Souza;CPF;98765432100
Step 2: Choose the Correct Payment Key
If using PagBank, the paymentKey must be the payee's email registered in PagBank.
| Key Type | Format | Example |
|---|---|---|
| Valid email | [email protected] |
If using Pix, the paymentKey can be one of the following:
| Key Type | Format (Regex) | Example |
|---|---|---|
| CPF | ^[0-9]{11}$ | 12345678901 |
| CNPJ | ^[0-9]{14}$ | 12345678901234 |
| Phone | ^\+[1-9][0-9]\d{1,14}$Country code required | +5511998765432 |
^[a-z0-9.!#$&'*+/=?^_{|}~-]+@[a-z0-9?(?:.a-z0-9?)]*$` | [email protected] | |
| Random | [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} | 123e4567-e89b-12d3-a456-426655440000 |
Country Code Required for Phone Pix Keys
Always include the international dialing code (e.g.,
+55for Brazil).
Step 3: Upload Your CSV File
- Log in to your PagSeguro MyAccount.
- Navigate to the Mass payout request section.
- Upload the CSV file.
- Confirm the details and click Create a New Mass Request.
Updated 5 days ago