Guia de Gestão de cobranças

Através do Dashboard Malga, apresentamos a visão centralizada dos pagamentos da loja, com as informações de diferentes provedores, onde é possível monitorar vendas e erros, estornar e capturar cobranças, e entender o que aconteceu no processamento dos pagamentos com a nossa solução.

Acesse nosso Dashboard

  • Realize seu cadastro ou faça login. O usuário administrador da sua empresa é responsável pela configuração das permissões no ambiente de produção.
  • Caso encontre qualquer dificuldade, contate nosso time de suporte: suporte@malga.io

Neste guia, apresentaremos a área de Cobranças do Dashboard, explicando as informações e operações disponíveis em cada sessão:

  1. Listagem de Cobranças
  2. Detalhes de uma Cobrança
  3. Histórico de Operações
  4. Identificadores de uma Transação na Malga
  5. Links e Documentações úteis

Como monitorar as cobranças da sua loja Malga:

Listagem de Cobranças

No menu de Cobranças no Dashboard Malga, exibimos a listagem das cobranças da loja e os detalhes de cada transação, ordenadas pela data de criação mais recente (correspondente à data da venda na loja). Na listagem, são apresentadas as seguintes informações:

  • Data de criação (created at)
  • ID da cobrança (charge ID)
  • Valor original da cobrança (valor bruto da venda na loja)
  • Valor atual da cobrança (valor após estorno e captura)
  • Método de pagamento
  • Provedor responsável pelo último status da cobrança
  • Status da cobrança
  • Se houve algum evento ou utilização de algum serviço adicional na cobrança, como split e recorrência

Através dos ícones na lateral direita do dashboard representado abaixo, é possível aplicar filtros e buscar por uma cobrança específica. Além de oferecermos nosso recurso de exportação do arquivo .csv da listagem:

Listagem de Cobranças

Filtros e pesquisas disponíveis para encontrar cobranças:

  • Pesquisas em tempo real por ID da cobrança, ID do pedido e NSU
  • Pesquisas processadas há mais de uma hora por Documento do cliente, Email do cliente e 4 últimos dígitos do cartão de crédito.
  • Filtros por período (data de criação da cobrança), método de pagamento, provedor, status, subconta, cobranças com split ou em disputa

Filtros da área de Cobranças

Pesquisas na área de Cobranças

Exportar cobranças em relatório .csv

INFORMAÇÕES ADICIONAIS PARA GESTÃO DE COBRANÇAS:

  • Renomear subcontas (merchants): Confira o passo a passo para renomear as subcontas, facilitando a utilização do filtro por subconta, disponível nos menus de Fluxos Inteligentes, Painel de Dados, Cobranças e Links de Pagamento
  • Dados na Malga: É possível extrair dados da plataforma com a exportação dos relatórios em arquivo .csv através do Dashboard e enviada para o seu e-mail e com a Analytics API, desenvolvida em GraphQL, com as informações detalhadas das cobranças

Detalhes de uma cobrança

Clicando nas cobranças da listagem, são exibidos os detalhes da cobrança, com os dados do pagamento, cartão e cliente associados ao pagamento. No detalhe são exibidas:

  • Informações da cobrança: ID da cobrança (charge ID), ID do pedido (order ID) e método de pagamento
  • Detalhes do pagamento: data de pagamento, valor original e atual, status, provedor responsável, NSU, nome do cliente, número do cartão, entre outros dados de acordo com o método de pagamento
  • Detalhes do cliente: dados do cliente final (pagador), se enviados através do objeto customer
  • Detalhes do split: se a cobrança possuir split, serão exibidos os detalhes dos recebedores associados àquela cobrança
  • Detalhes de recorrência: se a cobrança possuir serviço de recorrência, serão exibidos as informações sobre o tipo de reecorrência que foi atribuída àquela charge, correspondendo à:
    • initial: Primeira transação recorrente
    • subsequent: Transação recorrente consecutiva
    • unscheduled: Cobrança avulsa
  • Detalhes do originador: dados do originador da cobrança (plataforma, device e sistema), se enviados através do objeto appinfo

