Search Payouts

Once a payout is created, you can check the status of each individual payout using the Get Payout endpoint. This guide walks you through how the notification process works and how to retrieve item-level payout results using the payout reference.

Flow

PagSeguro → Merchant: PagSeguro notifies the merchant that a payout has reached a terminal status (SUCCESS, FAILED, or REVERSED).
Merchant → PagSeguro: The merchant uses the reference from the notification to query item-level results using the Search Payouts endpoint.
PagSeguro → Merchant: PagSeguro responds with item status codes, reasons, and payout metadata.

Step 1: Receiving the Notification

When a payout reaches the status COMPLETED, PagSeguro sends a POST request to your configured notification_url, as described in the Create a Payout guide.

{
  "notification_type": "payout",
  "reference": "e65ccb86-a917-445a-9abc-b7c72ea16e10"
}

Step 2: Querying the Payout Item

With the reference received in the notification, you can request the details of individual payouts using the Get Payouts endpoint. The following code block shows an example of response:

{
   "result":[
      {
         "reference":"29cfcb4b-4570-4ac3-bbdd-a3b6e5843ed6",
         "amount":{
            "value":10,
            "currency":"BRL"
         },
         "country":"BR",
         "method":"PIX",
         "destination":{
            "key":"[email protected]",
            "amount":{
               "value":10,
               "currency":"BRL"
            }
         },
         "reversals":[
            
         ],
         "status":{
            "code":"SUCCESS",
            "reason":""
         },
         "exchange":{
            "base":"BRL",
            "rate":1
         },
         "created_at":"2025-06-23T14:01:04.000000Z",
         "updated_at":"2025-06-23T14:01:07.000000Z"
      }
   ],
   "pagination":{
      "total_items":1,
      "total_pages":1
   }
}

{
   "result":[
      {
         "reference":"e6a4d36b-e51a-4e6d-897c-b718d7430f38",
         "amount":{
            "value":10,
            "currency":"BRL"
         },
         "country":"BR",
         "method":"PAGBANK",
         "destination":{
            "email":"[email protected]",
            "amount":{
               "value":10,
               "currency":"BRL"
            }
         },
         "reversals":[
            
         ],
         "status":{
            "code":"SUCCESS",
            "reason":""
         },
         "exchange":{
            "base":"BRL",
            "rate":1
         },
         "created_at":"2025-06-23T14:01:04.000000Z",
         "updated_at":"2025-06-23T14:01:07.000000Z"
      }
   ],
   "pagination":{
      "total_items":1,
      "total_pages":1
   }
}

{
   "result":[
      {
         "reference":"c662d89c-e5c8-46ab-be44-f837e455f75b",
         "amount":{
            "value":10,
            "currency":"BRL"
         },
         "country":"BR",
         "method":"BANK_TRANSFER",
         "destination":{
            "bank":{
               "code":"001",
               "account":{
                  "type":"CRN",
                  "number":"123456"
               }
            },
            "amount":{
               "value":10,
               "currency":"BRL"
            }
         },
         "reversals":[
            
         ],
         "status":{
            "code":"SUCCESS",
            "reason":""
         },
         "exchange":{
            "base":"BRL",
            "rate":1
         },
         "created_at":"2025-06-23T14:01:04.000000Z",
         "updated_at":"2025-06-23T14:01:07.000000Z"
      }
   ],
   "pagination":{
      "total_items":1,
      "total_pages":1
   }
}

{
   "result":[
      {
         "reference":"f86ae7d3-2147-4296-aa27-a4eebec7db51",
         "amount":{
            "value":1000,
            "currency":"COP"
         },
         "country":"CO",
         "method":"BANK_TRANSFER",
         "destination":{
            "bank":{
               "code":"001",
               "account":{
                  "type":"CRN",
                  "number":"123456"
               }
            },
            "amount":{
               "value":1000,
               "currency":"COP"
            }
         },
         "reversals":[
            
         ],
         "status":{
            "code":"SUCCESS",
            "reason":""
         },
         "exchange":{
            "base":"COP",
            "rate":1
         },
         "created_at":"2025-06-23T14:01:04.000000Z",
         "updated_at":"2025-06-23T14:01:07.000000Z"
      }
   ],
   "pagination":{
      "total_items":1,
      "total_pages":1
   }
}

📘
This endpoint is available in the sandbox environment for testing. Use references created via sandbox payout requests.