Boleto

Boleto is a billing instrument widely used in Brazil for commercial transactions of goods and services between businesses and consumers.

Malga performs the role of a payment intermediary, but does not perform the financial clearance, therefore it is necessary for the Malga’s customer to have an account at a financial institution that is part of the financial system. Thus, we receive the data sent by the customer in the charges’ API and communicate with issuers and fintechs.

The Boleto participants:

• The payee, Malga's customer who must have an account at a partner financial institution to receive payments via Invoice/Payment Slips
• The payment provider, a financial institution where the customer has an account, responsible for issuing and registering an Invoice/Payment slip with the payee's and buyer's bank information.
• The payer, any buyer who must scan the barcode at the financial institution of his choice to make the payment.

Boleto payment flow:

• To create a transaction with Invoice/Payment Slips the customer simply informs the payment method as Invoice/Payment Slips when creating a charge, its expiration date and data that identifies the buyer;
• A charge is registered in the central bank's Invoice/Payment Slip system and is available for payment. The data is returned in the form of an image, which can be scanned by the payer, and a code, which can be copied by the payer;
• The Client must present the charging data to the payer, who must make the payment within the expiration period defined in the bill by the payee;
• The payer must pay the Invoice/Payment Slip at the financial institution of his choice;
• After confirmation of the payment, the payment provider will transfer the funds to the payee's account.
• Subsequently the payee customer will be notified that the payment has been made and the charges were successfully completed.

Payment flow associated with the customer

• Create customer;
• Create new charge providing the previously created customer as the paymentSource, thus using the buyer's data for generating the charge.

Supported providers for billing via Invoice/Payment slip:

ProviderType	Descrição
PAGARME	Pagar.me
STRIPE	Stripe
SANDBOX	Simulator used to authorize payments in sandbox environment

The Invoice/Payment slip charges, when created on Malga, are registered with pending status, being automatically updated to authorized status when we are notified by the financial institution of the payment confirmation, this time may vary from provider to provider, and cannot exceed the expiration time defined in the creation of the charge. If the payment confirmation is not recognized by the due date, Malga automatically cancels the charges, updating its status to failed.

caution

It is not possible to perform refunds for payments of the Invoice/Payment slip type, and there is also no pre-authorization or capture on charges of this type.

Notification of status change

object	event	description
transaction	pending	Event sent when the charge is registered and payment data is available
transaction	authorized	Event sent when the payment confirmation of the charges is recognized
transaction	failed	Event sent when the charges are denied by the financial institution before it has been authorized, without a financial refund

caution

It is possible that the paid value from a boleto with authorized status is different from it's original intended amount, due to fees from late payments for instance. Always check the value returned in the amount field from the transactions to identify the correct paid amount.

Example of billing via Boleto slip

Create an Boleto charge using the buyer's data through the Charges Service.

curl --location --request POST 'https://sandbox-api.malga.io/v1/charges' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
      "amount": 150,
      "currency": "BRL",
      "statementDescriptor": "Pedido #231 loja joão",
      "capture": true,
      "paymentMethod": {
        "paymentType": "boleto",
        "expiresDate": "2022-12-31",
        "instructions": "Instruções para pagamento do boleto",
        "interest": {
          "days": 1,
          "amount": 100,
          "percentage": 0.2
        },
        "fine": {
          "days": 2,
          "amount": 200,
          "percentage": 0
        }
      },
      "paymentSource": {
        "sourceType": "customer",
        "customer": {
          "name": "Jose Bonifacio Da Silveira",
          "phoneNumber": "21 98889999099",
          "email": "jose@gmail.com",
          "document": {
              "number": "72912053013",
              "type": "cpf"
          }
        }
      }
}'

< HTTP/2 201
{
  "id": "148d5db0-f1c3-439f-902d-f1f268086e1d",
  "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
  "createdAt": "2012-06-30 23:59:59 +0000",
  "amount": 150,
  "originalAmount": 150,
  "currency": "BRL",
  "statementDescriptor": "Pedido #231 loja joão",
  "capture": true,
  "status": "pending",
  "paymentMethod": {
    "paymentType": "boleto",
    "expiresDate": "2021-12-31",
    "barcodeData": "412343241324321431241341",
    "barcodeImageUrl": "https://...."
  },
  "paymentSource": {
    "sourceType": "customer",
    "customerId": "1cdcf0c9-eb04-4e43-b9b2-b7a4acdead1f"
  }
}