Each payout request submitted to the Payout API results in an item with a specific status, which reflects the current state of the payout process. These statuses help you track payout processing, understand failure reasons, and determine if a retry is possible.
These statuses are essential for tracking the delivery of funds, diagnosing failures, and triggering retries or reconciliation workflows in your system.
The
statusfield indicates the current state of the payout, such as whether it’s still being processed, was successfully delivered, or failed due to an issue. This value may change over time as the payout moves through its lifecycle.
Payout Lifecycle
PENDING: The payout has been received and will be processed shortly.SUCCESS: The payout was successfully processed.FAILED: The payout was rejected due to a failure. The possible reasons are described in the table below.REVERSED: The payout was reversed by the end user or the destination financial institution.
A payout can transition from
SUCCESStoREVERSEDif the transaction is recalled by the end user or blocked by the financial institution.
Reversal Policy (Brazil Only)
If a payout reaches
REVERSEDstatus, it means the amount has been returned by the destination bank or user.
- Applies only to PIX and BANK TRANSFER.
- A reversal can occur up to 90 days after payment.
- Reversal can be partial or full.
Payout Statuses
The table below outlines all possible statuses a payout item can receive, their meanings, and whether retry attempts are allowed.
| Code | Reason | Payment Method | Description | Retry Allowed |
|---|---|---|---|---|
PENDING | – | All | Payout item was received and will be processed soon. | – |
SUCCESS | – | All | Payout was processed successfully. Funds were delivered to the recipient. | – |
FAILED | PROCESSING_ERROR | All | An unexpected error occurred during processing. | ✅ |
FAILED | INVALID_DESTINATION | All | The PIX key or bank account is invalid. | ❌ |
FAILED | INSUFFICIENT_FUNDS | All | Insufficient funds to process the payout. | ❌ |
FAILED | PAYEE_IRREGULAR_REGISTER | All | Payee failed compliance verification with PagSeguro policies. | ❌ |
FAILED | PAYOUT_DENIED | All | Payout could not be processed for internal or regulatory reasons. | ❌ |
FAILED | PAYEE_NAME_DOES_NOT_MATCH | All | Payee name did not meet the minimum match threshold with the document. Use the exact name on the document and avoid special characters. | ❌ |
FAILED | PAYEE_LEGAL_CONSTRAINTS | All | The payee is restricted due to legal or international compliance requirements. | ❌ |
FAILED | PAYEE_DECEASED | All | The CPF or CNPJ is associated with a deceased individual. | ❌ |
FAILED | PAYEE_UNDERAGED | All | Payee is under 18 and cannot receive payouts (especially in regulated sectors such as betting). | ❌ |
FAILED | PAYEE_EXCEEDED_FINANCIAL_LIMIT | All | The recipient has exceeded their allowed financial transaction limit. | ❌ |
FAILED | REJECTED_BY_RECEIVER | PIX / Bank Transfer | Payout was rejected by the receiving financial institution. | ❌ |
FAILED | PROCESSING_TIMEOUT | PIX / Bank Transfer | Timeout occurred in the SPI (Brazil’s instant payment system). | ✅ |
FAILED | DESTINATION_NOT_MATCH_DOCUMENT | PIX / Bank Transfer | Account owner’s name does not match the document provided. | ❌ |
FAILED | DESTINATION_ACCOUNT_BLOCKED | PagBank | The recipient’s account is blocked. | ❌ |
FAILED | PAYEE_NATIONAL_ID_CANCELLED | All | The national ID (CPF/CNPJ) has been administratively cancelled. | ❌ |
FAILED | PAYEE_NATIONAL_ID_INACTIVE | All | The national ID (CPF/CNPJ) is inactive or no longer valid. | ❌ |
FAILED | SALARY_ACCOUNT_TYPE_UNSUPPORTED | PIX / Bank Transfer | Salary-type accounts are not accepted for payouts. | ❌ |
FAILED | PAYEE_TYPE_NOT_ACCEPTED | PIX / Bank Transfer | The payee’s legal classification is not supported by the payout method. | ❌ |
| REVERSED | REJECTED_BY_PAYEE | PIX / BANK TRANSFER | Transfer was rejected by payee. | ❌ |
| REVERSED | REJECTED_BY_PAYEE_BANK | PIX / BANK TRANSFER | Transfer was rejected by payee bank. | ❌ |