Immediate payment x Scheduled payment

When creating a bill payment, define whether the operation should be processed on the same day or needs to be scheduled for a specific date.

Use the POST /v3/bill endpoint in both cases. The main difference is the use of scheduleDate.

See the full reference for the Create a bill payment endpoint.

Same-day payment

To request processing without scheduling a future date, send the digitable line in identificationField without scheduleDate.

Same-day processing depends on the type and amount of the boleto and must be requested on a business day within the applicable time window.

Outside the applicable window, do not consider the payment completed on the same day. Track the operation's processing until it reaches a conclusive status.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Get the digitable line"] --> B["Create payment without scheduleDate"]
    B --> C{"Within the same-day window?"}

    C --> CSim(("Yes"))
    C --> CNao(("No"))

    CSim --> D["Process on the same day"]
    CNao --> E["Process in the next available window"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B validacao
    class C decisao
    class D,E sucesso
    class CSim respostaSim
    class CNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#EF4444,stroke-width:4px

Example

{
  "identificationField": "23793369089519200016448005645600411990000034130",
  "externalReference": "order-5463"
}

Scheduled payment

To set the payment date, provide scheduleDate in the YYYY-MM-DD format.

The date cannot be earlier than the current date. Whether a same-day schedule is accepted depends on the boleto rules and the operational window. For boletos that are not overdue, the scheduled date must also respect the due date.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Get the digitable line"] --> B["Set scheduleDate"]
    B --> C["Create the payment"]
    C --> D["Validate the date"]
    D --> E["Wait for the scheduled date"]
    E --> F["Process the payment"]

    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,C,D,E validacao
    class F sucesso

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

Example

{
  "identificationField": "34191090570404959480975279260006611980000081488",
  "scheduleDate": "2025-09-11",
  "description": "Supplier payment",
  "externalReference": "order-4870"
}

How to choose the flow

See Important rules to validate boleto-specific conditions before creating the payment.

Track processing

Creating or scheduling does not confirm that the payment has been completed.

Use the Bill Payment Events to automatically receive state changes and update your operation.

Prefer Webhooks over periodic API queries. See Possible statuses to define how to handle each processing step.

Next steps

• Important rules
• Possible statuses
• Bill Payment Events
• Common errors and exceptions
• Testing in Sandbox