Pagamentos com boleto bancário na Malga

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

Veja os provedores que suportam cobrança via boleto na nossa tabela de provedores e meios de pagamento suportados. 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 varia de provedor para provedor.

A Malga não cancela boleto automaticamente no vencimento. Um boleto vencido permanece com status pending até que o provedor nos notifique. Alguns provedores enviam essa notificação e outros não, então o comportamento varia conforme o provedor configurado no seu fluxo.Isso é intencional: boleto é pago com frequência depois da data de vencimento, e cancelar no vencimento descartaria pagamentos legítimos. Use a data que você enviou em expiresDate como referência na sua conciliação, em vez de esperar uma mudança de status.

Quando o cancelamento acontece, o status da cobrança passa a ser canceled, nunca failed. O status failed indica que a cobrança foi negada no momento da criação, antes de existir um boleto pagável.

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.

Não é possível cancelar um boleto pela API. O estorno (POST /v1/charges/{id}/void) não envia o cancelamento do boleto ao provedor. O status canceled só é aplicado quando o provedor notifica a Malga sobre o cancelamento.

Notificação de alteração de status

objeto	evento	descrição
transaction	pending	Evento enviado quando a cobrança é registrada e os dados para pagamento estão disponíveis
transaction	authorized	Evento enviado quando é reconhecida a confirmação do pagamento da cobrança
transaction	failed	Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro

É 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 sandbox 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": "38f43103-24b3-4349-9358-25d7c3975038",
      "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": "a1d455eb-dafe-4a5c-b882-a5775422f850",
  "clientId": "d353deef-dacb-40a0-8cab-931ff773f274",
  "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": "abe2d98a-0dc8-4c70-b108-c98eb24364ad"
  }
}

Comece na Malga

Conexões

Guias

Serviços adicionais

Pagamentos com boleto bancário na Malga

Os participantes do Boleto

Fluxo de pagamento

Fluxo de pagamento associado ao customer

Provedores suportados para cobrança via Boleto

Notificação de alteração de status

Testando recebimento de notificação de boleto pago

Exemplo de cobrança

​Os participantes do Boleto

​Fluxo de pagamento

​Fluxo de pagamento associado ao customer

​Provedores suportados para cobrança via Boleto

​Notificação de alteração de status

​Testando recebimento de notificação de boleto pago

​Exemplo de cobrança

Os participantes do Boleto

Fluxo de pagamento

Fluxo de pagamento associado ao customer

Provedores suportados para cobrança via Boleto

Notificação de alteração de status

Testando recebimento de notificação de boleto pago

Exemplo de cobrança