Refusal Reasons
Interpret Automatic Pix refusals
When an Automatic Pix payment instruction is refused, use the returned reason to define how your application handles it.
Refusals may occur during the scheduling or settlement of the charge and may originate from Asaas or from the payer's financial institution.
When to use
See this page when:
- an instruction returns
REFUSED; - the
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSEDevent is received; - your application needs to identify the cause of the refusal;
- you need to decide whether the flow can proceed to a retry or requires another action.
How to identify the refusal
When the instruction has REFUSED status, check the refusalReason field to identify the reason.
Store the original code returned by the API and map it to the corresponding message or action in your application.
See the endpoint Retrieve a single payment instruction.
ImportantA refusal does not necessarily mean an integration failure.
The reason may be related to the payer's account, the authorization, the recurrence rules, or the financial institution's processing.
Refusal identified by Asaas
| Reason | Description |
|---|---|
PAYMENT_OVERDUE | Charge overdue due to insufficient balance or limit at the time of the debit |
Refusals returned by the paying institution
| Reason | Description |
|---|---|
EXTERNAL_INSTITUTION_ERROR | Error at the payer's financial institution |
ACCOUNT_CLOSED | Transactional account closed |
ACCOUNT_BLOCKED | Transactional account blocked |
SAME_INSTITUTION_ERROR | Scheduling cannot be requested for accounts that use the same SPI settlement participant |
MAXIMUM_AMOUNT_EXCEEDED | Amount higher than the limit set by the payer |
AMOUNT_MISMATCH | Amount different from what was expected in the recurrence |
RECEIVER_CPF_CNPJ_MISMATCH | Payee's CPF/CNPJ does not match the recurrence data |
PAYER_CPF_CNPJ_MISMATCH | Payer's CPF/CNPJ does not match the authorization data |
PARTICIPANT_NOT_REGISTERED | Participant not registered or unavailable in the SPI |
DUE_DATE_MISMATCH | Due date incompatible with the recurrence rules |
POST_DUE_DATE_ATTEMPT_NOT_ALLOWED | Attempt made outside the allowed window after the due date |
RECEIVED_TOO_EARLY | Request sent earlier than allowed |
RECEIVED_TOO_LATE | Request sent later than allowed |
OTHER | Reason not specified by the institution |
OUT_OF_TIME_FRAME_FOR_RETRY | The charge is outside the allowed window for a new attempt |
INVALID_RECURRING_PAYMENT_ID | Recurrence identifier nonexistent or invalid |
RECURRING_PAYMENT_NOT_CONFIRMED | The recurrence was not confirmed by the payer |
PAYMENT_ALREADY_SCHEDULED | There is already a pending settlement request for the charge |
PAYMENT_ALREADY_DONE | The charge has already been settled |
PAYMENT_INSTRUCTION_WITHOUT_AUTHORIZATION | The instruction does not have a valid associated authorization |
EXCEEDED_MAXIMUM_RETRY_ATTEMPTS | Maximum number of retries exceeded |
PARTICIPANT_ISPB_INVALID | Financial institution's ISPB invalid or nonexistent |
INVALID_CUSTOMER_CPF_CNPJ | Invalid CPF/CNPJ |
INCORRECT_CUSTOMER_CPF_CNPJ | Incorrect CPF/CNPJ |
How to handle the refusal
Use refusalReason to direct the application's behavior.
| Scenario | Handling |
|---|---|
| Charge already paid or scheduled | Do not create a new instruction without confirming the current state of the charge |
| Invalid or unconfirmed authorization | Check the authorization before continuing the recurrence |
| Data mismatch | Correct the data before a new attempt |
| Request outside the allowed window | Review the date and processing rules |
| Insufficient balance or limit | Check whether the scenario allows a retry |
| Retry limit exceeded | Do not request a new retry for the same charge |
| Financial institution error | Preserve the returned reason and handle the scenario according to the instruction's state |
Do not present the enum directly to the payer. Map it to a message appropriate to your application's context.
Retries after a refusal
Not every refusal allows a new attempt.
When the charge is eligible for a retry, follow the specific Automatic Pix rules.
AttentionExtra-day retries require the authorization to have been created with the corresponding retry policy.
Check the rules before requesting a new attempt.
See the Automatic Pix retry process.
Track the result
Use Webhooks to track the instruction lifecycle and identify changes after the refusal.
To understand the sequence of events, see Automatic Pix Webhook Flows.
To see the available payloads and events, go to Events for Automatic Pix.
Next steps
Updated 14 days ago