Operações disponíveis no detalhe da cobrança:

  • Copiar registro técnico de requisições: através deste botão, é possível copiar o histórico da cobrança, com todos os detalhes de seu processamento e eventos (pré-autorização, autorização, estorno, abertura de disputa, entre outros)
  • Consultar o Histórico de Operações: apresenta as requisições feitas aos provedores de pagamento e antifraude, e os eventos ocorridos na cobrança, como pré-autorização, cancelamento, autorização, recusa, abertura de disputa, estorno, cancelamento, captura e disputa finalizada, representados na Transaction request
  • **Realizar estorno e captura do pagamento, ** de acordo com o status da cobrança:
    • Cobrança pré-autorizada → Captura total ou parcial
    • Cobrança pré-autorizada → Estorno total (equivalente ao cancelamento)
    • Cobrança autorizada → Estorno parcial ou total

Detalhe de uma cobrança

EXIBIÇÃO DE CLIENTE E CARTÃO ASSOCIADOS À COBRANÇA Para a visualização dos detalhes do cliente final (pagador) e do cartão, deverá ser feita a integração da nossa API Customers e da Tokenização de cartões através da Malga. A loja pode optar por não enviar estas informações na cobrança, acarretando na sua ausência no Dashboard.

Status de Cobranças na Malga

Cada método de pagamento suportado pela Malga, possui diferentes status de cobrança no seu ciclo de processamento. Nas tabelas abaixo, explicamos:

  • Status de cobrança na Malga
  • Status das cobranças existentes em cada método de pagamento
  • Alterações nos status das cobranças nas operações de estorno e disputa (chargedback)

Status das cobranças

Confira mais informações em nossa documentação

StatusDescrição
pendingTransação criada porém não concluiu processamento ou ainda não foi paga
pre_authorizedTransação pré autorizada com sucesso pendente da captura
authorizedTransação autorizada e capturada com sucesso
failedTransação não autorizada, verifique o erro para identificar o motivo
canceledTransação estornada após aprovada porém não capturada
voidedTransação estornada após aprovada e capturada
charged_backTransação foi contestada por fraude, não reconhecimento da compra ou devolução
createdTransação criada que sofreu um erro desconhecido em seu processamento
capture_pendingTransação pré-autorizada com requisição de captura em andamento
refund_pendingTransação autorizada com requisição de estorno em andamento

Status de acordo com o método de pagamento

StatusBoletoCreditDripNupayPixVoucher
Authorized

Canceled

Capture Pending

Charged Back

Created

Failed

Pending

Pre-Authorized

Refund Pending

Voided

Alterações no status de cobrança → Estorno e ChargeBack

Status inicialEvento na cobrançaStatus durante o eventoStatus final após o evento
Pre-AuthorizedEstorno completoRefund_pendingCanceled
AuthorizedEstorno parcialAuthorizedAuthorized
AuthorizedEstorno completoRefund_pendingVoided
AuthorizedAbertura de disputa (flag: is dispute)AuthorizedAuthorized (disputa encerrada com ganho da loja)
AuthorizedAbertura de disputa (flag: is dispute)AuthorizedChargedback (disputa perdida pela loja)

Provedores com suporte à notificação de abertura de disputa

Dentre os provedores suportados, confira quais deles oferecem suporte a notificação de disputa:

ProvedorAbertura de Disputa - ProvedorAbertura de Disputa - Malga
Adyen

Mercado Pago

Pagar.Me V4

PagSeguro

Zoop

Operações de Estorno e Captura no Dashboard

Nos detalhes da cobrança, é possível realizar o estorno de transações autorizadas e pré-autorizadas e a captura manual de transações pré-autorizadas.

A seguir, apresentamos o passo a passo detalhado para realizar operações de estorno e captura:

Estornar e Capturar no Detalhe de Cobrança

Realizando Estorno total e parcial:

É possível estornar cobranças dos métodos de pagamento de crédito, pix, Nupay e Drip, de acordo com a documentação, quando os seguintes status forem apresentados:

  • Cobrança pré-autorizada → é possível realizar o estorno total do valor
  • Cobrança autorizada → é possível realizar estorno parcial ou total, enquanto houver saldo residual na cobrança

Ao clicar no botão Estornar, é aberto o menu para indicação do valor a ser estornado, conforme a imagem:

Estornar Cobrança

Confirmar Estorno

Após a operação de Estorno, a cobrança autorizada terá seu status alterado para Estornada e a requisição de estorno bem sucedido estará refletida no Histórico de Operações da cobrança, com os detalhes do estorno realizado:

  • Valor atual da cobrança
  • Valor do estorno
  • Valor restante após o estorno

