​

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.

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 por ID da cobrança, ID do pedido e NSU
• 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

​

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

​

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

Status	Descrição
pending	Transação criada porém não concluiu processamento ou ainda não foi paga
pre_authorized	Transação pré autorizada com sucesso pendente da captura
authorized	Transação autorizada e capturada com sucesso
failed	Transação não autorizada, verifique o erro para identificar o motivo
canceled	Transação estornada após aprovada porém não capturada
voided	Transação estornada após aprovada e capturada
charged_back	Transação foi contestada por fraude, não reconhecimento da compra ou devolução
created	Transação criada que sofreu um erro desconhecido em seu processamento
capture_pending	Transação pré-autorizada com requisição de captura em andamento
refund_pending	Transação autorizada com requisição de estorno em andamento

​

Status de acordo com o método de pagamento

Status	Boleto	Credit	Drip	Nupay	Pix	Voucher
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 inicial	Evento na cobrança	Status durante o evento	Status final após o evento
Pre-Authorized	Estorno completo	Refund_pending	Canceled
Authorized	Estorno parcial	Authorized	Authorized
Authorized	Estorno completo	Refund_pending	Voided
Authorized	Abertura de disputa (flag: is dispute)	Authorized	Authorized (disputa encerrada com ganho da loja)
Authorized	Abertura de disputa (flag: is dispute)	Authorized	Chargedback (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:

Provedor	Abertura de Disputa - Provedor	Abertura 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

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

​

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ário	Sucesso (requisição bem sucedida)	Em Andamento / Processamento	Falha	Timeout (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_Authorization	Descrição
networkResponseCode: String	Código de resposta do provedor
networkAuthorizationCode: String	Có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.

​

Identificadores de uma transação na Malga

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

Chaves principais

Identificador	Origem	Conceito
Order ID	Cliente	ID do pedido - Número da cobrança enviado do sistema do cliente para a Malga (envio opcional)
Charge ID	Malga	ID 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 ID	Provedor	ID 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 ID	Malga	ID 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

Identificador	Origem	Unicidade	Conceito
Transaction ID (networkTransactionId)	Provedor	Identificador único entre a Malga e o provedor	Identificação única da transação no provedor, gerada dinamicamente, retornado para a Malga
NSU (authorizationNsu)	Provedor	Identificador único entre o provedor e a Malga	Nú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)	Provedor	Identificador único entre o provedor e a Malga, para transação de crédito	Código de autorização retornado pelo provedor, que autoriza especificamente a captura de fundos (método crédito)
providerReferenceKey (external)	Cliente	Identificador enviado pelo cliente para a Malga e para o provedor	Chave 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)	Cliente	Identificador único de uma operação	Identificador enviado pelo cliente e pela Malga (chave de referência originadora da transação)
Idempotency key (Transaction request)	Malga	Identificador de uma requisição	Identificador enviado pela Malga para aquele provedor (chave de referência da requisição)
Session ID (ID da sessão)	Malga	Identificador de uma cobrança da API Sessions ou Link de Pagamento	Identifica 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

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

​

Identificadores no Histórico de Operações

---

​

Links e documentações úteis

• Provedores e métodos disponíveis na Malga
• Monitore sua operação através do Painel de dados
• Gerenciando subcontas na Malga
• Exportando dados do Dashboard
• Analytics API