Possible statuses

Understand the possible statuses of a payment, when each one occurs, and how to handle final and intermediate states and Sandbox behavior.

The status indicates which stage a bill payment is in and what action your integration should take. Use this information to keep the operation pending, complete the payment, handle a failure, cancel the flow, or record a refund.

Statuses and recommended handling

Status	What it represents	How to handle it in the integration
`PENDING`	Awaiting processing.	Keep the operation pending and wait for an update.
`BANK_PROCESSING`	Sent to the bank.	Keep the operation in processing. Do not consider the payment completed.
`PAID`	Payment made.	Mark the operation as completed.
`FAILED`	The payment failed.	Check the failure reason before advising a new attempt.
`CANCELLED`	The payment was canceled.	Stop the flow and record the cancellation.
`REFUNDED`	The payment was refunded.	Update the operation to reflect the refund.
`AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST`	Payment under review.	Keep the operation pending and wait for a new update before completing the flow.

How statuses can evolve

The flows below represent common transitions. Do not assume that every payment will necessarily go through all the intermediate states.

Payment completed

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PENDING"] --> B["BANK_PROCESSING"]
    B --> C["PAID"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B validacao
    class C sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Processing failure

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PENDING"] --> B["FAILED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px

When you receive FAILED, check the returned reason before making a new attempt.

Payment canceled

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PENDING"] --> B["CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Payment refunded

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAID"] --> B["REFUNDED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    class A inicio
    class B sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Payment under review

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["AWAITING_CHECKOUT_<br/>RISK_ANALYSIS_REQUEST"] --> B["Wait for a new update"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Track changes via Webhook

To track processing, prefer the Bill Payment Events over periodic API queries.

In the events received, event identifies the notified change and bill.status represents the current state of the payment. Use bill.id to match the update with the operation stored in your system.

When you receive BILL_FAILED, check bill.failReasons before deciding whether a new attempt is necessary.

Handling in the integration

Consider PENDING, BANK_PROCESSING, and AWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST as non-conclusive states. Do not release a flow that depends on the payment while the operation remains in these states.

PAID, FAILED, CANCELLED, and REFUNDED represent outcomes that require updating the operation's state in your system.

When processing updates received via Webhook, handle the events idempotently to avoid duplicate effects.

📘
In Sandbox, no payment is actually cleared. To test Bill Payment, use a boleto generated in the Sandbox account itself. Real boletos from external banks may return an error or the FAILED status.

Next steps

Updated 5 days ago

Did this page help you?