Histórico de operações | Detalhes da requisição de estorno bem sucedida

Cobrança com status Estornada

AMOUNT / ORIGINAL AMOUNT DA COBRANÇA APÓS O ESTORNO O valor original bruto da cobrança (originalAmount) corresponde ao valor inicial autorizado na transação, correspondente à venda na loja. Já o atributo valor atual da cobrança (amount) é alterado a cada solicitação de estorno parcial, exibindo o saldo residual da cobrança. No histórico de operações de uma requisição de estorno bem sucedida, são exibidos: - Valor atual da cobrança (valor da cobrança no momento da requisição de estorno) - Valor do estorno (valor a ser debitado da cobrança) - Valor restante após o estorno (valor da cobrança após o estorno parcial ou total)

Realizando a Captura manual de uma cobrança:

No método de crédito, é possível configurar para que a cobrança seja criada com pré-autorização, necessitando de captura manual (capture: false) , que pode ser feita pelo Dashboard ou pela API

No detalhe da cobrança, é possível realizar a captura parcial ou total da cobrança, conforme o passo a passo:

Capturar cobrança pré-autorizada

Confirmar captura

Detalhe de cobrança autorizada após a captura bem sucedida

STATUS APÓS A CAPTURA PARCIAL OU TOTAL A cobrança pré-autorizada pode sofrer uma captura parcial ou total do seu valor, tendo seu status alterado para “Autorizada” após a confirmação da captura. É possível conferir a requisição de captura bem sucedida no Histórico de Operações e também consultar o valor bruto e o valor atual, refletidos no detalhe da cobrança

Histórico de Operações da cobrança

O Histórico de Operações é um recurso muito importante no detalhe da cobrança, permitindo a análise e monitoramento dos pagamentos da loja. Nele estão contidos o histórico de eventos ocorridos na transação e seu status, em ordem cronológica pela alteração mais recente, exibindo detalhes de autorização, captura, e outras requisições dos provedores de pagamento e antifraude.

É possível obter informações acerca dos serviços de split e recorrência de uma cobrança e também sinalizaridores indicando quando uma transação estiver em disputa ou com reversão de estorno.

Histórico de operações com evento de disputa em aberto:

Histórico de operações com evento de disputa fechado:

Histórico de operações com estorno revertido pelo provedor (Adyen) como última requisição:

Histórico de operações com eventos de reversão de estorno e disputa simultaneamente:

Histórico de Operações de cobranças aberto

Máquina de estados das transações (tipos de requisições)

Dentro do Histórico de Operações, cada evento exibido reflete uma requisição da API Malga e o retorno do provedor, correspondendo a um tipo de requisição (request Type), um status de requisição (request Status) e um tempo de resposta da requisição (response TS).

Abaixo apresentamos a máquina de estados das requisições e respectivos status exibidos no Histórico do Dashboard:

Requisição / Retorno para o usuárioSucesso (requisição bem sucedida)Em Andamento / ProcessamentoFalhaTimeout (falhou por tempo excedido)Erro Interno (falhou por erro interno)
Pré-autorização

Autorização

Pré-autorização

Capture

Void / Refund

Revert void

Chargeback

Dispute

Zero dollar

Antifraude

Probe (Sonda) → requisição interna Malga

Created → requisição interna Malga

Principais eventos do Histórico de Operações

Nesta documentação, descrevemos os campos da Transaction Request, retornado no Histórico de Operações, conforme o tipo de requisição e o status.

A seguir, exemplificamos os principais objetos retornados no Histórico de Operações:

Cobrança pré-autorizada ou autorizada de crédito = Requisição de autorização/pré-autorização bem sucedida:

CAMPO: Objeto provider_AuthorizationDescrição
networkResponseCode: StringCódigo de resposta do provedor
networkAuthorizationCode: StringCódigo de autorização do provedor

Detalhe de cobrança > Histórico de Operações de uma cobrança recusada

Ações realizadas da Sonda Malga

Através do recurso de Fluxos Inteligentes da Malga, reprocessamos as transações recusadas por falha no provedor, passíveis de retentativa, de acordo com a configuração do fluxo de pagamentos da loja. Para evitar a duplicidade de transações e garantir a sincronização correta dos status entre a Malga e os provedores, temos um serviço de Sonda, responsável pela sondagem das cobranças realizadas em mais de um provedor no processo de retentativa.

