Documentation

Create a Payout

Suggest Edits

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

  1. Merchant → PagSeguro: Merchant sends a request to create a payout.
  2. 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:

AttemptCaused byRetry interval
1The payout status is changed to COMPLETED, triggering a notification attempt.After 10 minutes.
2Notification response was not HTTP 204.After 10 minutes.
3Notification response was not HTTP 204.After 10 minutes.
4Notification response was not HTTP 204.After 60 minutes.
5Notification response was not HTTP 204.After 60 minutes.
6Notification response was not HTTP 204.After 60 minutes.
7Final 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 2 months ago