> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Gestão de Cobranças
> Explore o Guia de Gestão de Cobranças no Dashboard Malga e aprenda a monitorar transações, efetuar estornos e capturas e analisar o processamento de pagamentos de forma eficiente.
export const CheckIcon = ({mode, type, id}) => {
const colorIcons = {
'error': '#919191',
'success': '#00AE42',
'noSupported': '#919191'
};
const foundColor = colorIcons[mode];
const iconType = mode === 'noSupported' ? type : `circle-${type}`;
return
;
};
# 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](https://dashboard.malga.io/sign-up) ou faça [login](https://dashboard.malga.io/). 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](mailto: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**, **NSU**, **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](/documentations/dashboard/merchants), facilitando a utilização do filtro por [subconta](https://dashboard.malga.io/app/merchants), 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](/documentations/dashboard/export-data) através do Dashboard e enviada para o seu e-mail e com a [Analytics API](/analytics/intro), 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](/api-reference/customers/criacao-de-novo-customer-para-cobranca)
* **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](/api-reference/charges/realizar-nova-cobranca)
**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](/api-reference/customers/criacao-de-novo-customer-para-cobranca) e da [Tokenização de cartões](/api-reference/tokens/criar-um-novo-token) 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](/documentations/type-tables/payment-methods-by-providers), 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](/documentations/payment-methods/intro#status-da-transacao)
| 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](/documentations/type-tables/payment-methods-by-providers), confira quais deles oferecem suporte a notificação de disputa:
| Provedor | Abertura de Disputa - Provedor | Abertura de Disputa - Malga |
| ------------ | ----------------------------------------- | ----------------------------------------- |
| Adyen | | |
| Barte | | |
| Braintree | | |
| Braspag | | |
| Cielo | | |
| Getnet | | |
| Klap | | |
| Mercado Pago | | |
| PicPay | | |
| Pagar.Me V4 | | |
| Pagar.Me V5 | | |
| PagSeguro | | |
| SafraPay | | |
| Stripe | | |
| WorldPay | | |
| 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 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](/documentations/payment-methods/credit-card#estorno-total-ou-parcial), 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
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
#### Detalhes da requisição de estorno bem-sucedido
#### 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](/documentations/payment-methods/credit-card#pre-autorizacao-e-captura), 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
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.
#### Disputa em aberto
#### Disputa fechada
### **Máquina de estados das transaçõ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](/analytics/objects/transaction-request), 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 recusada
**Ações realizadas da Sonda Malga**
Através do recurso de [Fluxos Inteligentes](/documentations/flow-guide/flow-dash) 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
#### 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**
| 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 |
CHAVE DE IDEMPOTÊNCIA Confira mais informações sobre a utilização **chave de idempotência** em nossa [documentação](/documentations/more/idempotency)
**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](/documentations/type-tables/payment-methods-by-providers)
* [Monitore sua operação através do Painel de dados](/documentations/dashboard/insights)
* [Gerenciando subcontas na Malga](/documentations/dashboard/merchants)
* [Exportando dados do Dashboard](/documentations/dashboard/export-data)
* [Analytics API](/analytics/intro)
SUPORTE MALGA Acione o nosso time através do email [suporte@malga.io](mailto:suporte@malga.io), para dúvidas e mais informações sobre o funcionamento dos recursos do Dashboard e da Malga.