A Sonda pode efetuar o cancelamento/estorno total de uma cobrança pré-autorizada ou autorizada, agindo posteriormente em um provedor que falhou na 1a tentativa, caso a transação já tenha sido enviada para autorização nos demais provedores configurados no fluxo.

O estorno realizado pela Sonda também é refletido no Histórico de Operações, seguindo a cronologia dos eventos da cobrança, o que permite que exista mais de uma ação de estorno em provedores distintos

Detalhe de cobrança > Histórico de Operações de uma cobrança autorizada com um estorno posterior feito pela Sonda

A ação da Sonda é a automática e ocorre quando a mesma cobrança é autorizada ou pré-autorizada em mais de um provedor, não demandando nenhum tipo de ação corretiva por parte do cliente.

CARACTERÍSTICAS DE UMA COBRANÇA COM ESTORNO FEITO PELA SONDA Detalhe da Cobrança > Histórico de Operações - Possui uma requisição de pré-autorização ou autorização com falha em um provedor - Possui uma requisição de pré-autorização ou autorização bem sucedida em outro provedor - Possui uma requisição de estorno bem sucedida em outros provedores, que não o provedor responsável pela cobrança, exibido no detalhe da cobrança - Se pré-autorizada ou autorizada, pode sofrer novo estorno pelo usuário através do Dashboard ou da API

Identificadores de uma transação na Malga

A seguir, apresentamos a descrição dos diferentes identificadores de uma cobrança na Malga:

Chaves principais

IdentificadorOrigemConceito
Order IDClienteID do pedido - Número da cobrança enviado do sistema do cliente para a Malga (envio opcional)
Charge IDMalgaID da cobrança - Refere-se à cobrança criada na Malga e possui várias requisições associadas (transaction request ID) e um transaction ID no provedor (network transaction ID)
Transaction IDProvedorID da transação - Refere-se à cobrança no provedor (Network Transaction ID), correspondendo ao identificador único da transação retornado pelo provedor, e pode ser usado para recuperar a transação nas APIs ou Dashboard do provedor
Transaction request IDMalgaID da requisição da Malga para o provedor, contendo um request type associado ao tipo da requisição (autorização, estorno, captura etc.)

Identificadores únicos de cobrança

IdentificadorOrigemUnicidadeConceito
Transaction ID (networkTransactionId)ProvedorIdentificador único entre a Malga e o provedorIdentificação única da transação no provedor, gerada dinamicamente, retornado para a Malga
NSU (authorizationNsu)ProvedorIdentificador único entre o provedor e a MalgaNúmero sequencial único associado à autorização (Unique sequence number), presente nas cobranças de crédito, voucher e boleto
Código de autorização (authorizationCode)ProvedorIdentificador único entre o provedor e a Malga, para transação de créditoCódigo de autorização retornado pelo provedor, que autoriza especificamente a captura de fundos (método crédito)
providerReferenceKey (external)ClienteIdentificador enviado pelo cliente para a Malga e para o provedorChave opcional enviada pelo cliente para ser encaminhada ao provedor pela Malga e registrada como identificador adicional.

Se enviada, sobrescreve a idempotency key da cobrança
Idempotency key (Charge)ClienteIdentificador único de uma operaçãoIdentificador enviado pelo cliente e pela Malga (chave de referência originadora da transação)
Idempotency key (Transaction request)MalgaIdentificador de uma requisiçãoIdentificador enviado pela Malga para aquele provedor (chave de referência da requisição)
Session ID (ID da sessão)MalgaIdentificador de uma cobrança da API Sessions ou Link de PagamentoIdentifica unicamente o pedido associado a esta transação. Este código é normalmente usado para vincular a transação ao item ou serviço específico que foi comprado

CHAVE DE IDEMPOTÊNCIA Confira mais informações sobre a utilização chave de idempotência em nossa documentação

Exemplo de evento no Histórico de Operações e seus identificadores

Identificadores no Histórico de Operações


SUPORTE MALGA Acione o nosso time através do email suporte@malga.io, para dúvidas e mais informações sobre o funcionamento dos recursos do Dashboard e da Malga.