🇧🇷 Boleto

Overview

Boleto is one of Brazil’s most traditional and trusted payment methods, allowing customers to pay invoices at banks, lottery agencies, ATMs, or online banking environments.
It is especially popular for customers without access to cards or bank accounts and remains widely used for e-commerce, utility bills, and services.

With Orkestra, you can create Boleto payments seamlessly through a single API, providing your customers with a secure and familiar way to pay.

📝 Minimum Required Fields for Boleto

When creating an Order for Boleto, the following fields are mandatory:

Field	Type	Description
charges[].customer.firstName	String	Customer’s first name.
charges[].customer.lastName	String	Customer’s last name.
charges[].customer.document	String	Customer’s CPF (individual) or CNPJ (company) number.
charges[].customer.documentType	Enum	Must be CPF or CNPJ.
charges[].customer.livingAddress	Object	Customer’s address information (mandatory for Boleto).
charges[].transactions[].paymentMethod	Enum	Must be set to BOLETO.

⚙️ Optional Boleto-specific Fields

Field	Type	Description
charges[].transactions[].boleto.expiresAt	ISO8601 Timestamp	Expiration date for the Boleto. Defaults to your account settings (usually 3 days).
charges[].transactions[].boleto.discount	Decimal	Fixed discount amount in cents if the customer pays before discountLimitDate.`
charges[].transactions[].boleto.discountType	Enum	Determines the type of discount if the customer pays before discountLimitDate. Values: ABSOLUTE,RELATIVE Default ABSOLUTE
charges[].transactions[].boleto.discountLimitDate	ISO8601 Date	Date limit to apply the discount (no time component, e.g., "2025-07-09").
charges[].transactions[].boleto.interest	Decimal (0.00–100.00)	Monthly interest rate (in percentage) to apply on late payment.
charges[].transactions[].boleto.penalty	Decimal	Fine applied once if the boleto is paid after expiration date.
charges[].transactions[].boleto.penaltyType	Enum	Determines the type of penalty if the customer pays after expiresAt. Values: ABSOLUTE,RELATIVE Default ABSOLUTE
charges[].transactions[].boleto.acceptsAfterExpiration	Boolean	If false, the Boleto becomes unpayable after expiresAt (payment attempts will be rejected). Default true.
charges[].transactions[].boleto.instructions	String[]	Additional instructions displayed on the Boleto (e.g., "Pay at any bank before due date").

📦 Example: Boleto Order Request

JSON

{
  "merchantOrderId": "order-56789",
  "softDescriptor": "Orkestra Services",
  "amount": 12000,
  "currency": "BRL",
  "allowsThirdPartyPayments": false,
  "charges": [
    {
      "customer": {
        "firstName": "João",
        "lastName": "Pereira",
        "documentType": "CPF",
        "document": "12345678900",
        "livingAddress": {
          "street": "Rua das Flores",
          "number": "123",
          "complement": "Apto 45",
          "neighborhood": "Centro",
          "zipCode": "01001000",
          "city": "São Paulo",
          "state": "SP",
          "country": "BRA",
          "mainInformation": "Rua das Flores, 123",
          "secondaryInformation": "Apto 45",
          "latitude": -23.55052,
          "longitude": -46.633308
        }
      },
      "transactions": [
        {
          "paymentMethod": "BOLETO",
          "boleto": {
            "expiresAt": "2025-07-10T23:59:59.000Z",
            "instructions": ["Pagar até o vencimento."]
          }
        }
      ]
    }
  ]
}

🔁 Payment Flow Overview

• You create an order with paymentMethod set to BOLETO.

• Orkestra generates a Boleto barcode and URL.

• The customer receives the Boleto, which they can print or pay digitally.

• Customer pays the Boleto at a bank, online, ATM, or authorized location.

• Payment confirmation is sent asynchronously via webhook once settled (typically 1 business day).

📦 Example: Boleto Payment Response

JSON

{  
  "id": 54321,  
  "merchantOrderId": "order-56789",  
  "softDescriptor": "Orkestra Services",  
  "amount": 12000,  
  "currency": "BRL",  
  "status": "PENDING",  
  "allowsThirdPartyPayments": false,  
  "charges": [  
    {  
      "id": 12345,  
      "amount": 12000,  
      "status": "PENDING",  
      "customer": {  
        "firstName": "João",  
        "lastName": "Pereira",  
        "documentType": "CPF",  
        "document": "12345678900"  
      },  
      "transactions": [  
        {  
          "id": 67890,  
          "amount": 12000,  
          "paymentMethod": "BOLETO",  
          "boleto": {  
            "barcode": "23793381286000159013676000012302975760000012000",  
            "typeableLine": "23790.13674 00012.302975 76000.001200 3 38128600015901",  
            "url": "https://orkestra.boleto.link/67890",  
            "expiresAt": "2025-07-10T23:59:59.000Z",  
            "instructions": ["Pagar até o vencimento."]  
          }  
        }  
      ]  
    }  
  ]  
}  

🚨 Important Notes

• Boleto payments are not real-time — settlement typically occurs within 1–2 business days after payment.

• Expired Boletos will not be payable after the expiration date unless your account has special configurations.

• Brazilian regulations require full customer address information for issuing Boletos.

• Use webhooks to be promptly notified when a Boleto payment is confirmed.

✅ Summary
To process Boleto payments with Orkestra:

• Collect customer full name, document (CPF/CNPJ), and address.

• Set the paymentMethod to BOLETO.

• Provide an optional expiration date and custom instructions.

Orkestra will handle the generation of the Boleto and provide tracking for payment confirmation, offering your customers a secure and trusted local payment experience.