Create a Payout
Once you're ready to send funds to your users, you can create a payout using the Create Payout endpoint. This guide walks you through the steps of preparing the necessary data and sending a request to our Payout API.
Payout Flow
- Merchant → PagSeguro: Merchant sends a request to create a payout.
- PagSeguro → Notification URL: PagSeguro notifies the merchant once the payout reaches a final status.
Step 1: Gather Required Data
Before you create a payout, make sure you have the following:
- Valid authentication credentials (API key and secret key).
- Payee details: PIX key, PagBank email, or Bank Transfer information, amount, and currency for each payout.
- A unique reference for the payout.
- A notification URL to receive status updates.
You can find the full list of required fields in the Create Payouts endpoint documentation.
Step 2: Submit the Create Payout Request
Send a request to the Create Payout endpoint. Below you find request examples:
{
"reference": "9adade04-4988-4a3f-bf4e-a5cfa3e5debb",
"notification_url": "https://merchant.com/notifications",
"items": [
{
"method": "PIX",
"country": "BR",
"destination": {
"key": "[email protected]"
},
"amount": {
"currency": "BRL",
"value": 50.0
},
"payee": {
"document": {
"type": "CPF",
"value": "00000000191"
},
"name": "Sample User"
},
"reference": "9adade04-4988-4a3f-bf4e-a5cfa3e5debb"
}
]
}
{
"reference": "533eb84b-06d4-46ce-8e77-dcddf674e1f3",
"notification_url": "https://merchant.com/notifications",
"items": [
{
"method": "PAGBANK",
"country": "BR",
"destination": {
"email": "[email protected]"
},
"amount": {
"currency": "BRL",
"value": 50.0
},
"payee": {
"document": {
"type": "CPF",
"value": "00000000191"
},
"name": "Sample User"
},
"reference": "533eb84b-06d4-46ce-8e77-dcddf674e1f3"
}
]
}
{
"reference": "59a4ad98-4c80-498d-9506-9ab4114e726f",
"notification_url": "https://merchant.com/notifications",
"items": [
{
"method": "BANK_TRANSFER",
"country": "BR",
"destination": {
"bank": {
"code": "12345678",
"account": {
"type": "CRN",
"branch": "1234",
"number": "123456"
}
}
},
"amount": {
"currency": "BRL",
"value": 50.0
},
"payee": {
"document": {
"type": "CPF",
"value": "00000000191"
},
"name": "Sample User"
},
"reference": "59a4ad98-4c80-498d-9506-9ab4114e726f"
}
]
}
{
"reference": "d771bed4-b336-4df0-bced-3abf4b1e82a4",
"notification_url": "https://merchant.com/notifications",
"items": [
{
"method": "BANK_TRANSFER",
"country": "CO",
"destination": {
"bank": {
"code": "001",
"account": {
"type": "CRN",
"number": "123456"
}
}
},
"amount": {
"currency": "COP",
"value": 1000
},
"payee": {
"document": {
"type": "CC",
"value": "1234567890"
},
"name": "Sample User"
},
"reference": "d771bed4-b336-4df0-bced-3abf4b1e82a4"
}
]
}
Ensure Unique References
Each payout must have a unique
reference
field for future tracking and reconciliation.
Batch Usage
Batch creation is deprecated in API version 1.0. Use individual item creation flows when possible.
Testing the Payout API
In the sandbox environment, you can simulate different payout failure scenarios by using test destination values listed in the following pages:
Step 3: Handle the API Response
The response will confirm creation and include a reference:
{
"reference": "reference-12345",
"status": "PENDING",
"created_at": "2025-04-23T10:00:00Z"
}
You can use this reference to Search for Payouts.
Step 4: Receive Notifications
PagSeguro will attempt to notify the specified notification_url
when the payout reaches a final status, either SUCCESS
, FAILED
, or REVERSED
. At that point, the status changes to COMPLETED
, and the Payout engine attempts to notify your notification_url
.
A notification is considered successfully received when your endpoint responds with the HTTP status 204
. If any other response code is received, PagSeguro retries the notification up to 7 times using the intervals shown below:
Attempt | Caused by | Retry interval |
---|---|---|
1 | The payout status is changed to COMPLETED , triggering a notification attempt. | After 10 minutes. |
2 | Notification response was not HTTP 204. | After 10 minutes. |
3 | Notification response was not HTTP 204. | After 10 minutes. |
4 | Notification response was not HTTP 204. | After 60 minutes. |
5 | Notification response was not HTTP 204. | After 60 minutes. |
6 | Notification response was not HTTP 204. | After 60 minutes. |
7 | Final attempt. No further retries will be made. | — |
Below is an example notification request:
curl --location --request POST 'https://merchant.com.br/payouts/notifications' \
--header 'Content-Type: application/json' \
--data-raw '{
"notification_type": "payout",
"reference": "reference-20240423-001"
}'
Firewall and allowlist settings
If you use a firewall or allowlists, please note that to receive our notifications, you MUST allowlist the following IPs:
- 54.233.188.209
- 18.228.56.27
Updated about 1 month ago