Pular para o conteúdo principal

Boleto

Boleto é um instrumento de cobrança bastante utilizado no Brasil para operações de comercialização de bens e serviços entre empresas e consumidores.

A Malga realiza o papel de intermediadora de pagamentos, porém não realiza a liquidação financeira, sendo necessário conta em uma instituição financeira integrante do sistema financeiro. Dessa forma, recebemos os dados enviados pelo cliente na api de charges e fazemos a comunicação com os emissores e fintechs.

Os participantes do Boleto

  • O recebedor, cliente da Malga, deve possuir uma conta em instituição financeira parceira para receber pagamentos via Boleto;
  • Provedor de pagamento, instituição financeira onde o cliente possui conta, é responsável pela emissão e registro de um Boleto com os dados bancários do recebedor e do comprador;
  • O pagador, um comprador qualquer que deverá realizar a leitura do código de barras em instituição financeira de sua escolha para realizar o pagamento.

Fluxo de pagamento

  • Para criar uma transação com Boleto, basta o cliente informar o meio de pagamento Boleto na criação de uma cobrança, sua data de expiração e dados que identifiquem o comprador;
  • Uma cobrança é registrada no sistema de boletos do Banco Central e fica disponível para pagamento, os dados são retornados no formato de imagem, que pode ser escaneado pelo pagador, e o código, que pode ser copiado pelo pagador;
  • O Cliente deve apresentar os dados da cobrança ao pagador que deve efetuar o pagamento dentro do tempo de validade definido na cobrança pelo recebedor;
  • O pagador deve realizar o pagamento do Boleto em instituição financeira de sua escolha;
  • Após confirmação do pagamento, o provedor de pagamento irá realizar a transferência de fundos para a conta do recebedor;
  • Posteriormente o cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso.

Fluxo de pagamento associado ao customer

  • Criar um customer;
  • Criar um novo charge informando como paymentSource o customer criado previamente, dessa forma iremos utilizar os dados do comprador para geração da cobrança.

Provedores suportados para cobrança via Boleto

ProviderTypeDescrição
PAGARMEPagar.me
STRIPEStripe
BS2_BOLETOBS2
GETNETGetnet
SANDBOXSimulador usado para autorizar pagamentos em ambiente de teste

A cobrança tipo Boleto quando criada na Malga é registrada com status pending, sendo atualizada automaticamente para o status de authorized quando somos notificados pela instituição financeira da confirmação do pagamento, esse tempo pode variar de provedor para provedor, não podendo exceder o tempo de expiração definido na criação da cobrança. Caso a confirmação do pagamento não seja reconhecida até o vencimento, a Malga cancela automaticamente a cobrança, atualizando seu status para failed.

caution

Não é possível realizar estorno para pagamentos do tipo Boleto, também não existe pré-autorização ou captura de cobranças deste tipo.

Notificação de alteração de status

objetoeventodescrição
transactionpendingEvento enviado quando a cobrança é registrada e os dados para pagamento estão disponíveis
transactionauthorizedEvento enviado quando é reconhecido a confirmação do pagamento da cobrança
transactionfailedEvento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro
caution

É possível que o valor de pagamento de um boleto com status authorized seja diferente do valor original de emissão do mesmo, como em caso de juros ou multa sendo aplicados. Sempre verifique o campo amount informado nas atualizações de transações para confirmar o valor pago.

Testando recebimento de notificação de boleto pago

Para testar sua integração com os webhooks da Malga, você pode desenvolver direto o seu sistema ou utilizar algum serviço como request.bin ou pipedream.com para validar inicialmente os eventos enviados. Basta gerar um novo endpoint nestes serviços e cadastrar um webhook na Malga com o endpoint gerado que todos os eventos enviados ficarão registrados nestes serviços para consulta e debug.

Permitimos no ambiente de sandobx sandbox-api.malga.io a atualização manual de transações criadas para os status de authorized, voided e charged_back, dessa forma você consegue criar uma transação e simular o evento desejado.

Requisição para atualizar manualmente um boleto como pago em sandbox

curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/<CHARGE_ID>' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"status": "authorized"
}'

Exemplo de cobrança

Realize uma cobrança BOLETO a partir dos dados do comprador usando o Serviço de Charges.

curl --location --request POST 'https://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
},
"fine": {
"days": 2,
"amount": 200
}
},
"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"
}
}