# Malga > Documentação da Malga: API REST, SDKs, métodos de pagamento, provedores e referência OpenAPI para orquestração de pagamentos. > ## Agent Instructions > Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga. > Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima. > Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação. > Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência". > Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas. > Sandbox é ambiente de testes e não afeta produção. # Como acessar a Analytics API Malga Source: https://docs.malga.io/analytics/authentication/authentication Aprenda como realizar a autenticação na Analytics API da Malga utilizando as credenciais X-Client-ID e X-Api-Key para acesso seguro aos dados. Você pode utilizar a sua aplicação ou o playground GraphiQL para interagir com a API em tempo real. Através dela, é possível visualizar os objetos, lista de campos e realizar as queries. A autenticação para todas as chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Malga e a chave secreta de acesso. Todas as requisições em GraphQL devem ser enviadas ao endpoint HTTP utilizando o método POST. ### Ambientes **Sandbox:** ```bash theme={null} curl --location --request POST 'https://api.dev.malga.io/v1/graphql' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{YOUR_QUERY}' ``` **Produção:** ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/graphql' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{YOUR_QUERY}' ``` Se você ainda não possui uma conta de sandbox na Malga, você pode criá-la aqui e imediatamente obterá as credenciais para acesso ao ambiente de testes. ### Credenciais #### X-Client-ID Identificador único da sua conta na Malga. Deve ser enviado no header obrigatoriamente em todas as requisições feitas à API. ```text theme={null} Security Scheme Type API Key Header parameter name X-Client-ID ``` #### X-Api-Key Sua chave de acesso à API. Funciona em par com o client-id e deve ser enviada no header obrigatoriamente em todas as requisições feitas à API. A chave precisa ter o escopo `graphql` ou `*`: * A chave secreta gerada no Dashboard no credenciamento da conta já tem escopo `*` e pode ser usada diretamente. * Para uma chave só da Analytics API, crie uma chave pública via [POST /v1/auth](/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side) com o escopo `graphql`. Use o `publicKey` retornado no header `X-Api-Key`. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/auth' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "scope": ["graphql"], "expires": 0 }' ``` > [!WARNING] > > Se a chave não tiver `graphql` nem `*`, a chamada em `/v1/graphql` retorna `403`. ```text theme={null} Security Scheme Type API Key Header parameter name X-Api-Key ``` Exemplo de requisição autenticada: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/graphql' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{YOUR_QUERY}' ``` ### Autenticação no Playground GraphiQL Para utilizar o Playground e realizar os testes na API, é necessário inserir o seu `X-Client-Id` e `X-Api-Key` no campo Headers, localizado na janela inferior do ambiente, conforme o exemplo abaixo: ![Autenticação no Playground GraphiQL](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/analytics/authentication-graphiQL.png?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=17084a6f3ab873d98a39c20761e3d530) # Tratamento de erros na Analytics API Source: https://docs.malga.io/analytics/errors/errors Tratamento de erros na Analytics API da Malga: interprete respostas GraphQL e entenda os códigos de status HTTP retornados em cada cenário. ## Status 200 - OK O GraphQL não retorna códigos de status da mesma forma que as APIs REST. Por exemplo, o GraphQL pode retornar um 200 OK nos casos em que uma API REST retornaria um código de status 5xx ou 4xx. Devido a esse fato, o GraphQL pode retornar um 200 OK mesmo quando uma ação no nível do aplicativo falha. ## Tratamento de erros Para verificar se há erros, você precisa verificar o objeto 'errors' na resposta, que contém informações adicionais sobre o que causou o problema. Algumas queries também têm um booleano "Sucesso" como campo de retorno, que retornará verdadeiro ou falso, dependendo do sucesso ou falha da ação. Para verificar os campos de retorno de todas as mutações e consultas, verifique nossa [documentação da API.](/documentations/welcome/errors) ## 4XX and 5XX Status Codes Conforme mencionado acima, na maioria dos casos, o GraphQL retornará uma resposta 200 OK quando uma API REST retornaria um código de status 4xx ou 5xx. Mas em alguns casos específicos, um código de status 4xx ou 5xx pode ser retornado. Veja abaixo esses casos e uma explicação deles. | Status Code | Explicação | | - | - | | 401 | Não autorizado. Um token válido não foi transmitido no cabeçalho da solicitação. | | 400 | Solicitação inválida (request\_without\_body) | | 403 | Proibido. | | 404 | Não encontrado. | | 415 | Tipo de mídia não compatível. | | 405 | Método não permitido. | | 422 | X-Client-Id é obrigatório. | ## Cenários de erros ### Método não permitido Fazer uma request utilizando o método GET na rota do `/v1/graphql`, onde só é permitido o método POST. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 404 | Not Found | ### Request sem header Fazer uma request sem o Header preenchido. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 403 | Forbidden | ### Request sem Body ou JSON null Fazer uma request sem o Body preenchido. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 415 | Unsupported Media Type | ### Request com GraphQL Query vazio Fazer uma request com o JSON não válido ou nulo. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 400 | No GraphQL query found in the request | ### Query incorreto ou inexistente Fazer uma request com o nome da Query incorreto ou inexistente. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 400 | `{"data": null,"errors": [{"message": "Cannot query field 'allCharge' on type 'Query'. Did you mean 'charge' or 'charges'?","locations": [{"line": 2,"column": 3 }]}]}` | ### Query com alguma sintaxe errada Fazer uma request com alguma sintaxe errada, seja falta de fechar um parêntese ou colchete. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 400 | `{"data": null,"errors": [{"message": "Syntax Error: Expected Name, found .","locations": [{"line": 52,"column": 2 }]}]}` | ### Query sem os campos (fields) Fazer uma request sem os campos (fields) no Body. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 200 | `{"data": null,"errors": [{"message": "Syntax Error: Expected Name, found '}'.","locations": [{"line": 10,"column": 7 }]}]}` | ### Query com campo (field) incorreto Fazer uma request sem os campos (fields) no Body. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 200 | `{"data": null,"errors": [{"message": "Cannot query field 'client' on type 'Charge'. Did you mean 'clientId'?","locations": [{"line": 10,"column": 9 }]}]}` | ### Query com campo (field) inexistente Fazer uma request com algum campo (field) inexistente. **ROTA**: `/v1/graphql` | Status Code | Explicação | | - | - | | 200 | `{"data": null,"errors": [{"message": "Syntax Error: Expected Name, found .","locations": [{"line": 19,"column": 2}]}]}` | # Exemplo Source: https://docs.malga.io/analytics/graphQl/exemplo Para conhecer a API em GraphQL e visualizar a estrutura de uma requisição, exibimos abaixo um exemplo de consulta (query) realizada através da Analytics API, demonstrando a operação: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/graphql' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{"query":"query allCharges {\n charges {\n allCharges(\n first: 1\n startDate: \"2023-09-01 00:00:00\"\n endDate: \"2023-10-01 00:00:00\"\n ) {\n edges {\n cursor\n node {\n clientId\n id\n createdAt\n description\n orderId\n originalAmount\n paymentMethod {\n installments\n paymentType\n }\n status\n transactionRequests {\n id\n amount\n createdAt\n transactionId\n idempotencyKey\n requestStatus\n requestType\n }\n }\n }\n pageInfo {\n endCursor\n hasNextPage\n hasPreviousPage\n }\n totalCount\n }\n }\n}","variables":{}}' ``` Que retornará (*response*): ```json theme={null} { "data": { "charges": { "allCharges": { "edges": [ { "cursor": "eyJpZCI6IDE2OTM2OTMxMzU4NjN9", "node": { "clientId": "1b2c2ef7-03cd-4012-9d1c-aff50551fae3", "id": "96c3e228-149c-4217-9a46-a411d66d3432", "createdAt": "2023-09-02T22:18:55.863042", "description": "Loja 1", "orderId": null, "originalAmount": 100, "paymentMethod": { "installments": 1, "paymentType": "credit" }, "status": "failed", "transactionRequests": [ { "id": "a1b9a02a-2e5a-477d-bd81-37f8d96a3799", "amount": "100", "createdAt": "2023-09-02T22:18:56.007904", "transactionId": "cb044961-731e-4abe-aaf5-0e3f7f259021", "idempotencyKey": "9c37cf52-d83d-4420-b4a6-95f37c10b807", "requestStatus": "failed", "requestType": "pre_authorization" } ] } } ], "pageInfo": { "endCursor": "eyJpZCI6IDE2OTM2OTMxMzU4NjN9", "hasNextPage": true, "hasPreviousPage": false }, "totalCount": 418417 } } } } ``` A seguir, confira como realizar a autenticação e utilizar a Analytics API Malga. # Glossário Source: https://docs.malga.io/analytics/graphQl/glossario Glossário de termos GraphQL usados na Analytics API da Malga, incluindo schema, queries, mutations, tipos, campos, argumentos e diretivas. ![Analytics API](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/analytics/glossary.png?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=fa98659d9f7c059dbb0650f8109ab0c0) > [accordion] Objeto \[type] > > Cada parte de um esquema em GraphQL é um tipo de objeto, que consiste em uma lista de campos e o valor de cada campo. > [accordion] Esquema \[schema] > > O esquema (schema), ou sistema de tipos (types), é a base de qualquer serviço em GraphQL e descreve o escopo de todas as entidades (types) e consultas (queries) disponíveis pela API. > > Com o esquema, é possível realizar a validação de cada requisição enviada, além de permitir a relação de consultas de introspecção, possibilitando o entendimento das entidades descritas no esquema. > [accordion] Consulta \[queries] > > A consulta (query) descreve como é feita a leitura dos dados em GraphQL e como a operação irá retornar os dados do servidor, permitindo a consulta de diferentes entidades em cada requisição. > > Na Analytics API da Malga, estão disponíveis as entidades de Charges, Cards, Dashboard, Authorization Rate e Subacquirer. > [accordion] Campo \[field] > > Cada campo corresponde a uma unidade de dados que é retornada dentro do objeto. > [accordion] Argumento \[argument] > > Os campos de um objeto em GraphQL podem ser descritos como uma função que retorna um valor e que aceitam argumentos pré-definidos, onde cada argumento pode ser qualquer campo que não seja um objeto. > > Na Analytics API Malga, disponibilizamos argumentos como filtros por ID e status de transação, que podem ser aplicados aos conjuntos de dados das entidades. > [accordion] Subacquirer — feature > > A **feature** identifica o contexto do saldo do subadquirente. Valores possíveis: `NUPAY`, `SUBACQUIRER`, `GENERAL` e `SUBACQUIRER_PREPAYMENT`. O padrão é `SUBACQUIRER`. > [accordion] Subacquirer — seller / sellerId > > O **seller** é o recebedor cadastrado para split de pagamentos. O argumento `sellerId` filtra o saldo de um seller específico. Quando omitido, a consulta resolve para o **client master** (o client cujo `reference_client_id` não está associado a um seller), e não para a soma de todos os sellers. > [accordion] Subacquirer — reconciled\_order > > Ordens conciliadas (`subacquirer_reconciled_order`) que compõem o saldo. O sinal é definido pelo `order_type`: `authorization` soma como crédito; `void` e `charge_back` subtraem como débito. A disponibilidade versus o pendente é determinada pela `payment_scheduled_at`. > [accordion] Subacquirer — reconciled\_adjustment > > Ajustes conciliados (`subacquirer_reconciled_adjustment`) aplicáveis às features suportadas, somados ao saldo. > [accordion] Subacquirer — payment\_batch > > Lotes de pagamento (`subacquirer_payment_batch`) pendentes (status `pending` ou `failed`), somando o `final_balance` ao saldo. > [accordion] Subacquirer — carry-forward > > Saldo de arraste (`subacquirer_balance`): apenas o registro mais recente por `(payment_method, payment_arrangement)` é considerado, evitando duplicar históricos. # Overview Source: https://docs.malga.io/analytics/graphQl/overview **GraphQL** é uma linguagem de consulta e ambiente server-side para APIs, que entrega flexibilidade, desempenho e rapidez na execução de operações e descreve consultas usando a estrutura definida para os dados. O GraphQL não está vinculado a nenhum banco de dados ou mecanismo de armazenamento específico, sendo apoiado por seu código e dados existentes. Um serviço GraphQL é criado definindo tipos e campos nesses tipos e, em seguida, fornecendo funções para cada campo em cada tipo. O GraphQL oferece a especificação e descrição completa dos dados disponíveis na API, facilitando a execução de consultas para extração dos dados, **retornando exatamente o que foi definido na requisição.** Além da Analytics API Malga, também disponibilizamos um ambiente integrado de desenvolvimento **(IDE / integrated development environment)** conhecido como **GraphiQL**, que chamamos de playground, através do qual é possível explorar a API utilizando suas credenciais Malga. No playground GraphQL, as consultas são interativas, onde o cliente consegue visualizar em tempo real quais são as queries disponíveis e os objetos da mesma e podem ser testadas, adicionando ou removendo campos, sem afetar as demais consultas existentes, apoiando a utilização do serviço e a construção de requisições previsíveis pelo cliente Malga. Para utilizar o playground GraphQL da Analytics API Malga, acesse aqui. Na interface do GraphQL, devem ser inseridas consultas e variáveis em formato GraphQL, inseridas em janelas separadas. Ao longo da documentação, disponibilizamos exemplos de requisições para utilização no IDE. # Começando em Analytics API Source: https://docs.malga.io/analytics/intro Conheça a Analytics API da Malga: acesso detalhado aos dados de pagamentos processados para análises gerenciais e monitoramento de transações. A **Analytics API Malga** é um serviço que disponibiliza os dados dos pagamentos realizados através da nossa API, retornando as informações registradas durante o seu processamento pelos provedores. Desenvolvida em linguagem de consulta [GraphQL](https://graphql.org/) e banco de dados **NoSQL OpenSearch**, oferece alto desempenho nas consultas. A Analytics API possibilita uma visão completa e acessível dos dados de transações e suas descrições, permitindo a realização de queries. Através de uma requisição na Analytics API, é possível retornar e combinar dados de diferentes serviços da Malga, obtendo o conjunto de informações necessárias para **análises gerenciais e acompanhamento dos pagamentos processados** em nossa API. > [card] ATUALIZAÇÃO DOS DADOS > > Os dados da **Analytics API** são disponibilizados em near real time, com uma latência de 1 a 2 segundos. ### Como usar este guia? Neste guia, você encontrará informações sobre: **1. GraphQL** Linguagem de consulta **GraphQL** e o playground GraphQL da Analytics API. **2. Requisições** Como fazer chamadas na API através do seu browser usando suas **credenciais da Malga.** **3. Entidade, queries e objetos** Lista completa de **entidades**, **queries** e **tipos de objetos** disponibilizados pela Analytics API, incluindo cobranças (Charges), cartões (Cards), dashboard, taxa de autorização (Authorization Rate) e saldo do subadquirente (Subacquirer). # AuthorizationRate Source: https://docs.malga.io/analytics/objects/auth-rate Lista de informações sobre a taxa de aprovação de cobranças:
**CAMPO: OBJETO** **DESCRIÇÃO**
authorizationRate: **Float** Taxa de aprovação
approvedCount: **Int** Número de cobranças aprovadas
date: **String** Data
deniedCount: **Int** Número de cobranças negadas
totalCount: **Int** Contagem total de cobranças
paymentMethod: **String** Método de pagamento usado na cobrança
providerType: **String** Nome do provedor usado na cobrança
# BillingAddress Source: https://docs.malga.io/analytics/objects/billing-address Lista de informações de endereço de cobrança:
**CAMPO: OBJETO** **DESCRIÇÃO**
country: **String** Padrão ISO 3166-1 alpha-2
state: **String** Estado
city: **String** Cidade
district: **String** Bairro
zipCode: **String** Código postal CEP
street: **String** Nome da rua/avenida/travessa
number: **Int** Número da rua
complement: **String** Complemento caso exista
# Informações Boleto Source: https://docs.malga.io/analytics/objects/boleto Tabela de campos do objeto Boleto na Analytics API da Malga com os atributos retornados nas consultas de cobranças via boleto bancário. Lista de informações do Boleto:
**CAMPO: OBJETO** **DESCRIÇÃO**
barcodeData: **String** Código de barras do boleto
barcodeImageUrl: **String** Imagem do código de barras do boleto
expiresDate: **Datetime** Data de expiração do boleto
paymentLimitDate: **String** Data de vencimento do boleto
recipientName: **String** Nome do recebedor
# Card Source: https://docs.malga.io/analytics/objects/card Lista de informações de cartão:
**CAMPO: OBJETO** **DESCRIÇÃO**
cardId: **String** ID do cartão
tokenId: **String** ID do token
clientId: **Datetime** Identificação do cliente na Malga
customerId: **String** ID do cliente vinculado ao cartão
expirationDate: **String** Data de expiração
holderName **String** Nome de cartão
cvvChecked: **Boolean** CVV validado
tokenExpirationDate: **String** Data de expiração do token
first6Digits: **Int** 6 primeiros dígitos
last4Digits: **Int** 4 últimos dígitos
cardUpdatedAt **Datetime** Data de atualização
cardCreatedAt **Datetime** Data de criação
cardStatus **String** Status do cartão: ativo ou inativo
statusReason: **String** Motivo de status
zeroAuthProviderType: **String** Provedor ZeroAuth
zeroAuthProviderId **String** ID do provedor ZeroAuth
brand **String** Bandeira
tokenUpdatedAt **String** Data de atualização do token
tokenCreatedAt **String** Data de criação do token
tokenDeletedAt **String** Data de deleção do token
idempotencyKey **String** Chave de idempotência do token
requestId **String** ID da requisição
type **String** Tipo de tokenização
tokenStatus **String** Status de tokenização
origin **String** Origem do token
# CardEdge Source: https://docs.malga.io/analytics/objects/card-edge Uma borda em uma conexão.
**CAMPO: OBJETO** **DESCRIÇÃO**
cursor **String** Um cursor para uso em paginação
node [\[Card\]](/analytics/objects/card) O item no final da borda
# CardsConnection Source: https://docs.malga.io/analytics/objects/cards-connection O tipo de conexão para Card.
**CAMPO: OBJETO** **DESCRIÇÃO**
edges [\[CardEdge\]](/analytics/objects/card-edge) A lista de conexões de uma cobrança
pageInfo [\[PageInfo\]](/analytics/objects/page-info) Informações da paginação
totalCount **Int!** Total de registros retornados pela consulta
# Objeto Cart na Analytics API Source: https://docs.malga.io/analytics/objects/cart Referência dos campos do objeto Cart na Analytics API da Malga, com nome, SKU, quantidade, preço unitário, risco e dados de ingressos dos itens do pedido. Lista de informações do carrinho:
**CAMPO: OBJETO** **DESCRIÇÃO**
name: **String** Nome do item/evento
quantity: **String** Identificador único do item na loja
sku: **String** Quantidade de itens do pedido
unitPrice: **String** Valor unitário do item/evento em centavos
risk: **String** Definição do índice de risco do item
tickets: **String** Informações relacionadas aos ingressos, em caso de evento
location: **String** Definição de endereço, em caso de evento
# Objeto Charge na Analytics API Source: https://docs.malga.io/analytics/objects/charge Referência dos campos do objeto Charge disponíveis nas queries da Analytics API da Malga, com tipos e descrições para cobranças processadas. Lista de informações de cobrança:
**CAMPO: OBJETO** **DESCRIÇÃO**
amount: **Int** Valor da transação
capture: **Boolean** Se a transação deve ser capturada automaticamente
clientId: **Datetime** Identificação do cliente na Malga
createdAt: **Datetime** Data de criação da cobrança
currency: **String** Moeda da transação
description: **String** Descrição da transação para conciliação futura
fraudAnalysisMetadata [\[FraudAnalysisMetadata\]](/analytics/objects/fraud-analysis-metadata) Informações sobre os metadados de análise de fraude
id: **Int** Charge ID
isDispute: **Boolean** Se a transação está em disputa
merchantId: **String** ID da Subconta
orderId: **String** Identificador único do cliente para conciliação futura
originalAmount: **Int** Valor original da transação enviada ao provedor
paymentMethod [\[PaymentMethod\]](/analytics/objects/payment-method) Informações sobre o método de pagamento da cobrança
paymentSource [\[PaymentSource\]](/analytics/objects/payment-source) Informações sobre a fonte de pagamento
statementDescriptor: **String** Descrição a ser exibida no extrato bancário do comprador
status: **Boolean** Status da transação
transactionRequests [\[TransactionRequests\]](/analytics/objects/transaction-request) Informações sobre o histórico de transações
updatedAt: **Datetime** Data da última atualização da cobrança
# ChargeConnection Source: https://docs.malga.io/analytics/objects/charge-connection O tipo de conexão para Charge.
**CAMPO: OBJETO** **DESCRIÇÃO**
edges [\[ChargeEdge\]](/analytics/objects/charge-edge) A lista de conexões de uma cobrança
pageInfo [\[PageInfo\]](/analytics/objects/page-info) Informações da paginação
totalCount **Int!** Total de registros retornados pela consulta
# ChargeCurrencies Source: https://docs.malga.io/analytics/objects/charge-currencies Lista de informações das moedas utilizadas nas cobranças processadas:
**CAMPO: OBJETO** **DESCRIÇÃO**
currency: **String** Moeda da transação
# ChargeEdge Source: https://docs.malga.io/analytics/objects/charge-edge Uma borda em uma conexão.
**CAMPO: OBJETO** **DESCRIÇÃO**
cursor **String** Um cursor para uso em paginação
node [\[Charge\]](/analytics/objects/charge) O item no final da borda
# Customer Source: https://docs.malga.io/analytics/objects/customer Lista de informações do cliente:
**CAMPO: OBJETO** **DESCRIÇÃO**
name: **String** Nome do usuário
email: **String** Email do usuário
identity: **String** Número do documento formato conforme tipo selecionado
identityType: **String** Tipo de documento, consultar tabela de tipos suportados
phone: **String** Telefone de contato do usuário
billingAddress [\[BillingAddress\]](/analytics/objects/billing-address) Endereço de cobrança
deliveryAddress [\[DeliveryAddress\]](/analytics/objects/delivery-address) Endereço de entrega
# DeclinedCode Source: https://docs.malga.io/analytics/objects/declined-code Lista de informações das cobranças agrupadas pelo campo de declinedCode do objeto [providerError](/analytics/objects/provider-error).
**CAMPO: OBJETO** **DESCRIÇÃO**
currency: **String** Moeda da transação
declinedCode: **String** Código de recusa do provedor
totalCount: **Int** Contagem total de cobranças
totalAmount: **Float** Valor total das cobranças
volume: **Float** Volume (%) de cobranças
# DeliveryAddress Source: https://docs.malga.io/analytics/objects/delivery-address Lista de informações de endereço de entrega:
**CAMPO: OBJETO** **DESCRIÇÃO**
country: **String** Padrão ISO 3166-1 alpha-2
state: **String** Estado
city: **String** Cidade
district: **String** Bairro
zipCode: **String** Código postal CEP
street: **String** Nome da rua/avenida/travessa
number: **Int** Número da rua
complement: **String** Complemento caso exista
# FraudAnalysisMetadata Source: https://docs.malga.io/analytics/objects/fraud-analysis-metadata Lista de informações de análise de fraude:
**CAMPO: OBJETO** **DESCRIÇÃO**
cart [\[Cart\]](/analytics/objects/cart) Detalhe do carrinho de produtos
customer [\[Customer\]](/analytics/objects/customer) Dados do comprador
# Merchants Source: https://docs.malga.io/analytics/objects/merchants Lista de informações da subconta:
**CAMPO: OBJETO** **DESCRIÇÃO**
merchantId: **String** Identificador da subconta usada nas transações
merchantName: **String** Nome da subconta usada nas transações
merchantVolume: **Float** Volume em % das transações
# Informações Nupay Source: https://docs.malga.io/analytics/objects/nupay Tabela de campos do objeto Nupay na Analytics API da Malga com os atributos retornados nas consultas de cobranças via método Nupay. Lista de informações da Nupay:
**CAMPO: OBJETO** **DESCRIÇÃO**
type: **String** Tipo de pagamento Nupay
installmentsNumber: **Int** Número de parcelas no crédito
expiresIn: **Int** Data de expiração
paymentUrl: **String** URL de pagamento
# PageInfo Source: https://docs.malga.io/analytics/objects/page-info Informações sobre paginação em uma conexão.
**CAMPO: OBJETO** **DESCRIÇÃO**
endCursor: **String** Cursor indicando a paginação
hasNextPage: **Boolean** Possui próxima página
hasPreviousPage: **Boolean** Possui página anterior
# PaymentMethod Source: https://docs.malga.io/analytics/objects/payment-method Lista de informações do método de pagamento:
**CAMPO: OBJETO** **DESCRIÇÃO**
installments: **Int** Quantidade de parcelas para cobrança do tipo crédito
paymentType: **String** Tipo de pagamento
# PaymentSource Source: https://docs.malga.io/analytics/objects/payment-source Lista de informações da fonte de pagamento:
**CAMPO: OBJETO** **DESCRIÇÃO**
sourceType: **Int** Tipo da origem da cobrança
cardId: **String** Identificador do cartão
customerId: **String** Identificador de comprador para consulta futura
tokenId: **String** Identificador do token do cartão
# Informações do Pix Source: https://docs.malga.io/analytics/objects/pix Tabela de campos do objeto Pix na Analytics API da Malga com os atributos retornados nas consultas de cobranças realizadas via Pix. Lista de informações do Pix:
**CAMPO: OBJETO** **DESCRIÇÃO**
qrCodeImageUrl: **String** Imagem do QR code
qrCodeData: **String** QR code
expiresIn: **Int** Data de expiração do Pix
type: **String** Tipo de pagamento Pix
# ProviderAuthorization Source: https://docs.malga.io/analytics/objects/provider-auth Lista das informações de autorização do provedor:
**CAMPO: OBJETO** **DESCRIÇÃO**
networkResponseCode: **String** Código de resposta do provedor
networkAuthorizationCode: **String** Código de autorização do provedor
# ProviderError Source: https://docs.malga.io/analytics/objects/provider-error Lista das informações de erro do provedor:
**CAMPO: OBJETO** **DESCRIÇÃO**
retryable: **Boolean** Transação é passível de retentativa
declinedCode: **String** Código de recusa do provedor
networkDeniedReason: **String** Motivo de recusa do provedor
networkDeniedMessage: **String** Mensagem de recusa do provedor
message: **String** Mensagem do provedor associada ao erro
# ProvidersResume Source: https://docs.malga.io/analytics/objects/providers-resume Lista de informações do provedor (volume, número de cobranças, total financeiro e taxa de aprovação):
**CAMPO: OBJETO** **DESCRIÇÃO**
authorizationRate: **Float** Taxa de aprovação
currency: **String** Moeda da transação
providerType: **String** Nome do provedor usado na cobrança
totalCount: **Int** Contagem total de cobranças
totalAmount: **Float** Valor total das cobranças
volume: **Float** Volume (%) de cobranças
# Objeto SubacquirerBalance na Analytics API Source: https://docs.malga.io/analytics/objects/subacquirer-balance Referência dos campos do objeto SubacquirerBalance na Analytics API da Malga, com saldo disponível e a receber do subadquirente em centavos. Lista de informações de saldo do subadquirente:
**CAMPO: OBJETO** **DESCRIÇÃO**
available: **Int** Saldo disponível (em centavos)
receivable: **Int** Saldo a receber (em centavos)
feature: **String** Feature do saldo. Valores possíveis: `NUPAY`, `SUBACQUIRER`, `GENERAL`, `SUBACQUIRER_PREPAYMENT`
currency: **String** Moeda do saldo. O padrão é `BRL`
# TotalCharges Source: https://docs.malga.io/analytics/objects/total-charges Lista de informações de cobranças (volume, número de cobranças e total financeiro):
**CAMPO: OBJETO** **DESCRIÇÃO**
currency: **String** Moeda da transação
date: **String** Data
totalCount: **Int** Contagem total de cobranças
totalAmount: **Float** Valor total das cobranças
volume: **Float** Volume (%) de cobranças
paymentMethod: **String** Método de pagamento usado na cobrança
providerType: **String** Nome do provedor usado na cobrança
# TransactionRequests Source: https://docs.malga.io/analytics/objects/transaction-request Lista de informações do histórico de transações:
**CAMPO: OBJETO** **DESCRIÇÃO**
amount: **Int** Valor da transação enviada para processamento do provider, em casos de estorno ou captura parcial o valor pode ser diferente do amount original da transação
authorizationCode: **String** Código de autorização retornado pelo provedor
authorizationNsu: **String** Número de autorização retornado pelo provedor
boleto [\[Boleto\]](/analytics/objects/boleto) Informações sobre a forma de pagamento por Boleto
createdAt: **Datetime** Data de criação da requisição da transação
id: **String** ID de requisição da transação
idempotencyKey: **String** Chave única de referência gerada pela Malga para cada requisição
nupay [\[Nupay\]](/analytics/objects/nupay) Informações sobre a forma de pagamento por Nupay
pix [\[Pix\]](/analytics/objects/pix) Informações sobre a forma de pagamento por Pix
providerAuthorization [\[ProviderAuthorization\]](/analytics/objects/provider-auth) Dados adicionais do retorno da autorização do provider no processamento da transação
providerError [\[ProviderError\]](/analytics/objects/provider-error) Detalhes do erro em caso de falha no processamento da transação
providerId: **String** Identificador do provedor relacionado ao merchant ID
providerType: **String** Nome do provedor
requestStatus: **String** Status of request processing
requestType: **String** Tipo de requisição no provedor
responseTs: **String** Tempo de processamento da requisição
transactionId: **String** Identificador único da transação retornado pelo provider, txId, pode ser usado para recuperar a transação nas APIs ou dashboard do provedor
updatedAt: **Datetime** Data de atualização da requisição da transação
# Playground GraphiQL Source: https://docs.malga.io/analytics/playground # Queries do grupo Authorization Rate na Analytics API Source: https://docs.malga.io/analytics/queries/authorization-rate Consulte a taxa de autorização das cobranças na Analytics API da Malga, com filtros por período, método de pagamento e provedor via queries GraphQL. A taxa de autorização `authorizationRate` corresponde ao percentual de cobranças aprovadas em relação ao total de cobranças processadas (somando pré-autorizadas, autorizadas e com falha). Esse indicador representa a conversão bem-sucedida de autorização das cobranças e pode ser filtrado por período, método de pagamento e provedor de cobrança. No grupo **Authorization Rate** disponibilizamos as seguintes consultas:
`totalAuthorizationRate` Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed)
`byInterval` Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) no intervalo selecionado
`byProviderType` Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) por provedor
`byPaymentMethod` Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) por método de pagamento
*** ## totalAuthorizationRate Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed)
**QUERY : OBJETO DE RETORNO** **totalAuthorizationRate: AuthorizationRate**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## byInterval Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) no intervalo selecionado
**QUERY : OBJETO DE RETORNO** **byInterval: AuthorizationRate**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
interval: **String!** Intervalo de agrupamento \[DAY, WEEK, MONTH, YEAR]
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## byProviderType Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) por provedor
**QUERY : OBJETO DE RETORNO** **byProviderType: AuthorizationRate**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## byPaymentMethod Retorna o percentual de cobranças aprovadas (pre\_authorized / authorized) dividido pela soma das cobranças aprovadas e recusadas (pre\_authorized / authorized / failed) por método de pagamento
**QUERY : OBJETO DE RETORNO** **byPaymentMethod: AuthorizationRate**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
# Cards Source: https://docs.malga.io/analytics/queries/cards Consultas GraphQL do grupo Cards na Analytics API da Malga, com as queries cards e card no novo índice card e a query allCards depreciada. As consultas disponíveis do serviço de `cards` têm o objetivo de prover os dados de cartões e tokens criados na Malga, bem como dos clientes associados, facilitando a análise das informações nestes serviços. Não são expostos dados sensíveis nestas consultas, tais como CVV e documentos dos clientes. No grupo **Cards** disponibilizamos as seguintes consultas:
`allCards` **(deprecated)** Retorna todos os cartões e tokens. **Depreciada** — será descontinuada em **2027**. Utilize `cards`.
`cards` Retorna os cartões a partir do novo índice `card`, com os tokens e as solicitações de transação aninhados, além de novos campos e filtros.
`card` Retorna um único cartão pelo `id` a partir do novo índice `card`.
*** ## allCards > [!WARNING] > > **Depreciada.** A consulta `allCards` está depreciada e será **descontinuada em 2027**. Migre para a nova consulta [`cards`](#cards), que consulta o índice `card` e mantém os mesmos argumentos, além de novos campos e filtros. Enquanto não for descontinuada, a `allCards` continua funcionando normalmente. Retorna todos os cartões.
**QUERY : OBJETO DE RETORNO** **allCards: CardsConnection**
**ARGUMENTO : TIPO** **DESCRIÇÃO**
first: **Int** Retorna os primeiros *n* elementos da lista. O padrão é 100.
after: **String** Retorna os elementos da lista que vêm após o ID global especificado.
startDate: **Datetime** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
endDate: **Datetime** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
cardId: **String** ID do cartão
cardStatus: **String** Status do cartão
brand: **String** Bandeira do cartão
customerId: **String** ID do cliente vinculado ao cartão
holderName: **String** Nome do portador do cartão
*** ## cards Retorna os cartões a partir do novo índice `card`. Mantém paridade de argumentos com `allCards` (o filtro de identificador passa a se chamar `id`). Adiciona novos campos e filtros, incluindo consultas nos objetos aninhados `tokens` e `transactionRequests`.
**QUERY : OBJETO DE RETORNO** **cards: CardV2Connection**
**ARGUMENTO : TIPO** **DESCRIÇÃO**
first: **Int** Retorna os primeiros *n* elementos da lista. O padrão é 100.
after: **String** Retorna os elementos da lista que vêm após o cursor especificado.
id: **\[String]** Filtra por um ou mais IDs de cartão
cardStatus: **\[String]** Status do cartão
tokenStatus: **\[String]** Status do token (consulta no objeto aninhado `tokens`)
customerId: **String** ID do cliente vinculado ao cartão
brand: **String** Bandeira do cartão
holderName: **String** Nome do portador do cartão
sellerId: **String** ID do recebedor (seller) vinculado ao cartão
merchantId: **String** ID do merchant vinculado ao cartão
fingerprint: **String** Fingerprint do cartão
tokenFingerprint: **String** Fingerprint do token (consulta no objeto aninhado `tokens`)
tokenProviderType: **\[String]** Tipo de provider do token (consulta no objeto aninhado `tokens`)
providerType: **\[String]** Tipo de provider (consulta no objeto aninhado `transactionRequests`)
expirationMonth: **String** Mês de expiração do cartão
expirationYear: **String** Ano de expiração do cartão
startDate: **Date** Início do intervalo de criação (`created_at`), no formato yyyy-MM-dd
endDate: **Date** Fim do intervalo de criação (`created_at`), no formato yyyy-MM-dd
updatedStartDate: **Date** Início do intervalo de atualização (`updated_at`), no formato yyyy-MM-dd
updatedEndDate: **Date** Fim do intervalo de atualização (`updated_at`), no formato yyyy-MM-dd
Além dos campos de raiz do cartão (por exemplo `id`, `clientId`, `customerId`, `status`, `brand`, `holderName`, `createdAt`, `updatedAt`, `expirationMonth`, `expirationYear`, `merchants`, `sellers`, `fingerprint`), o objeto de retorno traz os objetos aninhados `tokens` e `transactionRequests`. *** ## card Retorna um único cartão pelo `id` a partir do novo índice `card`.
**QUERY : OBJETO DE RETORNO** **card: CardV2Connection**
**ARGUMENTO : TIPO** **DESCRIÇÃO**
id: **String** ID do cartão a ser consultado
# Queries do grupo Charges na Analytics API Source: https://docs.malga.io/analytics/queries/charges Consultas GraphQL do grupo Charges na Analytics API da Malga, com allCharges, charge e filtros por status, data e provedor de pagamento. Uma cobrança `charge` representa um pagamento realizado através da Malga, que pode englobar diversas transações em provedores de cobrança e de antifraude, contendo as informações sobre o seu processamento. No grupo **Charges** disponibilizamos as seguintes consultas:
`allCharges` Retorna todas as cobranças
`charge` Retorna informações de uma cobrança pelo seu identificador único
`chargesByDeclinedCode` Retorna as cobranças com status failed pelo declined code (motivos de perda)
`totalCharges` Retorna o número de cobranças e o total financeiro de um período
`totalChargesByInterval` Retorna o número de cobranças e o total financeiro por um intervalo selecionado
`totalChargesByPaymentMethod` Retorna o número de cobranças e o total financeiro processados por método de pagamento
`totalChargesByProviderType` Retorna o número de cobranças e o total financeiro processados por provedor de pagamento
*** ## allCharges Retorna todas as cobranças
**QUERY : OBJETO DE RETORNO** **allCharges: ChargeConnection**
**ARGUMENTO : TIPO** **DESCRIÇÃO**
first: **Int** Retorna os primeiros *n* elementos da lista. O padrão é 100
after: **String** Retorna os elementos da lista que vêm após o ID global especificado.
startDate: **Datetime** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
endDate: **Datetime** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
updatedStartDate: **Datetime** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
updatedEndDate: **Datetime** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
status: **\[String!]** Status da transação
providerType: **\[String!]** Nome do provedor
paymentMethod: **\[String!]** Método de pagamento
merchantId: **\[String!]** ID da Subconta
orderId: **\[String!]** Identificador único do cliente para conciliação futura
amount: **Int** Valor da transação
originalAmount: **Int** Valor original da transação enviada ao provedor
totalPaidAmount: **Int** Valor total efetivamente pago pelo comprador na transação. Pode incluir encargos adicionais, como juros ou taxas repassadas ao pagador pelo provedor de pagamento. Atualmente apenas no Mercado Pago. **Os dados desse campo podem levar até 10 minutos para ficarem disponíveis na API após a criação da transação**
## charge Retorna informações de uma cobrança pelo seu identificador único
**QUERY : OBJETO DE RETORNO** **charge: ChargeConnection**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
id: **String** ID da cobrança
authorizationCode: **String** Código de autorização retornado pelo provedor
authorizationNsu: **String** Número de autorização retornado pelo provedor
idempotencyKey: **String** Chave única de referência gerada pela Malga para cada requisição
updatedStartDate: **Datetime** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
updatedEndDate: **Datetime** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd HH:mm:ss.SSSS)
## chargesByDeclinedCode Retorna as cobranças com status failed pelo declined code (motivos de perda)
**QUERY : OBJETO DE RETORNO** **chargesByDeclinedCode: DeclinedCode**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
updatedStartDate: **Datetime!** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd)
updatedEndDate: **Datetime!** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## totalCharges Retorna o número de cobranças e o total financeiro de um período
**QUERY : OBJETO DE RETORNO** **totalCharges: TotalCharges**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
updatedStartDate: **Datetime!** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd)
updatedEndDate: **Datetime!** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
status: **\[String!]** Status da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## totalChargesByInterval Retorna o número de cobranças e o total financeiro por um intervalo selecionado
**QUERY : OBJETO DE RETORNO** **totalChargesByInterval: TotalCharges**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
updatedStartDate: **Datetime!** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd)
updatedEndDate: **Datetime!** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd)
interval: **String!** Intervalo de agrupamento \[DAY, WEEK, MONTH, YEAR]
currency: **String!** Moeda da transação
status: **\[String!]** Status da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## totalChargesByPaymentMethod Retorna o número de cobranças e o total financeiro processados por método de pagamento
**QUERY : OBJETO DE RETORNO** **totalChargesByPaymentMethod: TotalCharges**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
updatedStartDate: **Datetime!** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd)
updatedEndDate: **Datetime!** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
status: **\[String!]** Status da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## totalChargesByProviderType Retorna o número de cobranças e o total financeiro processados por provedor de pagamento
**QUERY : OBJETO DE RETORNO** **totalChargesByProviderType: TotalCharges**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
updatedStartDate: **Datetime!** updatedStartDate (intervalo de datas pelo campo updated\_at, iniciando o range no formato yyyy-MM-dd)
updatedEndDate: **Datetime!** updatedEndDate (intervalo de datas pelo campo updated\_at, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
status: **\[String!]** Status da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
# Queries do grupo Dashboard na Analytics API Source: https://docs.malga.io/analytics/queries/dashboard Queries GraphQL do grupo Dashboard na Analytics API da Malga: providersResume para taxa de autorização por provedor e chargeCurrencies para moedas. O grupo de consultas **Dashboard** disponibiliza informações para o [Painel de Dados](https://dashboard.malga.io) da Malga, que também estão disponíveis para consulta pela Analytics API:
`providersResume` Retorna a taxa de autorização por provedor de pagamento
`chargeCurrencies` Retorna as moedas em que a empresa processa pagamentos
*** ## providersResume Retorna a taxa de autorização por provedor de pagamento
**QUERY : OBJETO DE RETORNO** **providersResume: ProvidersResume**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
startDate: **Datetime!** startDate (intervalo de datas, iniciando o range no formato yyyy-MM-dd)
endDate: **Datetime!** endDate (intervalo de datas, finalizando o range no formato yyyy-MM-dd)
currency: **String!** Moeda da transação
merchantId: **\[String!]** Lista de subcontas (merchantId's) das transações
## chargeCurrencies Retorna as moedas em que a empresa processa pagamentos
**QUERY : OBJETO DE RETORNO** **chargeCurrencies: ChargeCurrencies**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
currency: **String!** Moeda da transação
## merchants Retorna as subcontas (merchants) cadastradas
**QUERY : OBJETO DE RETORNO** **merchants: Merchants**
**ARGUMENTO : OBJETO** **DESCRIÇÃO**
environment: **\[EnvironmentEnum!]** Ambiente das subcontas, podendo ser `SANDBOX` (retorna todas as subcontas com provedores de Sandbox), `PRODUCTION` (retorna todas com provedor de produção) e, não enviando nenhum, todas disponíveis são retornadas
# Queries do grupo Subacquirer na Analytics API Source: https://docs.malga.io/analytics/queries/subacquirer Consultas GraphQL do grupo Subacquirer na Analytics API da Malga, com a query balance para saldo disponível e a receber do subadquirente. O grupo **Subacquirer** disponibiliza consultas relacionadas ao saldo do subadquirente, com paridade com a API oficial `/v1/payouts/balance`. No grupo **Subacquirer** disponibilizamos as seguintes consultas:
`balance` Retorna o saldo disponível e o saldo a receber do subadquirente
*** ## balance Retorna o saldo disponível e o saldo a receber do subadquirente
**QUERY : OBJETO DE RETORNO** **balance [\[SubacquirerBalance\]](/analytics/objects/subacquirer-balance)**
**ARGUMENTO : TIPO** **DESCRIÇÃO**
feature: **String** Feature do saldo. Valores possíveis: `NUPAY`, `SUBACQUIRER`, `GENERAL`, `SUBACQUIRER_PREPAYMENT`. O padrão é `SUBACQUIRER`
sellerId: **String** ID do recebedor (seller). Quando informado, retorna o saldo do client daquele seller; quando omitido, retorna o saldo do client master
# Criar um novo setup Source: https://docs.malga.io/api-reference/3ds-malga/criar-um-novo-setup post /v1/charges/3ds/setup Crie uma nova sessão de setup para autenticação 3DS2 Malga, iniciando o fluxo de autenticação do portador antes da cobrança no cartão de crédito. # Sobre as APIs da Malga Source: https://docs.malga.io/api-reference/about-apis Conheça as APIs da Malga para integração de pagamentos online, com autenticação segura via headers HTTP e acesso a múltiplos provedores de pagamento. A Malga oferece uma API completa para integração de pagamentos. A autenticação é feita via headers HTTP para todas as chamadas da API. É necessário informar o identificador do cliente (`X-Client-Id`) e a chave secreta de acesso (`X-Api-Key`) em cada requisição. [Clique aqui](/api-reference/authentication) e leia nossa documentação sobre a autenticação e tenha acesso ao conjunto de ferramentas para desenvolvimento que facilitarão a integração. ## Coleção de testes em sandbox Para facilitar sua integração e validações, disponibilizamos uma [**coleção pronta para testes**](https://www.postman.com/joint-operations-engineer-24793538/sandbox-malga/collection/34oyc6z/sandbox-malga?action=share\&creator=38848934) em nosso ambiente de sandbox. Nela, você encontra todos os endpoints e exemplos de payloads necessários para simular fluxos de pagamento, autenticação 3DS, operações de reembolso, tokenização e muito mais. **Como usar:** 1. Importe a coleção no Postman (ou ferramenta compatível). 2. Atualize as variáveis de ambiente com suas credenciais de sandbox (API Key, Merchant ID, clientId). 3. Escolha o cenário desejado e execute as requisições. 4. Analise as respostas e compare com a documentação detalhada para entender cada campo e status. ## Configurações da API A nossa API oferece endpoints para diversas funcionalidades. Comece a estruturar sua integração com a Malga explorando as páginas abaixo. ### Chaves para autenticação > [card] [Sub-keys](/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side) > > Crie e remova sub-keys: chaves com escopo e tempo de validade limitados para > aplicações back-end com acesso reduzido ou para o client-side, sem expor a > chave secreta da sua conta. ### Cartões > [card] [Tokens](/api-reference/tokens/) > > Utilize o serviço de Tokenização para coletar os dados de cartão dos seus clientes, sem que informações sensíveis trafeguem no seu servidor. Através dos tokens, você processa pagamentos de forma segura, atendendo às normas PCI > [card] [Cards](/api-reference/cards/) > > Crie e armazene cartões dos seus clientes com segurança para realizar novas cobranças ### Pagamentos > [card] [Charges](/api-reference/charges/) > > Crie cobranças com os métodos de pagamento disponíveis na Malga. É possível recuperar detalhes de transações individuais ou listá-las a partir do seu `X-Client-Id`; > [card] [Sessions](/api-reference/sessions/) > > Crie sessões para gerar pedidos com itens, com métodos de pagamento e outros atributos associados, que podem ser pagos através da nossa API, pelo Link de Pagamento ou integrado ao nosso Malga Checkout/Full; > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Utilize o serviço de 3DS2 Malga para autenticar transações com cartão de crédito, garantindo a segurança das transações e inversão de responsabilidade em caso de chargeback. > [card] [Customers](/api-reference/customers/) > > Realize a criação, edição, listagem e exclusão de dados de compradores para busca de cobranças e uso nos serviços de tokenização de cartões, cobrança por Pix, Boleto, uso em análise de motores de antifraude e de recorrência; > [card] [Merchants](/api-reference/merchants) > > O merchant (subconta) é a entidade que representa sua loja ou negócio na Malga e que guarda as chaves de provedores. Ele é utilizado para processar cobranças e separar operações, recebíveis e dados de cada loja ou cliente; > [card] [Vendors](/api-reference/vendors) > > Serviço que permite que facilitadores habilitem estabelecimentos comerciais para aceitação de pagamentos e que os beneficiários finais das transações sejam identificados na cobrança. Este serviço deve ser utilizado por negócios que possuem essa exigência regulatória; > [card] [Sellers](/api-reference/sellers) > > Realize a criação e a configuração de recebedores para transações com Split. > Um seller é um cadastro de PF ou PJ, com regras de recebimento associadas e > registrados nos provedores, para quem você irá repassar automaticamente > valores de uma cobrança; ### Configurações > [card] [Webhooks](/api-reference/webhooks/) > > Notifique o seu sistema sobre os eventos ocorridos na Malga. Através de webhooks, você consegue atualizar seu sistema sempre que um evento importante acontece > [card] [Flows](/api-reference/flows/) > > Através da API Flows, você pode conferir os fluxos de pagamentos da sua loja > ou merchant. Os fluxos inteligentes são um recurso da Malga para gestão > flexível dos pagamentos, possibilitando a inserção de regras e condicionais > para o processamento das cobranças > [card] [Analytics](/analytics/) > > Com a API de Analytics é possível consultar dados de transações processadas, > permitindo análises gerenciais e acompanhamento dos pagamentos > [card] [Settings](/api-reference/settings/) > > Customize o checkout (link de pagamento) com as cores e o logo da sua empresa utilizando a API de settings. # Autenticação Source: https://docs.malga.io/api-reference/authentication Autenticação na API da Malga: use os headers HTTP X-Client-Id e X-Api-Key com suas chaves de acesso geradas no Dashboard de cada conta. Os serviços de API da Malga são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu dashboard. É importante armazenar suas chaves de maneira privada e segura uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação. A Autenticação para todas as chamadas da API é feita através de headers HTTP, sendo necessário informar seu identificador de cliente na Malga e a chave secreta de acesso. ## X-Client-ID Identificador único da sua conta na Malga. Deve ser enviado no header obrigatoriamente em todas as requisições feitas à API. | Security Scheme Type | API Key | | - | - | | Header parameter name | `X-Client-ID` | ## X-Api-Key Sua chave de acesso à API. Funciona em par com o client-id devendo ser enviado no header obrigatoriamente em todas as requisições feitas à API. | Security Scheme Type | API Key | | - | - | | Header parameter name | `X-Api-Key` | ## Exemplo de requisição autenticada ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' ``` # Criar novo cartão a partir de token Source: https://docs.malga.io/api-reference/cards/criar-novo-cartao-a-partir-de-token post /v1/cards # Listar cartões Source: https://docs.malga.io/api-reference/cards/listar-cartoes get /v1/cards # Recuperar detalhes de cartão Source: https://docs.malga.io/api-reference/cards/recuperar-detalhes-de-cartao get /v1/cards/{id} # Alterar o status de uma cobrança no ambiente de sandbox Source: https://docs.malga.io/api-reference/charges/alterar-o-status-de-uma-cobranca-no-ambiente-de-sandbox post /v1/charges/{id} # Alterar o status do antifraude no ambiente de sandbox Source: https://docs.malga.io/api-reference/charges/alterar-o-status-do-antifraude-no-ambiente-de-sandbox patch /v1/charges/{id}/antifraud # Capturar cobrança pre-autorizada Source: https://docs.malga.io/api-reference/charges/capturar-cobranca-pre-autorizada post /v1/charges/{id}/capture # Estornar cobrança aprovada Source: https://docs.malga.io/api-reference/charges/estornar-cobranca-aprovada post /v1/charges/{id}/void # Listar cobranças Source: https://docs.malga.io/api-reference/charges/listar-cobrancas get /v1/charges # Realizar nova cobrança Source: https://docs.malga.io/api-reference/charges/realizar-nova-cobranca post /v1/charges Crie uma nova cobrança na API da Malga via POST /v1/charges, com suporte a cartão de crédito, Pix, boleto, voucher e demais meios de pagamento. # Recuperar detalhes de cobrança Source: https://docs.malga.io/api-reference/charges/recuperar-detalhes-de-cobranca get /v1/charges/{id} # Criar sub-key Source: https://docs.malga.io/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side post /v1/auth Crie uma sub-key com escopo e tempo de validade limitados para usar em aplicações back-end com acesso reduzido ou no client-side, sem expor a chave secreta da sua conta. A chave secreta da sua conta dá acesso a toda a API. Em vez de distribuí-la entre as suas aplicações, crie sub-keys: chaves derivadas da chave secreta, que só acessam os escopos que você escolher e deixam de funcionar quando expiram. Você gerencia as sub-keys pela API, sem abrir chamado com a Malga: crie quantas precisar, cada uma com os próprios escopos e validade, e [remova](/api-reference/client-token/remover-sub-key) as que não usa mais. ## Onde usar sub-keys > [card] Aplicações back-end > > Dê a cada serviço ou time uma sub-key só com os escopos de que ele precisa. Por exemplo, uma ferramenta interna de atendimento que só estorna cobranças recebe uma sub-key com o escopo `charges/*/void`. > [card] Aplicações client-side > > No navegador ou em aplicativos, use sub-keys de curta duração e, de preferência, só com o escopo `tokens`, para tokenizar cartões. Crie uma sub-key nova a cada sessão de compra. ## Como funciona **1. Crie a sub-key no seu servidor** Chame `POST /v1/auth` com o `X-Client-Id` e a chave secreta da sua conta no `X-Api-Key`. A chave secreta precisa ter o escopo `*` ou `auth`. **2. Entregue a sub-key à aplicação** Repasse o `publicKey` da resposta para o serviço, o navegador ou o aplicativo que vai usá-lo. A chave secreta continua só no seu servidor. **3. Use a sub-key nas chamadas** Envie o `publicKey` no header `X-Api-Key`, junto com o mesmo `X-Client-Id` da sua conta. ## Exemplo de criação ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/auth' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "scope": ["tokens"], "expires": 3600 }' ``` Resposta `201`: ```json theme={null} { "publicKey": "YOUR_PUBLIC_KEY", "clientId": "YOUR_CLIENT_ID", "scope": ["tokens"], "expires": 3600, "createdAt": "2026-09-30T14:00:00.000Z" } ``` Com a sub-key criada, o front-end pode tokenizar um cartão: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/tokens' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_PUBLIC_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4019598346009339", "cardCvv": "123", "cardExpirationDate": "12/2026" }' ``` ## Tempo de validade (`expires`) O campo `expires` é obrigatório e define por quantos segundos a sub-key vale, contados a partir da criação. Depois desse prazo, as chamadas com a sub-key são recusadas com `403`. Para invalidar uma sub-key antes do prazo, [remova a sub-key](/api-reference/client-token/remover-sub-key). | `expires` | Validade | Quando usar | | - | - | - | | `900` | 15 minutos | Uma tela de pagamento: crie a sub-key quando o cliente abrir o checkout | | `3600` | 1 hora | Jornadas de compra mais longas | | `86400` | 24 horas | Ferramentas internas usadas ao longo do dia | | `2592000` | 30 dias | Integrações em que a sub-key fica configurada por mais tempo | | `0` | Sem expiração | Aplicações back-end em que a sub-key não fica exposta, como a Analytics API em um servidor. Troque a sub-key de tempos em tempos | > [!WARNING] > > Para sub-keys usadas no navegador ou em aplicativos, prefira um prazo curto e crie uma sub-key nova a cada sessão de compra. Evite `0`: uma sub-key sem expiração continua válida se for copiada do front-end. ## Escopos (`scope`) O campo `scope` é obrigatório e recebe uma lista com um ou mais escopos. Cada escopo libera **todos os métodos HTTP** no recurso `/v1/` e em todos os caminhos abaixo dele. Por exemplo, o escopo `charges` libera `GET /v1/charges/{id}`, `POST /v1/charges`, `POST /v1/charges/{id}/capture` e `POST /v1/charges/{id}/void`. Para liberar só uma operação, use os escopos com `*` no lugar do `id`, como `charges/*/void`. | Escopo | O que libera | | - | - | | `tokens` | Tokenização de cartões (`/v1/tokens`) | | `cards` | Cartões salvos (`/v1/cards`) | | `customers` | Clientes e os cartões de cada cliente (`/v1/customers`) | | `charges` | Cobranças e todas as operações sobre elas, inclusive captura e estorno (`/v1/charges`) | | `charges/*/capture` | Somente a captura de cobranças pré-autorizadas | | `charges/*/void` | Somente o estorno de cobranças | | `sessions` | Sessões de pagamento (`/v1/sessions`) | | `purchases` | Vendas e todas as operações sobre elas (`/v1/purchases`) | | `purchases/*/capture`, `purchases/*/void`, `purchases/*/history` | Somente a captura, o cancelamento ou estorno, ou o histórico de uma Venda | | `subscriptions` | Motor de Assinaturas (`/v1/subscriptions`) | | `flows` | Fluxos inteligentes (`/v1/flows`) | | `sellers` | Sellers do Split de pagamentos (`/v1/sellers`) | | `providers` | Provedores (`/v1/providers`) | | `merchants` | Merchants (`/v1/merchants`) | | `vendors` | Vendors (`/v1/vendors`) | | `webhooks` | Configuração de webhooks (`/v1/webhooks`) | | `graphql` | [Analytics API](/analytics/authentication/authentication) (`POST /v1/graphql`) | | `auth` | Criação e remoção de sub-keys (`/v1/auth`) | Um escopo fora da lista retorna `422`, e uma chamada a um recurso fora dos escopos da sub-key retorna `403`. > [!WARNING] > > Libere só o que cada aplicação precisa. No checkout, `tokens` costuma ser suficiente. Não use no client-side escopos que alteram a sua conta ou movimentam dinheiro, como `charges`, `purchases`, `webhooks`, `merchants` e `auth`: com eles, qualquer pessoa que copiar a sub-key do navegador pode, por exemplo, estornar cobranças ou criar e remover chaves. Reserve o escopo `auth` para o servidor que gerencia as suas sub-keys. ### Exemplos de escopo ```json Tokenização no checkout theme={null} { "scope": ["tokens"], "expires": 900 } ``` ```json Tokenização e cartões salvos theme={null} { "scope": ["tokens", "cards"], "expires": 900 } ``` ```json Somente estorno theme={null} { "scope": ["charges/*/void"], "expires": 86400 } ``` ```json Analytics API theme={null} { "scope": ["graphql"], "expires": 0 } ``` ## Erros comuns | HTTP code | Quando acontece | O que fazer | | - | - | - | | `400` | O corpo tem campos fora do contrato, `scope` não é uma lista ou `expires` é negativo | Envie só `scope` (lista) e `expires` (número maior ou igual a `0`) | | `403` | Na criação: a chave secreta não existe, não pertence ao `X-Client-Id` ou não tem o escopo `*` ou `auth`. No uso: a sub-key expirou ou foi removida, o `X-Client-Id` é de outra conta ou o recurso está fora dos escopos | Confira as chaves e os escopos. Se a sub-key expirou ou foi removida, crie uma nova | | `422` | Um ou mais escopos não são válidos | Use os escopos da tabela acima | Exemplo de resposta `422`: ```json theme={null} { "statusCode": 422, "message": "payments is not a valid scope.", "error": "Unprocessable Entity" } ``` Veja também [Gestão de chaves](/documentations/welcome/authentication#gestão-de-chaves). # Remover sub-key Source: https://docs.malga.io/api-reference/client-token/remover-sub-key delete /v1/auth/{id} Remova uma sub-key antes do fim da validade para fazer uma rotação manual ou bloquear uma sub-key exposta. Toda sub-key expira sozinha quando termina o tempo definido no campo `expires`, na [criação](/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side). Você também pode remover uma sub-key antes desse prazo, por exemplo para: * fazer uma rotação manual: crie uma sub-key nova, atualize a aplicação e remova a anterior; * bloquear uma sub-key que foi exposta ou que uma aplicação não usa mais; * invalidar uma sub-key criada com `expires` igual a `0`, que não expira sozinha. Depois da remoção, as chamadas feitas com a sub-key são recusadas com `403`. As outras sub-keys e a chave secreta da sua conta continuam funcionando. ## Pré-requisitos * O `publicKey` da sub-key, retornado na criação. Ele é o `id` da rota. * A chave secreta da sua conta, ou outra chave com o escopo `*` ou `auth`. Faça a chamada no seu servidor. * A sub-key precisa pertencer ao mesmo `X-Client-Id` da chamada. ## Exemplo de remoção ```bash theme={null} curl --location --request DELETE 'https://api.malga.io/v1/auth/YOUR_PUBLIC_KEY' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` A resposta de sucesso é `200`, sem corpo. ## Rotação manual **1. Crie uma sub-key nova** Chame `POST /v1/auth` com os mesmos escopos da sub-key atual. **2. Atualize a aplicação** Troque a sub-key antiga pela nova na aplicação e confirme que as chamadas funcionam. **3. Remova a sub-key antiga** Chame `DELETE /v1/auth/{id}` com o `publicKey` da sub-key antiga. ## Erros comuns | HTTP code | Quando acontece | O que fazer | | - | - | - | | `403` | A chave usada na chamada não existe, não pertence ao `X-Client-Id` ou não tem o escopo `*` ou `auth` | Faça a chamada com a chave secreta da sua conta | Veja também [Gestão de chaves](/documentations/welcome/authentication#gestão-de-chaves). # Adicionar cartão de crédito ao customer Source: https://docs.malga.io/api-reference/customers/adicionar-cartao-de-credito-ao-customer post /v1/customers/{customer_id}/cards # Atualizar customer pelo id Source: https://docs.malga.io/api-reference/customers/atualizar-customer-pelo-id patch /v1/customers/{id} # Criação de novo customer para cobrança Source: https://docs.malga.io/api-reference/customers/criacao-de-novo-customer-para-cobranca post /v1/customers # Deletar customer pelo id Source: https://docs.malga.io/api-reference/customers/deletar-customer-pelo-id delete /v1/customers/{id} # Listagem de customers cadastrados Source: https://docs.malga.io/api-reference/customers/listagem-de-customers-cadastrados get /v1/customers # Listagem dos cartões do customer Source: https://docs.malga.io/api-reference/customers/listagem-dos-cartoes-do-customer get /v1/customers/{customer_id}/cards # Recuperar detalhes de customer Source: https://docs.malga.io/api-reference/customers/recuperar-detalhes-de-customer get /v1/customers/{id} # Consultar um fluxo pelo id Source: https://docs.malga.io/api-reference/flows/consultar-um-fluxo-pelo-id get /v1/flows/{id} # Recuperar todos os fluxos paginado Source: https://docs.malga.io/api-reference/flows/recuperar-todos-os-fluxos-paginado get /v1/flows # Ativar ou desativar platform fee do merchant Source: https://docs.malga.io/api-reference/merchants/ativar-desativar-platform-fee patch /v1/merchants/{merchantId}/platform-fee/enabled Liga ou desliga a platform fee da subconta. A flag vale para a subconta inteira e para todos os sellers dela: não existe flag por seller. Para um seller não pagar taxa, cadastre para ele uma regra com `percentage: 0` e `fixedAmount: 0`. Para ligar, a subconta precisa ter ao menos uma regra ativa própria. Regras de seller não contam: uma subconta só com regras de seller responde `400` com `PLATFORM_FEE_RULES_REQUIRED_TO_ENABLE`. Desligar é sempre aceito. # Atualizar configurações de merchant Source: https://docs.malga.io/api-reference/merchants/atualizar-configuracoes-de-merchant patch /v1/merchants/{id} # Atualizar regras de platform fee Source: https://docs.malga.io/api-reference/merchants/atualizar-regras-de-platform-fee put /v1/merchants/{merchantId}/platform-fee Atualiza as regras de platform fee da subconta. Aceita o mesmo corpo do `POST`, em array ou em objeto com a lista em `rules`. O efeito depende da forma usada em cada objeto: - **Regra avulsa** (`paymentMethod`, com `installment` quando for `credit`): atualiza a regra existente com o mesmo método e a mesma parcela, e só os campos enviados. Se a regra não existir, retorna `404`: o `PUT` não cria regra avulsa. - **Tabela ou fórmula de `credit`** (`installmentRates`, `installments` ou fórmula): substitui a tabela de crédito inteira. Atualiza as parcelas que já existem, cria as que faltam e remove as que ficaram de fora da nova tabela. As regras de `pix` e `boleto` e a regra de crédito sem `installment` não são alteradas. Na substituição, a tabela enviada passa a ser a tabela inteira. Enviar três parcelas numa subconta que tinha doze deixa a subconta com três, e as parcelas removidas passam a seguir o comportamento de parcela sem regra própria. O `PUT` é aplicado por inteiro ou não é aplicado. Se qualquer regra avulsa do corpo não existir, a resposta é `404` e nada muda, nem a tabela de crédito enviada no mesmo corpo. O mesmo método não pode aparecer duas vezes como tabela, nem como tabela e regra avulsa, no mesmo corpo. # Atualizar regras de platform fee de um seller Source: https://docs.malga.io/api-reference/merchants/atualizar-regras-de-platform-fee-do-seller put /v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee Atualiza as regras próprias do seller. Aceita o mesmo corpo do `POST` desta rota e segue as mesmas regras do `PUT /v1/merchants/{merchantId}/platform-fee`, aplicadas só às regras do seller: - **Regra avulsa**: atualiza a regra do seller com o mesmo método e a mesma parcela, e só os campos enviados. Se o seller não tiver essa regra, retorna `404` e nada muda. - **Tabela ou fórmula de `credit`**: substitui a tabela de crédito do seller inteira. A tabela da subconta e a de outros sellers não mudam. As parcelas que ficaram de fora da nova tabela do seller passam a seguir a regra da subconta. No crédito, o seller aceita só percentual. Um `PUT` que deixaria valor fixo diferente de 0 numa regra de crédito do seller é recusado com `400`. Um `PUT` só com `percentage: 0` mantém o `fixedAmount` gravado e não isenta o seller. Para isentar, envie os dois campos com 0 na mesma regra. # Criação de novo merchant para cobrança Source: https://docs.malga.io/api-reference/merchants/criacao-de-novo-merchant-para-cobranca post /v1/merchants Cria uma nova subconta (merchant) vinculada ao `X-Client-Id` informado no header. O campo `status` indica o estado da subconta: `true` para ativa e `false` para inativa. É opcional — quando omitido, a subconta é criada como ativa. # Criar regras de platform fee Source: https://docs.malga.io/api-reference/merchants/criar-regras-de-platform-fee post /v1/merchants/{merchantId}/platform-fee Cria as regras de platform fee da subconta. O corpo aceita um array de regras ou um objeto com a lista em `rules`. As duas formas têm o mesmo efeito. O corpo aceita até 50 objetos de regra, e uma tabela ou fórmula de crédito conta como um objeto. Não existe regra genérica: `paymentMethod: default` é recusado com `400` e `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`. Cadastre regra para cada método que você vende e, no crédito, para cada parcela. Com a platform fee ligada, a venda num método ou numa parcela sem regra na subconta nem no seller é recusada com `422` e `platform_fee_rule_not_configured`. No cartão de crédito, a taxa é definida por parcela exata, de 1x a 24x, e cada parcela pode ter um valor diferente. A tabela de crédito pode ser cadastrada de três formas, uma por objeto de regra: | Forma | Campos | Uso | |---|---|---| | Regra avulsa | `installment`, com `percentage` e/ou `fixedAmount` | Uma parcela por objeto | | Tabela | `installmentRates` (curta) ou `installments` (longa) | A tabela inteira num objeto só | | Fórmula | `maxInstallments`, `base`, `growth`, `surcharges`, `overrides` e `cap` | A Malga gera a tabela a partir de uma regra de crescimento | Qualquer que seja a forma, a Malga grava uma regra por parcela. A fórmula é calculada no cadastro e não fica armazenada: a resposta e o `GET` trazem a tabela gerada. O mesmo método não pode aparecer duas vezes como tabela, nem como tabela e regra avulsa, no mesmo corpo. Se alguma parcela já tiver regra, a requisição retorna `409`; para alterar uma tabela existente, use `PUT /v1/merchants/{merchantId}/platform-fee`. # Criar regras de platform fee de um seller Source: https://docs.malga.io/api-reference/merchants/criar-regras-de-platform-fee-do-seller post /v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee Cria regras de platform fee próprias de um seller dentro da subconta. A regra do seller substitui a regra da subconta para ele, método a método e só nas parcelas que ela cobre. O que a regra do seller não cobre segue a regra da subconta. O corpo aceita as mesmas formas do `POST /v1/merchants/{merchantId}/platform-fee`: regra avulsa, `installmentRates`, `installments` e fórmula, em array ou em objeto com a lista em `rules`. As diferenças para a regra da subconta: - No crédito, a regra do seller aceita só percentual por parcela. Qualquer `fixedAmount` diferente de 0, em qualquer forma do corpo, recusa a requisição com `400`. Em `pix` e `boleto`, o seller aceita percentual, valor fixo ou os dois. Como na subconta, `paymentMethod: default` é recusado com `400` e `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`, e o corpo aceita até 50 objetos de regra. O seller precisa estar cadastrado nesta subconta. Seller de outro cliente, de outra subconta ou sem subconta responde `404` com `PLATFORM_FEE_SELLER_NOT_FOUND`, com o mesmo corpo nos três casos. Para isentar o seller num método, envie `percentage: 0` e `fixedAmount: 0` na mesma regra. Para ele voltar a seguir a regra da subconta, apague a regra dele com `DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}`. A resposta traz as regras gravadas e um aviso fixo em `warnings` sobre assinaturas com split por valor. # Deletar merchant pelo id Source: https://docs.malga.io/api-reference/merchants/deletar-merchant-pelo-id delete /v1/merchants/{id} # Deletar uma regra de platform fee pelo ID Source: https://docs.malga.io/api-reference/merchants/deletar-regras-de-platform-fee delete /v1/merchants/{merchantId}/platform-fee/{platformFeeId} Remove uma regra pelo `id`, seja da subconta ou de um seller dela. Apagar a regra de um seller faz ele voltar a seguir a regra da subconta naquele método ou parcela. Com a platform fee ligada, a última regra da subconta não pode ser removida: a resposta é `400` com `PLATFORM_FEE_RULES_REQUIRED_WHILE_ENABLED`, e a regra continua. Crie outra regra da subconta antes ou desligue a platform fee. Regras de seller não contam e podem ser removidas sempre. # Listagem de merchants cadastrados Source: https://docs.malga.io/api-reference/merchants/listagem-de-merchants-cadastrados get /v1/merchants # Listar regras de platform fee Source: https://docs.malga.io/api-reference/merchants/listar-regras-de-platform-fee get /v1/merchants/{merchantId}/platform-fee Retorna as regras gravadas da subconta e dos sellers dela, o estado de cada método e parcela e, quando `simulationAmount` é enviado, a taxa calculada por método de pagamento e, no cartão de crédito, por parcela. - `rules`: as regras da subconta como estão gravadas. No crédito, uma regra por parcela. As regras de seller não entram aqui. - `sellerRules`: um item por seller com ao menos uma regra própria ativa, ordenados por `sellerId`, cada um com as regras dele no mesmo formato de `rules`. - `coverage`: o estado de `pix`, `boleto` e de cada parcela de `credit`, para a subconta em `coverage.merchant` e para cada seller de `sellerRules` em `coverage.sellers`, mais avisos em texto. - `simulation`: o valor de venda usado nas contas em dinheiro. Só com `simulationAmount`. - `methods`: a taxa que a cobrança aplicaria em cada método com a regra da subconta. No crédito, a lista `installments` traz sempre as 24 parcelas. Só com `simulationAmount`. - `sellerRules[].methods`: a mesma conta para cada seller, como se ele recebesse o valor simulado inteiro, com `scope` dizendo se vale a regra dele ou a da subconta. Só com `simulationAmount`. `platformFeeEnabled`, `rules`, `sellerRules` e `coverage` vêm sempre. `simulation`, `methods` e `sellerRules[].methods` só vêm com `simulationAmount`. Estados de `coverage`: | Estado | Significado | |---|---| | `own` | Regra própria que cobra algo | | `exempt` | Regra própria com `percentage: 0` e `fixedAmount: 0` | | `inherits` | Só em seller. Sem regra própria, segue a regra da subconta | | `missing` | Sem regra em nenhum nível. Com a platform fee ligada, a venda é recusada com `platform_fee_rule_not_configured` | Um seller sem regra própria num método ou parcela em que a subconta está em `missing` também aparece como `missing`, e não como `inherits`. A taxa incide sobre o valor total da venda, e não sobre o valor de cada parcela: `fee = floor(amount * percentage / 100) + fixedAmount`, e `sellerNet = amount - fee`. Quando a taxa é maior ou igual ao valor simulado, a venda seria recusada, e o item vem com `accepted: false` e `reason: fee_exceeds_amount`. `source` é sempre `rule`: a taxa vem da regra cadastrada para o método ou a parcela. No crédito, sem regra para a parcela, vale a regra de crédito sem `installment` da subconta, quando ela existe. Essa regra vem da conversão da antiga regra `default` e não é criada pela API. Sem nenhuma regra, o método ou a parcela vem com `accepted: false`, `reason: no_rule_configured` e sem os campos de taxa. # Listar regras de platform fee de um seller Source: https://docs.malga.io/api-reference/merchants/listar-regras-de-platform-fee-do-seller get /v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee Retorna as regras próprias ativas do seller nesta subconta e a flag de ativação da subconta. `rules` vem vazia quando o seller segue a regra da subconta em todos os métodos. Para ver as regras de todos os sellers junto com as da subconta, e o estado de cada método e parcela, use `GET /v1/merchants/{merchantId}/platform-fee`. # Recuperar detalhes de merchant pelo id Source: https://docs.malga.io/api-reference/merchants/recuperar-detalhes-de-merchant-pelo-id get /v1/merchants/{id} # Consultar ordem de pagamento pelo ID Source: https://docs.malga.io/api-reference/payouts/consultar-ordem-pelo-id get /v1/payouts/orders/{id} # Consultar repasse pelo ID Source: https://docs.malga.io/api-reference/payouts/consultar-payment-batch-pelo-id get /v1/payouts/payment-batches/{id} # Consultar saldo Source: https://docs.malga.io/api-reference/payouts/consultar-saldo-de-payouts get /v1/payouts/balance Retorna o saldo disponível e a receber da nossa subadquirente # Listar ordens de pagamento Source: https://docs.malga.io/api-reference/payouts/listar-ordens get /v1/payouts/orders Lista paginada das ordens de pagamento da nossa subadquirente. # Listar ordens de pagamento de um repasse Source: https://docs.malga.io/api-reference/payouts/listar-ordens-de-um-payment-batch get /v1/payouts/payment-batches/{id}/orders Lista paginada das ordens de pagamento que compõem um repasse. # Listar repasses Source: https://docs.malga.io/api-reference/payouts/listar-payment-batches get /v1/payouts/payment-batches Listagem paginada dos repasses realizados na subadquirente # Confirmar antecipação (aceite) Source: https://docs.malga.io/api-reference/prepayment/confirmar-antecipacao post /v1/subacquirer/prepayment/{id}/commit > **🚧 Beta** — esta API está em fase Beta e detalhes do contrato podem evoluir nas próximas versões. Confirma o aceite de uma simulação, efetivando a antecipação. Para receber em D+1, o aceite precisa acontecer até as **15h (horário de Brasília)** do dia em que a simulação foi criada. Após esse horário, a simulação fica expirada e é preciso simular novamente. # Recuperar detalhes de uma antecipação Source: https://docs.malga.io/api-reference/prepayment/consultar-antecipacao get /v1/subacquirer/prepayment/{id} > **🚧 Beta** — esta API está em fase Beta e detalhes do contrato podem evoluir nas próximas versões. Retorna os detalhes de uma simulação ou antecipação pelo seu identificador. Se a simulação ainda está com status `pending` mas o horário atual já passou do `expiresAt` (15h, horário de Brasília), o `status` retornado vem como `expired` automaticamente. Nesse caso, basta criar uma nova simulação. # Consultar recebíveis disponíveis para antecipação Source: https://docs.malga.io/api-reference/prepayment/consultar-recebiveis-disponiveis-para-antecipacao get /v1/subacquirer/prepayment/receivables > **🚧 Beta** — esta API está em fase Beta e detalhes do contrato podem evoluir nas próximas versões. Lista os recebíveis disponíveis para antecipação avulsa e retorna um resumo com o valor total disponível e a quantidade de recebíveis. Quando `sellerId` é informado, a consulta é feita sobre os recebíveis do recebedor correspondente. Sem `sellerId`, opera sobre a conta principal. # Listar antecipações Source: https://docs.malga.io/api-reference/prepayment/listar-antecipacoes get /v1/subacquirer/prepayment > **🚧 Beta** — esta API está em fase Beta e detalhes do contrato podem evoluir nas próximas versões. Lista as simulações e antecipações da sua conta, da mais recente para a mais antiga, com paginação. Cada item da lista traz exatamente o mesmo conteúdo retornado por `GET /v1/subacquirer/prepayment/{id}`, então não é preciso consultar cada antecipação individualmente para ver os detalhes. Simulações com status `pending` que já passaram do `expiresAt` são retornadas com o status `expired`, seguindo a mesma regra da consulta por identificador. # Simular antecipação Source: https://docs.malga.io/api-reference/prepayment/simular-antecipacao post /v1/subacquirer/prepayment > **🚧 Beta** — esta API está em fase Beta e detalhes do contrato podem evoluir nas próximas versões. Cria uma simulação de antecipação para o **período que termina em `endDate`**. A Malga inclui **todos os recebíveis elegíveis com data prevista de recebimento até `endDate` (inclusive)** e calcula o valor líquido a ser recebido pelo cliente, junto com o desconto aplicado. A simulação fica válida até as **15h (horário de Brasília)** do dia em que foi criada (campo `expiresAt`). Para receber em D+1, o aceite precisa acontecer dentro desse prazo. # Atualizar configurações de provedores do merchant Source: https://docs.malga.io/api-reference/providers/atualizar-configuracoes-de-provider-de-merchant patch /v1/providers/{id} # Cancelar ou estornar uma Venda Source: https://docs.malga.io/api-reference/purchases/cancelar-ou-estornar-venda post /v1/purchases/{id}/void Rota única para desfazer uma Venda, com o campo opcional `intent`: - `cancel`: cancela as pré-autorizações de uma Venda `pending` com todos os cartões `pre_authorized`. Responde `202` com `operation.type: void` e a Venda termina `cancelled`. - `refund`: estorna o valor integral de uma Venda `paid`. Responde `202` com `operation.type: refund` e a Venda permanece `paid`. Sem `intent` (corpo vazio, `{}` ou `intent: ""`), a Malga decide pelo estado da Venda: `paid` estorna e os demais estados cancelam, com as mesmas regras acima. Envie `intent` explicitamente para garantir que um cancelamento nunca vire estorno caso a Venda seja capturada entre a sua leitura e a chamada. Campos extras no corpo (como `amount`) devolvem `400`. Sem `X-Idempotency-Key`, ou com `intent` fora do enum, a API devolve `422` com `invalid_request`. Reenviar a mesma chave com o mesmo corpo devolve `202` com o estado atual da Venda. Casos de `409`: - `idempotency_key_payload_mismatch`: a chave já foi usada com outro corpo ou em outra operação. - `purchase_operation_in_progress`: já existe uma operação em andamento e você enviou uma chave nova. - `purchase_intent_mismatch`: `cancel` em Venda `paid`, ou `refund` em Venda com cartões apenas pré-autorizados. Nenhum valor é movimentado. - `purchase_invalid_state`: estado misto, Venda `failed` ou `cancelled`, ou sem saldo estornável. # Capturar uma Venda pré-autorizada Source: https://docs.malga.io/api-reference/purchases/capturar-venda-pre-autorizada post /v1/purchases/{id}/capture Captura os cartões `pre_authorized` de uma Venda criada com `capture: false` e responde `202` com `operation.type: capture`. O corpo da requisição é opcional e, quando enviado, deve ser `{}`: qualquer campo extra devolve `400`. Se a Venda estiver em estado misto (cartões `authorized` e `pre_authorized`), a captura atua somente nos cartões restantes e responde `202`. Envie o header `X-Idempotency-Key`; sem ele a API devolve `422` com `invalid_request`. Reenviar a mesma chave com o mesmo corpo devolve `202` com o estado atual da Venda. Casos de `409`: - `idempotency_key_payload_mismatch`: a chave já foi usada com outro corpo ou em outra operação. - `purchase_invalid_state`: a Venda foi criada com `capture: true` (a captura é automática), não está `pending` ou não tem cartões `pre_authorized`. - `purchase_operation_in_progress`: já existe uma operação em andamento e você enviou uma chave nova. # Criar uma Venda com múltiplos cartões Source: https://docs.malga.io/api-reference/purchases/criar-nova-venda post /v1/purchases Cria uma Venda paga com 2 ou 3 cartões de crédito e responde `202` com `status: pending`. O processamento é assíncrono: consulte `GET /v1/purchases/{id}` para acompanhar o desfecho. O campo `capture` define o que acontece depois das autorizações: - `capture: false`: a Venda permanece `pending` com os cartões `pre_authorized`. Você captura em `POST /v1/purchases/{id}/capture`. - `capture: true`: a Malga captura automaticamente os cartões pré-autorizados. Se todos os cartões já estiverem `authorized`, a Venda vai direto para `paid`. Envie o header `X-Idempotency-Key` em toda criação. Reenviar a mesma chave com o mesmo corpo devolve `202` com o estado atual da Venda. A mesma chave com corpo diferente, ou uma chave já usada em captura ou cancelamento, devolve `409` com `idempotency_key_payload_mismatch`. Informe cada cartão por referência, com `cardId` ou `tokenId`. Dados de cartão em claro (PAN) em `paymentSource`, `metadata` ou `fraudAnalysis` devolvem `422` com `pan_not_allowed`. # Listar Vendas Source: https://docs.malga.io/api-reference/purchases/listar-vendas get /v1/purchases Lista as Vendas do cliente autenticado, com paginação e filtros opcionais. Os filtros se combinam (E lógico). Itens da lista não trazem `operation`. `pendingReview`, `activeOperation` e `payments[].card` seguem a mesma regra da consulta individual. Sem resultados, a API responde `200` com `items` vazio. # Recuperar detalhes de uma Venda Source: https://docs.malga.io/api-reference/purchases/recuperar-detalhes-de-uma-venda get /v1/purchases/{id} Retorna a Venda e o estado de cada cartão. Use este endpoint para acompanhar o desfecho do processamento assíncrono. Uma Venda inexistente ou de outro cliente devolve `404` com `purchase_not_found`, sem distinção entre os dois casos. Depois da autorização, `payments[]` pode trazer `chargeId`, `declineReason` (somente o código de recusa) e `card` (`brand` e `last4`). Sem esses dados, o campo correspondente é omitido. Quando a Venda está `pending` e a operação mais recente terminou com uma anomalia (`reconciliation_failed`, `amount_mismatch` ou `claims_exhausted`), a resposta traz `pendingReview`. Nesse caso, interrompa o polling automático: a Venda permanece `pending`. # Recuperar o histórico de uma Venda Source: https://docs.malga.io/api-reference/purchases/recuperar-o-historico-da-venda get /v1/purchases/{id}/history Retorna a linha do tempo da Venda como um array de marcos, em ordem crescente de `createdAt`. A resposta não é paginada e não usa o formato `{ items, meta }`. Toda Venda existente tem ao menos o marco `created`. O campo `status` de cada item é o nome do marco, não o status da Venda. Os marcos não incluem dados de cartão, `metadata`, `fraudAnalysis` nem IP. Uma Venda inexistente, com `id` malformado ou de outro cliente devolve `404` com `purchase_not_found`. # Gerar documento comprobatório de estorno Source: https://docs.malga.io/api-reference/receipts/gerar-documento-comprobatorio post /v1/subacquirer/{transactionId}/receipts Gera o documento que comprova o estorno de uma cobrança e devolve a URL de download do arquivo. Disponível apenas para transações processadas pelo provedor Malga. # Alterar status de recebedor no Sandbox Source: https://docs.malga.io/api-reference/sellers/alterar-o-status-de-um-recebedor-no-ambiente-de-sandbox post /v1/sellers/{id}/status Altere manualmente o status de um recebedor no ambiente de Sandbox da Malga e dispare o webhook seller. correspondente à mudança. # Atualização de recebedor pelo ID Source: https://docs.malga.io/api-reference/sellers/atualizacao-de-recebedor-pelo-id patch /v1/sellers/{id} Atualização **parcial** do recebedor. Envie apenas os campos que deseja alterar; campos omitidos permanecem inalterados. **Atenção (Provedor Pagar.me V5):** Ao atualizar a conta bancária (`bankAccount`) de um seller, o IP do servidor que realiza a requisição **deve** estar previamente cadastrado na **Allow List** (Lista de Permissões) no dashboard da Pagar.me. [Saiba como configurar a Allow List aqui.](https://docs.pagar.me/reference/atualizar-conta-banc%C3%A1ria-do-recebedor-1) # Consultar documento Source: https://docs.malga.io/api-reference/sellers/consultar-documento get /v1/sellers/documents/{documentId} Retorna os detalhes de um documento. Documentos expirados retornam 404. # Consultar um recebedor pelo ID Source: https://docs.malga.io/api-reference/sellers/consultar-um-recebedor-pelo-id get /v1/sellers/{id} # Consultar recebedores por listagem paginada Source: https://docs.malga.io/api-reference/sellers/consultar-um-recebedor-por-listagem-paginada get /v1/sellers # Criação de um novo recebedor Source: https://docs.malga.io/api-reference/sellers/criacao-de-um-novo-recebedor post /v1/sellers # Deletar documento Source: https://docs.malga.io/api-reference/sellers/deletar-documento delete /v1/sellers/documents/{documentId} Remove um documento. Apenas documentos com status `uploaded` podem ser deletados. Documentos já associados a um seller (status `attached` ou `sent`) não podem ser removidos. # Deletar recebedor por ID Source: https://docs.malga.io/api-reference/sellers/deletar-recebedor-por-id delete /v1/sellers/{id} # Desvincular plano de venda de um recebedor Source: https://docs.malga.io/api-reference/sellers/desvincular-plano-de-venda-de-um-recebedor delete /v1/sellers/{id}/plan Remove o vínculo do seller com o plano de venda que estava associado a ele. O seller passa a seguir o plano padrão (`isDefault: true`) do cliente. # Enviar os dados coletados de uma revisão cadastral Source: https://docs.malga.io/api-reference/sellers/enviar-dados-de-revisao-cadastral post /v1/sellers/{sellerId}/registration-reviews/{processId}/submit Envia ao provedor os dados que você coletou do recebedor para encerrar o processo. O bloco `data` deve conter **exatamente** os campos listados em `requestedFields.fields` do processo: nem um a menos, nem um que não tenha sido pedido. O bloco `collection` registra como você obteve esses dados. A resposta é `202`: o envio ao provedor acontece em segundo plano e o desfecho chega pelos eventos `seller.registration_review.finished` e `seller.registration_review.failed`. # Listar documentos Source: https://docs.malga.io/api-reference/sellers/listar-documentos get /v1/sellers/documents Lista os documentos do cliente autenticado. Documentos expirados não são retornados. # Listar processos de revisão cadastral Source: https://docs.malga.io/api-reference/sellers/listar-processos-de-revisao-cadastral get /v1/sellers/registration-reviews Retorna os processos de revisão cadastral abertos pelos provedores para os seus recebedores, do mais recente para o mais antigo. Use esta rota para montar a fila de trabalho: os processos em `pending` e `overdue` aguardam o envio dos dados coletados. # Listar processos de revisão cadastral de um recebedor Source: https://docs.malga.io/api-reference/sellers/listar-processos-de-revisao-cadastral-de-um-recebedor get /v1/sellers/{sellerId}/registration-reviews Mesma listagem da rota anterior, restrita a um recebedor. Um recebedor com mais de um vínculo ao provedor recebe um item por vínculo, distinguidos pelo campo `providerId`. # Upload de documento Source: https://docs.malga.io/api-reference/sellers/upload-de-documento post /v1/sellers/documents Faz upload de um documento (imagem ou PDF) para posterior associação a um seller. O arquivo fica armazenado temporariamente por 7 dias. Após esse prazo, o documento expira e não pode mais ser utilizado. **Tipos aceitos:** SELFIE, CNH_FULL, CNH_FRONT, CNH_BACK, RG_FRONT, RG_BACK **Formatos aceitos:** - SELFIE e CNH_FULL: PNG, JPEG, BMP, WebP, HEIC, HEIF, PDF - CNH_FRONT, CNH_BACK, RG_FRONT, RG_BACK: PNG, JPEG, BMP, WebP, HEIC, HEIF (sem PDF) **Tamanho máximo:** 3MB # Atualizar relevância de uma sessão Source: https://docs.malga.io/api-reference/sessions/atualizar-o-status-de-uma-sessao patch /v1/sessions/{id} Atualiza campos de relevância da sessão: `isActive` (obrigatório), `dueDate` e `maxPayments` (sessões 1:N). A resposta é parcial e devolve apenas `id` e `isActive`; após a atualização, consulte `GET /v1/sessions/{id}` para obter o estado completo (`status`, `dueDate`, `maxPayments`, `multiplePayments`, etc.). **Restrição de reativação pix/boleto 1:1 consumida:** `isActive: true` em uma sessão pix ou boleto 1:1 já paga (`maxPayments = 1` com `paymentCount = 1`, ou sessão legada sem `maxPayments` já `paid` com `paymentCount = 1`) retorna `422` com `businessCode: "pix_boleto_one_to_one_reactivation_blocked"`. O bloqueio ignora `maxPayments` enviado no PATCH. # Cancelar uma sessão Source: https://docs.malga.io/api-reference/sessions/cancelar-uma-sessao post /v1/sessions/{id}/cancel # Criar nova sessão Source: https://docs.malga.io/api-reference/sessions/criar-nova-sessao post /v1/sessions Cria uma sessão de pagamento. Quando `maxPayments` é omitido, a sessão segue o fluxo 1:1 legado. Quando `maxPayments` é enviado, a sessão opera como link 1:N e a resposta completa retorna `multiplePayments` com a disponibilidade agregada para próximas cobranças. **Restrição pix/boleto em 1:N:** métodos `pix` e `boleto` não podem ser combinados com `maxPayments` finito maior que `1`. Nesse caso a API retorna `422` com `businessCode: "pix_boleto_multiple_payments_not_allowed"`. `maxPayments` omitido, `null`, `1` ou `-1` (ilimitado) continua permitido para pix/boleto. O bloqueio não se aplica a cartão de crédito. # Listar sessões Source: https://docs.malga.io/api-reference/sessions/listar-sessoes get /v1/sessions Consulte a lista paginada de sessões da sua conta na Malga, com filtros por status, data de criação e demais parâmetros de busca disponíveis. # Pagar uma sessão Source: https://docs.malga.io/api-reference/sessions/pagar-uma-sessao post /v1/sessions/{id}/charge Inicia uma cobrança para a sessão. Em sessões 1:N, cada chamada aceita representa uma tentativa individual dentro da capacidade configurada em `maxPayments`. A resposta é a cobrança criada e não retorna `multiplePayments`; consulte `GET /v1/sessions/{id}` para acompanhar o estado agregado atualizado. Sessões com múltiplos cartões (`paymentType: multiple`) não são pagas por este endpoint: use [`POST /v1/sessions/{id}/purchase`](/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes). # Pagar uma sessão com múltiplos cartões Source: https://docs.malga.io/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes post /v1/sessions/{id}/purchase Paga uma sessão configurada com `paymentType: multiple`, dividindo o valor entre 2 ou 3 cartões de crédito. A chamada cria uma [Venda](/api-reference/purchases/criar-nova-venda) e responde `202`: o processamento é assíncrono. Acompanhe o desfecho consultando a Venda e a sessão. O valor total, o merchant, a moeda, o modo de captura, o `orderId` e as regras de split vêm da própria sessão. Você informa apenas os cartões em `payments`. A quantidade de cartões vai de 2 até o `quantity` configurado na sessão, a soma dos valores deve ser igual ao valor da sessão e as parcelas de cada cartão não podem passar do `installments` configurado. A moeda da sessão deve ser `BRL`. Use este endpoint no lugar de `POST /v1/sessions/{id}/charge`: uma sessão com `multiple` não aceita `paymentType: multiple` no `/charge`. O header `X-Idempotency-Key` é opcional aqui. Quando ausente, a Malga gera uma chave a partir da sessão e dos cartões enviados, e uma repetição idêntica devolve a mesma Venda. Informe os cartões por referência, com `cardId` ou `tokenId`. Dados de cartão em claro devolvem `422` com `pan_not_allowed`. Enquanto uma Venda está em andamento, a sessão recusa novas chamadas com `purchase_in_progress`. Depois de uma Venda recusada (`failed`), a sessão volta a aceitar uma nova tentativa, com uma chave de idempotência nova. A liberação acontece no processamento assíncrono do desfecho, então uma tentativa feita no mesmo instante pode receber `purchase_in_progress`: tente de novo depois de alguns segundos. Uma Venda paga encerra a sessão. # Recupera sessão com os dados das configurações da empresa Source: https://docs.malga.io/api-reference/sessions/recupera-sessao-com-os-dados-das-configuracoes-da-empresa get /v1/sessions/{id}/link Retorna a sessão completa junto das configurações da empresa usadas no Link de Pagamento. Também inclui `multiplePayments` para indicar a disponibilidade agregada do link em sessões 1:1 e 1:N. # Recuperar detalhes de uma sessão Source: https://docs.malga.io/api-reference/sessions/recuperar-detalhes-de-uma-sessao get /v1/sessions/{id} Retorna a sessão completa. Use este endpoint como fonte do estado agregado de `multiplePayments` após criação, pagamento, atualização, cancelamento ou consulta de histórico. # Recuperar o histórico da sessão Source: https://docs.malga.io/api-reference/sessions/recuperar-o-historico-da-sessao get /v1/sessions/{id}/history Consulte a trilha de auditoria de alterações, pagamentos e expirações de uma sessão. O endpoint `GET /v1/sessions/{id}/history` retorna um **array de eventos em ordem decrescente**, com os registros mais recentes primeiro. Cada elemento descreve uma mudança ou um efeito observado (criação, atualização, tentativa de pagamento, confirmação assíncrona, expiração, entre outros). > [!NOTE] > > Use o histórico para **auditar** o que aconteceu. Para saber se o link ainda aceita pagamentos ou qual é o `multiplePayments.status` agora, consulte [Recuperar detalhes de uma sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao). ## Quando usar | Objetivo | Endpoint recomendado | | - | - | | Disponibilidade do link 1:N (`multiplePayments`, contadores) | `GET /v1/sessions/{id}` | | Linha do tempo de alterações e pagamentos | `GET /v1/sessions/{id}/history` | | Conciliação de uma cobrança específica | Histórico + detalhe da cobrança em Charges | Em sessões **1:N**, uma cobrança aprovada não encerra necessariamente a sessão. O histórico registra cada efeito; o estado agregado continua em `GET /v1/sessions/{id}`. ## Modelo da resposta Cada item do array possui os campos abaixo. | Campo | Descrição | | - | - | | `id` | Identificador **do registro de histórico**, não da sessão. | | `status` | Status na leitura do produto: `created`, `paid`, `canceled`, `voided` ou `disabled`. | | `createdAt`, `updatedAt` | Timestamps do registro (RFC 3339, com milissegundos). | | `clientId`, `merchantId` | Preenchidos quando gravados na auditoria. | | `action` | Ação principal derivada de `actions` (pode ser `null` quando dados legados não permitem derivar uma ação semântica com segurança). | | `actions` | Lista completa de ações semânticas do evento. | | `diff` | Objeto JSON com `changes`, `reason` e contexto do fluxo. | ### Status `disabled` no histórico O valor `disabled` **não** é um status persistido na sessão. Ele aparece no histórico quando o registro representa **expiração automática** por: * vencimento do `dueDate` (`sessionExpiredByDueDate`); ou * limite de pagamentos em sessão 1:N (`sessionExpiredByMaxPayments`). Cancelamento manual pelo integrador continua como `canceled`. ### Prioridade do campo `action` Quando há várias entradas em `actions`, a API escolhe uma ação principal nesta ordem: 1. `statusChanged` 2. `sessionExpiredByDueDate` 3. `sessionExpiredByMaxPayments` 4. `paymentExpired` 5. `updated` (genérico para demais combinações) ## Catálogo de ações (`actions`) As ações abaixo podem aparecer isoladas ou combinadas no mesmo registro. ### Alterações de sessão | Action | Significado | | - | - | | `statusChanged` | Mudança de `status` (criação, cancelamento, confirmação `paid`, `voided`, etc.). | | `amountChanged`, `currencyChanged` | Valor ou moeda alterados. | | `isActiveChanged` | Link ativado ou desativado (`manualActivation` / `manualDeactivation` no `diff`). | | `itemsChanged`, `itemsRemoved` | Itens do pedido alterados ou removidos. | | `dueDateChanged`, `maxPaymentsChanged` | Vencimento ou limite 1:N alterados. | | `nameChanged`, `descriptionChanged`, `captchaEnabledChanged` | Demais campos de configuração. | | `splitRulesChanged` | Regras de split atualizadas (ex.: enriquecimento de recebedor). | ### Pagamentos e estoque 1:N | Action | Significado | | - | - | | `paymentSucceeded` | Resposta **não falha** da tentativa de cobrança HTTP (inclui `pending`) **ou** confirmação assíncrona idempotente. | | `paymentFailed` | Falha HTTP, erro de transporte ou corpo da resposta com `status=failed`. | | `paymentPending` | Reserva de vaga pendente em sessão 1:N (Pix/boleto assíncrono). | | `paymentExpired` | Pagamento pendente expirado; libera a reserva pendente e pode reativar o link. | > [!WARNING] > > `paymentSucceeded` registrado após `POST /v1/sessions/{id}/charge` documenta a **resposta da tentativa de cobrança**, não necessariamente a confirmação final na sessão. Um item com `diff.changes.response.to.status: pending` indica tentativa em andamento. Para estado consolidado, use `GET /v1/sessions/{id}` ou aguarde a confirmação assíncrona. ### Expirações e bloqueios | Action | Significado | | - | - | | `sessionExpiredByDueDate` | Link desativado ao vencer `dueDate` (`status` na API: `disabled`). | | `sessionExpiredByMaxPayments` | Limite 1:N atingido; link desativado (`status` na API: `disabled`). | | `sessionExpiredByInvalidSeller` | Seller inválido; sessão encerrada (`status`: `canceled`). | | `captchaBlocked` | Bloqueio por score de captcha. | ## Fluxo de registro (visão geral) Dois destinos distintos: o **histórico** registra o que aconteceu; a **sessão** e as **métricas** guardam o estado atual do link. ### Trilha de auditoria Cada origem abaixo pode acrescentar um evento ao histórico. Consulte o resultado com `GET /v1/sessions/{id}/history`. ```mermaid theme={null} flowchart TD HTTP["API HTTP
criar ou atualizar sessão
POST /v1/sessions/{id}/charge"] ASSINC["Confirmação assíncrona
da cobrança"] EXP["Expiração por dueDate"] H[("Histórico da sessão")] READ_H["GET /v1/sessions/{id}/history
action · actions · diff"] HTTP -->|grava evento| H ASSINC -->|grava evento| H EXP -->|expiração automática| H H --> READ_H ``` ### Estado agregado do link As mesmas origens também atualizam contadores e disponibilidade do link. Para o estado **atual**, use `GET /v1/sessions/{id}` — não o histórico. ```mermaid theme={null} flowchart TD HTTP["API HTTP
criar · atualizar · cobrança"] ASSINC["Confirmação assíncrona
confirma ou expira pagamento pendente"] DESAT["Desativar link
vencido, esgotado (1:N) ou inválido"] S[("Estado atual da sessão")] READ_S["GET /v1/sessions/{id}
multiplePayments · contadores"] HTTP -.->|campos da sessão e métricas 1:N| S ASSINC -.->|pagamentos pendentes e status do link| S DESAT -.->|isActive e disponibilidade| S S --> READ_S ``` Registros com deduplicação por cobrança (`paymentPending`, `paymentSucceeded`, `paymentExpired` em 1:N) evitam reaplicar o mesmo efeito em reprocessamentos. Tentativas HTTP de cobrança **não** são deduplicadas: cada chamada pode gerar uma nova linha. ## Estrutura típica do `diff` Atualizações manuais costumam seguir: ```json theme={null} { "changes": { "isActive": { "from": true, "to": false, "reason": "manualDeactivation" } }, "updatedAt": "2026-05-19T13:00:00.000Z" } ``` Expiração por `dueDate`: ```json theme={null} { "status": "disabled", "action": "sessionExpiredByDueDate", "diff": { "reason": "expired by due date", "expiredAt": "2026-05-19T23:59:59.000Z", "changes": { "isActive": { "from": true, "to": false, "reason": "sessionExpiredByDueDate" } } } } ``` O payload do item não inclui `chargeId` como campo de nível raiz nem metadados de sistema. Quando houver contexto de cobrança, ele pode aparecer dentro de `diff`, por exemplo em `diff.chargeId` ou `diff.changes.response.to.chargeId`. ## Erros comuns | HTTP | Causa | | - | - | | `400` | `X-Client-Id` ausente ou identificador da sessão ausente no path. | | `404` | Sessão inexistente para o par `id` + `X-Client-Id`. | | `500` | Erro interno inesperado ao recuperar o histórico da sessão. | ## Próximos passos > [card] [Sessões](/documentations/more/sessions) > > Conceitos de sessão 1:1 e 1:N e acompanhamento de status. > [card] [Detalhes da sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao) > > Estado agregado atual e objeto `multiplePayments`. # Configurar link de pagamento personalizado Source: https://docs.malga.io/api-reference/settings/criar-configuracao-de-link-de-pagamento post /v1/settings # Editar configuração de link de pagamento Source: https://docs.malga.io/api-reference/settings/editar-configuracao-de-link-de-pagamento patch /v1/settings Atualiza a configuração do escopo informado (`X-Client-Id` e, opcionalmente, `X-Merchant-Id`). - **`multipart/form-data`:** todos os campos textuais e upload opcional de `logo` (File). - **`application/json`:** apenas campos textuais (sem upload de logo). Campos vazios (`""`) não são persistidos. Se nenhum campo efetivo for enviado (por exemplo `{}` ou somente `companyUrl` vazio) e não houver logo, retorna **422**. # Recuperar configuração de link de pagamento personalizado Source: https://docs.malga.io/api-reference/settings/recuperar-configuracao-de-link-de-pagamento get /v1/settings # Listar planos de venda Source: https://docs.malga.io/api-reference/subacquirer/listar-planos-de-venda get /v1/subacquirer/plans Lista os planos de venda cadastrados para o cliente autenticado. É por aqui que se descobre o `id` de um plano para vinculá-lo a um seller. # Atualizar assinatura Source: https://docs.malga.io/api-reference/subscriptions/atualizar-assinatura put /v1/subscriptions/{id} Atualiza só os campos enviados. Os demais ficam como estão. - **`recurrence` aceita só `cycles` e `startAt`.** O intervalo não pode ser alterado: `recurrence.interval` é ignorado sem erro e a resposta mantém o intervalo antigo. Para trocar o intervalo, cancele a assinatura e crie outra. - **`referenceKey` não pode ser alterado.** O campo é ignorado sem erro e a resposta mantém o valor original. - **`trial` não pode ser alterado.** Enviar `trial` devolve `400`. - **`splitRules` aceita só `percentage`.** Regra com `amount` devolve `400`. - **`startAt` só muda antes do primeiro ciclo.** Depois dele, devolve `400`. Se a nova data for hoje ou ontem (UTC), o primeiro ciclo é cobrado na mesma chamada. - **Cancelamento agendado.** Com `cancelAtPeriodEnd: true`, a assinatura precisa estar `active`, `paused`, `unpaid`, `trialing` ou `created`; em `canceled` ou `expired`, devolve `409`. **Atenção:** `cycles` precisa ser maior que a quantidade de ciclos já executados, e `items` e `splitRules` não podem ser listas vazias. Valide os valores antes de enviar. # Atualizar configurações do cliente Source: https://docs.malga.io/api-reference/subscriptions/atualizar-configuracoes-do-cliente patch /v1/subscriptions/settings Atualiza só os campos enviados das configurações do Motor de Assinaturas. O corpo precisa trazer pelo menos um dos campos `retryRules`, `statementDescriptor` ou `cancelAfterAllRetries`. Campos com outro nome, como `retryPolicy`, são ignorados, e um corpo só com eles devolve `400`. # Cancelar assinatura Source: https://docs.malga.io/api-reference/subscriptions/cancelar-assinatura patch /v1/subscriptions/{id}/cancel Cancela a assinatura na hora. Funciona nos status `active`, `paused`, `unpaid`, `trialing` e `created`; em `canceled` ou `expired`, devolve `409`. Uma assinatura cancelada não pode ser reativada. Os ciclos `scheduled`, `pending` e `retrying` passam para `canceled`. Ciclos `authorized` e `failed` não mudam. Se havia cancelamento agendado, ele é descartado. A operação emite o webhook `subscription.canceled`. O corpo é opcional. O `cancellationReason` enviado é gravado, mas não volta em nenhuma resposta da API. # Criação de uma nova assinatura Source: https://docs.malga.io/api-reference/subscriptions/criacao-de-uma-nova-assinatura post /v1/subscriptions Cria uma assinatura no Motor de Assinaturas. **Cobrança na criação.** O primeiro ciclo é cobrado na mesma chamada quando `recurrence.startAt` é hoje ou ontem (UTC), ou quando `startAt` é omitido e não há `trial`. A resposta é `201` mesmo se essa cobrança falhar: confira o resultado em `lastCycle.status` e em `lastCycle.paymentHistory`. Com `trial`, a assinatura nasce `trialing` e a primeira cobrança acontece em `trial.endDate`. **Datas.** Sem `startAt` e sem `trial`, o início é hoje. `startAt` anterior a ontem (UTC) devolve `400`. Sem `recurrence.interval`, vale `monthly`. **Sem idempotência.** Repetir a requisição, por exemplo depois de um timeout, cria outra assinatura e faz outra cobrança. Antes de repetir, procure pelo seu `referenceKey` na [listagem de assinaturas](/api-reference/subscriptions/listagem-de-assinaturas). # Listagem de assinaturas Source: https://docs.malga.io/api-reference/subscriptions/listagem-de-assinaturas get /v1/subscriptions Lista as assinaturas do seu client, paginadas. Não há filtros além de `page` e `limit`. Os itens da listagem são um resumo e não trazem `items`, `recurrence`, `trial` nem `lastCycle`; para esses dados, consulte a assinatura pelo `id`. # Listar cycles de uma assinatura Source: https://docs.malga.io/api-reference/subscriptions/listagem-de-cycles-de-uma-assinatura get /v1/subscriptions/{id}/cycles Lista os ciclos da assinatura, do mais recente para o mais antigo (ordem de criação). Os itens da listagem não trazem `paymentHistory`; para ver as tentativas de cobrança, consulte o ciclo pelo `cycleId`. # Obter configurações do cliente Source: https://docs.malga.io/api-reference/subscriptions/obter-configuracoes-do-cliente get /v1/subscriptions/settings Devolve as configurações do Motor de Assinaturas para o seu client (régua de retentativas, statement descriptor e cancelamento após as retentativas). Na primeira consulta, o serviço cria a configuração padrão, com a régua `1, 3, 5, 7` e `cancelAfterAllRetries` igual a `false`. Por isso esta rota não devolve `404`. # Pausar assinatura Source: https://docs.malga.io/api-reference/subscriptions/pausar-assinatura patch /v1/subscriptions/{id}/pause Pausa uma assinatura `active`. Em qualquer outro status, devolve `409`. Os ciclos `scheduled`, `pending` e `retrying` passam para `canceled` e não são recriados quando a assinatura é reativada. A operação emite o webhook `subscription.paused`. # Reativar assinatura Source: https://docs.malga.io/api-reference/subscriptions/reativar-assinatura patch /v1/subscriptions/{id}/resume Reativa uma assinatura `paused`, que volta para `active`. Em qualquer outro status, devolve `409`. Os ciclos cancelados na pausa não são recriados. A operação emite o webhook `subscription.resumed`. # Recuperar detalhes de assinatura Source: https://docs.malga.io/api-reference/subscriptions/recuperar-detalhes-de-assinatura get /v1/subscriptions/{id} # Recuperar detalhes de um cycle específico Source: https://docs.malga.io/api-reference/subscriptions/recuperar-detalhes-de-cycle get /v1/subscriptions/{id}/cycles/{cycleId} Devolve o ciclo com o histórico de tentativas de cobrança (`paymentHistory`). Use um `cycleId` da [listagem de ciclos](/api-reference/subscriptions/listagem-de-cycles-de-uma-assinatura). # Criar um novo token Source: https://docs.malga.io/api-reference/tokens/criar-um-novo-token post /v1/tokens # Atualizar um vendedor Source: https://docs.malga.io/api-reference/vendors/atualizacao-de-vendedor-pelo-id patch /v1/vendors/{id} # Recuperar detalhes de um vendedor Source: https://docs.malga.io/api-reference/vendors/consultar-um-vendedor-pelo-id get /v1/vendors/{id} # Criação de um novo vendedor Source: https://docs.malga.io/api-reference/vendors/criacao-de-um-novo-vendedor post /v1/vendors # Deletar vededor pelo id Source: https://docs.malga.io/api-reference/vendors/deletar-vendedor-por-id delete /v1/vendors/{id} # Listagem de vendedores paginada Source: https://docs.malga.io/api-reference/vendors/listagem-paginada-de-vendedores get /v1/vendors # Atualizar webhook pelo id Source: https://docs.malga.io/api-reference/webhooks/atualizar-webhook-pelo-id patch /v1/webhooks/{id} # Criação de novo webhook para notificação Source: https://docs.malga.io/api-reference/webhooks/criacao-de-novo-webhook-para-notificacao post /v1/webhooks # Deletar webhook pelo id Source: https://docs.malga.io/api-reference/webhooks/deletar-webhook-pelo-id delete /v1/webhooks/{id} # Listagem de webhooks cadastrados Source: https://docs.malga.io/api-reference/webhooks/listagem-de-webhooks-cadastrados get /v1/webhooks # Recuperar detalhes de webhook Source: https://docs.malga.io/api-reference/webhooks/recuperar-detalhes-de-webhook get /v1/webhooks/{id} # 3DS Data Only Source: https://docs.malga.io/documentations/3ds2-malga/3ds-data-only ## O que é o “Data Only” no 3-D Secure 2? É uma modalidade em que você envia ao emissor apenas os dados da transação (informações do navegador, do cartão, do comprador etc.) para que ele faça uma análise de risco, mas sem jamais apresentar qualquer desafio (p. ex. autenticação via SMS ou app). Isso significa que o cliente não vê nada diferente no checkout, tudo acontece “por trás dos panos”. **Principais diferenças em relação ao fluxo tradicional** * **Sem interação do portador:** nenhum redirecionamento ou pop-up de desafio. * **Nenhuma reserva ou débito no cartão:** só há coleta de dados, sem tentativa de autorização naquela etapa. * **Responsabilidade permanece com o lojista:** não há “liability shift” para o banco emissor, pois não houve autenticação propriamente dita. **Quando usar o Data Only** * Em mercados onde não há obrigatoriedade de Strong Customer Authentication (como no Brasil); * Para transações de baixo valor ou perfil de risco reduzido, em que você prefira não correr o risco de abortar vendas com desafios desnecessários; * Para alimentar modelos de fraude em cobranças futuras, criando um histórico de comportamento antes da primeira cobrança (útil em assinaturas e recorrências). **Vantagens** * **Experiência fluida:** o cliente não percebe nada diferente e não abandona o carrinho; * **Latência reduzida:** evita round-trips a servidores de autenticação externa; * **Mais conversões:** você dá ao emissor um “insight” de risco sem atrito extra (Não supera a conversão do 3DS com autenticação) **Limitações** * **Sem transferência de responsabilidade:** se ocorrer fraude, ela fica a seu cargo; * **Menor influência em emissores que exigem autenticação:** alguns bancos só aceitam autorização completa de 3-DS para migrar liability. Em resumo, o modo Data Only é ideal quando você quer enriquecer seus critérios de aprovação sem criar atrito para o cliente, mas precisa estar confortável em manter a responsabilidade por possíveis chargebacks. ## Como usar na Malga? Para ativar o modo Data Only, envie os campos de 3DS com `threeDSecure2.dataOnly: true` e **sem** `setupId`. > [!NOTE] > > Com `dataOnly: true` e **sem** `setupId`, a cobrança segue o roteamento de **crédito** (`paymentType=credit`). **Não** exige `operation=3ds2` nem `paymentTypes=3ds2_malga`. Se o merchant tiver provedor de crédito, a cobrança não é rejeitada só porque não há 3DS nativo configurado. > [!WARNING] > > Se a mesma cobrança enviar `setupId` e `dataOnly: true`, o `setupId` tem precedência: a cobrança é tratada como 3DS2 Malga e exige provedor com `paymentTypes=3ds2_malga` (não como Data Only de crédito). Detalhes no [hub de modalidades](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). > [!NOTE] > > Quando houver `splitRules` em Data Only puro (`dataOnly: true` sem `setupId`), o roteamento usa a capacidade de split do crédito (`operation=split`), sem exigir `operation=3ds2`. A regra de interseção `3ds2_malga`∩`split` aplica-se a Malga/`setupId` e MPI externo, e não a esse Data Only. Se houver `setupId`, vale a precedência acima (Malga + interseção com split). Detalhes no [MPI externo](/documentations/3ds2-malga/3ds-mpi-externo#capacidade-e-roteamento) e no [hub de modalidades](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). > [!NOTE] > > **Importante:** verifique se o seu provedor oferece suporte a 3DS Data Only; caso contrário, essas informações serão ignoradas. Consulte a [lista de provedores compatíveis](/documentations/type-tables/payment-methods-by-providers). ### Exemplo ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "b9bb37a3-cb2b-4d8e-a72e-f296bcec2ba7", "amount": 100, "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "123", "cardExpirationDate": "12/2026" } }, "threeDSecure2": { "dataOnly": true, "redirectURL": "http://your-company/receive", "requestorURL": "http://your-company", "browser": { "acceptHeader": "*/*", "colorDepth": 24, "javaEnabled": true, "javaScriptEnabled": true, "language": "pt-BR", "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36", "ip": "0.0.0.0" }, "cardHolder": { "email": "cardHolder@email.com", "mobilePhone": "11 99329899" }, "billingAddress": { "city": "Rio de Janeiro", "country": "Brasil", "streetNumber": "45", "zipCode": "2547896", "state": "RJ", "street": "Av. Brasil" }, "shippingAddress": { "city": "São Paulo", "country": "Brasil", "streetNumber": "45", "zipCode": "2957896", "state": "SP", "street": "Rua das Flores" } } }' ``` > [!NOTE] > > Não é necessário configurar nada adicional do lado da Malga - basta que o provedor utilizado ofereça suporte a dataOnly (confirme esse suporte na documentação da Malga). # Exemplo prático Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/exemplo-pratico Para facilitar o entendimento, a Malga disponibiliza um **projeto de demonstração (demo)** open-source ilustrando a integração do 3DS2. Esse projeto contém um servidor Node.js simples (simulando seu backend) e uma página de checkout web, demonstrando todos os passos descritos necessários no checkout. Você pode encontrar o código-fonte no GitHub: [plughacker/malga-3ds-demo](https://github.com/plughacker/malga-3ds-demo) No README do projeto há instruções de como executá-lo localmente. Em resumo: 1. **Configure as variáveis de ambiente (.env)** com suas credenciais da Malga e IDs necessários – incluindo `MERCHANT_ID`, `API_KEY` e `CLIENT_ID` da sua conta, além das URLs base da Malga (sandbox ou produção). 2. **Instale as dependências**: ```bash theme={null} npm install ``` 3. **Inicie o servidor**: ```bash theme={null} npm run serve ``` 4. **Abra o endereço local** (por padrão [http://localhost:3000](http://localhost:3000)), preencha os dados solicitados (informações do cartão, etc.) e clique em "Pay". O demo então executa o setup, coleta de dados, criação da cobrança e, se necessário, apresenta o desafio em uma interface simplificada, retornando o resultado no final. Essa demonstração é uma ótima referência para ver a sequência completa em funcionamento e pode servir de base para seus testes iniciais. Recomendamos estudá-la para entender a integração ponta-a-ponta. Lembre-se de usar as credenciais de **Sandbox** da Malga ao testar em ambiente de homologação, para não acionar transações reais. # Pré-requisitos e configurações Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao Antes de realizar transações com 3DS2 Malga (`setupId`), é necessário preparar sua conta Malga com as configurações adequadas. ## Capacidade exigida no provedor Cobranças com `threeDSecure2.setupId` exigem provedor cujo `paymentTypes` inclua **`3ds2_malga`**. Essa capacidade **não** exige `operation=3ds2` (reservada ao [3DS nativo](/documentations/3dsecure2-adyen/intro)). Consulte a [tabela de provedores e meios de pagamento](/documentations/type-tables/payment-methods-by-providers) e o [hub de modalidades](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) para comparar 3DS nativo, Malga, MPI externo e Data Only. ## Habilitando o 3DS2 na conta Malga * **Solicite a ativação do 3DS2:** Entre em contato com a equipe Malga para habilitar a funcionalidade 3D Secure 2 em sua conta. A Malga irá configurar o suporte ao 3DS2 para o seu ambiente. Somente após essa habilitação você poderá prosseguir com os próximos passos. * **Provedor de pagamento compatível:** Verifique se o merchant possui ao menos um provedor com `paymentTypes` contendo `3ds2_malga`. A lista de suporte está na [tabela de provedores](/documentations/type-tables/payment-methods-by-providers). ## Criando um Merchant com suporte a 3DS2 Após ter o 3DS2 habilitado e um provedor compatível, você deve criar ou atualizar o **Merchant** com informações adicionais exigidas. A criação de um merchant na Malga segue o padrão usual, porém alguns campos extras são necessários: * `merchantUrl` – URL do site da loja que está usando 3DS2 (geralmente a página inicial ou domínio do e-commerce). * `merchantName` – Nome do estabelecimento que aparecerá para o cliente durante o desafio 3DS. * `providers.acquirer.merchantId` – O identificador do seu merchant junto ao provedor de pagamento. Muitos provedores usam um único Merchant ID para todas as bandeiras de cartão; * `providers.acquirer.bin` – Lista de BINs do adquirente cadastrados para cada bandeira de cartão. Inclui: * `brand`: Nome da bandeira (por exemplo, "Visa", "Mastercard", "Elo"). * `value`: BIN (Bank Identification Number) do adquirente associado àquela bandeira. * `merchantId` (opcional por bandeira): Se o seu provedor utilizar um Merchant ID diferente para cada bandeira, você pode especificá-lo aqui. Caso contrário, se for igual para todas as bandeiras, use apenas o campo principal `providers.acquirer.merchantId`. > [!NOTE] > > **Importante:** As configurações de `acquirer` (BINs e MerchantIDs) devem ser fornecidas pelo seu provedor de pagamento. Certifique-se também de que o provedor confirmou o cadastro desses dados junto às **bandeiras de cartão**. Sem esse cadastro adequado, as tentativas de transação com 3DS podem resultar em erro. A seguir, um exemplo de requisição cURL para criar um merchant e atualizar com as configurações 3DS2 (substitua `` e `` pelos valores da sua conta, e ajuste os dados conforme o seu caso): > [tab] Criar Merchant > > ```bash theme={null} > curl --request POST 'https://api.malga.io/v1/merchants' \ > --header 'x-api-key: ' \ > --header 'x-client-id: ' \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "mcc": "4814", > "merchantUrl": "https://www.sualoja.com.br", > "merchantName": "Minha Loja Online", > "name": "Minha Loja Online", > "providers": [ > { > "priority": 1, > "name": "SandboxProvider", > "credentials": { > "type": "SANDBOX", > "apiKey": "SUaChaveDeAPI_Provedor" > }, > "acquirer": { > "merchantId": "ABC123MERCHANTID", > "bin": [ > { > "brand": "Visa", > "value": "000001" > }, > { > "brand": "Mastercard", > "value": "000002" > } > ] > } > } > ], > "status": true > }' > ``` > [tab] Atualizar Merchant > > ```bash theme={null} > curl --request PATCH 'https://api.malga.io/v1/merchants/' \ > --header 'x-api-key: ' \ > --header 'x-client-id: ' \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "merchantUrl": "https://www.sualoja.com.br", > "merchantName": "Minha Loja Online", > "name": "Minha Loja Online", > "providers": [ > { > "priority": 1, > "name": "SandboxProvider", > "credentials": { > "type": "SANDBOX", > "apiKey": "SUaChaveDeAPI_Provedor" > }, > "acquirer": { > "merchantId": "ABC123MERCHANTID", > "bin": [ > { > "brand": "Visa", > "value": "000001" > }, > { > "brand": "Mastercard", > "value": "000002" > } > ] > } > } > ] > }' > ``` No exemplo acima, o merchant é criado com um provedor de pagamento sandbox e informações fictícias (MCC, nome, URLs, Merchant ID e BINs). Ajuste esses campos para os valores reais fornecidos pelo seu provedor. ## Configurando o fluxo de pagamento 3DS2 A Malga utiliza Fluxos de Pagamento para orquestrar qual provedor será usado em cada transação. Você pode criar (ou atualizar) um fluxo com `paymentMethod` igual a `"3ds2_malga"`, apontando apenas para provedores cujo `paymentTypes` inclui `3ds2_malga`. A criação do fluxo **não** exige que esses provedores tenham `operation=3ds2`. > [!NOTE] > > Se o merchant **não** tiver um fluxo ativo para a cobrança, a Malga ainda aplica o gate inicial de elegibilidade: cobranças com `setupId` só seguem com provedores cujo `paymentTypes` inclui `3ds2_malga`, **sem** exigir `operation=3ds2`. Com fluxo ativo, configure `paymentMethod=3ds2_malga` apontando apenas para provedores compatíveis. Esse gate **não** garante preservação da ordem do fluxo nem retentativas limitadas à lista filtrada na autorização posterior. Exemplo de requisição cURL para criar um fluxo 3DS2 apontando para um provedor específico: ```bash theme={null} curl --request POST 'https://api.malga.io/v1/flows' \ --header 'x-api-key: ' \ --header 'x-client-id: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Fluxo 3DS2", "merchantId": "", "paymentMethod": "3ds2_malga", "flow": { "root": [ { "rule": "provider", "id": "<1__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>" }, { "rule": "provider", "id": "<2__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>" } ] } }' ``` Nesse exemplo, substitua `` pelo ID do merchant criado no passo anterior, e `<1__ID_DO_PROVEDOR_COM_SUPORTE_3DS2>` pelo identificador do provedor (conforme retornado na criação do merchant ou obtido via API). O fluxo acima direciona todas as transações 3DS2 do merchant para o provedor especificado. Após essa configuração, sua conta Malga está pronta para realizar transações com autenticação 3DS2. > [!NOTE] > > **Recomendação:** Esta etapa pode ser feita pelo Dashboard Malga, para tornar a configuração mais simples e prática. # Principais erros na autenticação 3DS da Malga Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/principais-erros Tabela com os principais erros de transações 3DS na Malga, organizados por etapa, com mensagem, descrição, detalhe e o que fazer para resolver cada caso. Abaixo estão os principais erros que podem acontecer durante uma transação com 3DS, para te ajudar a identificar e entender melhor cada situação. ## Erros de elegibilidade do provedor Antes de criar a cobrança, a Malga verifica se há um provedor com as capacidades exigidas pela modalidade. Quando não há um provedor elegível para 3DS2 Malga ou MPI externo, a API retorna um dos erros abaixo: | HTTP | `declined_code` | Quando ocorre | `details` retornado | O que fazer? | | - | - | - | - | - | | `400` | `provider_not_configured_for_3ds2` | Cobrança com `setupId` ou MPI externo, sem Data Only, quando nenhum provedor tem `paymentTypes=3ds2_malga`. | `no provider configured with paymentTypes=3ds2_malga for this charge` | Configure no merchant um provedor com suporte a **3DS2 Malga**. A capacidade `operation=3ds2`, isoladamente, não atende a essa modalidade. | | `400` | `provider_not_configured_for_required_capabilities` | Cobrança com `setupId` ou MPI externo combinada com `splitRules`, quando nenhum mesmo provedor tem `paymentTypes=3ds2_malga` e `operation=split`. | `no provider configured with required capabilities 3ds2_malga and split` | Configure um provedor que tenha **as duas capacidades**. Configurá-las em provedores diferentes não atende a essa cobrança. | Os valores de `details` acima são fixos e não incluem PAN, CVV, CAVV/UCAF, XID, tokens, credenciais ou o payload bruto do MPI. > [!WARNING] > > Esses `declined_code` não se aplicam ao 3DS nativo, com ou sem `splitRules`. Quando não há provedor com `operation=3ds2` para o caminho nativo, a API mantém o erro HTTP `404`, sem substituir esse comportamento pelos novos códigos `400`. | Etapa | Mensagem | Descrição | Detalhe | O que fazer? | | - | - | - | - | - | | Setup | brand not found | A bandeira do cartão não foi encontrada ou não é suportada. [Veja aqui as bandeiras suportadas](https://docs.malga.io/documentations/tokenization/intro#bandeiras-aceitas) | Verifique as configurações do merchant Malga | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. | | Setup | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | | Entre em contato com a Malga. | | Enroll | invalid card expiration date | A data de validade do cartão é inválida | | Cliente precisa enviar outro cartão durante a compra | | Enroll | acquirer merchantId not configured | O merchantId do adquirente não foi configurado | | Adicionar o merchantId no acquirer bin do provider na configuração do seu merchant Malga. [Veja aqui como fazer.](https://docs.malga.io/api-reference/merchants/criacao-de-novo-merchant-para-cobranca#body-providers-acquirer) | | Enroll | acquirer bin not configured for this brand | O BIN do adquirente não foi configurado para a bandeira do cartão informada | Precisa adicionar um acquirer bin no provider do merchant | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. | | Enroll | merchantName not configured | O merchantName não foi configurado | | Adicionar a informação de merchantName no merchant da Malga. [Veja aqui como fazer.](https://docs.malga.io/api-reference/merchants/criacao-de-novo-merchant-para-cobranca#body-merchant-name) | | Enroll | brand not found | A bandeira do cartão não foi encontrada ou não é suportada | | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. | | Enroll | Failed authentication eciRaw 07/00 | Falha na autenticação (ECI Raw 07/00) | Somente ECI 07 e 00 indicam que a autenticação foi feita com sucesso | Inicie o fluxo sem 3DS | | Enroll | Authentication attempts unavailable by issuer | As tentativas de autenticação não estão disponíveis pelo emissor | O status indica que o cliente está habilitado para autenticação (como 3DS), mas ela não está disponível no momento. | O lojista pode tentar novamente ou seguir com a autorização, mas **assume o risco do chargeback**, pois **não há proteção sem autenticação**. | | Enroll | Authentication error without challenge | Erro de autenticação sem desafio | A conta está habilitada para autenticação, mas o banco rejeitou a autenticação sem desafio. | O lojista **não pode seguir com a autorização** e deve **solicitar outro meio de pagamento**. Inicie o fluxo sem 3DS | | Enroll | Authentication Unavailable | A autenticação não está disponível | Esse status indica que a conta **não é elegível para autenticação**, a autenticação foi ignorada ou houve **erro/timeout**. | É possível seguir com a autorização, mas **sem proteção contra chargeback**, pois **não há transferência de responsabilidade**. Você pode iniciar o fluxo novamente, mas em caso de erro é possível que o cartão não seja suportado, então a recomendação é seguir sem 3DS | | Enroll | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | | Entre em contato com a equipe Malga. | | Enroll | Access denied, invalid endpoint acquirerBIN, acquirerMerchantID not recognized | O merchantID ou acquirerBin não foi cadastrado junto à bandeira. | | Entre em contato com o provedor e solicite o cadastro do **Acquirer BIN** e do **Merchant ID**. Esse processo costuma ser automático para transações com **Visa**, mas no caso da **Mastercard** é necessário solicitar o cadastro. | | Validate | Invalid PARes | O PARes (Payment Authentication Response) é inválido | Significa que a resposta da autenticação (PARes) recebida do banco emissor é inválida, corrompida ou malformada. Isso impede a finalização do processo de autenticação e pode resultar no bloqueio da transação. | Iniciar o fluxo 3DS do início. | | Validate | Issuer unable to perform authentication | O emissor não conseguiu realizar a autenticação | Significa que o banco emissor **não conseguiu completar a autenticação do cliente**, possivelmente por problemas técnicos, indisponibilidade do sistema ou falta de suporte ao 3DS. Nesse caso, **não há proteção contra chargeback.** | Iniciar o fluxo 3DS do início. | | Validate | Cardholder did not complete authentication | O portador do cartão não concluiu a autenticação | Significa que o **portador do cartão não finalizou o processo de autenticação**, seja por fechar a janela, não responder ao desafio ou deixar o tempo expirar. A transação pode falhar ou seguir sem proteção contra chargeback | Iniciar o fluxo 3DS do início. | | Validate | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | Erro inesperado ao chamar o parceiro | Entre em contato com a Malga. | ## Retentativas e SetupId Os erros `provider_not_configured_for_3ds2` e `provider_not_configured_for_required_capabilities` acontecem antes da criação da cobrança. Por isso, eles não consomem o `setupId` nem reservam a chave de idempotência. Após corrigir a configuração do provedor, você pode repetir a mesma requisição com a mesma chave de idempotência e o mesmo `setupId`, quando aplicável. > [!WARNING] > > Se a tentativa avançar além da verificação de elegibilidade e consumir o `setupId`, não reutilize esse identificador. O `setupId` é válido para uma única tentativa de cobrança. Para retentar após uma falha que consumiu o `setupId`, você deve: 1. **Criar um novo setup** — Chame novamente o endpoint `POST /v1/charges/3ds/setup` para obter um novo `setupId` [Veja aqui como criar o setup](/documentations/3ds2-malga/3ds-malga/transacao-3ds2-na-malga#passo-1-setup-da-sessão-3ds2) 2. **Realizar nova coleta de dados** — Execute novamente a etapa de coleta de dados do dispositivo (Passo 2) 3. **Criar nova cobrança** — Crie uma nova cobrança usando o novo `setupId` obtido Tentar reutilizar um `setupId` já consumido resultará em erro e impedirá o processamento da transação. # Testando 3DS Malga no Sandbox Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/testes-sandbox Como testar 3DS Malga no Sandbox: cartões de teste da Cybersource para sucesso sem fricção e com desafio, portador FAILED, regra do CVV e comportamento do antifraude. No Sandbox, a cobrança com 3DS Malga é aprovada ou recusada pelo **resultado da autenticação** retornado pela Cybersource. Quando a autenticação é bem-sucedida, a [regra do último dígito do cartão](/documentations/welcome/testing) **não** se aplica. ## Como o Sandbox decide Em cobranças com `threeDSecure2.setupId`, o resultado da autenticação define a cobrança: | Resultado da autenticação | Cobrança | | - | - | | `transStatus` `Y` ou `A` e ECI diferente de `00` e `07` | Aprovada: `authorized` (com captura) ou `pre_authorized` | | `transStatus` `Y` ou `A` com ECI `00` ou `07` | `threedsAuthenticated` falso; o Sandbox aplica a [regra do último dígito](/documentations/welcome/testing) | | Autenticação sem sucesso ou indisponível (ex.: `4456530000001013`, `4456530000001039`) | `failed` já na etapa `3DS_authentication_enroll`, com o `declinedCode` da autenticação; a cobrança não chega à autorização | > [!NOTE] > > Valem também as regras das seções seguintes: portador `FAILED`, CVV > terminado em `0` e ausência de antifraude. ## Cartões de teste da Cybersource Use os cartões de teste oficiais da Cybersource para gerar o resultado de autenticação desejado. Os números abaixo vêm da página [Test Cases for 3D Secure 2.x](https://developer.cybersource.com/library/documentation/dev_guides/Payer_Authentication_SCMP_API/html/Topics/Test_Cases_for_3D_Secure_2_x.htm) da Cybersource. Essa página também lista os demais cenários (falha, tentativa, indisponibilidade) e as demais bandeiras. ### Sucesso sem fricção A autenticação termina sem desafio ao portador (`PARes` `Y`). | Bandeira | Número do cartão | ECI / indicador de coleta | | - | - | - | | Visa | `4456530000001005` | 05 | | Mastercard | `5200000000001005` | 2 | ### Sucesso com desafio O portador recebe o desafio e, ao concluí-lo, a autenticação é bem-sucedida (`PARes` `Y`). | Bandeira | Número do cartão | ECI / indicador de coleta | | - | - | - | | Visa | `4456530000001096` | 05 | | Mastercard | `5200000000001096` | 2 | > [!NOTE] > > A Cybersource recomenda validade em **janeiro do ano atual mais três** (em > 2026, `01/2029`), mas outras validades futuras também funcionam no Sandbox. > Informe o número sem espaços. ### Cartões legados O Sandbox mantém uma lista fixa de cartões que sempre têm a autenticação aprovada em cobranças 3DS Malga, independentemente do resultado enviado: * `4000000000002503` * `4000000000001000` * `4000000000002719` ## Forçar falha com o portador `FAILED` Para forçar a falha de uma cobrança que seria aprovada, informe `FAILED` como nome do portador do cartão. Vale para os cartões legados e para cobranças com autenticação bem-sucedida. ## CVV O CVV precisa **terminar em `0`**. Com qualquer outro final, o Sandbox retorna o CVV como não validado, mesmo que a autenticação seja bem-sucedida. ## Antifraude O antifraude **não é executado** em cobranças 3DS Malga. A [regra de antifraude do Sandbox](/documentations/welcome/testing#antifraude), baseada no final do documento, não se aplica a elas. # Criando uma transação Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/transacao-3ds2-na-malga Com a configuração pronta, o fluxo de uma transação utilizando 3D Secure 2 na Malga envolve várias etapas. Abaixo descrevemos cada passo com explicações e exemplos práticos: ### Passo 1: Setup da sessão 3DS2 Antes de criar uma cobrança (transação) com 3DS2, é necessário iniciar uma sessão de autenticação. Essa etapa de **setup** prepara o provedor de autenticação 3DS e retorna parâmetros que serão usados nas próximas etapas. Você deve chamar o endpoint `/v1/charges/3ds/setup` informando a fonte do cartão. Essa fonte pode ser um cartão tokenizado (`sourceType: "token"`) ou um cartão previamente cadastrado (`sourceType: "card"`), junto com o identificador correspondente (`tokenId` ou `cardId`). **Exemplo de requisição (Setup 3DS2):** > [tab] Exemplo com tokenId > > ```bash theme={null} > curl --request POST 'https://api.malga.io/v1/charges/3ds/setup' \ > --header 'x-api-key: ' \ > --header 'x-client-id: ' \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "sourceType": "token", > "tokenId": "15b9d449-91c7-44a7-9dfb-14d1d2f67ec6" > }' > ``` > [tab] Exemplo com cardId > > ```bash theme={null} > curl --request POST 'https://api.malga.io/v1/charges/3ds/setup' \ > --header 'x-api-key: ' \ > --header 'x-client-id: ' \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "sourceType": "card", > "cardId": "15b9d449-91c7-44a7-9dfb-14d1d2f67ec6" > }' > ``` No primeiro exemplo acima, foi utilizado um cartão tokenizado (substitua "tokenId" por um ID de token de cartão válido obtido via tokenização da Malga). Se você tivesse um `cardId`, poderia usá-lo alterando `sourceType` para `card`. **Resposta do Setup:** Ao chamar o setup, a API retorna um objeto contendo informações essenciais para prosseguir. Um exemplo simplificado de resposta JSON seria: ```json theme={null} { "id": "b1204633-999d-4cb2-9546-f9b3108b23df", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....", "collectUrl": "https://centinel.api.cardecommerce.com/V1/Cruise/Collect", "providerType": "CYBERSOURCE", "error": null } ``` Os campos importantes desse retorno são: * `id` – Identificador único da sessão 3DS2 criada. Este **Setup ID** será usado posteriormente ao criar a cobrança 3DS2. * `token` – Um token JWT fornecido pelo provedor de autenticação 3DS. Este token deverá ser usado na próxima etapa de coleta de dados no navegador do cliente. * `collectUrl` – URL para a qual os dados do dispositivo do cliente deverão ser enviados. Também será usada na etapa de **coleta de dados** no front-end. * `providerType` – Indica qual provedor de 3DS2 está sendo utilizado (ex: CYBERSOURCE, etc). * `error` – Em caso de falha na criação da sessão, este campo trará detalhes do erro; caso contrário virá como null. Guarde o valor de `id` retornado (Setup ID), pois ele será necessário no passo de criação da cobrança. Em seguida, prossiga imediatamente para a etapa de coleta de dados do dispositivo no navegador. ### Passo 2: Coleta de dados do dispositivo (Data Collection) Com o `token` e o `collectUrl` retornados no setup, é preciso coletar informações do dispositivo/navegador do comprador. Essa coleta é feita no front-end do seu checkout, normalmente via um formulário invisível e um iframe, e serve para o provedor 3DS reunir dados de contexto para a autenticação. Para implementar essa etapa, inclua no HTML do seu checkout um bloco de código semelhante ao abaixo: ```html theme={null}
``` No código acima, substitua `collectUrl` e `token3DS` pelos valores reais obtidos no **Passo 1**. Ao executar esse script, o formulário é enviado em background (iframe oculto) para a URL de coleta do provedor 3DS, junto com o token JWT. O provedor então coleta atributos do navegador (como informações de dispositivo, IP, etc.) automaticamente. Um event listener é adicionado para ouvir a mensagem de retorno indicando que a coleta terminou (o provedor geralmente envia um evento de mensagem para a janela original ao concluir a coleta). Essa etapa é fundamental para a autenticação 3DS: ela fornece ao emissor do cartão os dados contextuais do dispositivo do cliente, auxiliando na decisão de aprovar diretamente (autenticação frictionless) ou exigir um desafio. ### Passo 3: Criação da cobrança (transação com 3DS2) Com a sessão criada (Setup ID) e a coleta de dados realizada, você pode prosseguir para criar a cobrança (transação de pagamento). A requisição de cobrança é feita no endpoint padrão `/v1/charges`, porém deve conter um objeto adicional `threeDSecure2` com os campos necessários. O campo mais importante é o `setupId` retornado no Passo 1. > [!NOTE] > > Cobranças com `setupId` passam por um gate inicial de elegibilidade: só provedores com `paymentTypes` contendo `3ds2_malga` são elegíveis. Não é necessário que o provedor declare `operation=3ds2` (essa operação vale para o [3DS nativo](/documentations/3dsecure2-adyen/intro)). Sem fluxo ativo, o gate ainda filtra por `3ds2_malga`. Com fluxo `3ds2_malga`, use apenas provedores compatíveis no fluxo. Esse gate **não** promete que a autorização preserve a ordem do fluxo nem que as retentativas fiquem restritas à lista filtrada. Veja os [pré-requisitos](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao) e a [tabela de provedores](/documentations/type-tables/payment-methods-by-providers). Na cobrança 3DS2, o provedor de pagamento tentará autenticar o portador do cartão junto ao banco emissor. Dependendo do resultado, o pagamento poderá ser autenticado de forma silenciosa (frictionless) ou o emissor pode solicitar um **desafio adicional** ao cliente (challenge). Montar a requisição corretamente é crucial. Segue um exemplo de **requisição cURL** para criar uma cobrança com 3DS2: ```bash theme={null} curl --request POST 'https://api.malga.io/v1/charges' \ --header 'x-api-key: ' \ --header 'x-client-id: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "", "amount": 5790, "currency": "BRL", "capture": true, "statementDescriptor": "Compra 3DS2 - Pedido 12345", "paymentSource": { "sourceType": "token", "tokenId": "15b9d449-91c7-44a7-9dfb-14d1d2f67ec6" }, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentFlow": { "metadata": { "exemplo": "algum valor" } }, "threeDSecure2": { "requiresLiabilityShift": true, "setupId": "", "redirectURL": "https://www.sualoja.com.br/checkout", "requestorURL": "https://www.sualoja.com.br", "billingAddress": { "city": "São Paulo", "country": "BR", "street": "Avenida Exemplo", "streetNumber": "100", "zipCode": "01010010", "state": "SP" }, "browser": { "ip": "203.0.113.45", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "language": "pt-BR", "colorDepth": 24, "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "javaEnabled": false, "javaScriptEnabled": true }, "cardHolder": { "email": "cliente@example.com", "mobilePhone": "5511999999999" } } }' ``` **Vamos explicar os principais campos usados acima dentro de threeDSecure2:** **requiresLiabilityShift** `boolean` Indica se você **exige o liability shift**. Se `true`, a transação só prosseguirá se houver mudança de responsabilidade para o emissor. **setupId** `string` *required* O ID da sessão de setup obtido no **Passo 1**. **Obrigatório**; vincula a transação atual com os dados coletados anteriormente. **Importante:** Este ID é válido apenas para **uma única tentativa de cobrança**. Se a transação falhar, você não pode reutilizar o mesmo `setupId` para retentar — será necessário criar um novo setup e reiniciar todo o fluxo 3DS. **redirectURL** `string` A URL para a qual o cliente será **redirecionado de volta** após completar a autenticação 3DS (no caso de desafio). Normalmente é uma página do seu site (por exemplo, a página de confirmação de pedido ou de checkout) que irá processar a resposta. O provedor/autenticador usará esta URL para retornar o controle ao seu sistema após o desafio. **requestorURL** `string` URL do domínio do **lojista (merchant)**, geralmente o endereço do seu site. Esse valor pode ser usado internamente pelo provedor 3DS2 durante a autenticação para verificar a origem da requisição. **billingAddress** `object` Endereço de cobrança do portador do cartão. Campos como cidade, país, CEP, etc. (**Dados importantes para análise de risco e autenticação**). **browser** `object` *required* Objeto contendo **informações do navegador** do comprador, coletadas preferencialmente do próprio navegador do cliente. Inclua exatamente os dados requeridos:
  • `ip`: IP do cliente.
  • `userAgent`: String do agente de usuário do navegador.
  • `acceptHeader`: Conteúdo do header HTTP "Accept" enviado pelo browser.
  • `language`: Idioma preferido do navegador (por exemplo, "pt-BR").
  • `colorDepth`, `screenHeight`, `screenWidth`: Profundidade de cor e resolução de tela do dispositivo.
  • `timeZoneOffset`: Fuso horário do usuário em minutos (ex.: Brasil = "180" minutos atrasados em relação a UTC).
  • `javaEnabled`: Se Java (Applet) está habilitado no browser (geralmente `false` hoje em dia).
  • `javaScriptEnabled`: Se o navegador tem JavaScript habilitado (`true` na maioria dos casos).
**cardHolder** `object` Informações do portador do cartão, como email e telefone celular. Esses dados podem ser utilizados pelo emissor durante a autenticação (por exemplo, enviar um OTP via SMS). > [!NOTE] > > **Observação:** No exemplo acima, usamos valores simulados (como IP e userAgent abreviado). Em um cenário real, você deve capturar esses dados do navegador do cliente no front-end e passá-los corretamente na requisição. A Malga não coleta esses dados automaticamente, portanto sua aplicação cliente deve fornecê-los (por exemplo, usando `window.navigator` para obter `userAgent`, `screen.width` etc., e APIs do browser para IP se disponível, ou obtendo IP do lado servidor). **Resposta da Cobrança:** Ao criar a cobrança com 3DS2, a resposta da API incluirá, além dos dados da transação, um objeto `threeDSecure2.authData` com informações sobre a autenticação. Em particular, duas situações podem ocorrer: * **Transação Autorizada de imediato (Frictionless):** O campo status da transação vem como `authorized` ou `pre_authorized` indicando que o banco emissor não exigiu desafio. ```json theme={null} { ... "threeDSecure2": { "authData": { "action": "REDIRECT", "networkTransactionId": "7518984890596838804807", "providerType": "CYBERSOURCE", "response": null, "responseType": "AUTHORIZATION" }, "authenticated": true } } ``` * **Transação Pendente (Desafio necessário):** O campo status da transação virá como `pending`, indicando que o emissor solicitou um desafio (challenge) de autenticação. Nesse caso, o objeto `threeDSecure2.authData.response` trará os campos `stepUrl` e `token` que serão usados para iniciar o desafio. A transação ficará pendente até a conclusão do desafio pelo cliente. ```json theme={null} { ... "threeDSecure2": { "authData": { "action": "REDIRECT", "networkTransactionId": "7518912480166601504805", "providerType": "CYBERSOURCE", "response": { "pareq": "...", "stepUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp", "token": "..." }, "responseType": "AUTHENTICATION" }, "authenticated": null } } ``` No caso `pending`, prossiga para o **Passo 4** abaixo para realizar o desafio de autenticação. Se a transação foi autorizada sem desafio, você pode pular o próximo passo e apenas informar o cliente do resultado (ou confirmar pagamento, etc.). > [!NOTE] > > **Importante sobre retentativas:** Se a transação falhar por qualquer motivo (timeout, erro de tokenização, erro de autenticação, etc.), **não é permitido reutilizar o mesmo `setupId`** para tentar novamente. Para retentar uma transação 3DS2 que falhou, você deve: > >
    >
  1. Criar um novo setup chamando `POST /v1/charges/3ds/setup` novamente
    2. >
  2. Realizar uma nova coleta de dados do dispositivo (Passo 2)
    3. >
  3. Criar uma nova cobrança com o novo `setupId` obtido (Passo 3)
    4. >
> > Cada `setupId` é válido apenas para uma única tentativa de cobrança e não pode ser reutilizado em retentativas. ### Passo 4: Desafio de autenticação (Challenge 3DS2) Quando o banco emissor exige uma validação adicional, é preciso apresentar ao cliente o desafio 3DS - normalmente uma tela onde ele deve, por exemplo, inserir um código SMS, senha ou outro fator de autenticação. A Malga simplifica esse processo fornecendo a URL e o token necessários para abrir a interface do banco emissor em um **iframe** dentro do seu site (ou via redirecionamento). Assim como na coleta de dados, a implementação do desafio é feita no front-end, inserindo um formulário que será automaticamente enviado para o `stepUrl` do desafio, contendo o token de autorização. Esses valores foram retornados na resposta da cobrança (Passo 3) dentro de `threeDSecure2.authData.response.stepUrl` e `...response.token`. Você pode implementar de forma similar à abaixo no seu HTML (por exemplo, abrindo um modal ou sobreposição com um iframe para o desafio): ```html theme={null} ``` No código acima, `stepUrl` (`threeDSecure2.authData.response.stepUrl`) e `stepToken` (`threeDSecure2.authData.response.token`) devem ser preenchidos com os valores retornados na resposta da criação da cobrança pendente (obtidos no **Passo 3**). Ao executar `formStep.submit()`, o navegador irá **redirecionar o iframe** para o endereço do desafio do emissor, efetivamente carregando a página de autenticação do banco dentro do iframe. O cliente então interage com essa página (por exemplo, digitando a senha do cartão ou um código enviado por SMS). Durante o desafio, o navegador do cliente está se comunicando diretamente com o **banco emissor** (via provedor 3DS). Uma vez concluído (sucesso, falha ou expirado), o fluxo de 3DS2 providenciará um redirecionamento de volta para a URL que você configurou em `redirectURL` no Passo 3. ### Passo 5: Verificando o resultado final Após o cliente completar (ou tentar) o desafio e retornar para o seu site (URL de retorno configurada), é necessário verificar o status final da transação para saber se o pagamento foi **autorizado** ou **negado** pelo emissor. A Malga permite consultar a transação a qualquer momento via API, então você deve fazer uma requisição **GET** para o endpoint `/v1/charges/{chargeId}` usando o ID da cobrança criada no Passo 3. Por exemplo, suponha que o ID da cobrança retornado no Passo 3 foi `5c327714-4016-47a2-847d-6146e016c4bd`. Você pode consultá-la assim: ```bash theme={null} curl --request GET 'https://api.malga.io/v1/charges/5c327714-4016-47a2-847d-6146e016c4bd' \ --header 'x-api-key: ' \ --header 'x-client-id: ' \ --header 'Accept: application/json' ``` A resposta trará todos os detalhes da cobrança, incluindo o campo `status` atualizado (que após o desafio provavelmente estará como `authorized` se o cliente autenticou com sucesso e o pagamento foi aprovado, ou outro status final como `declined` em caso de falha). Você também poderá ver dentro de `threeDSecure2` detalhes como `authenticated: true/false`, `liabilityShift: true/false`, etc., indicando o resultado da autenticação 3DS2. # Configurar a Content Security Policy (CSP) para o 3DS2 Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/urls-liberacao Saiba quais domínios liberar na Content Security Policy (CSP) do seu checkout para que a autenticação 3DS2 da Malga funcione sem bloqueios no navegador. Durante uma compra com 3DS2, o navegador do seu cliente abre páginas de outros domínios dentro do seu checkout: * **Coleta de dados do dispositivo:** um iframe invisível envia informações do navegador para o provedor de autenticação (a Cardinal, parceira da Cybersource). * **Desafio (challenge):** quando o banco pede uma confirmação extra, como um código por SMS, a tela de autenticação abre dentro de um iframe no seu checkout. Se o seu site define uma Content Security Policy (CSP), esses domínios precisam estar na lista de permissões (allowlist) da política. Caso contrário, o navegador bloqueia os iframes sem aviso para o cliente: a compra trava na tela de pagamento ou a autenticação não é concluída. Configurar a CSP **não exige nenhuma mudança na sua integração com a Malga**: as chamadas à API e os campos retornados continuam iguais. > [!NOTE] > > Se você usa o [Link de Pagamento](/documentations/payment-link/intro) da Malga, a Malga já faz essa configuração para você. ## Domínios para liberar | Domínio | Diretivas | Para que serve | | - | - | - | | `https://cas.client.cardinaltrusted.com` | `frame-src`, `connect-src` | Coleta de dados e desafio da Cardinal no ambiente de testes | | `https://client.cardinaltrusted.com` | `frame-src`, `connect-src` | Coleta de dados e desafio da Cardinal no ambiente de produção | | `https://*.cardinalcommerce.com` | `frame-src`, `connect-src` | Coleta de dados, desafio e tela do banco (ACS) servidos pela Cardinal | | `https://api.malga.io` e `https://sandbox-api.malga.io` | `frame-src` | Retorno do desafio antes do redirecionamento para a sua `redirectURL` | | Domínio da sua `redirectURL` | `frame-src` | Página de retorno, aberta dentro do iframe ao final do desafio. Se for o mesmo domínio do checkout, `'self'` já cobre | | Domínios dos bancos emissores (ACS), como `https://acs.apata.io` e `https://*.apata.io` | `frame-src`, `connect-src` | Tela de autenticação servida pelo próprio banco emissor | Libere os domínios de testes e de produção ao mesmo tempo. Assim, você não precisa alterar a CSP quando passar do Sandbox para a produção. > [!WARNING] > > Na CSP, o asterisco só cobre subdomínios. A regra `https://*.client.cardinaltrusted.com` **não** libera `https://client.cardinaltrusted.com`, que é o domínio usado em produção. Por isso, ele aparece de forma explícita na tabela. > [!NOTE] > > Não existe uma lista fixa de domínios de bancos emissores, porque cada banco usa o seu próprio servidor de autenticação (ACS). Acompanhe os bloqueios no console do navegador ou nos relatórios da sua CSP e libere os domínios que aparecerem. ## Exemplo de CSP O exemplo abaixo mostra apenas as diretivas relacionadas ao 3DS2. Junte esses domínios às diretivas que o seu site já usa e substitua `https://www.sualoja.com.br` pelo domínio da sua `redirectURL`, caso ele seja diferente do domínio do checkout. ```http theme={null} Content-Security-Policy: frame-src 'self' https://www.sualoja.com.br https://cas.client.cardinaltrusted.com https://client.cardinaltrusted.com https://*.cardinalcommerce.com https://api.malga.io https://sandbox-api.malga.io https://acs.apata.io https://*.apata.io; connect-src 'self' https://cas.client.cardinaltrusted.com https://client.cardinaltrusted.com https://*.cardinalcommerce.com https://acs.apata.io https://*.apata.io ``` > [!TIP] > > A coleta de dados e o desafio são feitos com formulários enviados por `POST` para os domínios da Cardinal. Se a sua CSP define a diretiva `form-action`, inclua nela os mesmos domínios da Cardinal listados em `frame-src`. ## Firewall, proxy ou WebView Se a sua empresa usa firewall ou proxy que só permite domínios aprovados, ou se o checkout roda em um aplicativo com WebView que limita os endereços carregados, libere nessas ferramentas os mesmos domínios da tabela acima. ## Como confirmar que está tudo certo Depois de configurar a CSP, faça uma compra de teste com 3DS2 no Sandbox e verifique se: 1. A compra passa pela etapa de coleta de dados sem travar. 2. Quando o banco pede o desafio, a tela de autenticação aparece normalmente dentro do seu checkout. 3. O console do navegador não mostra erros de CSP, como `Refused to frame` ou `Refused to connect`. Para entender cada etapa do fluxo em detalhes, veja [Transação 3DS2 na Malga](/documentations/3ds2-malga/3ds-malga/transacao-3ds2-na-malga). Se precisar de ajuda para avaliar o impacto no seu ambiente, entre em contato com a equipe Malga. # 3DS com autenticador externo (MPI) Source: https://docs.malga.io/documentations/3ds2-malga/3ds-mpi-externo O 3-D Secure com autenticador externo (MPI - Merchant Plug-In) é uma variação do fluxo padrão de autenticação que permite ao lojista ou à plataforma de pagamentos delegar a comunicação com o Directory Server (DS) e o ACS (Access Control Server) a um componente externo especializado. O MPI é um módulo (geralmente fornecido pelo seu gateway ou PSP) responsável por construir, assinar e enviar as mensagens de autenticação 3DS (EMV 3-DS) ao Directory Server da bandeira, além de receber e tratar as respostas. > [!NOTE] > > Se você não quer lidar com a complexidade de autenticação, recomendamos usar 3DS2 Malga. ## Capacidade e roteamento Cobranças com `threeDSecure2.mpi` (**sem** `dataOnly: true`) usam a mesma capacidade de autorização do 3DS2 Malga: o provedor precisa ter `paymentTypes` com **`3ds2_malga`**. **Não** é exigido `operation=3ds2`. Sem fluxo ativo, a Malga tenta autorização nos provedores elegíveis com `3ds2_malga`, preservando a **ordem e o fallback** padrão. Com fluxo `paymentMethod=3ds2_malga` ativo, a ordem do fluxo é mantida. > [!WARNING] > > Quando a cobrança combina MPI externo (ou 3DS2 Malga) com **split** (`splitRules`), somente provedores que satisfazem **ao mesmo tempo** `paymentTypes=3ds2_malga` e `operation=split` são elegíveis. Se nenhum provedor cumprir as duas capacidades, a cobrança é rejeitada antes da autorização. Compare as quatro modalidades no [hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). ## Como transacionar com MPI externo na Malga? Basta enviar os dados de 3DS e adicioná-los no campo `threeDSecure2.mpi`. ### Exemplo de requisição ```bash theme={null} curl --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "", "amount": 150, // valor em centavos: R$ 1,50 "statementDescriptor": "Teste 3DS – Adyen", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "4111111111111111", "cardCvv": "123", "cardExpirationDate": "12/2030", "cardHolderName": "John Smith" } }, "threeDSecure2": { "redirectURL": "https://www.sualoja.com.br/checkout", "browser": { "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36", "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "language": "pt-BR", "colorDepth": 24, "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "javaEnabled": false, "javaScriptEnabled": true, "ip": "203.0.113.45" }, "mpi": { "acsTransactionId": "bf08e64e-fb71-4ae3-b72c-f9350f131ea5", "threeDSServerTransactionId": "a2e24560-90ed-4abf-b265-997d745cd562", "directoryServerTransactionId": "c8d640c8-e722-4833-8cac-bf646f00d64e", "version": "2.2.0", "transStatus": "Y", "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=", "eci": "05", "challenged": true } } }' ``` **Observe que, nesse fluxo, você não receberá um desafio (challenge), apenas o resultado final da autorização.** Recomendamos consultar a [lista de provedores compatíveis](/documentations/type-tables/payment-methods-by-providers), filtrando aqueles com suporte a 3DS2 Malga (`3ds2_malga`), pois apenas esses provedores aceitam autorização com dados de MPI externo. ## Sobre os campos que precisam ser enviados * **threeDSecure2.mpi.acsTransactionId:** ID da transação gerado pelo **Access Control Server (ACS)** do emissor do cartão. Serve para identificar a autenticação no sistema do banco. * **threeDSecure2.mpi.threeDSServerTransactionId:** ID da transação gerado pelo **3DS Server**, que é quem inicia e gerencia o fluxo de autenticação 3DS (geralmente operado pela adquirente ou subadquirente). * **threeDSecure2.mpi.directoryServerTransactionId:** ID gerado pelo **Directory Server**, que é o serviço da bandeira (como Visa ou Mastercard) que faz o roteamento da autenticação para o emissor do cartão. * **threeDSecure2.mpi.version:** Versão do protocolo 3D Secure utilizada na autenticação. A `"2.2.0"` é uma versão atual que permite suporte a mais casos, como autenticação por app ou biometria. * **threeDSecure2.mpi.transStatus:** Status da autenticação. `"Y"` indica que a autenticação foi realizada com sucesso. Outros valores possíveis: `"N"` (falha), `"U"` (inconclusiva), `"A"` (tentativa). * **threeDSecure2.mpi.cavv (Cardholder Authentication Verification Value):** Valor criptográfico gerado pelo emissor que comprova que a autenticação foi feita. Ele é usado para validar a transação junto à bandeira/adquirente. * **threeDSecure2.mpi.xid:** Identificador da transação de autenticação. Em 3DS2, pode ser o mesmo valor do CAVV. É utilizado para rastreabilidade da autenticação. * **threeDSecure2.mpi.eci:** Electronic Commerce Indicator. Indica o nível de segurança da transação. O valor `"05"` normalmente significa que a autenticação foi feita com sucesso (Visa/Mastercard). * **threeDSecure2.mpi.challenged:** Indica se o portador foi desafiado durante o processo de autenticação. `true` significa que houve interação do usuário (ex: digitar senha, biometria). `false` indica que a autenticação foi feita de forma silenciosa (frictionless). # Glossário 3DS Source: https://docs.malga.io/documentations/3ds2-malga/glossario-3ds | Termo | Definição | | - | - | | **3-D Secure (3DS)** | Protocolo de autenticação para transações online que envolve três domínios (emissor, adquirente/lojista e interoperabilidade). | | **3DS nativo** | Modalidade em que a cobrança envia `threeDSecure2` sem `setupId`, MPI externo ou Data Only. Exige provedor com `operation=3ds2`; essa capacidade não é substituída por `paymentTypes=3ds2_malga`. | | **3DS2 Malga** | Modalidade identificada por `threeDSecure2.setupId`. Exige provedor com `paymentTypes=3ds2_malga`, sem exigir `operation=3ds2`. | | **3DS Server** | Servidor (lado PSP/lojista) que forma e assina as mensagens 3DS, interagindo com o DS e o ACS. | | **ACS (Access Control Server)** | Servidor mantido pelo banco emissor responsável por autenticar o portador durante o desafio. | | **AcsTransactionId** | UUID atribuído pelo ACS para a transação (challenge). | | **AReq / ARes** | Mensagens de autenticação da versão EMV 3DS (substituem PAReq/PARes). | | **BIN** | Bank Identification Number do adquirente, associado à bandeira. | | **CAVV** | Cardholder Authentication Verification Value – código criptográfico gerado pelo emissor que comprova a autenticação. | | **Challenge Flow** | Fluxo em que o emissor solicita uma ação extra (OTP, biometria, etc.); iniciado com stepUrl + token. | | **Collect URL** | Endpoint do provedor para onde o front-end envia o JWT e coleta dados de dispositivo na etapa data collection. | | **Data Collection** | Fase em que o navegador envia dados do dispositivo ao provedor via collectUrl, geralmente em iframe invisível. | | **Data Only** | Modalidade identificada por `threeDSecure2.dataOnly: true` sem `setupId`. Segue o roteamento de crédito e não exige `operation=3ds2` nem `paymentTypes=3ds2_malga`. Se houver `setupId`, prevalece a modalidade 3DS2 Malga. | | **DirectoryServerTransactionId** | UUID atribuído pelo DS para a transação. | | **DS (Directory Server)** | Componente que verifica se cartão, emissor e comerciante participam do 3DS e encaminha mensagens entre 3DS Server e ACS. | | **ECI** | Electronic Commerce Indicator; valor que indica nível de autenticação e se há transferência de responsabilidade. | | **EMV 3-D Secure (3DS2)** | Evolução do 3DS, definida pela EMVCo, que envia mais dados contextuais ao emissor e permite fluxos frictionless ou challenge. | | **EMVCo** | Organização que mantém o padrão EMV 3DS e outras especificações de pagamento. | | **Frictionless Flow** | Autenticação 3DS aprovada sem interação adicional do cliente. | | **JWT / Token** | JSON Web Token devolvido no setup; é reenviado ao provedor na coleta e no challenge. | | **Liability shift** | Transferência de responsabilidade por fraude do lojista para o emissor quando o 3DS é bem-sucedido. Quando usado MPI externo, a autenticação é de responsabilidade do parceiro, portanto devolveremos false para essa propriedade. | | **MCC** | Merchant Category Code – código da atividade comercial. | | **MPI (Merchant Plug-In)** | Módulo que integra o merchant ao 3DS (normalmente embutido no 3DS Server ou no PSP). | | **MPI externo** | Modalidade que envia dados de autenticação em `threeDSecure2.mpi`, sem Data Only. Exige provedor com `paymentTypes=3ds2_malga`, sem exigir `operation=3ds2`. | | **operation** | Eixo de capacidade de operação do provedor. No contexto 3DS, `operation=3ds2` identifica suporte ao 3DS nativo e `operation=split` identifica suporte a split. | | **PAReq / PARes** | Mensagens Payer Authentication Request/Response da especificação 3DS 1.x. | | **paymentTypes** | Eixo de capacidade por tipo de pagamento do provedor. O valor `3ds2_malga` identifica suporte à autorização de cobranças com `setupId` ou MPI externo. | | **Capacidades simultâneas** | Quando 3DS2 Malga ou MPI externo é combinado com split, o mesmo provedor precisa ter `paymentTypes=3ds2_malga` e `operation=split`. A ausência dessa interseção rejeita a cobrança. Essa regra não se aplica ao 3DS nativo com split. | | **Redirect URL** | Endereço do seu site para o qual o cliente volta após o desafio. | | **RequiresLiabilityShift** | Flag na Malga que exige liabilityShift=true para aprovar a cobrança. | | **Setup ID** | Identificador da sessão criada no setup 3DS2; vincula coleta de dados e cobrança. | | **StepUrl** | URL do ACS para exibir a tela de desafio dentro de um iframe ou redirecionamento. | | **ThreeDSServerTransactionId** | UUID gerado pelo 3DS Server para rastrear a transação. | | **TransStatus** | Código de resultado da autenticação (ex.: Y = Sucesso, N = Falha, C = Challenge). | | **UCAF** | Universal Cardholder Authentication Field – padrão de autenticação Mastercard. | | **VEReq / VERes** | Mensagens de verificação de enrolamento na versão 1.x (Visa). | | **XID** | Identificador de transação 3DS original (versão 1) ou adicional para algumas bandeiras. | # Começando em 3DS2 Malga Source: https://docs.malga.io/documentations/3ds2-malga/intro ## O que é 3DS 2.0? **3DS 2.0** (3-D Secure 2.0) é um protocolo de segurança para pagamentos online que verifica se o comprador é realmente o dono do cartão antes de autorizar a transação. Funciona como uma verificação extra: quando você faz uma compra online, o banco pode pedir uma confirmação adicional (senha, código SMS, biometria) para garantir que é você mesmo fazendo a compra. ### Por que "3D Secure"? O nome vem dos **três domínios** que trabalham juntos na transação: * **Lojista** (sua loja e processador de pagamento) * **Banco emissor** (banco que emitiu o cartão) * **Bandeira** (Visa, Mastercard, etc.) *** ## Como funciona na prática? O 3DS 2.0 é mais inteligente que a versão anterior: * **Transações de baixo risco**: Autenticação invisível, sem interrupção * **Transações de alto risco**: Solicita verificação extra (SMS, app do banco, biometria) * **Dados ricos**: Envia mais de 100 informações para análise de risco * **Mobile-first**: Funciona perfeitamente em apps e sites mobile *** ## Quem participa do processo? * **Cliente**: Compra e pode ser solicitado a se autenticar * **Lojista**: Integra o 3DS no checkout * **Malga**: Gerencia a comunicação com o protocolo 3DS * **Bandeira**: Conecta sua loja ao banco emissor * **Banco emissor**: Verifica a identidade do cliente *** ## Benefícios para sua loja * ✅ **Menos fraudes** - Cliente autenticado = menos chargebacks * ✅ **Mais aprovações** - Bancos confiam mais em transações 3DS * ✅ **Proteção legal** - Em caso de fraude, responsabilidade é do emissor * ✅ **Débito online** - Muitos bancos exigem 3DS para cartões de débito * ✅ **Conformidade** - Atende regulamentações como PSD2/SCA *** ## Modalidades de 3DS na Malga A Malga oferece quatro formas de usar 3DS em cobranças de cartão. Cada modalidade exige **capacidades diferentes** no provedor. Elas **não** são equivalentes: | Modalidade | Como identificar na cobrança | Capacidade do provedor | Guia | | - | - | - | - | | **3DS nativo** | Objeto `threeDSecure2` **sem** `setupId`, **sem** `mpi` e **sem** `dataOnly` | Requer `operation=3ds2` no provedor | [Guia de 3DS nativo](/documentations/3dsecure2-adyen/intro) | | **3DS2 Malga** | `threeDSecure2.setupId` (após setup e coleta de dispositivo) | Requer `paymentTypes` com `3ds2_malga`; **não** exige `operation=3ds2` | [Pré-requisitos](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao) | | **MPI externo** (não Data Only) | `threeDSecure2.mpi` com dados já autenticados | Requer `paymentTypes` com `3ds2_malga`; **não** exige `operation=3ds2` | [MPI externo](/documentations/3ds2-malga/3ds-mpi-externo) | | **Data Only** | `threeDSecure2.dataOnly: true` **sem** `setupId` | Segue roteamento de **crédito** (`paymentType=credit`); **não** exige `operation=3ds2` nem `3ds2_malga` | [Data Only](/documentations/3ds2-malga/3ds-data-only) | > [!WARNING] > > Se a mesma cobrança enviar `setupId` e `dataOnly: true`, o `setupId` tem precedência: a cobrança é tratada como 3DS2 Malga (exige `paymentTypes=3ds2_malga`), não como Data Only de crédito. Detalhes no [guia de Data Only](/documentations/3ds2-malga/3ds-data-only). > [!NOTE] > > Um provedor com suporte a 3DS2 Malga (`3ds2_malga`) **não** passa a ser elegível para 3DS nativo. Da mesma forma, `operation=3ds2` não substitui `3ds2_malga` nas cobranças com `setupId` ou MPI externo. ### Fallback sem fluxo de pagamento ativo Quando o merchant **não** tem um fluxo (`paymentFlow`) ativo para a cobrança, a Malga aplica um **gate inicial de elegibilidade**: só provedores com a capacidade exigida pela modalidade (tabela acima) entram no conjunto elegível. Com fluxo ativo (`paymentMethod=3ds2_malga` para Malga/MPI), o fluxo deve apontar somente para provedores compatíveis com essa capacidade. Para cobranças com `setupId` (3DS2 Malga), esse gate garante a capacidade `3ds2_malga` **sem** exigir `operation=3ds2`. Ele **não** promete que a autorização posterior preserve a ordem do fluxo nem que as retentativas fiquem restritas apenas à lista filtrada nesse gate. A preservação de ordem e fallback entre provedores elegíveis no caminho de autorização aplica-se ao [MPI externo](/documentations/3ds2-malga/3ds-mpi-externo). A **fonte canônica** do mapeamento de capacidades por modalidade (incluindo `operation=3ds2` no 3DS nativo) é a tabela desta seção. A [tabela de provedores e meios de pagamento](/documentations/type-tables/payment-methods-by-providers) lista meios de pagamento gerais e o badge de 3DS2 Malga; ela **ainda não** distingue suporte nativo (`operation=3ds2`) de `3ds2_malga`. *** ## Fluxo básico O 3DS 2.0 funciona de duas formas, dependendo do nível de risco da transação: ### 1. Autenticação invisível (frictionless) Quando a transação é de baixo risco, tudo acontece sem interrupção: ```mermaid theme={null} sequenceDiagram participant C as "Cliente" participant L as "Loja" participant M as "Malga" participant X as "3DS" participant Y as "Gateway" C -->> L: Inicia checkout
e envia dados do cartão L -->> M: Requisição de transação
(intenção 3DS) M -->> X: Inicia autenticação 3DS X -->> M: Devolve tokens para autorização (frictionless) M -->> Y: Solicita autorização financeira Y -->> M: Aprova ou nega transação M -->> L: Retorna status (authorized/failed) L -->> C: Mostra resultado do pagamento ``` ### 2. Autenticação com desafio Quando há risco maior, o cliente precisa se autenticar: ```mermaid theme={null} sequenceDiagram participant C as "Cliente" participant L as "Loja" participant M as "Malga" participant X as "3DS" participant Y as "Gateway" C -->> L: Inicia checkout
e envia dados do cartão L -->> M: Requisição de transação
(intenção 3DS) M -->> X: Inicia autenticação 3DS alt Desafio requerido X -->> M: Solicita desafio (Challenge) M -->> L: Dados do desafio L -->> C: Apresenta desafio para cliente C -->> X: Responde desafio (OTP, biometria, etc) X -->> M: Resultado do desafio end M -->> Y: Solicita autorização financeira Y -->> M: Aprova ou nega transação M -->> L: Retorna status (authorized/failed) L -->> C: Mostra resultado do pagamento ``` **Dica:** A maioria das transações é autenticada de forma invisível. O desafio só aparece quando o banco detecta algo suspeito. *** ## Próximos passos Agora que você entende o básico do 3DS 2.0, vamos para a implementação prática. A Malga oferece uma integração simples que você pode usar no seu checkout. > [card] [Começar a integrar](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao) ## Conheça mais sobre o 3DS 2.0 > [card] [3DS2 Malga](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao) > > Setup, coleta de dispositivo e cobrança com setupId > [card] [3DS nativo](/documentations/3dsecure2-adyen/intro) > > Autenticação no provedor com operation=3ds2 > [card] [3DS MPI externo](/documentations/3ds2-malga/3ds-mpi-externo) > > Autorização com dados de autenticação externos > [card] [3DS Data Only](/documentations/3ds2-malga/3ds-data-only) > > Análise de risco sem desafio no checkout > [card] [Tabela de provedores](/documentations/type-tables/payment-methods-by-providers) > > Meios de pagamento e badge 3DS2 Malga por provedor > [card] [Glossário](/documentations/3ds2-malga/glossario-3ds) > > Termos técnicos do 3DS 2.0 # Como funciona o 3D Secure 2 Source: https://docs.malga.io/documentations/3dsecure2-adyen/charge Entenda o fluxo de cobrança com 3D Secure 2 na Malga via Adyen, com autenticação do banco emissor, desafio ao usuário e retorno via webhook. Quando uma cobrança é enviada com dados de 3DS2, o provedor irá solicitar uma análise ao banco emissor.\ O banco emissor pode exigir que o cliente faça uma autenticação. Esse processo é conhecido como desafio.\ Uma cobrança pode ser autorizada pelo banco emissor sem exigir desafio.\ A cobrança com desafio exigirá uma ação por parte do usuário para autenticar a transação. Nesse caso o usuário será redirecionado ao banco para autenticar a transação.\ O resultado final da transação será enviado via [**webhook**](/documentations/webhooks/webhook1-0) ## Cobrança com 3D Secure 2 Para iniciar uma cobrança com **3DS nativo**, o provedor precisa declarar **`operation=3ds2`**. Confirme essa capacidade na [matriz de modalidades do hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) e pelo badge de **3DS nativo** na [tabela de meios de pagamento](/documentations/type-tables/payment-methods-by-providers). O badge de **3DS2 Malga** representa `paymentTypes=3ds2_malga`, uma capacidade diferente.\ Inclua o objeto [**threeDSecure2**](/api-reference/charges/listar-cobrancas) na cobrança **sem** `setupId`, **sem** `mpi` e **sem** `dataOnly`. Esse fluxo **não** é o mesmo do [3DS2 Malga](/documentations/3ds2-malga/3ds-malga/transacao-3ds2-na-malga): cobranças com `setupId` exigem `paymentTypes` com `3ds2_malga` e **não** exigem `operation=3ds2`. A comparação completa das modalidades está no [hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). ### Principais informações * **redirectURL**: A URL que o provedor irá utilizar para retornar ao site de origem após o redirecionamento * **requestorURL**: A URL do site do portador do cartão * **browser**: Dados do navegador do portador do cartão * **cardHolder**: Dados do portador do cartão * **billingAddress**: Endereço de cobrança * **shippingAddress**: Endereço para envio ### Exemplo de cobrança com 3D Secure 2 ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "b9bb37a3-cb2b-4d8e-a72e-f296bcec2ba7", "amount": 100, "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "123", "cardExpirationDate": "12/2026" } }, "threeDSecure2": { "redirectURL": "http://your-company/receive", "requestorURL": "http://your-company", "browser": { "acceptHeader": "*/*", "colorDepth": 24, "javaEnabled": true, "javaScriptEnabled": true, "language": "pt-BR", "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36", "ip": "0.0.0.0" }, "cardHolder": { "email": "cardHolder@email.com", "mobilePhone": "11 99329899" }, "billingAddress": { "city": "Rio de Janeiro", "country": "Brasil", "streetNumber": "45", "zipCode": "2547896", "state": "RJ", "street": "Av. Brasil" }, "shippingAddress": { "city": "São Paulo", "country": "Brasil", "streetNumber": "45", "zipCode": "2957896", "state": "SP", "street": "Rua das Flores" } } }' ``` ### Exemplo de resposta com 3D Secure 2 ```json theme={null} { "clientId": "e1f7e8ff-0f7a-4368-8191-9678f9fb6cfa", "merchantId": "b9bb37a3-cb2b-4d8e-a72e-f296bcec2ba7", "description": null, "orderId": null, "createdAt": "2023-02-24T21:46:36.392Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "isDispute": false, "status": "pending", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "86453dbc-7a26-45d0-bc37-9056f6fbb3d5" }, "transactionRequests": [ { "idempotencyKey": "c487de3c-5746-4fe7-bfe7-d75a9bb6db10", "providerId": "f0ec9808-304e-498e-90c7-75775588376f", "providerType": "ADYEN", "transactionId": null, "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "authorization", "responseTs": "971ms", "providerAuthorization": { "networkAuthorizationCode": null, "networkResponseCode": "RedirectShopper" } } ], "threeDSecure2": { "redirectURL": "http://your-company/receive", "requestorURL": "http://your-company", "browser": { "acceptHeader": "*/*", "colorDepth": 24, "javaEnabled": true, "javaScriptEnabled": true, "language": "pt-BR", "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36", "ip": "127.0.0.1" }, "billingAddress": null, "shippingAddress": null, "cardHolder": null, "authData": { "action": "REDIRECT", "providerType": "ADYEN", "responseType": "AUTHENTICATION", "response": { "md": "M2RzMi5lZTBiZTgzZTdmZDBlZDk...AkHGAAAA", "url": "https://checkoutshopper-test.adyen.com/checkoutshopper/threeDS2.shtml?pspReference=8636772643981111", "paReq": "BQABAgB-MNl4GsRJSf5EmZE8guLfFQX7Q5Q...L_dRprriZL72QXGCtIPK-Hd", "termUrl": "https://checkoutshopper-test.adyen.com/checkoutshopper/threeDS/return/H4sIAAAAAAAA_..." } } } } ``` A resposta da transação irá incluir o objeto **authData** dentro do objeto **threeDSecure2**, com dados para a ação de autenticação. ### Examinando o objeto **authData** * O atributo **action** representa que tipo de ação foi solicitada para autenticação. * O atributo **providerType** identifica em qual provedor o 3DS2 foi processado. * O atributo **responseType** mostra qual é a etapa do desafio, podendo ser uma etapa de autenticação ou autorização. * O atributo **response** é um objeto dinâmico com a resposta do provedor com dados para autenticação. Os provedores implementam o desafio de formas diferentes, exigindo tratamentos específicos.\ Na próxima seção iremos mostrar como lidar com o fluxo com desafio. # Começando em 3DS2 Source: https://docs.malga.io/documentations/3dsecure2-adyen/intro Entenda como funciona o 3D Secure 2 (3DS2) na Malga, com fluxos com e sem desafio para autenticar o portador do cartão e reduzir fraudes em pagamentos. 3D Secure 2 é um protocolo da indústria de pagamentos que permite prevenir e eliminar o risco de fraude em pagamentos online ao permitir ao pagador se autenticar durante o processo de compra. O 3D Secure 2 visa também gerar a melhor experiência para o usuário, possibilitando que o fluxo seja mais fluido para o usuário final. ## 3DS nativo versus 3DS2 Malga Este guia cobre o **3DS nativo**: a cobrança envia o objeto `threeDSecure2` **sem** `setupId`, **sem** `mpi` e **sem** `dataOnly`. Nesse caso, a autenticação é conduzida pelo próprio provedor de pagamento. Para o 3DS nativo, o provedor precisa declarar **`operation=3ds2`**. Provedores que só têm `paymentTypes` com `3ds2_malga` (autorização com dados produzidos pela Malga ou por MPI externo) **não** são elegíveis para este fluxo. Se você precisa do fluxo com setup e coleta de dispositivo na Malga, use o [3DS2 Malga](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao). A comparação das quatro modalidades está no [hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). ## Fluxo de cobrança com 3D Secure 2 Para utilizar o 3D Secure 2 nativo em suas transações, credencie-se em um provedor com **`operation=3ds2`**. Consulte a capacidade exigida por modalidade na [matriz do hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) e verifique os badges distintos de **3DS nativo** e **3DS2 Malga** na [tabela de meios de pagamento](/documentations/type-tables/payment-methods-by-providers). Configure esse provedor no merchant (ou no fluxo de pagamentos). Em seguida, adicione o objeto `threeDSecure2` ao corpo da cobrança com os campos requeridos, **sem** `setupId`, `mpi` ou `dataOnly`. Verifique nossa [**API**](/api-reference/charges/listar-cobrancas) para detalhes. Tanto o fluxo sem desafio quanto o fluxo com desafio utilizam redirecionamento para fazer a autenticação do portador do cartão. Nos exemplos a seguir iremos nos referir a 3D Secure 2 como 3DS2 * Fluxo sem desafio * O portador preenche os dados do cartão no checkout do estabelecimento. * O estabelecimento aciona a solução 3DS2 da Malga via API `/charges` para criar a transação com 3DS2. * A solução 3DS2 da Malga envia ao provedor de autenticação os dados do comprador. * O provedor de autenticação se comunica com a bandeira para processar a autenticação. * A bandeira identifica o emissor do cartão, e envia os dados do comprador para análise. * A bandeira retorna os dados de autenticação silenciosa ao provedor. * O provedor retorna dados para autenticação silenciosa à Malga. * A Malga retorna uma transação com status `pending` ao estabelecimento com dados adicionais para autenticação. * O estabelecimento utiliza os dados para autenticação por redirecionamento. * Para transações autorizadas, o redirecionamento será executado automaticamente pelo browser retornando para o endereço informado em `redirectURL`, não precisando da interação do portador do cartão. * O provedor de autenticação retorna o resultado da autorização silenciosa à solução 3DS2 da Malga via webhook. * A Malga retorna o resultado da autorização ao estabelecimento via webhook. * O estabelecimento informa o resultado do pagamento. * Fluxo com desafio * O portador preenche os dados do cartão no checkout do estabelecimento. * O estabelecimento aciona a solução 3DS2 da Malga via API `/charges` para criar a transação com 3DS2. * A solução 3DS2 da Malga envia ao provedor de autenticação os dados do comprador. * O provedor de autenticação se comunica com a bandeira para processar a autenticação. * A bandeira identifica o emissor do cartão, e envia os dados do comprador para análise. * O emissor identifica o portador como um possível risco, desta forma, exige o desafio e retorna os dados de Autenticação. * A bandeira retorna os dados de autenticação ao provedor. * O provedor de autenticação retorna os dados de autenticação à solução 3DS2 da Malga. * A Malga retorna uma transação com status `pending` ao estabelecimento com dados adicionais para autenticação. * O estabelecimento apresenta a tela da autenticação via lightbox. * O portador resolve o desafio na tela do emissor. * O emissor retorna o resultado da autenticação à bandeira. * A bandeira retorna o resultado da autenticação ao provedor de autenticação. * O provedor de autenticação retorna o resultado da autenticação à solução 3DS2 da Malga via webhook. * A Malga retorna o resultado da autorização ao estabelecimento via webhook. * O estabelecimento informa o resultado do pagamento. ## Diagrama de sequência ![Diagrama 3DS2](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/3ds2/3ds2_diagrama.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=bef4d3aa826670017c7cefb55564c989) ## Diagrama de fluxo ![Fluxo 3DS2](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/3ds2/3DSecure2.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=02b4f857dcbe36f0e07bdc42b1bb8a04) ### Capacidade exigida O 3DS nativo exige provedor com **`operation=3ds2`**. Use a [matriz de modalidades do hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) como fonte dessa regra e a [tabela de meios de pagamento](/documentations/type-tables/payment-methods-by-providers) para identificar o badge de **3DS nativo**. O badge de **3DS2 Malga** representa outra capacidade. Para autorização com `setupId` ou MPI externo, o provedor precisa declarar `paymentTypes=3ds2_malga`, sem exigir `operation=3ds2`. # Fluxo do Antifraude Assíncrono Source: https://docs.malga.io/documentations/anti-fraud/async-anti-fraud Entenda o fluxo do antifraude assíncrono na Malga: pré-autorização, análise de risco pelo provedor e captura ou estorno automático via webhook de retorno. Os provedores antifraude assíncronos na Malga possuem um ciclo de vida que percorre quatro etapas, separadas em dois momentos: 1. Pré Autorização 2. Solicitação de Análise Antifraude 3. Recebimento da Análise 4. Captura e envio do webhook No primeiro momento a transação é enviada para o provedor de cobrança para ser pré capturada e enviada para o provedor de antifraude como ilustra o diagrama a seguir. ![Fluxo Antifraude Assíncrono](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/antifraud/async-antifraud-flux-ptbr.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=cf6619007c7ce5945de13816c90f01ee) Num segundo momento, após a avaliação de risco ser feita pelo provedor antifraude, o mesmo retorna o status através de um webhook onde a automação de captura ou cancelamento acontece. ![Fluxo Notificação Antifraude Assíncrono](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/antifraud/async-antifraud-webhook-flux-ptbr.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=3f69fa68ca51e3018753cb07f59f05cd) > [!NOTE] > > O comportamento automatizado do ciclo de vida da transação pode ser escolhido > utilizando as configurações de `captureOnApproved` e `refundOnReproved` feitas > diretamente no setup de provedor de antifraude para uso na Malga. No sandbox, o final do documento do `customer` em `fraudAnalysis` simula o assíncrono: com final `0`, a análise começa pendente e é aprovada cerca de 2 minutos depois; com final `9`, começa pendente e é reprovada no mesmo prazo. Os demais finais estão em [Testando antifraude em sandbox](/documentations/anti-fraud/testing). ## Cobrança com `capture: true` Em cartão de crédito, inclusive Click to Pay, com antifraude configurado e sem fluxo de pagamentos, a Malga aceita `capture: true` e captura sozinha quando o antifraude aprova. Isso vale para o veredito síncrono e para o assíncrono, e acontece mesmo com `captureOnApproved: false`. Não vale para 3DS com `setupId` nem para MPI externo. * **Durante a análise:** a cobrança aparece como `pre_authorized` com `capture: false`. * **Depois da captura:** a cobrança passa a `authorized` com `capture: true`. Os webhooks seguem o status. * **Prazo de 72 horas:** uma aprovação que chega depois do prazo não captura. Uma pré-autorização sem veredito em 72 horas é cancelada automaticamente. * **Reprovação e erro:** seguem as opções `captureOnReproved`, `refundOnReproved`, `captureOnError` e `refundOnError` do provedor. * **Sessão ou link de pagamento 1:1:** um novo pagamento enquanto a cobrança está em análise recebe `409` com a mensagem "There is already a charge for this session under anti-fraud analysis". Repetir a requisição com a mesma `X-Idempotency-Key` devolve a cobrança original. O recurso está em liberação gradual. Enquanto a sua conta não for liberada, a API responde `400` com a mensagem "The capture cannot be true in this operation". Fale com o suporte para habilitar. No sandbox, a simulação do veredito segue a mesma regra, mas o cancelamento automático em 72 horas não existe. > [!WARNING] > > Não é possível configurar a opção `runBeforeCharge=true` utilizando produtos > de antifraude que possuam fluxos de avaliação assíncronos ou híbridos. Caso > tenha dúvidas sobre o suporte desta variável com o seu produto antifraude > entre em contato com o nosso suporte. ## Exemplos de uso do antifraude Para utilizar análises antifraude em suas transações basta estar credenciado em um provedor antifraude e configurá-lo em seu fluxo de pagamentos. Assim, será possível processar uma transação enviando as informações adicionais de antifraude. ### Exemplo de cobrança com Antifraude aprovado > [!NOTE] > > Os exemplos abaixo usam a URL de produção (`https://api.malga.io`). Para > testar no sandbox, use `https://sandbox-api.malga.io` com suas credenciais de > sandbox. As cobranças de sandbox aparecem no ambiente de testes do Dashboard. > Veja [Ambientes](/documentations/welcome/authentication#ambientes). Após a pré autorização, se a cobrança passar pela avaliação de risco, é aprovada e capturada na sequência. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "amount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964850", "identityType": "CPF", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted": false, "email": "comprador@test.com.br", "hostName": "google.com", "ipAddress": "127.0.0.1", "type": "Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "2a37eb2c-be9b-4f92-8e13-e609130e6cca", "clientId": "", "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "description": null, "orderId": null, "createdAt": "2022-08-25T20:56:37.265Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "d10c6dbd-aff6-4875-a2a4-bf3f64f5f424" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "name": "Joao Torres", "identity": "45762964850", "identityType": "CPF", "birthdate": null, "phone": "11 99329899", "billingAddress": { "street": "Rua Um", "number": "200", "complement": "ap 10", "zipCode": "02010010", "city": "Sao Paulo", "state": "SP", "district": "Jardim Paraiso" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } }, "transactionRequests": [ { "id": "384a258d-248d-43f9-ab79-fa79a2f06237", "createdAt": "2022-08-25T20:56:37.796Z", "updatedAt": "2022-08-25T20:56:37.796Z", "idempotencyKey": null, "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "SANDBOX", "transactionId": "1737284", "amount": 100, "authorizationCode": "6076640", "authorizationNsu": "3028818", "requestStatus": "success", "requestType": "capture", "responseTs": "8ms", "providerAuthorization": { "networkAuthorizationCode": "7354551", "networkResponseCode": "5759371" } }, { "id": "f5bf6c36-0c8a-4078-84fd-b9f374bb0e1b", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": 85, "status": "approved" } }, { "id": "f5bf6c36-0c8a-4078-84fd-b9f374bb0e1b", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "dfce8327-3ecf-4725-b389-af253823acfd", "createdAt": "2022-08-25T20:56:37.432Z", "updatedAt": "2022-08-25T20:56:37.866Z", "idempotencyKey": "e4b44aa1-8386-4541-a5f3-2b6801676e32", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "SANDBOX", "transactionId": "6498444", "amount": 100, "authorizationCode": "3698706", "authorizationNsu": "4897050", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "36ms", "providerAuthorization": { "networkAuthorizationCode": "7376566", "networkResponseCode": "2946159" } } ] } ``` ### Exemplo de cobrança com Antifraude reprovado Após a pré autorização, se a análise de risco for reprovada, a transação é rejeitada e a pré autorização é cancelada automaticamente. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "amount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964859", "identityType": "CPF", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted": false, "email": "comprador@test.com.br", "hostName": "google.com", "ipAddress": "127.0.0.1", "type": "Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "2a37eb2c-be9b-4f92-8e13-e609130e6cca", "clientId": "", "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "description": null, "orderId": null, "createdAt": "2022-08-25T20:56:37.265Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "d10c6dbd-aff6-4875-a2a4-bf3f64f5f424" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "name": "Joao Torres", "identity": "45762964859", "identityType": "CPF", "birthdate": null, "phone": "11 99329899", "billingAddress": { "street": "Rua Um", "number": "200", "complement": "ap 10", "zipCode": "02010010", "city": "Sao Paulo", "state": "SP", "district": "Jardim Paraiso" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } }, "transactionRequests": [ { "id": "7b3da617-94d1-4dfd-a9e2-0e23c66dfaac", "createdAt": "2023-11-08T20:02:20.249Z", "updatedAt": "2023-11-08T20:02:20.249Z", "idempotencyKey": null, "providerId": "dd9b8ebf-3715-4809-8490-ca29556dd7cf", "providerType": "SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "responseTs": null }, { "id": "382e655d-3747-464e-8d92-9f6cba35689d", "createdAt": "2023-11-08T20:02:19.984Z", "updatedAt": "2023-11-08T20:02:20.249Z", "idempotencyKey": null, "providerId": "c6d9a756-f0db-402f-a100-2df25153294a", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": null, "fraudAnalysis": { "score": null, "status": "reproved" } }, { "id": "5299e269-c128-49de-8d44-6a2d9840bbe2", "createdAt": "2023-11-08T20:01:35.769Z", "updatedAt": "2023-11-08T20:01:35.769Z", "idempotencyKey": "c4a95944-eb3f-42a5-8010-ce0ad9c51500", "providerId": "c6d9a756-f0db-402f-a100-2df25153294a", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "3262306", "amount": 500, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "90ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "4debbc88-d863-4bfc-bcbf-a315dd3426c0", "createdAt": "2023-11-08T20:01:34.157Z", "updatedAt": "2023-11-08T20:01:34.454Z", "idempotencyKey": "c4a95944-eb3f-42a5-8010-ce0ad9c51500", "providerId": "dd9b8ebf-3715-4809-8490-ca29556dd7cf", "providerType": "SANDBOX", "transactionId": "805d0a8e-0fa0-4d74-8021-37542731f280", "amount": 500, "authorizationCode": "2234373", "authorizationNsu": "6727421", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "113ms", "providerAuthorization": { "networkAuthorizationCode": "9761119", "networkResponseCode": "5098365" } } ] } ``` > [!WARNING] > > Sempre que a transação for reprovada no antifraude, faremos o cancelamento da > pré autorização automaticamente. Caso a tentativa de cancelamento falhe, a > transação manterá o status `pre_authorized` e poderá ser cancelada ou > capturada manualmente, de acordo com a sua preferência. ### Exemplo de cobrança com erro ao acessar Antifraude Em cobranças com `capture: false`, caso um erro ocorra no provedor antifraude e nenhuma das opções de erro esteja habilitada, a transação é retornada ainda pré-autorizada. Em cobranças com `capture: true` e antifraude, a pré-autorização também existe até o veredito, e o desfecho segue `captureOnError` ou `refundOnError`. Exemplo de erro ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "amount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964851", "identityType": "CPF", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted": false, "email": "comprador@test.com.br", "hostName": "google.com", "ipAddress": "127.0.0.1", "type": "Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "2a37eb2c-be9b-4f92-8e13-e609130e6cca", "clientId": "", "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "description": null, "orderId": null, "createdAt": "2022-08-25T20:56:37.265Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "d10c6dbd-aff6-4875-a2a4-bf3f64f5f424" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "name": "Joao Torres", "identity": "45762964851", "identityType": "CPF", "birthdate": null, "phone": "11 99329899", "billingAddress": { "street": "Rua Um", "number": "200", "complement": "ap 10", "zipCode": "02010010", "city": "Sao Paulo", "state": "SP", "district": "Jardim Paraiso" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } }, "transactionRequests": [ { "id": "49d91fec-d681-4ccb-8264-0bd7bc752c92", "createdAt": "2023-11-08T20:03:41.481Z", "updatedAt": "2023-11-08T20:03:41.565Z", "idempotencyKey": null, "providerId": "c6d9a756-f0db-402f-a100-2df25153294a", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "failed", "requestType": "anti_fraud", "responseTs": null, "fraudAnalysis": { "score": null, "status": "failed" } }, { "id": "5be5bf7c-9f1d-4f3d-ac8b-009dbaac149f", "createdAt": "2023-11-08T20:03:30.962Z", "updatedAt": "2023-11-08T20:03:30.962Z", "idempotencyKey": "3aaf78bf-f82a-4a8f-bffb-4d814e5d83f6", "providerId": "c6d9a756-f0db-402f-a100-2df25153294a", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "4027144", "amount": 500, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "106ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "adf7bee1-d44a-4c2b-b2cc-6129dffb7882", "createdAt": "2023-11-08T20:03:28.948Z", "updatedAt": "2023-11-08T20:03:29.756Z", "idempotencyKey": "3aaf78bf-f82a-4a8f-bffb-4d814e5d83f6", "providerId": "dd9b8ebf-3715-4809-8490-ca29556dd7cf", "providerType": "SANDBOX", "transactionId": "b45c8d76-449c-445c-9eca-1bb7bd37cec9", "amount": 500, "authorizationCode": "8128049", "authorizationNsu": "7221186", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "301ms", "providerAuthorization": { "networkAuthorizationCode": "8852082", "networkResponseCode": "3142846" } } ] } ``` > [!WARNING] > > Caso ocorra alguma instabilidade com o provedor antifraude, existem duas opções para lidar com este cenário que devem ser configuradas em seu fluxo de pagamentos: > > * `captureOnError`: Faz a captura mesmo que ocorra instabilidade no provedor de antifraude. > * `refundOnError`: Faz o estorno da transação em caso de instabilidade no provedor de antifraude. Não pode ser ligada ao mesmo tempo que `captureOnError`. > > Em cobranças com `capture: false`, quando `captureOnError` e `refundOnError` estão desligadas, a transação é retornada como `pre_authorized`. Em cobranças com `capture: true` e antifraude, a transação segue pré-autorizada até o veredito e, sem veredito em 72 horas, é cancelada automaticamente. > [!NOTE] > > Para testar os diversos comportamentos das propriedades descritas acima, veja > sobre [Alterar o status do antifraude no ambiente de > sandbox](/api-reference/charges/alterar-o-status-do-antifraude-no-ambiente-de-sandbox) # Fluxo de Feeding Source: https://docs.malga.io/documentations/anti-fraud/feeding-anti-fraud Com objetivo de **melhorar a taxa de aprovação dos antifraudes de nossos clientes e a perda de vendas legítimas**, a Malga é capaz de fornecer aos provedores de antifraude as informações das transações que **não serão avaliadas**, para que possam fazer composição de base e chegarem a um modelo melhor para avaliação das transações. O processo começa com a criação de uma transação, que pode ser efetuada por meio de qualquer método de pagamento disponível - transações de **Pix, Boleto, Wallets, BNPL e Voucher, aprovadas ou não, transações de cartão de crédito que não foram avaliadas pelo antifraude configurado (devido, por exemplo, a um fluxo inteligente configurado) aprovadas ou não**. O processo apenas ocorrerá quando o provedor antifraude estiver configurado na subconta \[`merchant`] com a propriedade `options.sendAllCharges` com valor `true`. Uma vez criada uma transação, se seu status final for `Authorized`, `Failed`, `Canceled` ou `Voided`, os dados relativos à sua criação serão encaminhados ao provedor de antifraude. O próprio pagamento **não será avaliado**, e sua aprovação na Malga e em outros provedores não estará condicionada ao aceite ou recusa do provedor de antifraude. Portanto, esse fluxo permite **otimizar a análise de fraudes**, uma vez que o provedor de antifraude, usando os dados de transações com os mais diversos métodos de pagamento, terá um maior volume de dados para usar como referência e criar um perfil dos seus clientes para uma avaliação mais precisa. ## Como habilitar Exemplo de payload de criação de provedor de antifraude com `options.sendAllCharges` assumindo valor `true`. ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mcc": "4040", "status": true, "providers": [ { "name": "SANDBOX", "priority": 1, "credentials": { "type": "SANDBOX", "apiKey": "apiKey_1044838358" } }, { "name": "ANTIFRAUD_SANDBOX", "priority": 1, "credentials": { "type": "ANTIFRAUD_SANDBOX", "apiKey": "apiKey_1044838358" }, "options": { "type": "ANTIFRAUD", "sendAllCharges": true, "captureOnApproved": true, "refundOnReproved": true } } ] }' ``` # Começando em Antifraude Source: https://docs.malga.io/documentations/anti-fraud/intro Como funciona o Antifraude na Malga: configure provedores para análise de risco em transações de cartão de crédito com mais segurança. ## Antifraude no cartão de crédito Nossa API está preparada para fazer análise de risco em provedores de antifraude, sem a necessidade de integrações adicionais e dentro do próprio fluxo de cobranças do cartão de crédito. Esta avaliação de risco pode ser feita de forma síncrona ou assíncrona e requer algumas **[informações adicionais](/api-reference/charges/realizar-nova-cobranca)** no payload de cobrança para que ela possa ser feita. Os provedores suportados podem ser consultados na **[tabela de provedores antifraude](/documentations/type-tables/antifraude-providers)**. ## Configurando um provedor antifraude Além da configuração no fluxo inteligente, é possível configurar o antifraude da Malga para processar algumas automações de acordo com o retorno da avaliação de risco. Quando for adicionar um provedor antifraude na Malga é importante estar atento ao modelo de retorno do serviço configurado. Estão disponíveis para orquestração na Malga antifraudes com retorno síncrono e retorno assíncrono. Em alguns casos provedores antifraude podem exibir comportamentos tanto de retornos síncronos quanto assíncronos, sendo chamados de híbridos. Quando estiver integrando um antifraude de modelo híbrido, você deve considerar os dois ciclos de vida. ### Ciclo de vida síncrono As transações são avaliadas no momento de sua criação e são resolvidas automaticamente. O resultado da avaliação e da transação é determinado na resposta da requisição de criação. ### Ciclo de vida assíncrono O provedor de avaliação de risco retorna um status aguardando uma validação e a transação só é finalizada após a conclusão dos eventos de webhook. Em geral, produtos com ciclo de vida assíncrono também podem ser híbridos (síncrono e assíncrono ao mesmo tempo). ### Opções de configuração de provedores antifraude | Opção | Descrição | Tem efeito quando | | - | - | - | | `runBeforeCharge` | Executa o provedor antifraude antes do provedor de cobrança. Não pode ser habilitado em provedores assíncronos ou híbridos. | sempre | | `captureOnApproved` | Captura a transação automaticamente quando o provedor antifraude aprova. | em cobranças com `capture: false`. Com `capture: true`, a captura após aprovação acontece mesmo com a opção desligada (veja abaixo) | | `captureOnReproved` | Captura a transação mesmo quando o provedor antifraude **reprova**. | em cobranças com `capture: false` ou `capture: true` liberada (veja abaixo) | | `refundOnReproved` | Estorna ou cancela a transação automaticamente quando o provedor antifraude reprova. | sempre | | `captureOnError` | Captura a transação quando a chamada ao provedor antifraude falha. Com `runBeforeCharge` habilitado, faz a cobrança seguir para o adquirente mesmo sem avaliação de risco. | com `capture: false` ou `capture: true` liberada, e também no modo `runBeforeCharge` | | `refundOnError` | Estorna a transação quando a chamada ao provedor antifraude falha. | sempre | | `productType` | Modo de funcionamento esperado do provedor. Aceita `SYNC` ou `ASYNC`. Para provedores com resposta híbrida, utilize `ASYNC`. | sempre | | `sendAllCharges` | Envia também as cobranças que não foram avaliadas, para melhorar a calibragem do provedor. | sempre | > [!WARNING] > > **Configure todas as opções explicitamente.** Quando uma opção não é > informada, o comportamento adotado depende do arranjo do seu fluxo, ou seja, > do `capture` da cobrança e do `runBeforeCharge` do provedor, e não é o mesmo > em todos os caminhos. Definir cada valor evita surpresa quando você muda de > um arranjo para outro. > [!WARNING] > > O `captureOnReproved` captura uma transação que o antifraude classificou como > risco. Use apenas se essa for uma decisão consciente de aceitar a venda mesmo > com reprovação, e não o combine com `refundOnReproved`, porque os dois pedem > desfechos opostos para o mesmo veredito. Além das configurações de automação, ao configurar um provedor antifraude em um merchant na Malga é possível escolher se você deseja enviar as transações não avaliadas pelo antifraude para o provedor com o objetivo de melhorar a calibragem do mesmo. Esta configuração também pode ser utilizada para calibrar um novo antifraude antes de utilizá-lo em sua orquestração. ### Cobrança com `capture: true` Em cartão de crédito, inclusive Click to Pay, com antifraude configurado e sem fluxo de pagamentos, a Malga pré-autoriza a cobrança e captura sozinha quando o antifraude aprova, seja o veredito síncrono ou assíncrono. A captura acontece mesmo com `captureOnApproved: false`. Reprovação e erro seguem as opções `captureOnReproved`, `refundOnReproved`, `captureOnError` e `refundOnError`. Não vale para 3DS com `setupId` nem para MPI externo. A aprovação precisa chegar em até 72 horas. Depois do prazo, a aprovação não captura, e uma pré-autorização sem veredito é cancelada automaticamente. O recurso está em liberação gradual: enquanto a sua conta não for liberada, a API responde `400` com a mensagem "The capture cannot be true in this operation". Fale com o suporte para habilitar. Os detalhes estão em [Antifraudes síncronos](/documentations/anti-fraud/sync-anti-fraud) e [Antifraudes assíncronos](/documentations/anti-fraud/async-anti-fraud). ### Informações de aparelhos e comportamentos de uso - Fingerprints É comum que provedores antifraude solicitem informações sobre o aparelho que está sendo utilizado para originar a transação. Recomendamos que você utilize o SDK do provedor configurado em seu fluxo de pagamentos e encaminhe o fingerprint nas requisições de cobrança, com o intuito de manter a qualidade da avaliação de risco e, assim, aumentar sua taxa de aprovação. > [!WARNING] > > Alguns provedores antifraude obrigam o uso de Fingerprints em sua integração. | Provedor | Fingerprint obrigatório? | | - | - | | Clearsale | SIM | ## Retornos possíveis Recomendamos enviar o objeto `fraudAnalysis` em todas as cobranças de cartão de crédito quando existe um provedor antifraude no seu fluxo inteligente. É ele que carrega os dados do comprador e do carrinho que o provedor usa para avaliar o risco. Para confirmar que a avaliação aconteceu, procure uma `transactionRequest` do tipo `anti_fraud` na cobrança. Se ela não existir, nenhuma avaliação de risco foi feita naquela transação. Quando uma transação é avaliada por um provedor de antifraude é criada uma `transactionRequest` do tipo `anti_fraud`, que pode assumir os status a seguir. | Status Fraud Analysis | Descrição | | - | - | | `pending` | Sua transação foi enviada para ser avaliada e terá um retorno de avaliação assíncrono. | | `approved` | Sua transação foi aprovada pelo provedor antifraude. | | `reproved` | Sua transação foi reprovada pelo provedor antifraude. | # Malga Checkout Source: https://docs.malga.io/documentations/anti-fraud/malga-checkout # Utilizando o Malga Checkout com antifraude É possível utilizar o Malga Checkout e enviar os parâmetros de antifraude para o provedor, além disso o nosso checkout pode ser combinado com o SDK de um provedor de antifraude para uma solução mais completa. ## Utilizando o Malga Checkout com a Clearsale Para adicionar o antifraude da Clearsale nos pagamentos feitos através do Malga Checkout é necessário adicionar o `Behavior Analytics SDK`, da própria Clearsale, na sua aplicação `front-end` e utilizar `sessionId` provido por ele nas configurações do Malga Checkout. * [Adicionando o Behavior Analytics SDK na sua aplicação;](https://api.clearsale.com.br/docs/behavior-analytics/sdk/browser) Depois, já com o `Behavior Analytics SDK` devidamente implementado, basta enviar o `sessionId` no campo `browserFingerprint`, como mostra o exemplo abaixo: > [!NOTE] > > O sessionId pode ser um UUID gerado randomicamente a cada nova sessão de > usuário e enviado para a Clearsale ou ser gerado pelo próprio SDK dela. > Confira mais detalhes sobre o sessionId no FAQ do [`Behavior Analytics > SDK`](https://api.clearsale.com.br/docs/behavior-analytics/faq) ```md theme={null} Malga Checkout Components
``` # Fluxo do Antifraude Síncrono Source: https://docs.malga.io/documentations/anti-fraud/sync-anti-fraud Entenda o fluxo do antifraude síncrono na Malga, com pré-autorização, análise de risco e captura ou estorno automático via runBeforeCharge. Os provedores antifraude síncronos na Malga podem ser configurados para serem executados antes ou depois das transações através da opção `runBeforeCharge`. Para `runBeforeCharge=false`, o ciclo de vida de uma transação com avaliação antifraude percorre três etapas: 1. Pré Autorização 2. Análise Antifraude 3. Captura Para garantir que a venda não será perdida e que está apta a ser processada pelo antifraude, o pagamento é pré-autorizado e, em seguida, é feita uma verificação no provedor de risco. Por padrão, caso a análise seja aprovada, o pagamento é capturado. Caso contrário, ela é estornada automaticamente. ![Fluxo Antifraude](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/antifraud/antifraud-flux-ptbr.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=a056ed4bb5c1d7cd062614a6cfdad59f) > [!NOTE] > > O comportamento automatizado do ciclo de vida da transação pode ser escolhido > utilizando as configurações de `captureOnApproved` e `refundOnReproved` feitas > diretamente no setup de provedor de antifraude para uso na Malga. Para `runBeforeCharge=true`, o ciclo de vida de uma transação com avaliação antifraude percorre duas etapas: 1. Análise Antifraude 2. Captura ![Fluxo Antifraude](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/antifraud/antifraud-flux-runBeforeCharge-ptbr.jpg?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=6ed43f0907994ea3a5a184b999225d23) Com esta configuração, todas as transações serão avaliadas pelo antifraude antes de serem processadas nos provedores de cobrança. ## Quais opções valem em cada arranjo O `capture` que você envia na cobrança define quais opções do provedor antifraude chegam a ser consideradas. É a fonte mais comum de confusão, porque a intuição costuma ser a oposta do comportamento real. | Arranjo da cobrança | O que acontece | Opções que decidem o desfecho | | - | - | - | | `capture: false` | Pré-autorizamos, avaliamos o risco e então capturamos ou cancelamos. | `captureOnApproved`, `captureOnReproved`, `refundOnReproved`, `captureOnError`, `refundOnError` | | `capture: true` | Pré-autorizamos, avaliamos o risco e capturamos quando o antifraude aprova, mesmo com `captureOnApproved: false`. Depende de liberação gradual. | `captureOnReproved`, `refundOnReproved`, `captureOnError`, `refundOnError` | | `runBeforeCharge` habilitado | Avaliamos antes de acionar o adquirente. Uma reprovação impede que a cobrança exista. | `captureOnReproved` e `captureOnError` decidem se a cobrança segue mesmo assim | > [!WARNING] > > Com `capture: true` e antifraude configurado, a Malga pré-autoriza a cobrança > e captura sozinha quando o antifraude aprova, sem que você chame o serviço de > captura. Esse comportamento vale para cartão de crédito, inclusive Click to > Pay, em merchants sem fluxo de pagamentos. Não vale para 3DS com `setupId` nem > para MPI externo. > > Durante a análise, a cobrança aparece como `pre_authorized` com > `capture: false`. Depois da captura, ela passa a `authorized` com > `capture: true`, e os webhooks seguem o status. > > O recurso está em liberação gradual. Enquanto a sua conta não for liberada, a > API responde `400` com a mensagem "The capture cannot be true in this > operation". Fale com o suporte para habilitar. Se você quer que o resultado > do antifraude decida os dois lados sem depender dessa liberação, envie > `capture: false`. > [!NOTE] > > O prazo para o antifraude aprovar e a cobrança ser capturada é de 72 horas, > contadas da criação. Uma aprovação que chega depois do prazo não captura. Uma > pré-autorização que continua sem veredito após as 72 horas é cancelada > automaticamente. Reprovação e erro do antifraude seguem as opções do > provedor, como em qualquer outra cobrança. No sandbox, a simulação do > veredito segue a mesma regra, mas o cancelamento automático em 72 horas não > existe. ## Exemplos de uso do antifraude Para utilizar análises antifraude em suas transações basta estar credenciado em um provedor antifraude e configurá-lo em seu fluxo de pagamentos. Assim, será possível processar uma transação enviando as informações adicionais de antifraude. ### Exemplo de cobrança com Antifraude aprovado > [!NOTE] > > Os exemplos abaixo usam a URL de produção (`https://api.malga.io`). Para > testar no sandbox, use `https://sandbox-api.malga.io` com suas credenciais de > sandbox. As cobranças de sandbox aparecem no ambiente de testes do Dashboard. > Veja [Ambientes](/documentations/welcome/authentication#ambientes). Após a pré autorização, se a cobrança passar pela avaliação de risco, é aprovada e capturada na sequência. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "amount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964851", "identityType": "CPF", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted": false, "email": "comprador@test.com.br", "hostName": "google.com", "ipAddress": "127.0.0.1", "type": "Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "2a37eb2c-be9b-4f92-8e13-e609130e6cca", "clientId": "", "merchantId": "c04b6955-09d5-42ab-bc4a-287504ed0098", "description": null, "orderId": null, "createdAt": "2022-08-25T20:56:37.265Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "d10c6dbd-aff6-4875-a2a4-bf3f64f5f424" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "name": "Joao Torres", "identity": "45762964851", "identityType": "CPF", "birthdate": null, "phone": "11 99329899", "billingAddress": { "street": "Rua Um", "number": "200", "complement": "ap 10", "zipCode": "02010010", "city": "Sao Paulo", "state": "SP", "district": "Jardim Paraiso" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "complement": "ap 1", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } }, "transactionRequests": [ { "id": "384a258d-248d-43f9-ab79-fa79a2f06237", "createdAt": "2022-08-25T20:56:37.796Z", "updatedAt": "2022-08-25T20:56:37.796Z", "idempotencyKey": null, "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "SANDBOX", "transactionId": "1737284", "amount": 100, "authorizationCode": "6076640", "authorizationNsu": "3028818", "requestStatus": "success", "requestType": "capture", "responseTs": "8ms", "providerAuthorization": { "networkAuthorizationCode": "7354551", "networkResponseCode": "5759371" } }, { "id": "f5bf6c36-0c8a-4078-84fd-b9f374bb0e1b", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": 85, "status": "approved" } }, { "id": "dfce8327-3ecf-4725-b389-af253823acfd", "createdAt": "2022-08-25T20:56:37.432Z", "updatedAt": "2022-08-25T20:56:37.866Z", "idempotencyKey": "e4b44aa1-8386-4541-a5f3-2b6801676e32", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "SANDBOX", "transactionId": "6498444", "amount": 100, "authorizationCode": "3698706", "authorizationNsu": "4897050", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "36ms", "providerAuthorization": { "networkAuthorizationCode": "7376566", "networkResponseCode": "2946159" } } ] } ``` ### Exemplo de cobrança com Antifraude reprovado Após a pré autorização, se a análise de risco for reprovada, a transação é rejeitada e a pré autorização é cancelada automaticamente. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "8b6b4c57-fa57-4d8b-84e8-77cce8482cc9", "amount": 991, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "João Neves", "identity": "62871519005", "identityType": "CPF", "birthdate": null, "phone": "219988776654", "billingAddress": { "street": "Rua CJ-14", "number": "100", "zipCode": "69314702", "country": "BR", "state": "PR", "district": "Jardim Tropical", "city": "Boa vista", "complement": "ap 110" }, "browser":{ "browserFingerprint":"57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted":false, "email":"comprador@test.com.br", "hostName":"google.com", "ipAddress":"127.0.0.1", "type":"Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 991, "risk": "High" } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "44d7ceab-f501-4abc-965c-45f5265d249f", "clientId": "", "merchantId": "8b6b4c57-fa57-4d8b-84e8-77cce8482cc9", "description": null, "orderId": null, "createdAt": "2022-08-10T19:21:19.452Z", "amount": 0, "originalAmount": 991, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "canceled", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "f84d1566-0398-471d-b48b-3048ed83ea3e" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "id": "32ef3246-2635-4060-a3e3-a6d34e0bcb10", "updatedAt": "2022-08-10T14:31:37.045Z", "createdAt": "2022-08-10T14:31:37.045Z", "idempotencyKey": null, "requestId": null, "name": "João Neves", "identity": "62871519005", "identityType": "CPF", "birthdate": null, "phone": "219988776654", "billingAddress": { "street": "Rua CJ-14", "number": "100", "zipCode": "69314702", "country": "BR", "state": "PR", "district": "Jardim Tropical", "city": "Boa vista", "complement": "ap 110" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 991, "risk": "High" } ] } }, "transactionRequests": [ { "id": "18c9aae5-4723-4913-9cb0-28b7536e83ff", "createdAt": "2022-08-10T19:21:21.910Z", "updatedAt": "2022-08-10T19:21:21.910Z", "idempotencyKey": null, "providerId": "7a6c5924-076f-45d6-82ca-ca3dfc9ab2a8", "providerType": "PAGARME_V5", "transactionId": "17979806", "amount": 991, "authorizationCode": "386630", "authorizationNsu": "17979806", "requestStatus": "success", "requestType": "void", "responseTs": "333ms", "providerAuthorization": { "networkAuthorizationCode": "386630", "networkResponseCode": "authorized" } }, { "id": "7cd80b1c-59b3-46a6-9ef9-a6fe1d036cb9", "createdAt": "2022-08-10T19:21:21.393Z", "updatedAt": "2022-08-10T19:21:21.393Z", "idempotencyKey": null, "providerId": "7fe5a4b6-9428-45da-94ca-184819f3f273", "providerType": "CLEARSALE", "transactionId": "877429535F26463EA0EB7991471BCD43", "amount": 991, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "1340ms", "fraudAnalysis": { "score": 97, "status": "reproved" } }, { "id": "61e799c0-8388-46a3-8d52-768e8c5d4982", "createdAt": "2022-08-10T19:21:19.532Z", "updatedAt": "2022-08-10T19:21:21.982Z", "idempotencyKey": "345fcdec-a431-41f5-8976-69e79ca908e8", "providerId": "7a6c5924-076f-45d6-82ca-ca3dfc9ab2a8", "providerType": "PAGARME_V5", "transactionId": "17979806", "amount": 991, "authorizationCode": "386630", "authorizationNsu": "17979806", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "418ms", "providerAuthorization": { "networkAuthorizationCode": "386630", "networkResponseCode": "authorized" } } ] } ``` > [!WARNING] > > Sempre que a transação for reprovada no antifraude, por padrão faremos o > cancelamento da pré autorização automaticamente. Caso a tentativa de > cancelamento falhe, a transação manterá o status `pre_authorized` e poderá ser > cancelada ou capturada manualmente, de acordo com a sua preferência. ### Exemplo de cobrança com erro ao acessar Antifraude Em cobranças com `capture: false`, caso um erro ocorra no provedor antifraude e nenhuma das opções de erro esteja habilitada, a transação é retornada ainda pré-autorizada. Em cobranças com `capture: true` e antifraude, a pré-autorização também existe até o veredito, e o desfecho segue `captureOnError` ou `refundOnError`. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "4dc47427-0257-44dd-9607-e10f10a7bdb1", "amount": 991, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2026" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "João Neves", "identity": "62871519005", "identityType": "CPF", "birthdate": null, "phone": "219988776654", "billingAddress": { "street": "Rua CJ-14", "number": "100", "zipCode": "69314702", "country": "BR", "state": "PR", "district": "Jardim Tropical", "city": "Boa vista", "complement": "ap 110" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 991, "risk": "High" } ] } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "0bbd06e6-7424-4f17-a66b-be313212bf97", "clientId": "", "merchantId": "4dc47427-0257-44dd-9607-e10f10a7bdb1", "description": null, "orderId": null, "createdAt": "2022-08-10T19:26:55.701Z", "amount": 991, "originalAmount": 991, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "pre_authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "4481cbca-c501-40c3-9136-0bed194301c5" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "id": "32ef3246-2635-4060-a3e3-a6d34e0bcb10", "updatedAt": "2022-08-10T14:31:37.045Z", "createdAt": "2022-08-10T14:31:37.045Z", "idempotencyKey": null, "requestId": null, "name": "João Neves", "identity": "62871519005", "identityType": "CPF", "birthdate": null, "phone": "219988776654", "billingAddress": { "street": "Rua CJ-14", "number": "100", "zipCode": "69314702", "country": "BR", "state": "PR", "district": "Jardim Tropical", "city": "Boa vista", "complement": "ap 110" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 991, "risk": "High" } ] } }, "transactionRequests": [ { "id": "326624fb-9140-4ceb-b81f-7345aacc3c5a", "createdAt": "2022-08-10T19:26:56.388Z", "updatedAt": "2022-08-10T19:26:56.388Z", "idempotencyKey": "d1501629-d6cf-495f-a533-15e53df02765", "providerId": "7fe5a4b6-9428-45da-94ca-184819f3f273", "providerType": "CLEARSALE", "transactionId": null, "amount": 991, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "timeout", "requestType": "anti_fraud", "responseTs": "9ms", "providerError": { "retryable": false, "declinedCode": null, "networkDeniedMessage": null, "networkDeniedReason": null } }, { "id": "dbf43dad-3434-4a17-bd59-6b24d2db2647", "createdAt": "2022-08-10T19:26:55.802Z", "updatedAt": "2022-08-10T19:26:56.412Z", "idempotencyKey": "d1501629-d6cf-495f-a533-15e53df02765", "providerId": "7a6c5924-076f-45d6-82ca-ca3dfc9ab2a8", "providerType": "PAGARME_V5", "transactionId": "17981570", "amount": 991, "authorizationCode": "430210", "authorizationNsu": "17981570", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "467ms", "providerAuthorization": { "networkAuthorizationCode": "430210", "networkResponseCode": "authorized" } } ] } ``` > [!WARNING] > > Caso ocorra alguma instabilidade com o provedor antifraude, existem duas > opções para lidar com este cenário que devem ser configuradas em seu fluxo de > pagamentos: - `captureOnError`: Faz a captura mesmo que ocorra instabilidade > no provedor de antifraude. - `refundOnError`: Faz o estorno da transação em > caso de instabilidade no provedor de antifraude. Não pode ser ligada ao mesmo > tempo que `captureOnError`. Em cobranças com `capture: false`, quando > `captureOnError` e `refundOnError` estão desligadas, a transação é retornada > como `pre_authorized`. Em cobranças com `capture: true` e antifraude, a > transação segue pré-autorizada até o veredito e, sem veredito em 72 horas, é > cancelada automaticamente. # Testando em Sandbox Source: https://docs.malga.io/documentations/anti-fraud/testing Você pode usar o provedor de sandbox da Malga para controlar os resultados de antifraude em transações de teste. O controle usa o documento de identidade do `customer` enviado junto aos dados de `fraudAnalysis`. Gere o número da identidade em qualquer gerador de identidades, seguindo a regra abaixo: | Documento | Autorizado? | Status | Declined Code | | - | - | - | - | | Final 0 | NÃO | Pendente; **Aprovado** após 2 minutos | Nulo | | Final 1 | SIM | Aprovado | Nulo | | Final 2 | NÃO | Falha | Aleatório `timeout` ou `processing_error` | | Final 3 | NÃO | Erro no antifraude (análise falha) | Nulo | | Final 9 | NÃO | Pendente; **Reprovado** após 2 minutos | Nulo | | Qualquer outro final | NÃO | Reprovado | Nulo | Os finais 0 e 9 simulam o antifraude assíncrono: a análise começa pendente e o veredito chega sozinho cerca de 2 minutos depois. A cobrança então segue as `options` cadastradas para o provedor, como `captureOnApproved` e `refundOnReproved`. > [!NOTE] > > Para escolher o veredito e o momento do assíncrono você mesmo, use o > **[endpoint de alteração de status de > antifraude](/api-reference/charges/alterar-o-status-do-antifraude-no-ambiente-de-sandbox)** > e observe as várias alterações possíveis de status na transação, dependendo > das `options` cadastradas para o provedor. Para configurar o antifraude de sandbox, adicione o provedor antifraude `"ANTIFRAUD_SANDBOX"` a um **merchant** da sua conta de sandbox que já use o provedor de transação `"SANDBOX"`. Em seguida, determine o comportamento automático do antifraude com as flags do objeto `options`. > [!WARNING] > > As chaves de sandbox não criam merchants: `POST /v1/merchants` devolve `403 > Forbidden` nesse ambiente. Também não adianta enviar `providers` no `PATCH > /v1/merchants/{id}`, porque o campo é ignorado na atualização. Para adicionar > o antifraude, use o endpoint de providers descrito abaixo. # Exemplo de cadastro do provedor de antifraude de sandbox Consulte o `id` do merchant em `GET /v1/merchants` e envie-o em `merchantId`: ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/providers' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw ' { "merchantId": "", "name": "antifraud_sandbox", "priority": 1, "credentials": { "type": "ANTIFRAUD_SANDBOX", "apiKey": "" }, "options": { "type": "ANTIFRAUD", "captureOnError": false, "refundOnError": false, "captureOnApproved": true, "refundOnReproved": true } }' ``` A resposta, com status `201`, traz o `id` do provedor criado. Para remover o antifraude do merchant, use esse `id`: ```bash theme={null} curl --location --request DELETE 'https://sandbox-api.malga.io/v1/providers/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' ``` A remoção devolve `204 No Content`. Para mudar as flags de `options` sem remover o provedor, use o **[endpoint de atualização de provider](/api-reference/providers/atualizar-configuracoes-de-provider-de-merchant)**. # Gestão de Cobranças Source: https://docs.malga.io/documentations/dashboard/charge-details Guia de Gestão de Cobranças no Dashboard Malga: monitore transações, faça estornos e capturas e acompanhe o processamento de pagamentos. # 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. > [!TIP] > > 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 seçã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 ![Listagem de cobranças](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/list-charges-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=af964bff7bf728c3c9463d673029c9aa) **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**, **recebedor**, **cobranças com split ou em disputa** e, na visão Empresa, **subconta** > [!NOTE] > > O filtro de subconta aparece apenas na visão Empresa. Na visão de uma subconta, a listagem já mostra somente as cobranças dela, conforme o [seletor de contexto](/documentations/dashboard/context-selector) do menu lateral. #### Filtros da área de cobranças ![Filtros da área de Cobranças](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/filters-charges-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=783506dded1857f1c5429f90ed1e2c17) ![Filtros da área de Cobranças em Subconta](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/filters-charges-merchant-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=c64b41741290d40b026de70ffff25709) #### Pesquisas na área de cobranças ![Search Charges Light](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/search-charges-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=639a8fbbae8c365b9fdccefb35059135) #### Exportar cobranças em relatório .csv ![Export Charge](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/export-charge-light.gif?s=a1485ef377037bedafec21fccd908a01) > [!NOTE] > > 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 identificação delas no seletor de contexto e no filtro por subconta, disponível na visão Empresa dos menus Painel de Dados, Cobranças, Relatórios e Assinaturas > * **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. O detalhe se divide nas abas **Geral** e **Repasses**. Na aba **Geral** 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 de recorrência:** se a cobrança possuir serviço de recorrência, serão exibidas as informações sobre o tipo de recorrência que foi atribuída àquela charge, correspondendo a: * **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 A aba **Repasses** mostra para onde foi o dinheiro da cobrança: * **Regras da divisão:** se a cobrança possuir split, a aba mostra uma linha por recebedor, com a regra aplicada e o valor bruto. Nas cobranças do provedor Malga, a aba também mostra as taxas e o valor líquido de cada recebedor * **Recebíveis:** nas cobranças do provedor Malga, a aba mostra as parcelas da cobrança, agrupadas por recebedor, com a previsão de cada uma e o repasse em que ela entrou. Pelo link **Ver repasse**, você abre o detalhe do repasse #### Detalhe de uma cobrança ![Detalhe de uma cobrança](https://mintlify.s3.us-west-1.amazonaws.com/malga/assets/images/dashboard/charge-details/charge-details--light.gif) #### Aba Repasses no detalhe da cobrança ![Detalhe da cobrança com as abas Geral e Repasses, mostrando as regras da divisão e os recebíveis](https://mintcdn.com/malga/ZIWewmI5oz773_hd/assets/images/release/2026-10-19/cobranca-aba-repasses.gif?s=85dc63b1d459653f4beaf65addad9df8) > [!TIP] > > 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 a 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 (chargeback) #### **Status das cobranças** Confira mais informações em nossa [documentação](/documentations/payment-methods/intro#status-da-transaçã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 | Chargeback (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 à notificação de disputa: | Provedor | Abertura de Disputa - Provedor | Abertura de Disputa - Malga | | - | - | - | | Adyen | | | | Barte | | | | Braintree | | | | Braspag | | | | Cielo | | | | Klap | | | | Mercado Pago | | | | Owempay | | | | PicPay | | | | Pagar.Me V5 | | | | PagSeguro | | | | PayPal | | | | Rede | | | | SafraPay (Beta) | | | | Stripe | | | | WorldPay | | | | Zoop | | | > [!NOTE] > > Na **SafraPay (Beta)**, a Malga recebe apenas o webhook de **início da operação de disputa**. Não há integração com a API completa de chargeback do provedor. #### **Acompanhamento e tratamento de disputas** A Malga recebe as notificações de disputa enviadas pelo provedor e as repassa via [webhooks](/documentations/webhooks/webhook1-1). A abertura da disputa é sinalizada pelo evento `transaction.dispute` e pela flag `isDispute` na cobrança. O encerramento é sinalizado pelo evento `transaction.dispute_closed` (disputa encerrada com ganho da loja, cobrança permanece **Authorized**) ou `transaction.charged_back` (disputa perdida pela loja, cobrança muda para **Chargeback**). Sobre o escopo da Malga nas disputas: * Os webhooks de disputa não incluem o motivo ou a justificativa da contestação. Para consultar o motivo alegado pelo portador do cartão, acesse o portal do provedor ou adquirente responsável pela transação. * A Malga não oferece endpoint na API nem ação no Dashboard para responder, contestar ou encerrar uma disputa. O envio da documentação de defesa é feito diretamente com o provedor ou adquirente. * A Malga não realiza a liquidação financeira. Quando a loja perde a disputa, o débito do valor contestado é conduzido pelo provedor ou adquirente. * As regras do processo de disputa em si são definidas pela bandeira do cartão e pelo emissor. Isso inclui prazos de abertura e a possibilidade de o portador contestar novamente uma disputa já perdida. A Malga apenas reflete o resultado da disputa no status da cobrança, conforme a tabela de mudanças de status acima. ### **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 ![Estornar e Capturar no Detalhe de Cobrança](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/voided-and-capture-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=389c00cf53c61e3d218c6d9ad62b8e4d) **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 ![Estornar Cobrança](https://mintcdn.com/malga/RfUqGSgomX0rzDrW/assets/images/dashboard/charge-details/voided-charge-light.webp?fit=max\&auto=format\&n=RfUqGSgomX0rzDrW\&q=85\&s=6752ea6af157bfc70d316973552a2e53) Após a operação de **Estorno**, a cobrança autorizada terá seu status alterado para **Estornada** e a requisição de estorno bem-sucedida 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-sucedida ![Detalhes de uma transação após estorno](https://mintcdn.com/malga/rhnxtwlq4HOPUO6e/assets/images/dashboard/charge-details/details-voided-light.png?fit=max\&auto=format\&n=rhnxtwlq4HOPUO6e\&q=85\&s=e7600a994d424a44160e3ca31467b7a9) #### Cobrança com status estornada ![Cobrança com status Estornada](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/status-voided-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=090d2a462a6e5288f880b6271867c05a) > [!NOTE] > > 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#pré-autorização-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 ![Capturar cobrança pré-autorizada](https://mintcdn.com/malga/rhnxtwlq4HOPUO6e/assets/images/dashboard/charge-details/capture-charge-light.png?fit=max\&auto=format\&n=rhnxtwlq4HOPUO6e\&q=85\&s=b106f47ccc4e07294106ca90342eb0cb) > [!NOTE] > > 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 sinalizadores indicando quando uma transação estiver em disputa ou com reversão de estorno. #### Disputa em aberto ![Disputa aberta](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/dispute-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=3e0c447608554a57fd0db22191f2a95a) #### Disputa fechada ![Disputa fechada](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/dispute-closed-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=5200c09fa3158d07bb4d091f4f80ea9f) ### **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 | | | | | | | 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**, retornados 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 autorizada ![Histórico de Operações de uma cobrança autorizada](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/details-history-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=619e20328989aa977ae2f6d44e3dbbb7) **Ações realizadas pela 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 1ª 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 ![Histórico de Operações de uma cobrança pela sonda](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/charge-details/sonda-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=267aa5d0044bf99906e406333a6b1e28) A **ação da Sonda é 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. > [!TIP] > > 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 | > [!NOTE] > > CHAVE DE IDEMPOTÊNCIA Confira mais informações sobre a utilização da **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 ![Identificadores no Histórico de Operações](https://mintcdn.com/malga/rhnxtwlq4HOPUO6e/assets/images/dashboard/charge-details/identifiers-in-operation-history-light.png?fit=max\&auto=format\&n=rhnxtwlq4HOPUO6e\&q=85\&s=5bdf4fcbaee38e023e9c9dbe4ad2b5e6) *** ### 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) > [!NOTE] > > 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. # Navegação por empresa e subcontas Source: https://docs.malga.io/documentations/dashboard/context-selector Use o seletor do menu lateral para alternar entre a visão consolidada da empresa e a visão de uma subconta específica. O Dashboard Malga segue o modelo **empresa → subcontas**. Pelo **seletor de contexto**, no topo do menu lateral, você escolhe uma única vez se quer ver os dados consolidados da empresa ou os de uma subconta específica. A escolha vale para toda a navegação: menus, filtros e formulários se ajustam ao contexto selecionado. ![Seletor de contexto aberto no menu lateral](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/context-selector/selector-open-dark.gif?s=3beba29bb88a11b41ae2af579650becb) ## Visão Empresa e visão Subconta * **Visão Empresa**: dados consolidados de todas as subcontas. Nas páginas com filtros, você pode filtrar por subconta. * **Visão Subconta**: somente os dados da subconta selecionada. O filtro de subconta não aparece, porque o contexto já está definido pelo seletor. ## Como trocar de contexto **1. Abra o seletor** Clique no nome da empresa (ou da subconta ativa), no topo do menu lateral. **2. Escolha o contexto** Selecione **Empresa** para a visão consolidada, ou uma subconta na seção **Subcontas**. Use o campo **Buscar empresa ou subconta** para encontrar uma subconta pelo nome. **3. Pronto** Você continua na mesma página e apenas os dados mudam. Se a página não existir no novo contexto, você é levado para o **Painel de dados**. > [!NOTE] > > Ao trocar de contexto, os filtros aplicados e a posição de rolagem da página são reiniciados. ## O que aparece no seletor * **Empresa**: a conta consolidada, com o favicon configurado em Settings (ou o ícone padrão da Malga). * **Subcontas (N)**: até 6 subcontas, ordenadas por volume de transações. As demais ficam no grupo **Sem transações recentes**, em ordem alfabética, acessível pela rolagem. * O item ativo é indicado com um check. * **Gerenciar subcontas**: abre a [listagem de subcontas](/documentations/dashboard/merchants). ### Conta principal A conta principal é marcada com uma estrela preenchida e define o contexto padrão. Para alterar, passe o mouse sobre outra conta e clique na estrela vazia (**Definir como conta principal**). ## Menus disponíveis em cada visão | Menu | Visão Empresa | Visão Subconta | | - | :-: | :-: | | Painel de dados | ✓ | ✓ | | Cobranças | ✓ | ✓ | | Financeiro | ✓ | — | | Clientes | ✓ | ✓ | | Assinaturas | ✓ | ✓ | | Cartões | ✓ | ✓ | | Relatórios | ✓ | ✓ | | Recebedores | ✓ | ✓ | | Links de pagamento | — | ✓ | | Fluxos inteligentes | — | ✓ | | Equipe e permissões | ✓ | — | ## Filtros e formulários * Em **Painel de dados**, **Cobranças**, **Relatórios** e **Assinaturas**, o filtro de **subconta** aparece apenas na visão Empresa. * O filtro de **recebedor** está disponível nas duas visões. * Os formulários de **criar link de pagamento** e **criar fluxo inteligente** usam a subconta ativa no seletor, sem campo de seleção de subconta. # Exportando dados através do Dashboard Source: https://docs.malga.io/documentations/dashboard/export-data Pela área de **Relatórios** do [Dashboard Malga](https://dashboard.malga.io/), você solicita arquivos em formato .csv com os detalhes das cobranças, parcelas, extrato e repasses da sua conta. Também é possível exportar cobranças diretamente pela listagem de **Cobranças**. Depois da solicitação, a Malga processa o pedido e envia o arquivo para o e-mail cadastrado no Dashboard, garantindo a segurança das informações. ## Relatórios disponíveis O menu **Relatórios** reúne um card para cada tipo de relatório. Cada card abre um formulário com o período e os filtros opcionais do relatório. | Relatório | Recomendado para | Disponibilidade | | - | - | - | | **Relatório de cobranças** | Analisar cobranças e pagamentos realizados | Usuários com permissão para exportar cobranças | | **Relatório de parcelas** | Acompanhar a data prevista de recebimento de cada parcela | Subadquirentes com permissão para exportar repasses | | **Relatório de extrato** | Analisar todos os lançamentos e a posição de saldo | Subadquirentes com permissão para exportar repasses | | **Relatório de repasses** | Analisar todos os repasses pagos referentes às transações | Subadquirentes com permissão para exportar repasses | > [!NOTE] > > O menu **Relatórios** não aparece no ambiente de testes (sandbox). Nele, exporte as cobranças pelo menu **Cobranças**. ## Exportando cobranças Você exporta o relatório de cobranças de duas formas: * **Menu Relatórios:** abra o card **Relatório de cobranças** e configure o período, o tipo de relatório e os filtros opcionais. * **Listagem de Cobranças:** clique em **Exportar**, na barra de ferramentas da listagem, e configure o período e o tipo de relatório. A exportação já parte dos filtros aplicados na listagem (subconta, método de pagamento, status e período), e o Dashboard avisa com o alerta **Contém filtros aplicados.** Em ambos os casos, você configura: * **Período de criação da cobrança**, equivalente à venda na loja, com a data inicial e final (obrigatório); * **Tipo de relatório**, entre o relatório [**simples**](/documentations/dashboard/simple-report) e o [**completo**](/documentations/dashboard/full-report) (obrigatório); * **Filtros opcionais** de subconta, métodos de pagamento e status da cobrança, disponíveis no formulário do menu **Relatórios**. ![Export Charge Light](https://mintcdn.com/malga/xoT4Fujx0AuASD-g/assets/images/dashboard/charge-details/export-charge--light.gif?s=e1efdf8ebe3820ec7951592aa1c13fe5) > [!NOTE] > > **Período da exportação** > > O período é contado pela data de criação das cobranças, em **UTC**, com o **máximo de 31 dias** por relatório. Cada arquivo .csv gerado tem até 40 mil linhas, e os links para download chegam no e-mail. > [!WARNING] > > O filtro de **Recebedor** está indisponível na versão beta do relatório de cobranças. Se a listagem de Cobranças tiver um filtro de recebedor aplicado, o botão **Solicitar exportação** fica desabilitado. Remova o filtro para continuar. ### Tipos de relatório | Relatório | Dados principais | API Reports | Característica | | - | - | - | - | | Simples | Cobrança, pagamento, recusa, cliente | report type `transactions` | Contempla dados para análise do último status da cobrança. Consulte os campos [aqui](/documentations/dashboard/simple-report) | | Completo | Cobrança, pagamento, recusa, cliente e histórico completo das transações | report type `transactionsHistory` | Contempla todos os dados para análise do histórico de operações. Consulte os campos [aqui](/documentations/dashboard/full-report) | > [!NOTE] > > **Exemplos de relatório** > > Pelos links abaixo, você baixa exemplos dos relatórios e confere o formato e os dados disponíveis em cada tipo: > > **Relatório simples** - [link para download](https://drive.google.com/file/d/1czu4KxR39EXlon2WCd4oRXQWg_m3I5T_/view?usp=drive_link) > > **Relatório completo** - [link para download](https://drive.google.com/file/d/1iwImKmM3cUmnc_DvaawUOdtDJT9domMo/view?usp=drive_link) ## Exportando parcelas, extrato e repasses Os relatórios de parcelas, extrato e repasses aparecem no menu **Relatórios** para subadquirentes com permissão de repasses. Todos pedem o **período** (obrigatório) e aceitam **filtros opcionais**: | Relatório | Filtros opcionais | | - | - | | **Relatório de parcelas** | Subconta, recebedor e métodos de pagamento | | **Relatório de extrato** | Subconta e recebedor | | **Relatório de repasses** | Subconta e recebedor | O período também tem o **máximo de 31 dias**, em **UTC**. Nos relatórios de cobranças e de parcelas, você informa data e hora. Por padrão, os relatórios de parcelas, extrato e repasses vêm preenchidos com os últimos 7 dias, até o dia anterior. ## Passo a passo para exportar dados pelo Dashboard **Step 1** Faça login no [Dashboard Malga](https://dashboard.malga.io) e acesse o menu **Relatórios**. Para exportar pela listagem, acesse a área de [Cobranças](https://dashboard.malga.io/app/charges). **Step 2** No menu **Relatórios**, clique em **Exportar** no card do relatório desejado. Na listagem de Cobranças, clique em **Exportar** na barra de ferramentas. **Step 3** **Selecione o período pela data de criação da cobrança.** No relatório de cobranças, selecione também o **tipo de relatório**, entre o [simples](/documentations/dashboard/simple-report) e o [completo](/documentations/dashboard/full-report). **Step 4** Se necessário, abra **Filtros opcionais** e escolha subconta, métodos de pagamento e status da cobrança, conforme o relatório. **Step 5** Clique em **Solicitar exportação** para confirmar o seu pedido. O Dashboard exibe a mensagem **Solicitação recebida**. **Step 6** Após o processamento, a Malga **envia os arquivos para o e-mail** cadastrado no Dashboard. **Step 7** Acesse sua caixa de e-mail e faça o **download dos arquivos .csv pelos links do e-mail da Malga, com o título** \[Cobranças - período das cobranças exportadas | Malga]. **Step 8** Abra os arquivos na ferramenta que você usa para analisar e editar planilhas .csv. **Step 9** Se os filtros da exportação não retornarem cobranças no período indicado (arquivo vazio), a Malga envia um e-mail com a orientação para fazer uma nova exportação. ![Email com o link para download do relatório](https://mintcdn.com/malga/bFW0-6WF_tj4QsJS/assets/images/dashboard/export-data/email-export.png?fit=max\&auto=format\&n=bFW0-6WF_tj4QsJS\&q=85\&s=f08c35af0261320a45a1558b7d149287) > [!NOTE] > > **Envio dos arquivos por e-mail** > > O **tempo de espera para receber os arquivos no seu e-mail** varia conforme o período e o tipo de relatório. A Malga informa por e-mail sobre o processamento da sua solicitação. > > O arquivo exportado fica disponível por 30 dias em nosso servidor, e o acesso expira depois desse período. > > Se você ainda não tem **acesso ao Dashboard**, faça o [cadastro pelo link](https://dashboard.malga.io/sign-up). Para ajuda na configuração da conta, acione o nosso time pelo [suporte@malga.io](mailto:suporte@malga.io). **Ciclo de vida de uma exportação da API Reports:** ![](https://mintcdn.com/malga/CNIt8g3uASeU-e_S/assets/images/dashboard/export-data/state-machine.png?fit=max\&auto=format\&n=CNIt8g3uASeU-e_S\&q=85\&s=b3c3be9435d41c567b933189af846fe1) # Financeiro Source: https://docs.malga.io/documentations/dashboard/financeiro/intro Entenda o menu Financeiro do Dashboard Malga: o que cada página mostra e os conceitos que aparecem em todas elas. No menu **Financeiro** do [Dashboard Malga](https://dashboard.malga.io/), você acompanha o seu saldo, os repasses para a sua conta bancária e a previsão dos valores que ainda vão liquidar. Tudo isso conectado às cobranças que deram origem a cada valor. > [!WARNING] > > A área **Financeiro** está disponível para clientes do Provedor Malga (subadquirência) e aparece para usuários com perfil **Proprietário** e **Admin**. Todas as telas são de consulta. No menu **Financeiro** você encontra: | Página | Responde | | - | - | | [**Repasses**](/documentations/dashboard/financeiro/payouts) | Quanto tenho de saldo, quanto já caiu na minha conta e quanto sai no próximo repasse | | [**Extrato**](/documentations/dashboard/financeiro/statement) | O que entrou e saiu do meu saldo, lançamento a lançamento | ## Conceitos importantes Antes de navegar pelas telas, vale entender algumas ideias que aparecem em todo o menu Financeiro. ### Recebível e repasse são coisas diferentes Um **recebível** é cada parcela de uma cobrança que a Malga vai liquidar para você. Uma venda à vista gera um recebível; uma venda em 3x gera três. Um **repasse** é a transferência do seu saldo para a sua conta bancária. Um repasse agrupa vários recebíveis, e pode descontar outros valores, como tarifas e estornos. **Status do repasse** | Status | Significado | | - | - | | **Em andamento** | O repasse foi criado e a transferência está em processamento | | **Pago** | O valor foi depositado na sua conta bancária | | **Falha** | A transferência não foi concluída. O valor volta para o seu saldo | ### Empresa e recebedores O escopo de cada tela depende de onde você está: * Em **Financeiro**, você vê o saldo, os repasses e o extrato **da sua empresa**. * Em **Recebedores**, no detalhe de um recebedor, as mesmas visões aparecem como abas, com os valores **daquele recebedor**. * No **detalhe da cobrança**, você vê os recebíveis daquela venda, de todos os recebedores envolvidos. > [!WARNING] > > O saldo da empresa não é a soma dos saldos dos recebedores. Cada recebedor tem o próprio saldo, consultado no detalhe dele. ## Links e documentações úteis * [Repasses](/documentations/dashboard/financeiro/payouts) * [Extrato](/documentations/dashboard/financeiro/statement) * [Gestão de cobranças](/documentations/dashboard/charge-details) > [!NOTE] > > **Suporte Malga** > > Acione o nosso time pelo e-mail [suporte@malga.io](mailto:suporte@malga.io) para dúvidas sobre o seu saldo, recebíveis e repasses. # Repasses Source: https://docs.malga.io/documentations/dashboard/financeiro/payouts O que a página Repasses do Dashboard mostra, quando e onde o repasse cai na conta e como acompanhar cada repasse pela API. O **repasse** é a transferência do seu saldo para a sua conta bancária, e é sempre automático. A página **Repasses**, no menu **Financeiro** do [Dashboard Malga](https://dashboard.malga.io/), mostra a posição do seu saldo e todos os repasses já criados. Para entender a diferença entre recebível e repasse, veja a [introdução ao Financeiro](/documentations/dashboard/financeiro/intro). ## Listagem de repasses ![Listagem de repasses](https://mintcdn.com/malga/m4Lp6Ez2CCzbt0OA/assets/images/dashboard/financeiro/payouts/payouts-list-light.png?fit=max\&auto=format\&n=m4Lp6Ez2CCzbt0OA\&q=85\&s=befbd49c32ecf8b7d4b2290a726abdfc) Por padrão, a listagem mostra os últimos 7 dias. Use o **filtro de período** para consultar outras datas. Clique em uma linha para abrir o detalhe do repasse. ## Saldos | Card | O que mostra | | - | - | | **Saldo a receber** | Tudo o que você ainda vai receber na conta bancária de vendas aprovadas: o que já liquidou e não foi repassado, mais o que ainda vai liquidar | | **Saldo reserva** | Valor retido como garantia. Não entra nos repasses nem nos outros saldos | | **Próximo repasse** | Previsão do valor e da data do próximo repasse, conforme a sua política de repasse | O saldo da sua empresa não é a soma dos saldos dos recebedores, nem no Dashboard nem na API. Para ver o saldo de um recebedor, abra o detalhe dele em **Recebedores** ou consulte a API com `sellerId`. ## Status | No Dashboard | Status na API | O que significa | | - | - | - | | Em andamento | `pending` | Lote criado, aguardando a data de pagamento | | Pago | `paid` | Valor transferido para a conta de recebimento | | Falha | `failed` | A transferência foi tentada e não se concluiu. O motivo vem em `error.reason` | | Não aparece | `offset` | O lote fechou com saldo zero ou negativo e foi usado para abater saldo devedor | O status `offset` vale para a API e para os relatórios. No Dashboard, ele não é uma linha da listagem de repasses: o valor entra como **Saldo negativo anterior** na composição do repasse que quitou a dívida. ## Detalhe do repasse O detalhe do repasse explica como o valor depositado foi formado. **Composição do repasse:** cada linha é um valor que somou ou descontou do repasse, até chegar ao que foi depositado. | Linha | O que é | | - | - | | **Valor bruto** | Soma do valor bruto dos recebíveis que liquidaram neste repasse | | **Taxas** | MDR e, quando houver, taxa de antecipação desses recebíveis | | **Tarifas** | Serviços cobrados por uso, como antifraude e autenticação 3DS | | **Estornos e chargebacks** | Valores de vendas desfeitas depois de liquidadas, já com a taxa devolvida | | **Ajustes** | Correções lançadas pela Malga. É a única linha que pode ser positiva | | **Saldo negativo anterior** | Desconto de um ciclo anterior que fechou com saldo negativo | | **Taxa de saque** | Valor fixo cobrado por transferência, um por repasse | | **Depositado na conta** | O valor que chegou à sua conta bancária | Linhas sem valor não aparecem. Um repasse sem tarifas, por exemplo, não mostra a linha **Tarifas**. **Recebíveis do repasse:** lista cada parcela que liquidou neste repasse. Clique na linha para abrir o detalhe da cobrança. * Um recebível com **cancelamento parcial** aparece pelo valor que de fato liquidou. * Recebíveis **totalmente cancelados** não aparecem e não entram no valor bruto. * **Estornos e chargebacks** não aparecem na lista, porque o recebível deles liquidou em um repasse anterior. Eles estão na linha correspondente da composição. **Pela cobrança:** o caminho inverso também funciona. No detalhe de uma cobrança, a aba **Recebíveis** mostra os recebíveis que aquela venda gerou, com a data prevista, o status de cada um e se o repasse já foi pago. Quando o repasse já existe, clique na linha para abrir o detalhe dele. > [!NOTE] > > O detalhe do repasse é um retrato do dia em que ele foi feito. Se a cobrança sofrer um estorno depois, o repasse já pago não muda: o estorno entra como desconto em um repasse futuro. Para ver o estado atual da venda, abra o detalhe da cobrança. ## Quando e onde o repasse cai ### Horários Os repasses são feitos apenas em dias úteis bancários. O horário depende do método de pagamento: | Método | Horário do repasse | | - | - | | Pix | 18h | | Cartão de crédito | A partir das 7h50 | ### Conta de recebimento | De quem | Onde está a conta | Como trocar | | - | - | - | | **Sua empresa** | Cadastrada na contratação do Provedor Malga | Pelo suporte da Malga | | **Recebedor** | Campo `bankAccount` do recebedor | [PATCH /v1/sellers/\{id}](/api-reference/sellers/atualizacao-de-recebedor-pelo-id) | O titular da conta precisa ser o mesmo documento do recebedor. Veja [Recebedores](/documentations/split/seller). No Dashboard, a conta de destino aparece completa na listagem de repasses. ## Pela API Não há webhook de repasse, de ordem nem de antecipação. Acompanhe pela API de payouts, pelo lote. **1. Liste os lotes do dia.** Para um recebedor específico, envie também `sellerId`. ```bash theme={null} curl --location 'https://api.malga.io/v1/payouts/payment-batches?paymentDate=2026-10-14&status=pending,paid,failed' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` **2. Veja as ordens de cada lote.** ```bash theme={null} curl --location 'https://api.malga.io/v1/payouts/payment-batches/BATCH_ID/orders?limit=100' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` **3. Repita até o status final.** Consulte de novo os lotes `pending` mais tarde no dia. > [!TIP] > > Não use o `updatedAt` da ordem para saber se ela entrou num lote: o vínculo ao lote não altera esse campo. Acompanhe pelo lote, como acima. ### Endpoints | Ação | Endpoint | | - | - | | Saldo disponível e a receber | [GET /v1/payouts/balance](/api-reference/payouts/consultar-saldo-de-payouts) | | Listar repasses (lotes) | [GET /v1/payouts/payment-batches](/api-reference/payouts/listar-payment-batches) | | Consultar um repasse | [GET /v1/payouts/payment-batches/\{id}](/api-reference/payouts/consultar-payment-batch-pelo-id) | | Ordens de um repasse | [GET /v1/payouts/payment-batches/\{id}/orders](/api-reference/payouts/listar-ordens-de-um-payment-batch) | | Listar ordens | [GET /v1/payouts/orders](/api-reference/payouts/listar-ordens) | | Consultar uma ordem | [GET /v1/payouts/orders/\{id}](/api-reference/payouts/consultar-ordem-pelo-id) | Todas as rotas são de leitura e aceitam `sellerId` para filtrar por recebedor. Sem `sellerId`, `orders` traz só as ordens da sua conta. ## Links e documentações úteis * [Introdução ao Financeiro](/documentations/dashboard/financeiro/intro) * [Extrato](/documentations/dashboard/financeiro/statement) * [Relatório de repasses](/relatorio-de-repasses-detalhe-por-transacao-do-lote) * [API de Payouts](/api-reference/payouts/listar-payment-batches) > [!NOTE] > > **Suporte Malga** > > Acione o nosso time pelo e-mail [suporte@malga.io](mailto:suporte@malga.io) para dúvidas sobre repasses, saldo e recebíveis. # Extrato Source: https://docs.malga.io/documentations/dashboard/financeiro/statement Consulte tudo o que entrou e saiu do seu saldo, por movimentação ou por recebível, e concilie cada lançamento com as suas vendas e repasses. O **Extrato**, no menu **Financeiro** do [Dashboard Malga](https://dashboard.malga.io/), mostra tudo o que movimentou o seu saldo: liquidações de vendas, repasses para a sua conta bancária, estornos, chargebacks, tarifas e ajustes. > [!WARNING] > > O Extrato está disponível para clientes do Provedor Malga (subadquirência) e aparece para usuários com perfil **Proprietário** e **Admin**. As telas são de consulta. Use o Extrato para conferir o que já aconteceu com o seu saldo. > [!NOTE] > > Em **Financeiro**, o Extrato mostra os lançamentos **da sua empresa**. Para ver o extrato de um recebedor, acesse **Recebedores**, abra o detalhe do recebedor e use a aba **Extrato**. ## Visualizações do Extrato No topo da página, três cards resumem o período selecionado. Abaixo deles, você escolhe entre duas visualizações: | Visualização | Cada linha é | Use para | | - | - | - | | **Por movimentação** | Um lançamento no saldo | Entender o que entrou e saiu, e em que data | | **Por recebível** | Uma parcela de uma cobrança | Acompanhar o status de cada parcela até virar saldo | Por padrão, o Extrato mostra os últimos 7 dias. ### Por movimentação ![Extrato por movimentação](https://mintcdn.com/malga/m4Lp6Ez2CCzbt0OA/assets/images/dashboard/financeiro/statement/statement-by-movement-light.png?fit=max\&auto=format\&n=m4Lp6Ez2CCzbt0OA\&q=85\&s=f69ac208072320c495e2bfa88756ae68) Colunas: **Data**, **Movimentação**, **Descrição**, **Valor bruto**, **Taxa** e **Valor líquido**. Filtro disponível: **período**. ### Por recebível ![Extrato por recebível](https://mintcdn.com/malga/m4Lp6Ez2CCzbt0OA/assets/images/dashboard/financeiro/statement/statement-by-receivable-light.png?fit=max\&auto=format\&n=m4Lp6Ez2CCzbt0OA\&q=85\&s=259729380ff1009a76822165c0b88604) Colunas: **Previsão**, **Método**, **Bandeira**, **Parcela**, **Valor bruto**, **Taxa**, **Valor líquido** e **Status**. Filtros disponíveis: **período** e **status** do recebível. | Status | Significado | | - | - | | **Agendado** | A liquidação está prevista para a data indicada | | **Liquidado** | O valor virou saldo na Malga | | **Estornado** | O valor já tinha liquidado e será debitado do saldo | | **Cancelado** | O valor não vai liquidar. Não afeta o seu saldo | > [!TIP] > > Um recebível **Liquidado** já virou saldo, mas pode ainda não ter chegado à sua conta bancária. Para saber se o dinheiro já caiu, consulte o status do repasse em [Repasses](/documentations/dashboard/financeiro/payouts). ## Tipos de movimentação | Movimentação | Efeito no saldo | O que é | | - | - | - | | **Liquidação** | Crédito | Um recebível de venda que virou saldo | | **Repasse** | Débito | Transferência do saldo para a sua conta bancária | | **Devolução de repasse** | Crédito | Retorno ao saldo do valor de um repasse que falhou, incluindo a taxa de saque | | **Estorno** | Débito | Valor de uma venda desfeita depois de liquidada | | **Chargeback** | Débito | Valor de uma venda contestada pelo portador do cartão e perdida pela loja | | **Tarifa** | Débito | Cobrança por um serviço usado, como autenticação 3DS ou análise antifraude | | **Ajuste** | Crédito ou débito | Correção lançada pela Malga | > [!WARNING] > > **Devolução de repasse** e **Estorno** são diferentes. A devolução de repasse traz de volta ao seu saldo um repasse que não chegou ao banco. O estorno desfaz uma venda e devolve o valor ao comprador. ### Como ler os valores * **Valor bruto** é o valor da movimentação antes das taxas. * **Taxa** mostra o efeito da taxa no seu saldo: negativa quando é cobrada, positiva quando é devolvida. * **Valor líquido** é sempre o efeito final no seu saldo. | Movimentação | Valor bruto | Taxa | Valor líquido | Por quê | | - | - | - | - | - | | Liquidação | 434,90 | − 10,52 | + 424,38 | A taxa da venda reduz o crédito | | Repasse | 4.402,10 | − 3,50 | − 4.405,60 | A taxa de saque aumenta o débito. O banco recebe 4.402,10 | | Estorno | 250,00 | + 6,05 | − 243,95 | A taxa da venda é devolvida e reduz o débito | | Chargeback | 869,80 | | − 869,80 | A taxa não é devolvida. O débito é o valor bruto | | Devolução de repasse | 4.402,10 | + 3,50 | + 4.405,60 | A taxa de saque é devolvida. O crédito desfaz o repasse por inteiro | > [!NOTE] > > **Taxas em estornos e cancelamentos** > > A taxa é cobrada na venda e devolvida proporcionalmente ao valor estornado ou cancelado. No fim, você paga taxa só sobre o valor que de fato ficou com você. ## Links e documentações úteis * [Repasses](/documentations/dashboard/financeiro/payouts) * [Gestão de cobranças](/documentations/dashboard/charge-details) * [API de Payouts](/api-reference/payouts/listar-ordens) > [!NOTE] > > **Suporte Malga** > > Acione o nosso time pelo e-mail [suporte@malga.io](mailto:suporte@malga.io) para dúvidas sobre o seu extrato e lançamentos. # Relatório completo com histórico de operações das cobranças Source: https://docs.malga.io/documentations/dashboard/full-report Exporte o relatório completo do Dashboard ou API reports com o histórico detalhado de cobranças, requisições, estornos e retornos dos provedores. O relatório do tipo "**Completo**", disponível na [**Exportação de Cobranças**](/documentations/dashboard/export-data) pelo Dashboard, contempla os dados para análises mais detalhadas dos pagamentos. Ele contém todo o histórico de operações e requisições da cobrança, além de retornos detalhados de provedores e outras informações. Na estrutura deste relatório, cada cobrança ocupa diferentes linhas. Cada linha corresponde a uma requisição (pré-autorização, autorização, estorno, abertura de disputa, entre outros) ou movimentação na cobrança. Com isso, você pode analisar: * Performance dos provedores no Fluxo Inteligente * Tentativas de autorização * Cobranças com falhas * Dados do cliente * Análise de risco * Operações de estorno * Acompanhamento de disputas Você também pode aplicar filtros adicionais antes de exportar o relatório, para facilitar a gestão das informações necessárias para análise. Os filtros suportados atualmente são os de período, método de pagamento, status e subconta. Caso precise apenas do último status da cobrança pelo provedor responsável, exporte o relatório do tipo "**Simples**". Você pode consultar os detalhes desse relatório na nossa documentação. > [!NOTE] > > O período de exportação é **pela data de criação das cobranças e o período máximo por relatório é de até 31 dias de transações**, a partir do dia anterior (d-1). > [!WARNING] > > O período de exportação é ordenado pela data de criação das cobranças e o período máximo é de até 1 mês anterior à data selecionada. **Confira abaixo os campos disponíveis no relatório do tipo "Completo":** | **Dados** | **Campo no relatório pt-br** | **Campo no relatório eng-us** | | - | - | - | | **Cobrança** | Data da criação | Created at | | | ID da cobrança | Charge ID | | | ID do pedido | Order ID | | | Chave de idempotência da cobrança | Idempotency key (charge) | | | ID da subconta | Merchant ID | | | Subconta | Merchant name | | | Recorrência | Recurrence | | | Captura (automática) | Capture (automatic) | | | Descrição | Description | | | ID do link de pagamento | Session ID | | | ID do fluxo de pagamento | Flow ID | | | Metadata enviada na cobrança | Metadata | | **Pagamento** | Método de pagamento | Payment method | | | Tipo do método (Nupay) | Payment type (Nupay) | | | ID do cartão | Card ID | | | Nome do cartão | Card holder name | | | Número do cartão | Card number | | | Bandeira do cartão | Card brand | | | Descrição no recibo | Statement descriptor | | | Transação utilizando token de bandeira | Transaction using network token | | | Cartão tokenizado na bandeira em | Tokenized card in network on | | | ID do provedor responsável pela cobrança | Responsible provider ID | | | Provedor | Responsible provider | | | Moeda | Currency | | | Valor atual | Amount | | | Valor original | Original amount | | | Parcelas | Installments | | | Status final da cobrança | Payment status | | | Em disputa | Dispute | | **Cliente** | ID do cliente | Customer ID | | | Nome do cliente | Customer name | | | Documento | Document | | | Email | Email | | | Telefone | Phone number | | | Endereço do cliente | Customer Address (Street, Number, Complement, Zip code, City, State, District, Country) | | | Endereço de cobrança | Billing Address (Street, Number, Complement, Zip code, City, State, District, Country) | | | Endereço de entrega | Delivery Address (Street, Number, Complement, Zip code, City, State, District, Country) | | **Retorno do provedor** | Data de criação da requisição | Request created at | | | Data de atualização da requisição | Request updated at | | | ID de requisição da transação | Transaction request ID | | | ID do provedor responsável pela requisição | Request responsible provider ID | | | NSU de autorização da requisição | Request NSU | | | ID da transação no provedor | Network transaction ID | | | Chave de idempotência da requisição | Request Idempotency key | | | Provedor responsável pela requisição | Request responsible provider | | | Código de autorização no provedor | Idempotency key (request) | | | Tipo de requisição no provedor | Request type | | | Tempo de processamento da requisição | Provider response time | | | Valor da requisição | Request amount | | | Status da requisição | Request status | | | Mensagem de recusa do provedor | Network denied message | | | Mensagem do provedor associada ao erro | Detailed error message | | | Código de resposta do provedor | Provider response code | | | Código de resposta da requisição | Request response code | | | Código de recusa | Declined code | | | Motivo de recusa | Network denied reason | | | Retentável | Retriable | | | Score de análise antifraude | Score | | | Status de análise antifraude | Antifraud analysis | | **Análise de risco** | Análise de risco | Risk analysis | | | Tipo de análise | Analysis type | | | Cobertura de risco 3DS2 | Liability shift | | | Autenticação 3DS2 | 3DS2 Authentication | | | Tipo de autenticação 3DS2 | 3DS2 Authentication type | | | Resultado de autenticação 3DS2 | 3DS2 Authentication result | | | 3DS2 DataOnly | 3DS2 DataOnly | Confira um [exemplo do relatório completo](https://drive.google.com/file/d/1iwImKmM3cUmnc_DvaawUOdtDJT9domMo/view) com os campos disponíveis. > [!NOTE] > > Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)) # Começando em Painel de Dados Source: https://docs.malga.io/documentations/dashboard/insights/intro O **Painel de Dados** do **Dashboard Malga** apresenta as informações de vendas e performance dos pagamentos realizados na sua loja, simplificando a gestão e análise das operações. Para as informações de vendas, exibimos uma aba dedicada, a [Visão geral](https://dashboard.malga.io/app/insights), que sintetiza detalhes das cobranças realizadas. E para as informações de [Performance](https://dashboard.malga.io/app/performance), na aba de mesmo nome, apresentamos informações com foco no desempenho do seu **fluxo de crédito**. Os dados do painel seguem o [seletor de contexto](/documentations/dashboard/context-selector) do menu lateral: na **visão Empresa**, o painel consolida todas as subcontas e permite filtrar por subconta; na **visão de uma subconta**, exibe somente os dados dela. ![Overview Demo Light](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/insights/overview-demo-light.gif?s=6ae02613422a8d4cce4017a32550ab74) Através da **aba de Visão geral** do painel, é possível obter a **visão consolidada das cobranças autorizadas e recusadas** por período, com dados organizados por **status**, divisão por **provedores de pagamento e bandeira de cartão**, **taxa de aprovação** geral e diária, além da listagem dos principais motivos de recusa de transação. E na **aba de Performance**, com uma subconta selecionada (na visão Empresa, é necessário selecionar a subconta; na visão de uma subconta, os dados seguem a subconta ativa no seletor de contexto), é possível visualizar: **taxas de aprovação por tentativa**, **desempenho dos provedores em cada tentativa**, **cobranças recuperadas por tentativa** e **histórico de fluxos inteligentes.** Essa visão permite uma análise detalhada dos fatores que impactaram os resultados da subconta selecionada. Acesse o Painel de Dados: > [card] [Visão geral](/documentations/dashboard/insights/overview) > [card] [Performance](/documentations/dashboard/insights/performance) Confira as informações gerais do **Painel de dados Malga**, incluindo suas restrições de acesso: > [!NOTE] > > * **Acesso pelo Dashboard:** Ambas as abas estão disponíveis apenas em ambiente **online** (produção). > * **Painel exclusivo para usuários administradores:** O painel de dados, incluindo ambas as abas, possui acesso restrito aos administradores da conta da sua empresa, listados em **Equipe e permissões**, no menu lateral da visão Empresa. Para usuários comuns, você consegue personalizar as permissões de acesso. Caso queira realizar alteração em usuários **administradores**, entre em contato com nosso time! > * **Atualização do Painel:** Os dados são atualizados aproximadamente a cada 20 minutos. > * Através da [Analytics API](/analytics/intro), é possível realizar consultas na base de cobranças e obter as métricas do Painel e o retorno completo sobre o processamento dos provedores. Saiba mais sobre os cálculos disponíveis na API [neste release](/release-notes/2023-10-06-Release-Notes). # Visão geral Source: https://docs.malga.io/documentations/dashboard/insights/overview ![Visão geral do Painel de dados Malga](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/insights/overview-dashboard-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=0af8001e97d63661a1221827efe1e565) Na parte superior apresentamos a visão geral das cobranças no período selecionado, com base na data de atualização da cobrança (`updated_at`) e na moeda (`currency`). Essa seção apresenta as seguintes métricas: #### Total das cobranças Exibe o valor financeiro total e a quantidade de cobranças realizadas no período selecionado. Este número representa o total de vendas ou pedidos processados pela loja. #### Cobranças autorizadas Mostra o valor financeiro total e a quantidade de cobranças pré-autorizadas e autorizadas dentro do período selecionado. #### Cobranças recusadas Indica o valor financeiro total e a quantidade de cobranças que foram recusadas no período, considerando as transações com status de falha (`failed`). #### Taxa de aprovação Representa o percentual de **cobranças aprovadas**, em relação ao total de cobranças criadas no período selecionado. > [!NOTE] > > **Cobranças aprovadas** > > São consideradas aprovadas as cobranças que foram **autorizadas** ou **pré-autorizadas** pelo emissor, **mesmo que tenham mudado de status posteriormente**. Entre os status possíveis de uma cobrança aprovada estão: > > * Autorizada > * Pré-autorizada > * Cancelada > * Estornada > * Chargeback > > Esse conceito permite uma análise mais realista da performance de autorização, mesmo em cenários em que parte das cobranças autorizadas eventualmente não são concluídas com sucesso. > [!NOTE] > > **Fórmula de cálculo** > > **Taxa de aprovação** = (Cobranças aprovadas / Total de cobranças) × 100 #### Taxa de aprovação por dia Disponível no gráfico de linha do tempo, apresenta a taxa de aprovação diária no período selecionado. Em cada ponto do gráfico, é possível visualizar: * A taxa de aprovação do dia; * A quantidade de cobranças aprovadas, detalhadas por status: autorizada, pré-autorizada, cancelada, estornada e chargeback; * A quantidade de cobranças recusadas; * E o total de cobranças processadas naquele dia. A taxa de aprovação é calculada com base na **data da última atualização da cobrança**. Isso significa que, se uma cobrança aprovada for posteriormente cancelada, estornada ou sofrer chargeback, ela deixa de ser considerada no dia da autorização e passa a ser contabilizada no dia da atualização de status. #### Cobranças por status Distribuição percentual do volume de cobranças por status, dentro do período selecionado. Para cada status, é possível consultar a quantidade de cobranças e o valor financeiro correspondente. *** Na sequência, é possível conferir os principais métodos e provedores de pagamento responsáveis pelas cobranças da sua loja, conforme descrito abaixo: ![Visão métodos de pagamentos e provedores](https://mintcdn.com/malga/zw_w0ef1taXHyV2N/assets/images/dashboard/insights/performance/method-providers--light.png?fit=max\&auto=format\&n=zw_w0ef1taXHyV2N\&q=85\&s=170fa91078e1eb3f6de3cae0565321e0) #### Métodos de pagamento Exibe as cobranças autorizadas — incluindo os status de **pré-autorizada**, **autorizada**, **cancelada**, **estornada** e **chargeback** — agrupadas por método de pagamento. Os dados são apresentados em ordem decrescente de volume, considerando os 6 (seis) principais métodos de pagamento. Para cada um, são exibidas as seguintes métricas: * **Volume %** por método de pagamento sobre o total de cobranças autorizadas; * **Quantidade** de cobranças autorizadas no método; * **Valor** financeiro do valor monetário autorizado por método; #### Provedores de pagamento Apresenta as cobranças autorizadas (**pré-autorizada**, **autorizada**, **cancelada**, **estornada** e **chargeback**) por provedor de pagamento, ordenadas de forma decrescente conforme o volume dos 6 (seis) principais provedores da sua loja. Para cada provedor, são apresentadas: * **Volume %** por provedor de pagamento sobre o total de cobranças autorizadas; * **Aprovação** representa a taxa geral percentual de autorização de cobranças naquele provedor, correspondendo à soma das cobranças aprovadas — ou seja, todas as cobranças que, em algum momento, foram autorizadas ou pré-autorizadas — sobre o total de cobranças processadas pelo provedor no período selecionado. * **Quantidade** de cobranças aprovadas no provedor; * **Valor** financeiro correspondente ao valor monetário aprovado por provedor; > [!NOTE] > > **Provedores de pagamento** > > No Painel de Dados do **ambiente de produção** (ambiente online) do Dashboard, são exibidas as cobranças dos provedores de pagamento do fluxo, excluindo o provedor sandbox e antifraude. > > No **ambiente de testes** (sandbox), são exibidos os dados de cobranças de provedores e sandbox, excluindo o provedor antifraude. > > [Confira os métodos e provedores de pagamento suportados pela Malga.](/documentations/type-tables/payment-methods-by-providers) *** ![Visão geral das cobranças](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/insights/overview-brand-declined-light.gif?s=962903f3c12fe66b0e8c57aa36449e41) #### Bandeira de cartão Apresenta as cobranças autorizadas (com os status de **pré-autorizada**, **autorizada**, **cancelada**, **estornada** e **chargeback**) por bandeira de cartão, ordenadas de forma decrescente pelo volume de cobranças nas 6 (seis) principais bandeiras de cartão. As métricas representam: * **Volume %** por bandeira de cartão sobre o total de cobranças aprovadas; * **Aprovação** representa a taxa geral percentual de autorização de cobranças naquela bandeira, correspondendo à soma das cobranças aprovadas — ou seja, todas as cobranças que, em algum momento, foram autorizadas ou pré-autorizadas — sobre o total de cobranças processadas pelo provedor no período selecionado. * **Quantidade** de cobranças aprovadas na bandeira; * **Valor** financeiro, correspondente ao valor monetário aprovado por bandeira; #### Detalhes de cobranças recusadas Neste bloco, são apresentados os principais motivos de recusa das cobranças com status recusada (`failed`), correspondendo ao `declinedCode` retornado pelo provedor de pagamento e tratado pela Malga. A listagem dos motivos é exibida em ordem decrescente, começando por aquele com maior volume de recusas. Para cada motivo, são apresentados: * **Quantidade** de cobranças recusadas; * **Valor** financeiro total associado às recusas daquele motivo. #### Tratamento dos motivos de recusa Para facilitar a análise dos **motivos de recusa**, tratamos a listagem de `declinedCode` recebidos dos provedores para o Painel, correspondendo às mensagens da tabela abaixo. [Saiba mais](/documentations/type-tables/declined-code) sobre os **motivos de recusa** em nossa documentação. | **Motivo de recusa do Painel de Dados** | **Provider error (Declined code)** | | - | - | | Cartão bloqueado | blocked\_card | | Cartão cancelado | canceled\_card | | Cartão com a segurança comprometida | security\_violation | | Cartão com código de segurança inválido | invalid\_cvv / invalid\_security\_code | | Cartão com data inválida | invalid\_data | | Cartão com limite insuficiente | insufficient\_funds | | Número do cartão inválido | invalid\_card\_number / invalid\_number | | Cartão com restrição | restricted\_card | | Cartão com restrições identificadas | pick\_up\_card / pickup\_card / pin\_retry\_exceeded / pin\_try\_exceeded | | Cartão com PIN inválido | invalid\_pin | | Cartão expirado | expired\_card | | Cartão inválido para o tipo da cobrança realizada | transaction\_not\_allowed | | Cartão reportado como perdido | lost\_card / card\_reported\_lost | | Cartão reportado como roubado | stolen\_card / card\_reported\_stolen | | Cobrança com fraude confirmada | fraud\_confirmed | | Cobrança com suspeita de fraude | fraud\_suspect | | Cobrança não permitida pelo cartão | not\_permitted | | Cobrança recusada por merchant inválido no provedor | invalid\_merchant | | Cobrança recusada por quantidade de parcelas inválida | invalid\_installment | | Credencial inválida | invalid\_credential / invalid\_credentials | | Erro de processamento no provedor | not\_found / request\_not\_sent / timeout / generic / try\_again | | Erro de processamento no provedor por falha de contrato | api\_error / processing\_error / bad\_request | | Erro interno na Malga | internal\_error / requestStatus.internal\_error | | Falha de contato com o emissor do cartão | issuer\_not\_available | | Função do cartão incompatível com a cobrança realizada | card\_not\_supported / card\_cannot\_make\_this\_charge | | Motivo de recusa não transmitido pelo provedor | denied\_reason\_not\_available / service\_not\_allowed | | Recebedor de split inválido | invalid\_seller | | Valor da cobrança não permitido pelo provedor | invalid\_charge\_amount / invalid\_amount | | Falha na autenticação 3DS2 | failed\_authentication / authentication\_error | | Tentativas de autenticação 3DS2 indisponíveis pelo emissor | authentication\_attempts\_unavailable\_by\_issuer | | Erro de autenticação 3DS2 sem desafio | authentication\_error\_without\_challenge | | Autenticação 3DS2 indisponível | authentication\_unavailable | | Status (pares) da autenticação inválido | invalid\_pares | | Emissor não consegue realizar a autenticação | unable\_to\_perform\_authentication | | Titular do cartão não concluiu a autenticação 3DS2 | cardholder\_not\_complete\_authentication | ### Filtros ![Visão geral do Painel de dados Malga](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/insights/painel-filtros-light.gif?s=4c4d0ef05676443936b638b648f971d1) Através dos filtros de período, moeda, método de pagamento, recebedor e, na visão Empresa, subconta, é possível filtrar a visualização dos dados do painel, conforme descrito abaixo: * **Período** em que uma ou mais cobranças foram criadas * **Método de pagamento** das cobranças processadas * **Provedor de pagamento** responsável pelo processamento da cobrança * **Moeda** em casos de vendas em uma única moeda, ela será automaticamente aplicada no painel, e quando houver cobranças em diferentes moedas, é necessário selecionar a moeda desejada * **Subconta** (somente na visão Empresa): é possível selecionar uma subconta para visualizar somente as cobranças processadas por aquela conta na Malga, facilitando a visão de operações e filiais. Na visão de uma subconta, esse filtro não aparece, porque o contexto já está definido pelo seletor do menu lateral. * **Recebedor**: filtre as cobranças pelo recebedor do split. Disponível nas duas visões. > [!NOTE] > > **Filtro por período** > > O filtro por período corresponde à data de atualização da cobrança na loja (`updated_at`), estando disponíveis cobranças no ambiente online (produção) e no sandbox (ambiente de testes) do Dashboard; > > Estão disponíveis todos os dados desde a primeira cobrança processada pela loja com a Malga, atualizados aproximadamente a cada 30 minutos; > > Também é possível consultar e extrair os dados em arquivo .csv no menu de [Cobranças](https://dashboard.malga.io/app/charges) e da [Analytics API](/analytics/intro). # Performance Source: https://docs.malga.io/documentations/dashboard/insights/performance Ao realizar o login em nosso [Dashboard](https://dashboard.malga.io/app/i), a aba de performance será exibida no menu lateral esquerdo. Na visão de uma subconta, a aba mostra diretamente os dados da subconta ativa no seletor de contexto. Na visão Empresa, é necessário selecionar uma subconta para visualizar os dados da aba. > [!NOTE] > > Esta aba exibe informações de performance do fluxo de crédito, sendo necessário ter ao menos uma cobrança processada com método crédito para visualizá-la. ![Performance](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/insights/performance-demo-light.gif?s=d7411880f28dd7193871279d45fedfc7) ## Filtros disponíveis Na aba de performance, você confere as informações de cobranças processadas em cada subconta selecionada levando em conta os filtros de: * **Período** em que uma ou mais cobranças foram criadas * **Moeda**: em casos de vendas em uma única moeda, ela será automaticamente aplicada no painel, e quando houver cobranças em diferentes moedas, é necessário selecionar a moeda desejada * **Subconta**: na visão de uma subconta, os dados seguem o seletor de contexto. Na visão Empresa, é necessário selecionar uma subconta (Merchant) para visualizar as cobranças processadas por aquela conta na Malga. Somente subcontas com transações de **crédito** podem ser visualizadas nesta aba. ## Detalhes sobre a Taxa de Aprovação A taxa de aprovação representa o percentual de **cobranças aprovadas**, em relação ao total de cobranças criadas no período selecionado. > [!NOTE] > > **Cobranças aprovadas** > > São consideradas aprovadas as cobranças que foram **autorizadas** ou **pré-autorizadas** pelo emissor, **mesmo que tenham mudado de status posteriormente**. Entre os status possíveis de uma cobrança aprovada estão: > > * Autorizada > * Pré-autorizada > * Cancelada > * Estornada > * Chargeback > > Esse conceito permite uma análise mais realista da performance de autorização, mesmo em cenários em que parte das cobranças autorizadas eventualmente não são concluídas com sucesso. > [!NOTE] > > **Fórmula de cálculo** > > **Taxa de aprovação** = (Cobranças aprovadas / Total de cobranças) × 100 Exibimos uma visão detalhada da taxa de aprovação em diferentes cenários. Veja: #### Taxa de aprovação ![Taxa de aprovação por retentativa](https://mintcdn.com/malga/zw_w0ef1taXHyV2N/assets/images/dashboard/appr-rate-light.webp?fit=max\&auto=format\&n=zw_w0ef1taXHyV2N\&q=85\&s=839d21f548d9e5fae85cd97256fe7919) Nesse primeiro bloco, você consegue visualizar: * A taxa de aprovação geral da subconta atual * A taxa de aprovação na primeira tentativa de cobrança * A taxa de aprovação em relação ao somatório de todas as outras tentativas, excluindo a primeira. > [!TIP] > > Passando o mouse sobre os gráficos, uma tooltip é aberta, informando a quantidade de cobranças **autorizadas** e **recusadas**. #### Taxa de aprovação por provedor e por tentativa ![Taxa de aprovação por provedor e por tentativa](https://mintcdn.com/malga/b4xExEdGMbnwh0V0/assets/images/dashboard/insights/approval-rate-by-attempts-light.png?fit=max\&auto=format\&n=b4xExEdGMbnwh0V0\&q=85\&s=c1414107466a1972a7359194a9d8ebc6) Neste segundo bloco, apresentamos um gráfico de linha, que permite visualizar as cobranças por provedor (representadas pelas linhas) em cada tentativa, destacando a taxa de aprovação ao longo do tempo. No lado superior direito do gráfico também é possível filtrar para exibir a visão da tentativa desejada. > [!TIP] > > Passando o mouse sobre as linhas, uma tooltip é aberta, informando a **quantidade e valor total de cobranças autorizadas** em cada dia e provedor. ### Cobranças recuperadas ![Cobranças recuperadas](https://mintcdn.com/malga/zw_w0ef1taXHyV2N/assets/images/dashboard/insights/recovery-light.png?fit=max\&auto=format\&n=zw_w0ef1taXHyV2N\&q=85\&s=95b0e9bae800257830f3f28808f1bcae) Representa o valor das cobranças que foram recuperadas após uma primeira tentativa de pagamento não autorizada, seja na segunda, terceira ou quarta tentativa. #### Visão "Aprovado" x Visão "Recebido" Você pode alternar entre duas formas de visualizar os dados: * **Aprovado**: considera todas as cobranças que foram autorizadas ou pré-autorizadas, independentemente de terem sido estornadas, canceladas ou sofrido chargeback depois. É a visão ideal para acompanhar a conversão e a performance do seu fluxo de pagamento. * **Recebido**: considera apenas as cobranças que de fato resultaram em recebimento de valor (ou seja, que não foram estornadas, canceladas ou que sofreram chargeback). É útil para analisar a entrada real de receita no caixa. Essas visões fornecem perspectivas complementares: uma foca na conversão (**aprovado**), e a outra no impacto financeiro real (**recebido**). As seguintes informações podem ser visualizadas nesse bloco: * Volume financeiro recuperado * Total de cobranças recuperadas * Volume financeiro e quantidade de cobranças recuperadas em cada retentativa > [!TIP] > > Passando o mouse sobre as barras, uma tooltip é aberta, informando naquela tentativa: > > * Taxa de aprovação > * Total de cobranças aprovadas (na visão “Aprovado”) > * Total de cobranças autorizadas (na visão “Recebido”) > * Total das cobranças que foram retentadas ### Histórico de fluxos inteligentes ![Histórico de fluxos inteligentes](https://mintcdn.com/malga/zw_w0ef1taXHyV2N/assets/images/dashboard/insights/performance/flow-history-light.webp?fit=max\&auto=format\&n=zw_w0ef1taXHyV2N\&q=85\&s=d95efdf02f9cbc47478b6c5b281b8752) Na tabela de **fluxos inteligentes**, é possível identificar o histórico de todos os fluxos criados naquela subconta. Trazendo as seguintes informações de cada fluxo: * Data de criação * Nome do fluxo inteligente * Quantidade de cobranças processadas * Taxa de aprovação > [!NOTE] > > O fluxo ativo no momento é representado pela badge verde de **ativo** ao lado de seu nome na tabela. Se o merchant selecionado tiver autenticação **3DS2 Malga**, é possível que **mais de um fluxo esteja ativo**. # Gerenciar subcontas no Dashboard Malga Source: https://docs.malga.io/documentations/dashboard/merchants Gerencie as subcontas (merchants) no Dashboard Malga: veja a listagem, provedores ativos e métodos de pagamento, e edite nomes personalizados de cada uma. Através da página **Gerenciar subcontas** do Dashboard Malga, acessada pelo seletor de contexto no topo do menu lateral, é possível conferir informações básicas, visualizar os provedores ativos, além de editar e atribuir nomes personalizados para as subcontas (merchants) da sua empresa. Isso facilita a gestão dos provedores e métodos habilitados para o fluxo inteligente de pagamentos e a identificação de cada subconta no seletor e nos filtros. \[!NOTE] O antigo item **Subcontas** do menu lateral foi substituído pelo botão **Gerenciar subcontas**, no rodapé do [seletor de contexto](/documentations/dashboard/context-selector). O endereço da página continua o mesmo. ## Listagem de subcontas Em **Gerenciar subcontas**, exibimos a **listagem de subcontas** desta conta, ordenadas pela data de atualização mais recente. Na listagem, são apresentadas as seguintes informações: * Data de atualização; * Nome da subconta; * ID do merchant (subconta); * Provedores ativos; * Métodos de pagamento. No campo de busca, localizado no canto superior direito da página, é possível encontrar uma subconta específica pelo nome. ## Detalhes de uma subconta ![Detalhe da subconta](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/merchant/merchant-details-light.gif?s=6b905193ca61eb427d2310f81ba22daf) Ao clicar em uma subconta na listagem, você pode visualizar os detalhes da subconta. Na página de detalhes, são exibidos: * Nome da subconta; * Merchant ID (identificador da subconta); * MCC cadastrado; * Métodos de pagamento ativos; * Datas de criação e de última atualização da subconta; * Provedores ativos. ### Provedores ativos no detalhe da subconta ![Detalhe de provedor de um merchant](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/merchant/provider-details-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=ee80f2c29a7beefbfeee04112b5aeee8) Ao clicar na “setinha” no provedor, são exibidas as seguintes informações relacionadas ao provedor naquela subconta: * Nome do provedor; * ID do provedor; * Status; * Data de ativação; * Métodos de pagamento ativos. ## Status da subconta Toda subconta tem um campo `status` que indica se ela está ativa (`true`) ou inativa (`false`). Esse estado é gerenciado exclusivamente pela API — não há edição pelo Dashboard. > [!NOTE] > > O `status` é informativo. Uma subconta inativa **continua processando transações normalmente**: desativá-la não bloqueia cobranças, links de pagamento ou assinaturas. Não confunda o `status` da subconta com: * O **Status do provedor**, exibido no detalhe da subconta, que se refere à conexão com aquele provedor; * A **exclusão da subconta**, feita pelo endpoint de deleção, que remove a subconta da listagem. ### Como o status é definido e atualizado | Operação | Comportamento | | - | - | | Criação de subconta | O campo `status` é opcional. Quando omitido, a subconta é criada como ativa (`true`). | | Atualização de subconta | Envie apenas o campo `status` para ativar (`true`) ou desativar (`false`) a subconta. | | Listagem e detalhe | O campo `status` é retornado em todas as respostas de subconta. | ### Exemplos de requisição ```bash Criar subconta inativa theme={null} curl --request POST 'https://api.malga.io/v1/merchants' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Minha Loja", "mcc": "4789", "status": false, "providers": [ { "name": "SandboxProvider", "priority": 1, "credentials": { "type": "SANDBOX", "apiKey": "YOUR_PROVIDER_API_KEY" } } ] }' ``` ```bash Ativar subconta theme={null} curl --request PATCH 'https://api.malga.io/v1/merchants/MERCHANT_ID' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": true }' ``` ```bash Desativar subconta theme={null} curl --request PATCH 'https://api.malga.io/v1/merchants/MERCHANT_ID' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": false }' ``` > [card] [Criação de novo merchant](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) > > Contrato completo do endpoint de criação de subcontas. > [card] [Atualizar configurações de merchant](/api-reference/merchants/atualizar-configuracoes-de-merchant) > > Contrato completo do endpoint de atualização de subcontas. ## Renomear subcontas Confira o **passo a passo para nomear as Subcontas:** **1. Acesse Gerenciar subcontas** Clique no nome da empresa no topo do menu lateral, selecione **Gerenciar subcontas** no rodapé do seletor e clique na subconta que deseja nomear. **2. Clique em editar** Na tela de detalhes da subconta, através do botão Editar localizado no canto superior direito, será habilitada a edição do campo de nome **3. Escolha um novo nome** Digite o nome personalizado que deseja atribuir e clique em Salvar **4. Pronto!** Ao retornar para listagem de subcontas, ela estará ordenada pela atualização mais recente; A partir daí, o **nome da sua subconta** estará refletido no seletor de contexto do menu lateral, na área de Fluxos Inteligentes, através da qual é possível editar e publicar alterações no fluxo de pagamentos da sua loja, no filtro de subconta (visão Empresa), no detalhe e na exportação de cobranças e na área de Links de pagamento. ![Edição do nome da subconta](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/merchant/rename-merchant-light.gif?s=d5f08f2899b2fca0903240eaba88b11b) # Relatório simples (pelo último status da cobrança) Source: https://docs.malga.io/documentations/dashboard/simple-report O relatório do tipo "**Simples**", disponível na [**Exportação de Cobranças**](/documentations/dashboard/export-data) pelo Dashboard, contempla dados para análises rápidas dos pagamentos e das cobranças pelo último status. Ele também contém os dados do cliente final e a recusa no provedor, caso tenha ocorrido. Na estrutura deste relatório, cada linha representa uma cobrança. Com isso, você pode fazer a **consolidação das vendas** de um período a partir de informações como: * Provedor responsável * Último status da cobrança * Análise de risco * Motivos de recusa * Dados do cliente Você também pode aplicar filtros adicionais antes de exportar o relatório, para facilitar a gestão das informações necessárias para análise. Os filtros suportados atualmente são os de período, método de pagamento, status e subconta. Caso precise de todos os eventos da cobrança, representados pelas requisições (transaction requests), exporte o relatório do tipo "**Completo**". Ele traz detalhes de pré-autorização, estorno, captura, entre outras. Você pode consultar os detalhes desse relatório na nossa documentação. > [!NOTE] > > O período de exportação é **pela data de criação das cobranças e o período máximo por relatório é de até 31 dias de transações**, a partir do dia anterior (d-1). > [!WARNING] > > Se a exportação de cobranças não contiver informações para alguma coluna, a Malga suprime essa coluna do arquivo para facilitar o gerenciamento. **Confira abaixo os campos disponíveis no relatório do tipo "Simples":** | **Dados** | **Campo (pt-br)** | **Campo (eng-us)** | | - | - | - | | **Cobrança** | Data de criação | Created at | | | ID da cobrança | Charge ID | | | ID do pedido | Order ID | | | Chave de idempotência da cobrança | Idempotency key (charge) | | | ID da subconta | Merchant ID | | | Descrição | Description | | | ID do link de pagamento | Session ID | | **Pagamento** | Método de pagamento | Payment method | | | Tipo do método (Nupay) | Payment type (Nupay) | | | Nome do cartão | Card holder name | | | Número do cartão | Card number | | | Bandeira do cartão | Card brand | | | Descrição no recibo | Statement descriptor | | | Transação utilizando token de bandeira | Transaction using network token | | | Cartão tokenizado na bandeira em | Tokenized card in network on | | | Moeda | Currency | | | Valor atual | Amount | | | Valor original | Original amount | | | Parcelas | Installments | | | Status final da cobrança | Payment status | | **Cliente** | ID do cliente | Customer ID | | | Nome do cliente | Customer name | | | Documento | Document | | | Email | Email | | | Telefone | Phone number | | | Endereço do cliente | Customer address | | | Endereço de cobrança | Billing address | | | Endereço de entrega | Delivery address | | **Retorno do provedor** | NSU de autorização da requisição | Request NSU | | | ID da transação no provedor | Network transaction ID | | | Código de autorização no provedor | Idempotency key (request) | | | Código de recusa | Declined code | | | Motivo de recusa | Network denied reason | | | Retentável | Retriable | | **Análise de risco** | Análise de risco | Risk analysis | | | Tipo de análise | Analysis type | | | Cobertura de risco 3DS2 | Liability shift | | | Autenticação 3DS2 | 3DS2 Authentication | | | Tipo de autenticação 3DS2 | 3DS2 Authentication type | | | Resultado de autenticação 3DS2 | 3DS2 Authentication result | | | 3DS2 DataOnly | 3DS2 DataOnly | | | Score antifraude | Antifraud score | | | Status de análise antifraude | Antifraud analysis status | | **Disputa** | Disputa | Dispute | Confira um [exemplo do relatório completo](https://drive.google.com/file/d/1iwImKmM3cUmnc_DvaawUOdtDJT9domMo/view) com os campos disponíveis. > [!NOTE] > > Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)) # Usuários e perfis de permissão no Dashboard Malga Source: https://docs.malga.io/documentations/dashboard/users Conheça os perfis de acesso do Dashboard Malga, como Proprietário, Administrador, Operador e Analista, e configure as permissões dos usuários da empresa. O [**Dashboard Malga**](https://dashboard.malga.io/), conta com diferentes perfis de acesso, permitindo que o proprietário e os administradores configurem as permissões dos usuários da empresa — definindo o que cada pessoa pode visualizar e realizar na plataforma. No quadro abaixo, descrevemos os perfis disponíveis e respectivas características: | Perfil de acesso | Descrição | | - | - | | **Proprietário** | Acesso total à plataforma. Reúne todas as permissões do Administrador e pode editar ou excluir outros Administradores. | | **Administrador** | Acesso completo à operação, com todas as permissões da plataforma, exceto excluir o Proprietário e outros Administradores. | | **Operador** | Executa operações de vendas (cobranças, clientes, links de pagamento e assinaturas), gerencia recebedores e exporta relatórios de cobrança, sem acesso a dados estratégicos da conta. | | **Analista** | Visualiza operações de vendas (cobranças, clientes, links de pagamento e assinaturas) e exporta relatórios de cobrança, sem acesso a dados estratégicos da conta. | | **Analista de cobranças** | Visualiza apenas o menu de cobranças e os detalhes de transações, sem acesso aos demais menus e sem permissão para executar operações. | | **Analista de subconta** | Visualiza todos os dados da subconta vinculada ao produto white label, exporta relatórios de cobrança e pode convidar usuários com a mesma permissão, mas sem permissão para executar operações. | | **Desenvolvedor** | Executa operações apenas no ambiente sandbox, sem acesso ao ambiente produção. | > [!TIP] > > O Administrador pode gerenciar usuários e convidar novos usuários, exceto editar ou remover outros administradores. Essa ação é exclusiva do **Proprietário**, perfil único por empresa. > > Se sua empresa ainda não possui um perfil com o papel de **Proprietário**. Para configurar esse acesso, entre em contato com o nosso time de atendimento através do e-mail [suporte@malga.io](mailto:suporte@malga.io). Abaixo detalhamos as permissões de cada perfil de usuário nos menus do Dashboard: | Menu | Funcionalidade | Proprietário | Administrador | Operador | Analista | Analista de cobranças | Analista de subconta | | - | - | :-: | :-: | :-: | :-: | :-: | - | | **Fluxos inteligentes** | Visualizar o fluxo de pagamentos por método e subconta | | | | | | | | | Publicar alterações no fluxo de pagamentos | | | | | | | | | Acessar ao histórico de versões do fluxo de pagamentos | | | | | | | | | Restaurar uma versão anterior do fluxo de pagamentos | | | | | | | | **Painel de Dados** | Visualizar métricas de performance da loja | | | | | | | | **Cobranças** | Acessar histórico da transação | | | | | | | | | Filtrar e buscar cobranças | | | | | | | | | Copiar payload da cobrança | | | | | | | | | Exportar relatórios em .csv | | | | | | | | | Cancelar cobrança | | | | | | | | | Realizar estorno e captura total ou parcial da cobrança | | | | | | | | **Clientes** | Visualizar a listagem e detalhes de customers | | | | | | | | | Filtrar um cliente pelo ID (customer\_id) | | | | | | | | | Realizar a exclusão de um customer | | | | | | | | **Cartões** | Visualizar a listagem e detalhes de cartões cadastrados | | | | | | | | **Links de pagamento** | Visualizar listagem, URL e detalhes de um link de pagamento | | | | | | | | | Filtrar e buscar links de pagamento | | | | | | | | | Acessar detalhes da cobrança vinculada ao link | | | | | | | | | Criar link de pagamento | | | | | | | | | Alterar o status de um link para ativo ou inativo | | | | | | | | | Cancelar link de pagamento | | | | | | | | **Gerenciar subcontas** | Visualizar a listagem e detalhe das subcontas | | | | | | | | | Ver métodos e IDs de contas nos provedores | | | | | | | | | Renomear subconta | | | | | | | | **Recebedores** | Visualizar a listagem de recebedores cadastrados | | | | | | | | | Filtrar e buscar recebedores | | | | | | | | **Equipe e permissões** | Visualizar a listagem de usuários cadastrados na empresa | | | | | | | | | Editar o nome de um usuário | | | | | | | | | Editar o papel de um usuário | | | | | | | | | Excluir usuário da empresa | | | | | | | | | Editar ou excluir um usuário administrador | | | | | | | | **Assinaturas** | Visualizar listagem e detalhes de assinaturas | | | | | | | | | Pausar uma assinatura | | | | | | | | | Retomar uma assinatura | | | | | | | | | Cancelar uma assinatura | | | | | | | > [!NOTE] > > Além do perfil, a visibilidade de alguns menus depende do contexto escolhido no seletor do menu lateral: **Financeiro** e **Equipe e permissões** aparecem apenas na visão Empresa; **Links de pagamento** e **Fluxos inteligentes**, apenas na visão de uma subconta. **Gerenciar subcontas** fica no rodapé do seletor, e o antigo menu **Usuários** agora se chama **Equipe e permissões**. [Saiba mais](/documentations/dashboard/context-selector). ### Convidando um novo usuário Para convidar um usuário a fazer parte da sua organização, acesse **Equipe e permissões**, no menu lateral da visão Empresa, e clique no botão **"Convidar usuário"**. Após, inserir o e-mail do convidado, nome (opcional) e indicar qual será o seu papel de acesso. ![Convida usuário](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/dashboard/users/invite-light.gif?s=cf9970af63ec2ecb31b04f720f79d326) Administradores também conseguem apagar ou reenviar um convite. Na listagem de usuários, ao passar o mouse por cima de cada linha, você verá essas ações, mas também conseguirá realizá-las nos detalhes de um convite específico. ### Excluindo, reenviando ou editando um convite Para apagar, editar ou reenviar um convite, basta passar o mouse sobre a linha do usuário na listagem — as ações disponíveis aparecerão. Você também pode realizar essas ações acessando os detalhes do convite específico. ![Ações na listagem de usuários](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/dashboard/users/actions-menu-users-light.gif?s=11cbeb8fb8519bf63dc857c5ca5343bc) ### Reativar usuários Por segurança, usuários que ficarem mais de 90 dias sem acessar o Dashboard serão desativados automaticamente. Apenas o **Proprietário** da conta poderá reativá-los. > [!NOTE] > > Se precisar de ajuda na edição dos usuários da sua empresa, acione o nosso time de atendimento através do e-mail [suporte@malga.io](mailto:suporte@malga.io); # Utilizando condicionais Source: https://docs.malga.io/documentations/flow-guide/conditional Saiba como funcionam as regras condicionais do fluxo de pagamentos na Malga e aprenda a configurá-las para otimizar o processamento de suas transações. Através do fluxo inteligente, é possível adicionar regras condicionais para o processamento das cobranças. Os condicionais podem utilizar **dados das cobranças**, como o valor, parcelas, bandeira do cartão selecionado, ou **metadados** enviados no campo `metadata` das `charges`. Através do botão :heavy\_plus\_sign: nas ramificações do fluxo, é possível adicionar novos condicionais, utilizando do menu na lateral direita, conforme imagem: #### Menu para adição de condicionais ![Menu lateral para adição de condicionais](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/choosing-params-light.png?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=6f3ff20487d21fb9b3ed60d9ee0e8dfe) Confira os parâmetros de condicional disponíveis para inserir no fluxo de pagamentos: * **Balanceador de Distribuição de carga** * **Bandeira do cartão** * **Campo personalizado (parâmetro de metadata enviado na cobrança)** * **Moeda** * **Número do cartão** * **Parcelas** * **Valor** * **Combinações (diferentes condicionais no mesmo card)** > [!WARNING] > > Após cada condicional inserida no fluxo, serão exibidas as **saídas Sim/Não para configuração do que deve acontecer após a aplicação do condicional na cobrança**, podendo ser outra condicional ou provedor de antifraude e cobrança. ## Como configurar cada tipo de condicional ### 1. Balanceador de distribuição de carga **Conceito**: Divide o processamento das transações de forma randômica entre duas ramificações, considerando os valores % estabelecidos na configuração (exemplo 40% ramificação 1, 60% ramificação 2); **Como utilizar**: * A soma dos valores deve somar 100% da carga * Aceita até duas ramificações para divisão da carga * Devem ser adicionados provedores após o condicional para processar cada carga estabelecida * Podem ser adicionados condicionais após o balanceador * Não podem ser inseridos valores negativos na distribuição da carga (exemplo - 10%) #### Configuração do condicional de Balanceador, indicando a distribuição de carga ![Configuração do condicional de Balanceador, indicando a distribuição de carga](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-balancer-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=0f95bc84498d8bdb918cf2abf4204229) #### Card de distribuição de carga ![Card de distribuição de carga](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-balancer-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=b2ae37f405073e74720006cbeb897f71) ### 2. Bandeira do cartão **Conceito**: Utiliza a bandeira do cartão \[`brand`] como condicional para o processamento da transação. **Como utilizar**: * Operadores: Igual a / Diferente de * Selecionar o operador e a bandeira da condicional #### Configuração ![Menu lateral para adicionar condicional de Bandeira](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-brand-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=4130aa3819b703cde349f03d0594e0bc) #### Adição ![Visualização do condicional de bandeira no fluxo](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-brand-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=492e0291e3abe016375e907df2b0052d) > [!NOTE] > > Caso queira criar um condicional para um **conjunto de bandeiras**, realize a edição do card adicionando mais condicionais com cada bandeira e utilize o conector **OU** entre cada parâmetro. > > **Exemplo**: Para criar uma condicional para transações de VISA e MASTERCARD, utilize a configuração “Se bandeira = MASTERCARD **OU** Se bandeira = VISA”. ### 3. Campo personalizado \[metadata] **Conceito**: Utiliza a informação de metadata enviada na cobrança \[`paymentFlow.metadata.*`] para uso como condicional para o processamento da transação; **Como utilizar**: * Indicar o **nome do atributo** (exatamente igual a `paymentFlow.metadata.nome_do_atributo` enviada na cobrança); * Indicar o **operador** que quer utilizar na condicional, conforme o tipo de atributo: * **Número** \[number] - operadores: menor/maior que, menor ou igual/maior ou igual a, igual a/diferente de; * **Booleano** \[boolean] - operadores: true/false; * **Texto** \[string] - operadores: igual a/diferente de. * Indicar em **qual ramificação** o fluxo deve seguir **caso a informação de metadata não seja enviada na cobrança**, se o fluxo seguirá o caminho do condicional "Verdadeiro" ou "Falso" #### **Tipo número - Configuração** ![Condicionais Metadado (número) Drawer Light 3x](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-number-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=5429d1f790251e4f4760ead7e87126d4) #### **Tipo número - Adição** ![Condicionais Metadado (número) Canva Light 3x](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-number-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=9d042f691cf6566909108e51c9b9b467) #### **Tipo texto - Configuração** ![Condicionais Metadado (texto) Drawer Light 3x](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-text-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=9c3a55a05608ff2ff7c54ce945073c6a) #### **Tipo texto - Adição** ![Condicionais Metadado (texto) Canva Light 3x](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-text-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=d5ffc567ae8fda8f2678b3ae98657b18) #### **Tipo booleano - Configuração** ![Condicionais Metadado (booleano) Drawer Light 3x](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-boolean-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=0d30b4d828089942273ed4a6300f8946) \\ #### **Tipo booleano - Adição** ![Condicionais Metadado (booleano) Canva Light](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-metadata-boolean-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=4a0530b106c62393956297b5e3982f88) ### 4. Moeda **Conceito**: Utilizar a moeda da cobrança \[`currency`] como condicional para o processamento da transação. **Como utilizar**: * Operadores: Igual a / Diferente de * Selecionar moeda na listagem #### Configuração ![Configuração de condicional de Moeda](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-currency-drawer-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=c0577365a3b01cb8e4f331e079752b5a) #### Adição ![Card condicional de Moeda](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/conditional/cond-currency-canva-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=bda2db975d01b620dd1fa109100bf90c) ### 5. Número do cartão **Conceito**: Utilizar o número do cartão \[`cardBin`] como condicional para o processamento da transação; **Como utilizar**: * Operadores: Igual a / Diferente de * Preencher dado com os seis primeiros dígitos do cartão. #### Configuração ![Configuração de condicional de Número de cartão](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/bin-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=dedcfe9dd2430f3cbf499109bd8c035a) #### Adição ![Card condicional de Número de cartão](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/bin-card-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=d59ba6fe691e1af92b6880a6d1ce6ad1) ### 6. Parcelas **Conceito**: Utilizar o número de parcelas da cobrança \[`installments`] como condicional para o processamento da transação. **Como utilizar**: * Operadores: menor/maior que, menor ou igual/maior ou igual a, igual a/diferente de; * Selecionar quantidade de parcelas até 12 vezes #### Configuração ![Configuração de condicional de Parcelas](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/installments-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=562faba00084421fbf7fa6a20b77e6ee) #### Adição ![Card condicional de Parcelas](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/installments-card-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=4b1efdae8ba690d2d8db3d0221d474e6) ### 7. Valor **Conceito**: Utilizar o valor da cobrança \[`amount`] como condicional para o processamento da transação; **Como utilizar**: * Operadores: menor/maior que, menor ou igual/maior ou igual a, igual a/diferente de; * Preencher o valor estabelecido como condicional. #### Configuração ![Configuração de condicional de Valor](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/value-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=cf1f8bac5d91aa278f8d9e6f4f90db03) #### Adição ![Card condicional de Valor](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/amount-card-light.webp?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=5c88a2ac093f43c35ff5cd384346833d) ### 8. Combinações Através do condicional de Combinações, é possível adicionar mais de uma regra condicional em um card do fluxo inteligente, utilizando o conector E/OU para combinar condicionais. **Conceito**: Utilizar duas ou mais condicionais no mesmo card do fluxo, como regra para processamento da transação; **Exemplo de combinação de condicionais**: Se a Bandeira do Cartão é "Mastercard" E Parcelas "Maior que 7 vezes" > processar no provedor x; **Como utilizar**: Podem ser combinados condicionais de diferentes tipos, com limitação de dois condicionais por operação; **Não podem ser combinados:** * Balanceador de distribuição de carga não pode ser combinado com outro condicional no mesmo card; * Provedores de cobrança e antifraude não podem ser combinados, estando sempre em cards independentes; * Condicionais utilizando o operador = (igual a) e o conector E com a mesma propriedade; * **Exemplo**: bandeira do cartão é igual a (=) MASTERCARD E bandeira do cartão é igual a (=) VISA; * Condicionais numéricos com operador > (maior) e \< (menor) conflitantes; **Exemplo**: valor da cobrança é maior > que 500 E valor da cobrança é menor \< que 100; #### Operador lógico "OU" ![Configuração do condicional de Combinações - Operador lógico E](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/and-operator-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=3241c94c714794631dca52b183b39384) #### Operador lógico "E" ![Configuração do condicional de Combinações - Operador lógico OU](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/or-operator-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=bb29e759adaed2d1dcf9828b2b845aa6) #### Exibição do card combinações ![Exibição do card combinações no fluxo](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/or-operator-card-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=44b4f5ec4fa10c4772ec6833c60c156e) #### Feedback em caso de inserção inválida - Condicionais iguais ![Feedback em caso de inserção inválida - Condicionais iguais](https://mintcdn.com/malga/93O_RJ8mY0E9U0-f/assets/images/flow-guide/conditional/operator-error-light.png?fit=max\&auto=format\&n=93O_RJ8mY0E9U0-f\&q=85\&s=f1c7cd3e9f8340882537aabe0d3a93f0) #### Combinando condicionais de campo personalizado Você pode realizar a **combinação de mais de um campo personalizado** e nesse cenário, deve se atentar que, caso o metadata não seja enviado na transação, o caminho que o fluxo seguirá é o resultado dos valores default que foram combinados. **Utilizando o operador lógico** `OU`, o valor que será predominante é o **verdadeiro**. As combinações possíveis são: | Primeiro valor default | Segundo valor default | Resultado | | - | - | - | | falso | falso | falso | | falso | verdadeiro | verdadeiro | | verdadeiro | falso | verdadeiro | | verdadeiro | verdadeiro | verdadeiro | **Utilizando o operador lógico** `E`, o valor que será predominante é o falso. As combinações possíveis são: | Primeiro valor default | Segundo valor default | Resultado | | - | - | - | | falso | falso | falso | | falso | verdadeiro | falso | | verdadeiro | falso | falso | | verdadeiro | verdadeiro | verdadeiro | > [!NOTE] > > O **valor default** indica qual caminho o fluxo deve seguir caso o `metadata` (campo personalizado) não seja enviado na transação, podendo ser verdadeiro ou falso. # Editando Fluxo Source: https://docs.malga.io/documentations/flow-guide/editing Entenda como editar um Fluxo Inteligente de Pagamento na Malga, ajustando provedores e condicionais para otimizar suas transações financeiras. É possível editar os cards do fluxo, através do ícone de 3 pontos localizado no canto superior direito do card. **Ações disponíveis para cada tipo de card**: * **Editando um card do tipo provedor**: o card do tipo provedor sempre contém somente 1 provedor, sendo possível: * **Substituir** um provedor de cobrança ou antifraude; * **Excluir** um provedor de cobrança ou antifraude * **Editando um card do tipo condicional**: o card do tipo condicional pode conter 1 ou mais condicionais, sendo possível: * **Editar** o condicional configurado dentro do menu lateral de edição, removendo ou adicionando novos condicionais, tornando-o um condicional do tipo Combinações; * **Excluir** o condicional configurado #### Edição ![Opções de edição do card de provedor de cobrança ou antifraude](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/flow-guide/editing/edit-provider-light.gif?s=f42cc020c9bad8a1ffaa6fb44b342382) #### Exclusão ![Opções de remoção do card de provedor de cobrança ou antifraude](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/flow-guide/editing/remove-provider-light.gif?s=c1cde036debf1796a00b9dba8421093e) ## Adicionando novos parâmetros Através do botão :heavy\_plus\_sign: em cada ramificação, é aberto o menu lateral para inserir novos cards ao fluxo. A seguir, explicaremos as **regras de utilização de cada parâmetro**: **Adicionando provedores de cobrança** * No menu lateral, serão exibidos **somente os provedores configurados e ativos** da subconta ativa no seletor de contexto, correspondente ao fluxo que está sendo editado; * Só é possível adicionar **1 (um) provedor** em cada card no fluxo; * É recomendado inserir **até 3 (três) provedores na mesma ramificação** para retentativas; * Ao **adicionar um novo provedor no meio de uma ramificação**, os demais elementos são deslocados para a direita, dando prosseguimento ao fluxo conforme as regras configuradas; * Ao adicionar **dois provedores de cobrança em sequência**, o fluxo entenderá que o segundo provedor configurado na ramificação será responsável pela retentativa da cobrança, em caso de falha ou reprovação no primeiro provedor, conforme imagem abaixo: #### Provedores de cobrança em sequência Exemplo: PagSeguro > retentativa > Cielo, onde a cobrança sofrerá retentativa na Cielo caso haja falha na cobrança pela PagSeguro ![Provedores de cobrança em sequência. Exemplo: PagSeguro > retentativa > Cielo, onde a cobrança sofrerá retentativa na Cielo caso haja falha na cobrança pela PagSeguro](https://mintcdn.com/malga/yws4rxGEzT5wCNep/assets/images/flow-guide/editing/change-providers.webp?fit=max\&auto=format\&n=yws4rxGEzT5wCNep\&q=85\&s=a2ceeb2de8c66a0892eb43fcd4ee96e3) > [!WARNING] > > Ao configurar o fluxo com as regras de processamento nos provedores e retentativas, a prioridade até então contida no merchant, passa a considerar **somente** a prioridade do fluxo inteligente. * **Adicionando antifraude** * O provedor antifraude só pode ser adicionado ao fluxo no **método de pagamento de crédito**; * Sempre deve haver um **provedor de cobrança após o provedor antifraude** no fluxo, ou seja, o card de antifraude **não pode estar na última posição** de uma ramificação; * **Não podem existir dois cards de antifraude** na mesma ramificação; * Se a transação for reprovada pela análise de antifraude, o fluxo de cobrança é encerrado. * **Adicionando condicionais** * Podem ser adicionadas **regras condicionais a partir dos dados da cobrança ou de metadados** enviados na cobrança. Confira as regras de utilização de cada condicional no fluxo inteligente aqui \[[https://docs.malga.io/documentations/flow-guide/conditional](https://docs.malga.io/documentations/flow-guide/conditional)] ## Excluindo parâmetros Ao excluir um card do fluxo inteligente de pagamentos, temos os seguintes comportamentos: * Quando um **card do tipo condicional** é excluído, todos os cards de ramificações após o card excluído também serão removidos; * Quando um **card do tipo de provedor de cobrança ou antifraude** é excluído, somente o seu card é removido e o fluxo é movido para a esquerda, preservando os demais cards e a ordem da ramificação. #### Confirmando a exclusão de um card condicional no fluxo ![Confirmando a exclusão de um card condicional no fluxo](https://mintcdn.com/malga/yws4rxGEzT5wCNep/assets/images/flow-guide/editing/exclude-card-light.png?s=12c78bbe7764a3c3fe734323dce266a8) # Tratamento de erros nos Fluxos inteligentes Source: https://docs.malga.io/documentations/flow-guide/errors Entenda o tratamento de erros nos Fluxos Inteligentes de Pagamento da Malga e saiba como corrigir configurações para garantir transações bem-sucedidas. Durante o **processo de publicação do fluxo de pagamentos**, realizamos a validação das configurações de cada ramificação para garantir que as transações sejam processadas corretamente. Caso algum erro seja identificado, será retornada a mensagem com a orientação da respectiva alteração necessária no fluxo, conforme abaixo: | Erro identificado | Mensagem | O que fazer | | - | - | - | | **Ramificação NÃO possui provedor de cobrança** | *Cada caminho do seu fluxo deve ter pelo menos um provedor de cobrança.* | Adicione um provedor de cobrança na ramificação | | **Ramificação apenas com antifraude, SEM provedor de cobrança** | *Cada caminho do seu fluxo deve ter pelo menos um provedor de cobrança.* | Adicione um provedor de cobrança na ramificação | | **Ramificação com dois ou mais antifraudes ao mesmo tempo** | *Cada caminho do seu fluxo permite apenas um provedor antifraude atuando simultaneamente na transação.* | Remova um dos antifraudes inseridos na ramificação | | **Ramificação quando há um antifraude SEM provedor de cobrança depois do antifraude** | *Cada caminho do seu fluxo deve ter pelo menos um provedor de cobrança depois de um provedor antifraude.* | Adicione um provedor de cobrança após o antifraude na ramificação | | **Provider utilizado no fluxo NÃO pertence ao merchant sendo atualizado** | *O provedor \[nome do provedor] não pode ser usado por essa subconta. Por favor, contate nosso suporte para mais informações.* | Entre em contato com o nosso atendimento para realizar a correção no fluxo | | **Valor de metadata está sendo usado no flow sem um valor/caminho default** | *Cada metadado do seu fluxo deve ter um valor default. Por favor, contate nosso suporte para mais informações.* | Entre em contato com o nosso atendimento para realizar a correção no fluxo | | **Fluxo inválido** | *Houve um problema ao publicar o fluxo. Por favor, verifique e tente novamente.* | Entre em contato com o nosso atendimento para realizar a correção no fluxo | # Exemplos de uso Source: https://docs.malga.io/documentations/flow-guide/examples Exemplos práticos de orquestração de fluxos inteligentes na Malga: ajuste provedores, aplique condicionais e use metadados para otimizar pagamentos. Abaixo descrevemos **três operações através da orquestração do fluxo inteligente** para otimizar os resultados de pagamentos: ## 1. Modificando a ordem dos provedores Através do Dashboard, é muito simples ajustar a **ordem dos provedores no fluxo de pagamentos**, visando otimizar os custos de adquirência, cumprir acordos negociados e manter a taxa de aprovação. Por exemplo, caso haja um acordo de processamento de volume de vendas mínimo com um determinado provedor \[1] visando uma taxa negociada, e sendo necessária a realização de novas tentativas em outros provedores \[2 e 3, por exemplo] para garantir a aprovação das transações em caso de erro/recusa na 1a tentativa, é possível ordenar o fluxo com o provedor 1 como prioritário, seguido dos provedores 2 e 3 para novas tentativas. Veja o fluxo de exemplo abaixo: #### Modificando a ordem dos provedores ![Modificando a ordem dos provedores](https://mintcdn.com/malga/yws4rxGEzT5wCNep/assets/images/flow-guide/examples/examples-providers-light.png?fit=max\&auto=format\&n=yws4rxGEzT5wCNep\&q=85\&s=a4fbc9c1b921623a53fc10dad6391fcd) ## 2. Utilizando condicionais no fluxo de crédito Através da inserção de **condicionais no fluxo de crédito** (bandeira, valor e parcelas), é possível otimizar os custos de adquirência e aumentar a taxa de aprovação. Por exemplo, caso você possua uma taxa mais vantajosa para antecipar vendas parceladas em um determinado provedor, é possível utilizar o **condicional de parcelas** para indicar qual provedor deverá processar as transações de acordo com o número de parcelas. Também é possível combinar os **condicionais de parcela e bandeira**, indicando quais provedores devem processar quais transações, conforme abaixo: #### Utilizando condicionais no fluxo de crédito ![Utilizando condicionais no fluxo de crédito](https://mintcdn.com/malga/OhKJSIVNLKMf9rYz/assets/images/flow-guide/examples/examples-conditional-light.png?fit=max\&auto=format\&n=OhKJSIVNLKMf9rYz\&q=85\&s=387a2f887fc94536ef3788e2657efc30) ## 3. Uso da metadata como condicional para antifraude Outra forma de otimizar custos através do fluxo inteligente, é reduzindo o volume de transações analisadas pelo antifraude através do envio de campos personalizados (metadata) para serem utilizados como condicionais no processamento da transação. Por exemplo, se você possui um determinado produto ou evento que não deverá ser analisado pelo antifraude, você pode inserir a identificação correspondente e depois aplicá-la nas configurações. Também é possível indicar que essa transação corresponde a um cliente final que já realizou outras compras em sua loja e já teve seu perfil validado, não sendo necessária nova avaliação do antifraude. Neste cenário, você pode enviar o código identificador do cliente e indicar que a transação deve seguir pelo fluxo sem antifraude, conforme exemplo abaixo: #### Uso da metadata como condicional para antifraude ![Uso da metadata como condicional para antifraude](https://mintcdn.com/malga/OhKJSIVNLKMf9rYz/assets/images/flow-guide/examples/examples-antifraud-light.png?fit=max\&auto=format\&n=OhKJSIVNLKMf9rYz\&q=85\&s=5b4763eb241c9956ee4538a5dff6cabc) Confira mais informações sobre o [uso da metadata em nossa documentação](/documentations/flow-guide/introduction#exemplo-de-uso-de-metadata). # Fluxos Inteligentes no Dashboard Malga Source: https://docs.malga.io/documentations/flow-guide/flow-dash Use Fluxos Inteligentes no Dashboard Malga para gerenciar transações, ajustar provedores e regras de orquestração de pagamentos em tempo real. Através do menu de Fluxos Inteligentes no [Dashboard Malga](https://dashboard.malga.io/app/smart-flows), é possível visualizar e fazer alterações em tempo real no fluxo de pagamentos com **autonomia e flexibilidade**, modificando os provedores de **cobrança, antifraude e as regras de orquestração** através do uso de condicionais. > [!NOTE] > > O menu **Fluxos Inteligentes** aparece somente na visão de uma subconta. Para acessá-lo, clique no nome da empresa no topo do menu lateral e selecione a subconta. [Saiba mais](/documentations/dashboard/context-selector). > [!NOTE] > > A página para gerenciamento tem **acesso exclusivo para usuários administradores** da conta. Caso precise realizar alterações nos usuários da sua empresa, contate o nosso time de atendimento. A seguir, explicaremos o **passo a passo** para visualizar, criar, editar, restaurar e publicar o fluxo de pagamentos através do Dashboard. #### Fluxo inteligente no Dashboard ![Fluxo inteligente no Dashboard](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/flow-guide/flow-dash/smart-flow-light.png?fit=max\&auto=format\&n=-IrbFw4MHs9nOTYj\&q=85\&s=393f1d870f0630b322632264956fe0b7) ### Como funcionam os fluxos inteligentes? O fluxo inteligente de pagamentos Malga pode ser configurado através do Dashboard e consultado pela API Flows. Está disponível para os métodos de cartão de crédito, pix e boleto. Ao acessar o fluxo pela primeira vez no Dashboard, caso você ainda não possua um fluxo inteligente configurado, irá visualizar os provedores e a ordem de prioridade estabelecidos na subconta \[`merchant`] com o nome de “Fluxo Padrão”. A partir da criação e publicação de um fluxo inteligente, a ordem de prioridade dos provedores seguirá as regras configuradas. Para visualizar as suas subcontas, provedores e métodos ativos, acesse [Gerenciar subcontas](https://dashboard.malga.io/app/merchants), no rodapé do seletor de contexto do Dashboard. O menu de Fluxos Inteligentes está disponível **somente no ambiente online do Dashboard Malga**. Cada método de pagamento (crédito, pix, boleto e Apple Pay) possui o seu respectivo fluxo inteligente de pagamentos, separados por subconta (`merchant`). O fluxo exibido é sempre o da subconta ativa no seletor de contexto. Os fluxos inteligentes permitem a combinação de provedores e condicionais, sendo somente possível adicionar provedor de antifraude ao método crédito. Você possui a opção de criar uma subconta para testes utilizando o provedor sandbox Malga. Encontre também mais informações [aqui](/documentations/flow-guide/introduction). # Histórico de fluxos Source: https://docs.malga.io/documentations/flow-guide/historic Visualize e restaure versões anteriores dos seus Fluxos Inteligentes de pagamento na Malga com o histórico de fluxos do Dashboard. Através do **Histórico de Fluxos**, é possível visualizar e restaurar fluxos anteriores naquele merchant e método de pagamento. Acessando o menu de Histórico, é exibida a listagem dos fluxos em ordem cronológica de criação, sendo o fluxo ativo em produção o primeiro da listagem com a indicação "Versão atual". ### Restaurando um fluxo Ao reabrir um fluxo pelo Histórico, é possível publicá-lo novamente tornando-o ativo. Este fluxo passa a ter um vínculo com o fluxo a partir do qual foi restaurado (indicado na informação “Restaurado de” dentro do menu do Histórico). ![Historic Flow Light](https://mintlify.s3.us-west-1.amazonaws.com/malga/assets/images/flow-guide/historic/historic-flow-light.gif) > [!TIP] > > O Histórico de Fluxos traz segurança para o usuário publicar e restaurar versões anteriores do fluxo de pagamentos, caso queira desfazer alguma alteração publicada. Através dele, é possível visualizar a listagem e os fluxos que estiverem ativos em algum momento e quais foram restaurados, indicados através do nome dos fluxos na listagem. # Começando em fluxos inteligentes Source: https://docs.malga.io/documentations/flow-guide/introduction Como funciona a Orquestração de Fluxos Inteligentes na Malga: configure provedores e regras condicionais para otimizar suas transações de pagamento. Conforme as empresas crescem, a estrutura de pagamentos digitais também cresce e fica mais complexa. Em muitos modelos de negócio o uso de múltiplos provedores precisa ser feito de forma estratégica para otimizar a aprovação de cobranças com características específicas, assim como os custos de operação. Os Fluxos Inteligentes colocam à disposição **Operadores Condicionais** que podem ser configurados para alterar o comportamento de suas cobranças, como modificar as prioridades de provedores ou ativar um provedor antifraude para melhorar a segurança, no momento de seu processamento. Com essa funcionalidade, aqui na Malga, as cobranças seguem o comportamento definido no Fluxo Inteligente vinculado ao **Merchant** e **Método de Pagamento** que está sendo utilizado. Caminhos únicos dentro de um Fluxo Inteligente são chamados de **Ramificações**. No momento, cada **Método de Pagamento** pode ter até um Fluxo Inteligente ativo com até um provedor antifraude e até três provedores de cobrança por ramificação. ## Operadores condicionais Os Operadores Condicionais são **separadores de fluxo** que podem ser configurados utilizando comparadores lógicos em conjunto com dados disponíveis nas cobranças para decidir quais provedores serão utilizados no processamento daquela cobrança. Os condicionais podem utilizar dados nativos das cobranças, como o valor, quantidade de parcelas e a bandeira do cartão selecionado ou **metadados** enviados no campo `metadata` das `charges`. ### Tabela de operadores suportados | Operador | Descrição | Tipo dos Operandos | Exemplo de Expressão | | - | - | - | - | | **lt \<** | Menor que | `number` | `transaction.amount < 5000` | | **gt >** | Maior que | `number` | `transaction.amount > 5000` | | **le \<=** | Menor ou igual a | `number` | `transaction.amount <= 5000` | | **ge >=** | Maior ou igual a | `number` | `transaction.amount >= 5000` | | **eq =** | Igual a | `number`, `string` | `transaction.installments = 0` | | **ne !=** | Diferente de | `number`, `string` | `transaction.installments != 0` | | **and** | Operador lógico E | `boolean` | `transaction.installments = 0 and transaction.amount < 5000` | | **or** | Operador lógico OU | `boolean` | `transaction.installments = 0 or transaction.amount < 5000` | ## Propriedades de charge disponíveis As propriedades das `charges` podem ser utilizadas para fazer a composição das regras de processamento de cobrança junto dos Operadores Condicionais. As propriedades atualmente mapeadas para uso nas regras de processamento se encontram na tabela a seguir. | Propriedade | Tipo | Descrição | | - | - | - | | **amount** | `number` | Valor da cobrança em centavos | | **currency** | `string` | Identificador da moeda para processamento da cobrança, formato ISO 4217 | | **cardBin** | `string` | Os seis primeiros dígitos de um cartão, conhecidos como Bank Identification Number ou Issuer Identification Number | | **brand** | `string` | Bandeira do cartão *(exclusivo para cartões)* | | **installments** | `number` | Quantidade de parcelas para cobrança *(exclusivo para transações do tipo crédito)* | | **metadata** | - | Propriedade para inserção de campos adicionais na cobrança. Podem ser adicionadas propriedades do tipo `number`, `string`, `boolean`, `object` ou `list` | ## Uso de metadados de transação É possível enviar **metadados** da cobrança para uso em seus Fluxos Inteligentes. Esta propriedade é uma propriedade especial da cobrança que aceita quaisquer propriedades dentro dela, possibilitando que você processe regras de negócio de um ponto de vista de escolha dos provedores que devem processar aquela transação utilizando o motor da Malga. ```json theme={null} { [...], "paymentFlow": { "metadata": { "stringProperty": "value for property 1", "numericProperty": 10, "numericProperty2": 10.5, "listProperty": ["element1", "element2"], "objectProperty": { "subProp1": "value" } [...] } }, [...] } ``` ### Exemplo de uso de metadata Os dados adicionais de cobrança são extremamente flexíveis e servem para que você possa processar suas regras de negócio utilizando o motor interno da Malga. Por exemplo, caso queira utilizar propriedades que não existem normalmente em uma cobrança Malga, é possível adicionar estas propriedades utilizando o campo de `metadata`, como demonstrado no exemplo a seguir: ![Exemplo de Fluxo Inteligente](https://mintcdn.com/malga/9REabHx8RAbPGMBg/assets/images/flow-guide/payment-flow/flow-example01-light.png?fit=max\&auto=format\&n=9REabHx8RAbPGMBg\&q=85\&s=e383a5faf40178bcc0c1f4195a05386e) Neste cenário, caso o valor de `metadata.daysToEvent` seja maior do que 60, não é feito o uso de provedores antifraude para proteger a cobrança. Assim como o envio da propriedade arbitrária `daysToEvent`, qualquer propriedade pode ser enviada com uma cobrança para processar regras condicionais. | Cobrança | Antifraude | Provedor 1 | Provedor 2 | Provedor 3 | | - | - | - | - | - | | daysToEvent = 61; amount = 550; installments = 2 | - | PagSeguro 2 | PagSeguro 3 | Adyen | | daysToEvent = 45; amount = 300; installments = 6 | Clearsale 2 | PagSeguro 1 | PagSeguro 3 | Adyen | | daysToEvent = 70; amount = 1200; installments = 3 | Clearsale 1 | PagSeguro 2 | PagSeguro 3 | Adyen | > [!NOTE] > > As retentativas baseadas nos provedores antifraude acontecem na etapa de **pré-autorização**, portanto, uma vez pré-autorizada em um provedor, a transação termina seu ciclo de vida neste provedor até o momento de captura ou falha. > > Apesar de ser possível enviar metadados passando uma lista de elementos ou objetos aninhados em **metadata** para processamento, ainda não existem operadores compatíveis com estes tipos de propriedades. > > As palavras *currency*, *cardBin*, *installments*, *amount*, *brand*, *paymentType* e *operation* são reservadas e não podem ser utilizadas como chaves nos metadados. Caso sejam enviadas, podem resultar em erros ou comportamentos inesperados. ## Distribuição de carga É possível fazer a distribuição de cobranças em ramificações do Fluxo Inteligente utilizando a propriedade `math/random`. Esta propriedade gera um número aleatório entre 0 e 1 e pode ser acessada em conjunto com operadores lógicos para criar regras de distribuição de carga, como no exemplo a seguir, onde 60% das transações são enviadas pela ramificação **true** e 40% são enviadas pela ramificação **false**: `math/random < 0.6` ![Exemplo de Distribuição de Carga](https://mintcdn.com/malga/9REabHx8RAbPGMBg/assets/images/flow-guide/payment-flow/flow-loadbalancing-light.png?fit=max\&auto=format\&n=9REabHx8RAbPGMBg\&q=85\&s=5d5e6fa2a99f2e8bc544c57543543dfe) ## Comportamento de provedores de cobrança Os Provedores de Cobrança são configurados em uma ordem de prioridade dentro dos Fluxos Inteligentes. Uma vez que uma cobrança não seja devidamente aprovada em um provedor, caso a causa do erro seja retentável, a cobrança segue para ser processada no próximo provedor configurado no Fluxo Inteligente. Caso não haja um novo provedor a ser tentado após o último erro retentável retornado, a cobrança é retornada como `failed`. > [!NOTE] > > Podem ser configurados até três provedores de cobrança em uma única **ramificação** do seu Fluxo Inteligente. ### Tabela de causas de falha Causas comuns de falha podem ser vistas [aqui](/documentations/type-tables/declined-code). ## Comportamento de provedores antifraude Em um Fluxo Inteligente é possível configurar Provedores Antifraude para proteger suas transações e seu comportamento pode ser verificado em [**nossa documentação**](/documentations/anti-fraud). Dentro de uma única **ramificação** do Fluxo Inteligente é possível configurar apenas um provedor antifraude, ou seja, não é possível processar múltiplos provedores antifraude para uma única cobrança. Este tipo de configuração permite que você alterne entre múltiplos Provedores Antifraude, ou até desligue este tipo de proteção, utilizando estratégias diferentes para cobranças de características distintas. Estas regras são processadas cobrança a cobrança de acordo com as características configuradas no Fluxo Inteligente. > [!NOTE] > > As retentativas baseadas nos provedores antifraude acontecem na etapa de **pré-autorização**, portanto, uma vez pré-autorizada em um provedor, a transação termina seu ciclo de vida neste provedor até o momento de captura ou falha. # Começando um novo fluxo Source: https://docs.malga.io/documentations/flow-guide/new Saiba como começar um novo Fluxo de Pagamentos na Malga, configurando provedores de cobrança, antifraude e condicionais para otimizar suas transações. A partir da tela Fluxos Inteligentes, é possível **limpar o fluxo atual ativo e iniciar a configuração de um novo fluxo de pagamentos** para o método de pagamento selecionado. A criação do fluxo inicia através da inserção de um card, que pode ser um provedor de cobrança, antifraude ou uma condicional, seguindo o fluxo abaixo: ![Botão de iniciar novo fluxo](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/flow-guide/create-flow/new-flow-light.gif?s=19643927339a204e39e1ac6abf47acac) ## Parâmetros disponíveis Confira os **parâmetros disponíveis** para inserir no fluxo de pagamentos: 1. Provedores de cobrança; 2. Provedor antifraude; 3. Condicionais. | Tipo de Parâmetro | Opções disponíveis | Exemplo de card | | - | - | - | | **Provedor de cobrança** | [Provedores disponíveis Malga](/documentations/type-tables/payment-methods-by-providers) | ![Card](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/create-flow/card.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=ca612ff2c7d90f97f40f1f39615ff39b) | | **Provedor antifraude** **\[1 provedor de antifraude]** | Disponível para crédito • Clearsale | ![Card Antifraude](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/create-flow/card-antifraude.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=9eaafb3bcaa10d1f02321fb7f33dcf3c) | | **Condicionais** **\[7 condicionais + combinações]** | Condicionais para crédito, pix e boleto • Balanceador de Distribuição de carga • Campo personalizado (metadata) • Moeda • Valor • Combinações (diferentes condicionais no mesmo card) | ![Card Conditional](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/create-flow/card-conditional.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=6c9ba4ff217a905f9146bc746aa6c5ef) | > [!NOTE] > > Os provedores de cobrança e antifraude disponíveis para adição no fluxo correspondem aos provedores configurados na subconta ativa no seletor de contexto do menu lateral. Caso queira utilizar outros provedores, entre em contato com o nosso time de atendimento. #### Navegando pelos provedores e parâmetros disponíveis ![Menu lateral para adição/edição de provedores de cobrança e antifraude do fluxo](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/create-flow/params-navigation-light.gif?s=8820b96714eff87c65947d05520a4f61) # Validação e publicação Source: https://docs.malga.io/documentations/flow-guide/validation Saiba como publicar um Fluxo de Pagamentos no Dashboard da Malga, validando e ativando suas configurações para otimizar o processamento de transações. ## Publicando o fluxo de pagamentos Após a edição, é necessário realizar a **publicação do fluxo** para torná-lo ativo e iniciar o processamento das transações através dele. Esta ação acontece através do botão **Publicar**, localizado no canto superior direito da tela. Durante o processamento da publicação, as seguintes ações acontecem: 1. **Nomear fluxo**: É possível atribuir um nome personalizado ao fluxo; 2. **Validação do fluxo**: são validadas as configurações realizadas pelo usuário, recebendo a mensagem de sucesso ou feedback do que precisa ser ajustado para aprovação do fluxo; 3. **Publicação do fluxo**: caso o fluxo seja aprovado na validação, ele é automaticamente publicado e passa a ser o fluxo ativo para o processamento das transações; > [!NOTE] > > A **publicação de um novo fluxo** em produção não impacta as transações em andamento pois acontece após a atualização do fluxo anterior ativo. Se houver uma transação em andamento no momento da requisição de mudança, ela será concluída, e a seguinte será processada pelo novo fluxo publicado. ![Success Light](https://mintcdn.com/malga/yws4rxGEzT5wCNep/assets/images/flow-guide/publish/success-light.png?s=9b0718d0d87ff8662e6e638d7ff15c8a) > [!NOTE] > > **O que é validado para publicação do fluxo de pagamentos?** > > * Se toda ramificação possui pelo menos um provedor de cobrança; > * Se a ramificação com antifraude possui pelo menos um provedor de cobrança depois do antifraude; > * Se nenhuma ramificação contém dois ou mais cards de antifraude; > * Se todos os provedores inseridos no fluxo estão ativos naquele merchant no momento da publicação. ## Descartando alterações realizadas Ao fazer alterações no fluxo, você deve publicá-lo para que as novas regras passem a processar transações. Caso queira sair durante a edição de um fluxo que ainda não está publicado, será exibida uma mensagem **confirmando o descarte das alterações realizadas**. Caso confirme, as alterações realizadas são perdidas e o fluxo ativo permanece inalterado. ![Confirmação de saída de um fluxo em edição com alterações não publicadas](https://mintcdn.com/malga/yws4rxGEzT5wCNep/assets/images/flow-guide/validation/exit-modal-light.png?fit=max\&auto=format\&n=yws4rxGEzT5wCNep\&q=85\&s=1a1c4d1ccedc7a9ca9bc85283e54bf3d) # Visualizando o fluxo Source: https://docs.malga.io/documentations/flow-guide/visualization Visualize o Fluxo Inteligente no Dashboard da Malga: escolha a subconta no seletor do menu lateral e o método de pagamento para monitorar e gerenciar suas transações. Com uma subconta ativa no seletor de contexto do menu lateral, acesse o menu de Fluxos Inteligentes e selecione o método de pagamento para o qual deseja ver o fluxo. Para ver o fluxo de outra subconta, troque o contexto no seletor: você continua na página de Fluxos Inteligentes e só os dados mudam. **Cada método de pagamento possui apenas um fluxo de pagamentos ativo por subconta**, estando disponíveis crédito, pix e boleto para configuração do fluxo inteligente. Para conhecer as funcionalidades de orquestração, [consulte a documentação](/documentations/flow-guide/introduction). Para consultar **quais provedores estão ativos** para o seu fluxo, acesse [Gerenciar subcontas](https://dashboard.malga.io/app/merchants), no rodapé do seletor de contexto, e confira as contas configuradas para a sua empresa (vinculadas ao seu client-ID). Caso queira inserir ou ajustar os provedores na sua subconta, [consulte aqui](/documentations/type-tables/payment-methods-by-providers) os provedores e métodos de pagamento suportados pela Malga, e caso já possua as chaves de acesso ao provedor, utilize a [API de merchants](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) para alterar a sua subconta. ## Visualizando um fluxo de pagamentos Ao selecionar o método de pagamento, é possível visualizar o fluxo ativo da subconta selecionada no seletor de contexto, exibido na ordem dos provedores em que uma transação será processada e as regras configuradas para cada ramificação. Na tela de Fluxos Inteligentes, através dos botões no canto inferior esquerdo, você pode: #### Funcionalidades disponíveis para navegação | Botões | Função | Identificador | | - | - | - | | **Zoom in** | Aplicar zoom para ampliar a visualização | ![Zoom In](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/zoom-in.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=3305fe5ea6e863f35ee6f22abcbb474c) | | **Zoom out** | Aplicar zoom para reduzir a visualização | ![Zoom Out](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/zoom-out.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=56bf56e1ca9b2b0d28dedd7d1d72e2bc) | | **Centralização** | Centralizar a visualização | ![Centralize](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/centralize.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=ab829fdaf614b39f50fc27b8101f6876) | No cabeçalho do fluxo, está disponível o **nome do fluxo de pagamentos**, que pode ser alterado no momento da publicação, facilitando a identificação futura do seu fluxo no histórico de versões e nas transações processadas através dele. ## Ações disponíveis na visualização ![Seleção de subconta e método de pagamento | botões de criar, histórico e publicar](https://mintcdn.com/malga/-hsjUTcViP8rhfzc/assets/images/flow-guide/view/flow-header-light.png?fit=max\&auto=format\&n=-hsjUTcViP8rhfzc\&q=85\&s=69e17784d835771170913cd421d566a9) Durante a visualização e edição do fluxo, estão disponíveis as seguintes ações: | Botões | Função | Identificador | | - | - | - | | **Criar um novo fluxo** | Botão que inicia a criação de um novo fluxo vazio | ![New Flow](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/new-flow.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=637d2b88754722bcfa0bb4eca2402624) | | **Histórico** | Consultar histórico de fluxos e restaurar fluxos | ![History](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/history.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=0186c068d98832aff48e22042cbdc230) | | **Publicar fluxo** | Validar e ativar fluxo configurado | ![Publish](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/publish.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=3770bc58b87c709fd32d400db8e66b9e) | #### Seleções Através do menu, também é possível selecionar: * Método de pagamento * Fluxo com 3DS2 ou sem A subconta é definida pelo seletor de contexto do menu lateral. ## Status do fluxo de pagamentos Ao visualizar o fluxo, é exibido o seu status, conforme indicado no canto superior da tela. **Existem quatro status disponíveis do fluxo no Dashboard**: | Status | Conceito | Identificador | | - | - | - | | **Ativo** | Fluxo de pagamentos ativo e processando para aquele método de pagamento e subconta | ![Status Active](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/status-active.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=bee6305f3ec216c8cbbc925356f638c5) | | **Novo** | Fluxo de pagamentos criado e ainda sem configurações | ![Status New](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/status-new.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=4b70da45b79969c7801f61f94400f741) | | **Em edição** | Fluxo de pagamentos ativo que possui alterações ainda não publicadas pelo usuário | ![Status Edditing](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/status-edit.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=6e4b1b0e3c066d7efbd2f2af7741fb4a) | | **Restaurado** | Fluxo de pagamentos aberto a partir do histórico de fluxos e que ainda não foi editado e não está publicado | ![Status Restored](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/status-restored.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=330bdd4315f908af231e9f82b64b25ad) | ## Identificando as regras Na tela de visualização e em cada ramificação exibida do fluxo de pagamentos, estão contidas informações visuais para identificação das regras de processamento da transação. #### Elementos visuais para identificação das regras de processamento do fluxo ![Elementos visuais para identificação das regras de processamento do fluxo](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/visual-elements-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=e021e831a2878ae8df619beca68ca1ec) **Confira o que significa cada elemento do fluxo:** | Nome | Conceito | Identificador | | - | - | - | | **Card** | Corresponde a cada elemento do fluxo, podendo ser um card de provedor de cobrança, provedor antifraude ou condicional. | ![Card](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/create-flow/card.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=ca612ff2c7d90f97f40f1f39615ff39b) | | **Retentativa** | É a ordem na qual a transação será em caso de reprovação ou falha por motivo passível de retentativa. [Confira os motivos de falha ou recusa de uma transação](/documentations/flow-guide/introduction#tabela-de-causas-de-falha). | ![Retry](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/retry.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=910e534aed8d9d08401c6b7ecf11c37a) | | **Aprovação** | Indica a ligação entre o antifraude e o provedor de cobrança, indicando onde a transação será processada após a aprovação do antifraude. **Transações reprovadas no antifraude não são processadas**. Confira [como utilizar o antifraude](/documentations/flow-guide/introduction#comportamento-de-provedores-antifraude) no seu fluxo. | ![Authorized](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/authorized.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=bfa0426abe27ef141e791d61bb2a70c5) | | **Distribuição de carga \[condicional]** | Através do [condicional de distribuição de carga](/documentations/flow-guide/introduction#distribuição-de-carga), é possível dividir o processamento das transações entre dois provedores de cobrança. O símbolo % indica qual a quantidade de transações será direcionada para cada ramificação. | ![Percentage](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/percentage.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=f6014303c2a36a52902d9447f6b5309b) | | **Operadores Condicionais** | Após a inserção de um [operador condicional](/documentations/flow-guide/introduction#tabela-de-operadores-suportados) no fluxo, as ramificações de "Sim" ou "Não" indicam o próximo passo do fluxo para o resultado daquela condicional. | ![Yes](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/yes.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=6f82a3850cdc154436f9ab61571f3ed5) ![No](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/no.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=75ac45c281c52b98ea85a663f58ebdf4) | | **Adição de elementos** | Através do :heavy\_plus\_sign:, é possível adicionar um novo provedor de cobrança, antifraude ou condicional, entre ou após os elementos daquela ramificação. | ![Add New](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/flow-guide/view/add-new.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=a7f32124a48be5128db3d689144a7ebf) | # Idempotência Source: https://docs.malga.io/documentations/more/idempotency Entenda como as chaves de idempotência na API da Malga previnem a duplicidade no processamento de requisições, garantindo operações seguras e eficientes. A API da Malga suporta chaves de idempotência para evitar duplicidade no processamento de requisições no caso de retentativas de uma mesma operação. Este recurso é útil quando uma requisição falha por erro na comunicação e você não recebeu uma resposta conclusiva. Se você receber um erro de conexão em uma determinada chamada você pode simplesmente retentar uma nova requisição usando a mesma chave de idempotência, dessa forma nossa API consegue garantir que a segunda chamada não será processada em duplicidade. Para realizar chamadas com idempotência basta enviar um header adicional `X-Idempotency-Key`. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --header 'X-Idempotency-Key: ' ``` Nosso serviço salva a chave de `Idempotency-Key` e o `Body` enviado no seu request dado um request, independente de falha ou sucesso no processamento. Salvamos o resultado do processamento, e quando uma segunda requisição é feita com a mesma chave de idempotência nosso serviço retorna o mesmo conteúdo retornado na primeira chamada, incluindo os erros. > [!WARNING] > > A chave de idempotência precisa ser única, gerada no lado do cliente, sendo > necessário garantir do seu lado que as chaves não colidam. Sugerimos usar V4 > UUID ou outro algoritmo similar que garanta hashes únicos. O resultado só é armazenado no lado da Malga, caso tenha sido iniciado o processamento do primeiro request. Se existir alguma falha na validação dos campos, ou se outra chave estiver em processamento simultaneamente, nenhuma resposta de idempotência é dada. Todas as chamadas de POST aceitam chave de idempotência. ## Condição de corrida Caso uma transação seja enviada mais de uma vez ao mesmo tempo, usando a mesma chave de idempotência, o processo entra em condição de corrida (race condition). Caso isso ocorra você poderá receber 1 transação com status de sucesso e outra com erro informando essa condição. Os erros retornados em caso de condição de corrida são: * Http 409 - Transaction is processing * Http 400 - There is a transaction with the same idempotency key in transaction at that time Para evitar a condição de corrida recomendamos que você adicione um tempo mínimo de intervalo entre duas chamadas com mesma chave de idempotência, e trate os erros recebidos de 409 e 400 para fazer retentativa. Recomendamos pelo menos 3 tentativas, no máximo 5, com intervalo mínimo de 10 segundos entre elas. Veja um exemplo: > [tab] Node > > Para rodar o exemplo instale o axios `npm i axios axios-retry` então rode executando `node index.js` > > ```javascript theme={null} > const axios = require("axios"); > const axiosRetry = require("axios-retry"); > > const MERCHANT_ID = ""; > const CARD_ID = ""; > const CLIENT_ID = ""; > const API_KEY = ""; > const IDEMPOTENCY_KEY = ""; > > axiosRetry(axios, { > retries: 3, > retryDelay: () => { > return 10_000; > }, > retryCondition: (error) => { > if (axiosRetry.isNetworkOrIdempotentRequestError(error)) { > return true; > } > > const isUsingIdempotencyKey = > error.request.getHeader("x-idempotency-key") !== undefined; > const isMethodPost = error.request.method === "POST"; > if (isUsingIdempotencyKey && isMethodPost) { > return true; > } > > return false; > }, > onRetry: (retryCount) => { > console.debug(`retried ${retryCount}`); > }, > }); > > async function main() { > const data = JSON.stringify({ > merchantId: MERCHANT_ID, > amount: 150, > currency: "BRL", > statementDescriptor: "Pedido #231 loja joão", > capture: true, > paymentMethod: { > paymentType: "credit", > installments: 1, > }, > paymentSource: { > sourceType: "card", > cardId: CARD_ID, > }, > }); > > const headers = { "x-idempotency-key": IDEMPOTENCY_KEY }; > const result = await createCharge(data, headers); > > console.log(result?.data); > } > > /** > * Create a transaction without using idempotency key > */ > async function createCharge(data, headers = {}) { > const config = { > method: "post", > url: "https://api.malga.io/v1/charges", > headers: { > "x-client-id": CLIENT_ID, > "x-api-key": API_KEY, > "Content-Type": "application/json", > ...headers, > }, > data: data, > }; > > try { > const response = await axios(config); > return response; > } catch (e) { > return e.response; > } > } > > main(); > ``` # Limite de falhas no estorno Source: https://docs.malga.io/documentations/more/limite-falhas-estorno Entenda por que a Malga recusa um estorno com os erros 429 ou 422 depois de falhas repetidas no provedor e o que fazer em cada caso. Quando o provedor recusa várias vezes o estorno de uma mesma cobrança, a Malga para de enviar novos pedidos de estorno ao provedor. Assim, tentativas que tendem a falhar do mesmo jeito não sobrecarregam o provedor. O limite vale para os estornos feitos pela [requisição de void](/api-reference/charges/estornar-cobranca-aprovada), em qualquer meio de pagamento. ## Como a contagem funciona * Contam as tentativas de estorno da cobrança no mesmo provedor que não terminaram com sucesso, inclusive as que ainda estão em processamento. * Um estorno concluído com sucesso zera a contagem. ## Erros retornados Ao atingir o limite, a requisição de `void` é recusada com um dos erros abaixo: | HTTP code | `error.type` | Quando acontece | O que fazer | | - | - | - | - | | *429* | *too\_many\_requests* | O estorno falhou várias vezes seguidas. O tempo de espera aumenta conforme as falhas se acumulam. | Aguarde até o horário informado em `retry_after_at` e tente de novo. | | *422* | *unprocessable\_entity* | A cobrança atingiu o limite total de falhas de estorno. O bloqueio é definitivo: esperar não libera um novo estorno. | Não repita a requisição. Se necessário, entre em contato com o suporte da Malga. | Nesses dois casos, a Malga não envia o pedido ao provedor, não cria um novo `transactionRequest` e não altera o status da cobrança. A resposta é um erro HTTP, e não um `201` com um `transactionRequest` com status `failed`. ### Exemplo de requisição ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges/YOUR_CHARGE_ID/void' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 150 }' ``` ### Resposta `429` O corpo traz o tempo de espera em minutos (`retry_after_minutes`) e o horário em UTC a partir do qual você pode tentar de novo (`retry_after_at`): ```json theme={null} { "error": { "type": "too_many_requests", "code": 429, "message": "Too many consecutive refund failures for this charge. Please wait before trying again.", "retry_after_minutes": 15, "retry_after_at": "2026-09-30T14:35:00.000Z" } } ``` ### Resposta `422` ```json theme={null} { "error": { "type": "unprocessable_entity", "code": 422, "message": "This charge has too many refund failures at the provider. Please contact Malga support to have the refund processed manually." } } ``` ## Como tratar na sua integração **1. Respeite o tempo de espera do 429** Se a sua integração repete o estorno automaticamente, não faça uma nova tentativa antes do horário de `retry_after_at`. **2. Trate o 422 como erro final** Não repita a requisição: a resposta continua sendo `422`, mesmo depois de algum tempo. **3. Se necessário, fale com o suporte** Se precisar de ajuda, entre em contato com o suporte da Malga. Veja também a [tabela de erros da API](/documentations/welcome/errors). # Antecipação avulsa Source: https://docs.malga.io/documentations/more/prepayment Antecipe seus recebíveis futuros sob demanda na Malga. Consulte os recebíveis disponíveis, simule o valor que vai receber e confirme a antecipação. > [!NOTE] > > A **antecipação avulsa** e os endpoints relacionados estão em **Beta**. A funcionalidade já está disponível para clientes habilitados, mas detalhes da API e do fluxo podem evoluir nas próximas versões. A **antecipação avulsa** permite que você receba antes da data prevista os recebíveis das suas vendas processadas pela Malga, pagando uma taxa proporcional ao tempo antecipado. É "avulsa" porque é solicitada sob demanda — você decide quando e quais recebíveis quer antecipar. ## Como funciona A antecipação é solicitada **por período**. Você informa uma **data-limite** (`endDate`) e a Malga inclui na simulação **todos os recebíveis elegíveis com data prevista de recebimento até essa data (inclusive)**, calculando o valor líquido que você vai receber. Após confirmar a simulação, o pagamento é feito via transferência para a conta cadastrada. ## Pré-requisitos > [!NOTE] > > Antes de começar, sua conta precisa atender a estes dois requisitos: > > 1. **Transacionar pelo provedor de pagamento Malga.** A antecipação avulsa cobre apenas os recebíveis gerados em transações processadas pelo provedor Malga. Transações feitas por outros provedores conectados à plataforma (como Cielo, Rede, Adyen, etc.) não entram na antecipação. > 2. **Estar habilitada para antecipar recebíveis com a Malga.** Para solicitar a habilitação, entre em contato com o nosso suporte pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). A solicitação passa por uma análise antes de ser aprovada. Se a sua conta ainda não está habilitada, qualquer chamada à API de antecipação retornará um erro com status `403 Forbidden`. ## Fluxo de uso **1. Consulte os recebíveis disponíveis** Use o endpoint [Consultar recebíveis disponíveis](/api-reference/prepayment/consultar-recebiveis-disponiveis-para-antecipacao) para listar os recebíveis elegíveis para antecipação e ver o valor total disponível. ```bash theme={null} curl --location 'https://api.malga.io/v1/subacquirer/prepayment/receivables' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` A resposta traz um `summary` com o valor total disponível e a quantidade de recebíveis, além da lista de recebíveis com a data prevista de recebimento de cada um. **2. Simule a antecipação** Escolha uma **data-limite** (`endDate`) e crie uma simulação com o endpoint [Simular antecipação](/api-reference/prepayment/simular-antecipacao). A Malga inclui **todos os recebíveis elegíveis com data prevista de recebimento até essa data (inclusive)** e devolve o valor líquido que você vai receber. ```bash theme={null} curl --location 'https://api.malga.io/v1/subacquirer/prepayment' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "endDate": "2026-06-20" }' ``` A resposta traz o `id` da simulação (que você usa no aceite), o `endDate` considerado, o valor bruto, o valor líquido, o desconto, a taxa efetiva e o `expiresAt` (até quando a simulação pode ser aceita). **3. Confirme a antecipação** Para efetivar a antecipação, faça o aceite chamando o endpoint [Confirmar antecipação](/api-reference/prepayment/confirmar-antecipacao). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/subacquirer/prepayment/{id}/commit' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Após o aceite, a antecipação passa para o status `committed` e segue para pagamento. ## Acompanhe suas antecipações Para consultar o histórico, use o endpoint [Listar antecipações](/api-reference/prepayment/listar-antecipacoes). Ele devolve as simulações e antecipações da sua conta, da mais recente para a mais antiga, paginadas por `page` e `limit`. ```bash theme={null} curl --location 'https://api.malga.io/v1/subacquirer/prepayment?page=1&limit=10' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Cada item da lista traz os mesmos campos da consulta por identificador, então você não precisa guardar o `id` de cada simulação para acompanhar o que já foi solicitado. ## Como o valor antecipado é calculado Cada recebível tem um valor bruto e uma data prevista de recebimento. Quanto **mais distante** essa data, **maior o desconto** aplicado, porque você está antecipando mais dias. A resposta da simulação devolve: * `grossAmount`: soma do valor original dos recebíveis (em centavos). * `netAmount`: valor líquido que você vai receber (em centavos). * `feeAmount` e `markupAmount`: componentes do desconto aplicado (em centavos). * `effectiveRate`: taxa efetiva total da antecipação sobre o valor bruto. * `endDate`: data-limite considerada na simulação (YYYY-MM-DD). A regra que vale em todo recebível e no total da simulação é: ```text theme={null} grossAmount = netAmount + feeAmount + markupAmount ``` ## Prazos — horário de corte das 15h (horário de Brasília) > [!WARNING] > > A Malga sempre opera em **horário de Brasília**. O campo `expiresAt` é retornado em formato ISO 8601, mas representa esse horário. Para receber a antecipação **amanhã (D+1)**, a simulação precisa ser **criada e aceita até as 15h (horário de Brasília)** do mesmo dia. Após as 15h, qualquer simulação criada (ou aceite ainda não realizado) é tratada como se tivesse sido feita no dia seguinte, e o pagamento passa para **D+2**. O campo `expiresAt` no response indica esse limite — sempre 15h (horário de Brasília) do dia em que a simulação foi criada. ## Antecipação para recebedores Se você opera com [split de pagamentos](/documentations/split/intro), pode antecipar os recebíveis de um recebedor específico. Para isso, informe o `sellerId` no parâmetro da consulta e no corpo da simulação. Quando o `sellerId` não é informado, a operação é feita sobre os recebíveis da sua conta principal. ## Status da antecipação | Status | O que significa | | - | - | | `pending` | Simulação criada, ainda não aceita. | | `committed` | Aceite confirmado. A antecipação está em processamento. | | `paid` | Pagamento da antecipação realizado. | | `expired` | Simulação expirou (passou de 15h sem aceite) ou o aceite foi recusado porque o conjunto de recebíveis mudou desde a simulação. Basta simular novamente. | ## Próximos passos > [card] [Consultar recebíveis disponíveis](/api-reference/prepayment/consultar-recebiveis-disponiveis-para-antecipacao) > > Liste os recebíveis disponíveis para antecipação e o valor total disponível. > [card] [Simular antecipação](/api-reference/prepayment/simular-antecipacao) > > Crie uma simulação informando a data-limite (`endDate`) do período a antecipar. > [card] [Listar antecipações](/api-reference/prepayment/listar-antecipacoes) > > Consulte o histórico paginado das suas simulações e antecipações. > [card] [Recuperar detalhes de uma antecipação](/api-reference/prepayment/consultar-antecipacao) > > Consulte o status e os detalhes de uma simulação ou antecipação. > [card] [Confirmar antecipação](/api-reference/prepayment/confirmar-antecipacao) > > Faça o aceite da simulação para efetivar a antecipação. # Recorrência do provedor Source: https://docs.malga.io/documentations/more/recurrence/charges Repasse informações de recorrência ao provedor através do parâmetro recurrence em cobranças de cartão de crédito na API Charges da Malga. Ao realizar uma nova cobrança no método de crédito, é possível enviar o parâmetro `recurrence`, indicando se a cobrança faz parte de uma cobrança recorrente. Confira a estrutura de requisição para criar uma cobrança com a [API Charges](/api-reference/charges/realizar-nova-cobranca). > [!NOTE] > > Usando essa propriedade, é possível informar aos provedores que uma transação faz parte de uma recorrência, e portanto não há presença do CVV do cartão nas cobranças subsequentes ou avulsas, aumentando as taxas de aprovação dessas transações. A propriedade pode assumir os valores `initial`, `subsequent` ou `unscheduled`, de acordo com os cenários indicados abaixo: | Recurrence | Descrição | | - | - | | `initial` | indica a primeira transação de uma recorrência | | `subsequent` | indica transação que é parte de uma recorrência com frequência determinada | | `unscheduled` | indica transação não programada ou sem parcelas fixas dentro de uma periodicidade determinada, parte de uma recorrência | ### Provedores com suporte ao parâmetro de recorrência | Provedor | Suporte | | - | :-: | | Adyen | | | Barte | | | Braspag | | | Cielo | | | Getnet SEP | | | Pagarme v5 | | | Pagseguro | | | PicPay | | | Rede | | | Safrapay | | | Worldpay | | > [!TIP] > > No menu [Cobranças](https://dashboard.malga.io/) do Dashboard Malga, é possível extrair o relatório completo de cobranças, em formato `.csv`, contendo todas as informações das cobranças recorrentes. Confira [aqui](/documentations/dashboard/export-data) o passo a passo para obtenção do relatório e os dados disponíveis. # Introdução Source: https://docs.malga.io/documentations/more/recurrence/engine Conheça o Motor de Assinaturas da Malga, que automatiza cobranças recorrentes com agendamento, retentativas, Dashboard e webhooks. A **Malga** oferece um **Motor de Assinaturas** que automatiza todo o ciclo de vida de cobranças recorrentes — desde o agendamento e execução até as retentativas em caso de falha — com monitoramento centralizado via Dashboard e notificações via Webhooks. ## Benefícios * **Automatização completa** * **Monitoramento centralizado via Dashboard** * **Webhooks para notificações de eventos** * **Provedor-agnóstico + uso do Fluxo Inteligente** ## Ciclo de vida da assinatura Assinaturas podem ser definidas com frequência semanal, mensal, trimestral, anual, bienal ou trienal. O dia de vencimento segue regras específicas: ```mermaid theme={null} graph TD A[Criação da assinatura] --> B[Primeira cobrança] B --> C{Falha?} C -- Não --> D[Assinatura ativa] C -- Sim --> E[Retentativas automáticas] E --> F{Sucesso?} F -- Sim --> D F -- Não --> G[Status unpaid ou cancelamento] G --> H[Novas faturas ou encerramento] ``` ### Frequências e regras * **weekly**: sempre mesmo dia da semana de `startAt` * **monthly**: mesmo dia do mês (ou próximo dia válido) * **quarterly**: a cada 3 meses, idem ao mensal * **yearly**: mesmo dia/ano (ou adaptação para anos bissextos) * **biennial**: a cada 2 anos, mesma data do `startAt` (ou adaptação equivalente ao anual) * **triennial**: a cada 3 anos, mesma data do `startAt` (ou adaptação equivalente ao anual) ### Estados das assinaturas | Estado | Descrição | | - | - | | `created` | Assinatura criada, aguardando primeira cobrança | | `trialing` | Em período de trial | | `active` | Assinatura ativa com cobrança recorrente | | `paused` | Temporariamente suspensa | | `canceled` | Encerrada definitivamente | | `unpaid` | Inadimplente após falhas | | `expired` | Exauriu as faturas permitidas | ## Retentativas & estratégia Fluxo padrão de retentativas (5 tentativas) **1. D+0** Tentativa inicial no dia da fatura **2. D+1** Primeira retentativa (1 dia depois) **3. D+4** Segunda retentativa (4 dias depois) **4. D+9** Terceira retentativa (9 dias depois) **5. D+16** Última retentativa (16 dias depois) Você também pode personalizar a estratégia de retentativas através do campo `retryRules` nas [configurações](/documentations/more/recurrence/engine/client-settings). ### Erros irreversíveis O campo `retryable` da transação determina se a assinatura deve seguir as retentativas completas ou falhar imediatamente. Isso se deve porque alguns erros são passíveis de multa caso insistirmos em cobrar. Confira na [tabela de erros](/documentations/type-tables/declined-code) quais são irreversíveis. ### Consequências da falha completa Se todas as retentativas falharem: * A fatura recebe status `failed` * **Comportamento padrão**: assinatura vai para `unpaid` * Se `cancelAfterAllRetries` estiver ativo: `canceled` * Status `unpaid`: próximas faturas ainda serão processadas * Status `canceled`: não haverá mais cobranças automáticas ## Integração via API Você pode integrar o motor de assinaturas via [API](/api-reference/subscriptions/criacao-de-uma-nova-assinatura). > [card] [Comece a integração](/documentations/more/recurrence/engine/getting-started) > > Siga o passo a passo para implementar o motor de assinaturas na sua aplicação. # Configurações Source: https://docs.malga.io/documentations/more/recurrence/engine/client-settings Personalize o comportamento padrão de assinaturas no Motor de Assinaturas da Malga via API de configurações do cliente, com retentativas e políticas. O motor de assinaturas permite personalizar o comportamento das assinaturas através da rota de configurações. Essas configurações são aplicadas automaticamente a todas as assinaturas criadas. ### Consultar configurações Obtendo as suas configurações atuais: ```bash Request theme={null} curl --location 'https://api.malga.io/v1/subscriptions/settings' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ```json Response theme={null} { "retryRules": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 3}, {"daysAfterLastAttempt": 5}, {"daysAfterLastAttempt": 7} ], "statementDescriptor": "MINHA EMPRESA", "cancelAfterAllRetries": false } ``` ### Alterando as configurações ```bash Request theme={null} curl --location --request PATCH 'https://api.malga.io/v1/subscriptions/settings' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "retryRules": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 3}, {"daysAfterLastAttempt": 7} ], "statementDescriptor": "NOVA EMPRESA", "cancelAfterAllRetries": true }' ``` ```json Response theme={null} { "retryRules": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 3}, {"daysAfterLastAttempt": 7} ], "statementDescriptor": "NOVA EMPRESA", "cancelAfterAllRetries": true } ``` ## Conheça os parâmetros **retryRules** `array` O campo `retryRules` permite personalizar quando as retentativas de cobrança devem acontecer após uma falha inicial. **Importante**: As retentativas só acontecem quando a transação retorna `retryable = true`. Se a resposta da transação vier com `retryable = false`, a fatura falha imediatamente, independentemente da política de retry configurada. **Saiba mais** Se não configurado, o sistema usa a estratégia padrão: * **D+1**: 1ª retentativa * **D+4**: 2ª retentativa * **D+9**: 3ª retentativa * **D+16**: 4ª retentativa Exemplo de personalização: ```json theme={null} { "retryRules": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 2}, {"daysAfterLastAttempt": 4}, {"daysAfterLastAttempt": 7}, {"daysAfterLastAttempt": 10} ] } ``` Regras de validação: * **De 1 a 6 regras** de retry. Uma lista vazia é rejeitada com HTTP 400 * **Valores únicos**: Não repita o mesmo valor. A Malga salva as regras em ordem crescente * **Valores válidos**: Cada regra precisa ter pelo menos 1 dia * **Soma total**: A soma de todos os `daysAfterLastAttempt` não pode exceder 30 dias * **Formato obrigatório**: Array de objetos com `daysAfterLastAttempt` **Importante**: Os dias são cumulativos. Por exemplo, `[1, 3, 5]` significa: * 1ª tentativa: D+1 * 2ª tentativa: D+1+3 = D+4 * 3ª tentativa: D+1+3+5 = D+9 **cancelAfterAllRetries** `boolean` (default: false) O campo `cancelAfterAllRetries` define o comportamento da assinatura quando todas as tentativas de cobrança de uma fatura falham. * **false** (padrão): Assinatura vai para status `unpaid` e continua tentando nas próximas faturas * **true**: Assinatura é automaticamente cancelada após todas as retentativas falharem **statementDescriptor** `string` O campo `statementDescriptor` é o texto que aparece na fatura do cartão de crédito do cliente, ajudando na identificação da cobrança. * **Prioridade**: Se configurado, é usado em todas as cobranças * **Fallback**: Se não configurado, usa o nome da assinatura * **Limite**: Depende das regras do banco/operadora (geralmente 13-25 caracteres) * **Formatação**: Texto em maiúsculas, sem caracteres especiais ## Próximos passos > [card] [Criar primeira assinatura](/documentations/more/recurrence/engine/getting-started) > > Use suas configurações personalizadas na primeira assinatura > [card] [Monitorar retentativas](/documentations/more/recurrence/engine/webhooks) > > Configure webhooks para acompanhar o desempenho das retentativas # Integração Source: https://docs.malga.io/documentations/more/recurrence/engine/getting-started Guia passo a passo para integrar o motor de assinaturas da Malga: cadastre customer, salve cartão e crie assinaturas com cobranças automáticas. O motor de assinaturas da Malga permite criar assinaturas automáticas com cobranças recorrentes. Este guia mostra como configurar uma assinatura completa desde a criação do customer até a assinatura. ## Pré-requisitos Antes de começar, você precisará de: * **Merchant ID**: Identificador do seu fluxo na Malga; * **API Keys**: Chaves de autenticação para acessar as APIs; * **ClientId**: Seu identificador na Malga. ## Passo 1: Criar um Customer Primeiro, você precisa criar um customer na Malga para associar à assinatura. > [!NOTE] > > O customer é obrigatório para criar uma assinatura. Confira a [documentação > completa da API de > Customers](/api-reference/customers/criacao-de-novo-customer-para-cobranca) > para mais detalhes. > > Adicionamos novos campos de endereço de entrega e de cobrança para melhor suporte a antifraude dos provedores de pagamento. ### Exemplo de criação de customer ```bash Request theme={null} curl -X POST https://api.malga.io/v1/customers \ -H "X-Client-Id: YOUR_CLIENT_ID" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Maria Fernanda Souza", "email": "maria.souza@example.com", "phoneNumber": "+55 21 99888-9999", "document": { "number": "98765432100", "type": "cpf", "country": "BR" } }' ``` ```bash Response theme={null} { "id": "847a3085-131a-40a4-9ac4-6e573de9711a", "name": "Maria Fernanda Souza", "email": "maria.souza@example.com", "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "phoneNumber": "+55 21 99888-9999", "createdAt": "2025-07-31T13:04:13.494Z", "document": { "number": "98765432100", "type": "cpf", "country": "BR" } } ``` ## Passo 2: Salvar um cartão Para criar uma assinatura, você precisa de um cartão salvo na Malga. O processo é dividido em duas etapas: ### Criar um Token Primeiro, crie um token com os dados do cartão. > [!NOTE] > > O token é temporário e deve ser usado imediatamente para salvar o cartão. > Confira a [documentação da API de > Tokens](/api-reference/tokens/criar-um-novo-token) para mais detalhes. ```bash Request theme={null} curl -X POST https://api.malga.io/v1/tokens \ -H "X-Client-Id: YOUR_CLIENT_ID" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cardHolderName": "MARIA FERNANDA SOUZA", "cardNumber": "4019598346009339", "cardCvv": "123", "cardExpirationDate": "12/2026" }' ``` ```bash Response theme={null} { "tokenId": "d353deef-dacb-40a0-8cab-931ff773f274" } ``` ### Salvar o cartão Agora, use o token para salvar o cartão. > [!NOTE] > > O cartão salvo será usado para as cobranças recorrentes. Confira a > [documentação da API de > Cards](/api-reference/cards/criar-novo-cartao-a-partir-de-token) para mais > detalhes. ```bash Request theme={null} curl -X POST https://api.malga.io/v1/cards \ -H "X-Client-Id: YOUR_CLIENT_ID" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tokenId": "d353deef-dacb-40a0-8cab-931ff773f274" }' ``` ```bash Response theme={null} { "id": "e21ae714-e50b-4738-9f69-ab8fea37403d", "status": "pending", "statusReason": null, "createdAt": "2025-07-31T13:12:27.095Z", "clientId": "YOUR_CLIENT_ID", "customerId": null, "brand": "Visa", "cardHolderName": "MARIA FERNANDA SOUZA", "cvvChecked": false, "fingerprint": "UiASDuDi7YeEFznY9oPrr11AAADUZLkBHT0F8n5Y2Vs=", "first6digits": "401959", "last4digits": "9339", "expirationMonth": "12", "expirationYear": "2026", "tokenFingerprint": "hUrLmnf8tjJN7+tTsknaUgh7XOsMztm02dlusWCJwBw=" } ``` ### Vincular o cartão de crédito ao customer (recomendado) Não é obrigatório vincular o cartão de crédito ao customer, mas é recomendado para melhorar a experiência do cliente. Por padrão não vinculamos o cartão de crédito ao customer. Para fazer isso, utilize a API de [Vinculação de cartão de crédito ao customer](/api-reference/customers/adicionar-cartao-de-credito-ao-customer). ```bash Request expandable theme={null} curl -X POST https://api.malga.io/v1/customers/YOUR_CUSTOMER_ID/cards \ -H "X-Client-Id: YOUR_CLIENT_ID" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cardId": "e21ae714-e50b-4738-9f69-ab8fea37403d" }' ``` ## Passo 3: Criar a assinatura Agora você pode criar a assinatura recorrente com todos os dados necessários. > [!NOTE] > > Os intervalos de assinatura disponíveis são: **weekly** > (semanal), **monthly** (mensal), **quarterly** (trimestral), **yearly** (anual), **biennial** (bienal, a cada 2 anos) e **triennial** (trienal, a cada 3 anos). Escolha o intervalo que > melhor se adequa ao seu modelo de negócio. > > **Novidade**: Agora também suportamos assinaturas com **período de trial gratuito** - confira a [documentação do sistema de trial](/documentations/more/recurrence/engine/trial-system). > > **Importante**: O campo `startAt` deve ser informado em formato UTC (YYYY-MM-DD). ```bash Request theme={null} curl --location 'https://api.malga.io/v1/subscriptions' \ --header 'Content-Type: application/json' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --data '{ "name": "Assinatura Premium com Eventos", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "recurrence": { "interval": "monthly", "startAt": "2025-07-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" }, }, "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ] }' ``` ```bash Response theme={null} { "id": "subscription_id_example", "name": "Assinatura Premium com Eventos", "clientId": "YOUR_CLIENT_ID", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-07-30", "nextDueDate": "2025-08-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "bfb60d16-108c-440b-bdb8-bbe67140f936" }, "installments": 1 }, "status": "created", "amount": 29900, "liveMode": true, "createdAt": "2025-07-30T20:14:12.191866Z", "updatedAt": "2025-07-30T20:14:12.606647259Z" } ``` > [!NOTE] > > Assinaturas trimestrais seguem a mesma estratégia de retentativas das assinaturas mensais e anuais: 5 tentativas em D+0, D+1, D+4, D+9 e D+16. ## Assinaturas com Trial O motor de assinaturas suporta períodos de trial gratuito. Durante o trial, a assinatura fica no status `trialing` e não gera faturas de cobrança. ### Exemplo: Assinatura com Trial ```bash Request theme={null} curl --location 'https://api.malga.io/v1/subscriptions' \ --header 'Content-Type: application/json' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --data '{ "name": "Assinatura Premium com Trial", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "items": [ { "name": "Plano Premium", "description": "Acesso premium com período de trial", "amount": 9990, "quantity": 1 } ], "recurrence": { "interval": "monthly" }, "trial": { "endDate": "2025-02-01" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" }, "installments": 1 } }' ``` ```bash Response theme={null} { "id": "subscription_id_example", "name": "Assinatura Premium com Trial", "status": "trialing", "trial": { "endDate": "2025-02-01" }, "amount": 9990, "recurrence": { "interval": "monthly", "startAt": "2025-02-01", "nextDueDate": "2025-02-01" }, "createdAt": "2025-01-20T10:00:00Z" } ``` ### Características dos Trials * **Período gratuito**: Cliente pode usar o serviço sem ser cobrado * **Status `trialing`**: Assinatura fica neste status durante o período * **Transição automática**: Ao expirar, transiciona para `created` * **Apenas cancelamento**: Durante o trial, apenas cancelamento é permitido (não pausar) > [!NOTE] > > O campo `trial.endDate` deve ser uma data futura no formato `YYYY-MM-DD` indicando quando o trial termina. Se `startAt` não for fornecido, será automaticamente definido como a data de término do trial. Se for fornecido, `startAt` não pode ser anterior a `trial.endDate`. > [!WARNING] > > Envie o trial exatamente como `trial.endDate`. A Malga ignora sem erro um campo com outro nome, como `trialEnd` ou `trial.endAt`. Nesse caso, a assinatura nasce sem trial. Sem `startAt`, a Malga cobra o primeiro ciclo na criação. ## Próximos passos Agora que sua assinatura está criada, você pode: > [card] [Entenda cobranças instantâneas](/documentations/more/recurrence/engine/instant-payment) > > Saiba como realizar cobranças instantâneas com a assinatura e entenda as > suas particularidades. > [card] [Gerenciar assinatura](/documentations/more/recurrence/engine/managing) > > Ative, pause ou cancele a assinatura conforme necessário. > [!NOTE] > > Ao pausar ou cancelar uma assinatura, as faturas pendentes (scheduled, pending, retrying) são automaticamente marcadas como `canceled` para preservar o histórico de auditoria. Faturas já finalizadas (authorized, failed) não são alteradas. > [card] [Trial](/documentations/more/recurrence/engine/trial-system) > > Configure períodos de trial gratuito para suas assinaturas. > [card] [Configurações](/documentations/more/recurrence/engine/client-settings) > > Personalize retentativas e statement descriptors. > [card] [Configurar webhooks](/documentations/more/recurrence/engine/webhooks) > > Configure regras de retentativa personalizadas para suas assinaturas. > [card] [Revisar a API de Subscriptions](/api-reference/subscriptions) > > Revise a documentação completa da API de Subscriptions. > [card] [Configurar webhooks](/documentations/more/recurrence/engine/webhooks) > > Receba notificações em tempo real sobre mudanças de status. # Cobrança instantânea Source: https://docs.malga.io/documentations/more/recurrence/engine/instant-payment Primeira cobrança imediata na criação da assinatura ou ao atualizar startAt antes do primeiro ciclo no motor de assinaturas da Malga. Quando você cria uma assinatura com `startAt` definido como a data atual, o motor de assinaturas da Malga processa a primeira cobrança imediatamente. Este comportamento especial permite que você inicie a cobrança no mesmo dia da criação da assinatura. > [!WARNING] > > **Importante**: O campo `startAt` deve ser informado em formato UTC (YYYY-MM-DD). ## Comportamento especial Ao definir `startAt` como a data atual, o motor de assinaturas: 1. **Processa a cobrança imediatamente** após a criação da assinatura 2. **Retorna informações detalhadas** sobre o processamento na resposta da API 3. **Envia webhooks específicos** para notificar sobre o resultado da cobrança 4. **Atualiza o status** da assinatura baseado no resultado da cobrança ## Exemplo de criação com startAt sendo hoje ```bash Request theme={null} curl --location 'https://api.malga.io/v1/subscriptions' \ --header 'Content-Type: application/json' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --data '{ "name": "Assinatura Premium com Eventos", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "recurrence": { "interval": "monthly", "startAt": "2025-08-06" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" } }, "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ] }' ``` ```json Response - Success theme={null} { "id": "subscription_id_example", "name": "Assinatura Premium com Eventos", "clientId": "YOUR_CLIENT_ID", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-08-05", "nextDueDate": "2025-09-05" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": true, "lastCycle": { "id": "cycle_id_example", "customerId": "YOUR_CUSTOMER_ID", "merchantId": "YOUR_MERCHANT_ID", "cycle": 1, "attempts": 1, "status": "authorized", "isEmulated": false, "createdAt": "2025-08-05T17:59:45.243691Z", "scheduledAt": "2025-08-05", "executedAt": "2025-08-05", "paymentHistory": [ { "id": "payment_history_id_example", "createdAt": "2025-08-05T17:59:45.249579Z", "chargeId": "charge_id_example", "attemptNumber": 1, "status": "authorized", "error": null } ] }, "createdAt": "2025-08-05T17:59:45.219657Z", "updatedAt": "2025-08-05T17:59:47.02068159Z" } ``` ```json Response - Error theme={null} { "id": "subscription_id_example", "name": "Assinatura Premium com Eventos", "clientId": "YOUR_CLIENT_ID", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-08-06", "nextDueDate": "2025-09-06" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" }, "installments": 1 }, "status": "created", "amount": 29900, "liveMode": true, "lastCycle": { "id": "cycle_id_example", "customerId": "YOUR_CUSTOMER_ID", "merchantId": "YOUR_MERCHANT_ID", "cycle": 1, "attempts": 1, "status": "retrying", "isEmulated": false, "createdAt": "2025-08-06T13:57:36.3877Z", "scheduledAt": "2025-08-06", "executedAt": "2025-08-06", "nextAttemptAt": "2025-08-07", "paymentHistory": [ { "id": "payment_history_id_example", "createdAt": "2025-08-06T13:57:36.396306Z", "chargeId": null, "attemptNumber": 1, "status": "failed", "error": { "code": 404, "details": null, "message": "Card not found", "type": "invalid_request_error" } } ] }, "createdAt": "2025-08-06T13:57:36.295605Z", "updatedAt": "2025-08-06T13:57:36.39395571Z" } ``` > [!NOTE] > > **Sobre o campo `lastCycle`**: O campo `lastCycle` sempre está presente nas respostas individuais de assinatura (GET, CREATE, UPDATE), mesmo quando não há cobrança instantânea. Quando não existem faturas, o campo será `null`. Nos exemplos acima, o campo contém um objeto porque há cobrança instantânea, mas em outros cenários você pode receber `"lastCycle": null`. ## Webhooks específicos Quando você cria uma assinatura com cobrança instantânea, você receberá webhooks específicos: ### Ordem de eventos 1. Quando a assinatura é criada: **`subscription.created`**; 2. Quando a cobrança é processada: * **`subscription.activated`** (em caso de sucesso); * **`subscription.cycle_failed`** (quando há falha no processamento da cobrança); 3. **`subscription.unpaid`** (após esgotar todas as tentativas de cobrança da fatura). ### Novo webhook: subscription.cycle\_failed Este webhook é enviado quando uma fatura de cobrança falha após todas as retentativas: ```json theme={null} { "id": "webhook_event_id_example", "apiVersion": "1.1", "object": "subscription", "event": "cycle_failed", "createdAt": "2025-08-06T13:57:36.672Z", "data": { "subscription": { "id": "subscription_id_example", "name": "Assinatura Premium com Eventos", "clientId": "YOUR_CLIENT_ID", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-08-06", "nextDueDate": "2025-09-06" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" }, "installments": 1 }, "status": "created", "amount": 29900, "liveMode": true, "createdAt": "2025-08-06T13:57:36.295605Z", "updatedAt": "2025-08-06T13:57:36.393955Z", "lastCycle": { "id": "cycle_id_example", "customerId": "YOUR_CUSTOMER_ID", "merchantId": "YOUR_MERCHANT_ID", "cycle": 1, "attempts": 1, "status": "pending", "isEmulated": false, "createdAt": "2025-08-06T13:57:36.3877Z", "scheduledAt": "2025-08-06", "paymentHistory": [ { "id": "payment_history_id_example", "createdAt": "2025-08-06T13:57:36.396306294Z", "chargeId": null, "attemptNumber": 1, "status": "pending", "error": null } ] } }, "errorCode": 404 } } ``` ## Atualização de startAt, scheduler e validações > [!WARNING] > > **Atenção**: `startAt` só pode ser alterado **antes do primeiro ciclo**. Depois que o primeiro ciclo for gerado, qualquer tentativa de atualização será rejeitada com HTTP 400. Se você alterar `recurrence.startAt` com `PUT /v1/subscriptions/:id` **antes do primeiro ciclo**, o comportamento segue a mesma ideia da cobrança na criação: quando a nova data de início cai na janela aceita pela plataforma, a primeira cobrança pode ser disparada **na própria resposta** da atualização, sem depender do próximo ciclo do scheduler. Datas fora da janela aceita pela plataforma são rejeitadas com HTTP 400. > [!NOTE] > > As mensagens de erro de validação da API são retornadas em inglês (por exemplo, em caso de falha com HTTP 400). ### Resumo do comportamento * **Scheduler**: para assinaturas em `created` ainda sem primeiro ciclo, a data de início da assinatura é validada com base na **data atual**. * **Validação na atualização**: não é permitido alterar `startAt` após o primeiro ciclo. Quanto à data em `startAt`, não é aceita data anterior a **mais de um dia** em relação à data atual (mensagem HTTP 400 equivalente a `startAt cannot be more than 1 day in the past`; vide fluxograma nesta seção). * **Mapeamento**: antes do primeiro ciclo, ao atualizar `startAt`, a **próxima data de vencimento** acompanha o novo início, para o scheduler e as regras de `next_due_date` permanecerem coerentes. * **Cobrança imediata no update**: com `recurrence.startAt` no body e assinatura ainda elegível (`created`, sem primeiro ciclo, com a data de hoje), a primeira cobrança pode ocorrer **no mesmo request**. * **`scheduledCancellationAt`**: na atualização da assinatura, a Malga valida a data à parte de `startAt`, mas com a mesma janela. `scheduledCancellationAt` não pode ser anterior a ontem em relação à data atual em UTC (comparação por calendário). Detalhes em [Cancelamento agendado: validações implementadas](/documentations/more/recurrence/engine/scheduled-cancellation#validações-implementadas). ### Elegibilidade do agendamento (primeiro ciclo) ```mermaid theme={null} %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1f2937', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#475569', 'lineColor': '#64748b', 'secondaryColor': '#0f766e', 'tertiaryColor': '#7c3aed', 'background': '#0b1220', 'mainBkg': '#111827', 'nodeBorder': '#334155', 'clusterBkg': '#0f172a', 'clusterBorder': '#1f2937', 'titleColor': '#e2e8f0', 'edgeLabelBackground': '#0f172a', 'textColor': '#cbd5e1' }}}%% flowchart TD subscriptionNode([Assinatura]) --> statusCheck{status?} statusCheck -->|"created
sem 1º ciclo"| startAtCheck{"Data de início
é hoje?"} statusCheck -->|"created
com ciclo gerado"| nextDueCreated{"Próxima cobrança
é hoje?"} statusCheck -->|"active / unpaid"| nextDueActive{"Próxima cobrança
é hoje?"} startAtCheck -->|"fora da janela"| excluded(["Não será processada"]) startAtCheck -->|dentro| cancelCheck nextDueCreated -->|não| excluded nextDueCreated -->|sim| cancelCheck nextDueActive -->|não| excluded nextDueActive -->|sim| cancelCheck cancelCheck{"Há cancelamento
agendado?"} -->|não| eligible(["Será processada"]) cancelCheck -->|sim| excluded style subscriptionNode fill:#1d4ed8,stroke:#3b82f6,color:#e0f2fe style eligible fill:#065f46,stroke:#10b981,color:#d1fae5 style excluded fill:#7f1d1d,stroke:#ef4444,color:#fee2e2 style cancelCheck fill:#1f2937,stroke:#475569 style startAtCheck fill:#312e81,stroke:#6366f1,color:#e0e7ff ``` ### Fluxo do PUT com recurrence.startAt A referência da operação está em [Atualizar assinatura](/api-reference/subscriptions/atualizar-assinatura). ```mermaid theme={null} %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1f2937', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#475569', 'lineColor': '#64748b', 'secondaryColor': '#0f766e', 'tertiaryColor': '#92400e', 'background': '#0b1220', 'mainBkg': '#111827', 'nodeBorder': '#334155', 'clusterBkg': '#0f172a', 'clusterBorder': '#1f2937', 'titleColor': '#e2e8f0', 'edgeLabelBackground': '#0f172a', 'textColor': '#cbd5e1' }}}%% flowchart TD patch(["PUT /v1/subscriptions/:id
com recurrence.startAt"]) --> cycleCheck subgraph validate ["Validação"] cycleCheck{"O primeiro ciclo
já foi gerado?"} cycleCheck -->|Sim| err400a(["400: startAt cannot be updated
after the first cycle has been generated"]) cycleCheck -->|Não| dateCheck{"startAt é válido
para atualização?"} dateCheck -->|Sim| ok["Válido"] dateCheck -->|Não| err400b(["400: startAt cannot be more than
1 day in the past"]) end subgraph apply ["Atualização"] ok --> updateSubscription["Assinatura atualizada"] updateSubscription --> syncCheck{"Ainda não houve
a 1ª cobrança?"} syncCheck -->|Sim| sync["Próxima cobrança alinhada
ao novo startAt"] syncCheck -->|Não| save sync --> save["Alterações salvas"] end subgraph payment ["Cobrança imediata"] save --> payCheck{"startAt foi enviado
na atualização?"} payCheck -->|Não| response payCheck -->|Sim| eligCheck{"Assinatura criada,
sem 1ª cobrança e
startAt = hoje?"} eligCheck -->|Não| response eligCheck -->|Sim| charge["Geração do ciclo e
processamento do pagamento"] charge --> response(["200 OK"]) end style patch fill:#1d4ed8,stroke:#3b82f6,color:#e0f2fe style err400a fill:#7f1d1d,stroke:#ef4444,color:#fee2e2 style err400b fill:#7f1d1d,stroke:#ef4444,color:#fee2e2 style sync fill:#312e81,stroke:#6366f1,color:#e0e7ff style charge fill:#065f46,stroke:#10b981,color:#d1fae5 style response fill:#065f46,stroke:#10b981,color:#d1fae5 style validate fill:#0f172a,stroke:#1f2937 style apply fill:#0f172a,stroke:#1f2937 style payment fill:#0f172a,stroke:#1f2937 ``` ### Por que essas regras existem Em cenários reais, uma assinatura podia permanecer em `created` com o primeiro ciclo nunca gerado quando a **data de início** era alterada retroativamente enquanto o scheduler considerava a **data atual**, ou quando a **próxima cobrança** não acompanhava a nova data de início antes do primeiro ciclo. O alinhamento da próxima data de vencimento e a **cobrança imediata no update** quando aplicável reduzem esse risco. ## Observações importantes * **Campo `lastCycle`**: Sempre presente nas respostas individuais de subscription (GET, CREATE, UPDATE). Pode ser `null` se não houver cycles, ou um objeto completo com os detalhes do último cycle. Na cobrança instantânea, o campo conterá informações sobre o cycle processado imediatamente. * **Status da assinatura**: * Sucesso: `active` * Erro: `created` (permanece até [retentativas esgotadas](/documentations/more/recurrence/engine/managing#regras-de-retentativas)) * **Status da fatura**: * Sucesso: `authorized` * Erro: `retrying` * **Payment History**: Contém detalhes de cada tentativa, incluindo erros * **Next Attempt**: Indica quando será a próxima tentativa de cobrança ## Próximos passos > [card] [Gerenciar assinatura](/documentations/more/recurrence/engine/managing) > > Aprenda como gerenciar assinaturas após a criação > [card] [Configurar webhooks](/documentations/more/recurrence/engine/webhooks) > > Configure webhooks para receber notificações em tempo real # Gerenciando suas assinaturas Source: https://docs.malga.io/documentations/more/recurrence/engine/managing Gerencie o ciclo de vida das assinaturas recorrentes na Malga via API: pause, reative, cancele e atualize cobranças automatizadas com facilidade. O motor de assinaturas da Malga oferece uma API para você gerenciar suas assinaturas recorrentes de forma programática. ## Ciclo de vida das assinaturas O motor de assinaturas gerencia automaticamente o ciclo de vida das suas assinaturas, desde a criação até a expiração. Entender como funciona esse fluxo é essencial para implementar corretamente as ações de gerenciamento. ### Estados das assinaturas * **created**: Assinatura criada, aguardando primeira cobrança * **trialing**: Assinatura em período de trial gratuito * **active**: Assinatura ativa com cobranças sendo processadas * **paused**: Assinatura pausada temporariamente * **canceled**: Assinatura cancelada manualmente * **unpaid**: Assinatura inadimplente (após falha de todas as retentativas, exceto se `cancelAfterAllRetries` estiver habilitado) * **expired**: Assinatura expirada (atingiu o limite de faturas configurado) ### Sistema de Trials O motor de assinaturas suporta períodos de trial gratuito para assinaturas. Durante o trial, a assinatura fica no status `trialing` e não gera faturas de cobrança. #### Características dos Trials * **Período gratuito**: Cliente pode usar o serviço sem ser cobrado * **Status especial**: Assinatura fica com status `trialing` durante o período * **Sem cobrança**: Não são geradas faturas de cobrança durante o trial * **Transição automática**: Ao expirar, transiciona automaticamente para `created` #### Estados com Trial ```mermaid theme={null} flowchart TD A[trialing] -->|Trial expira| B[created] B -->|Primeira cobrança| C[active] A -->|Apenas pode ser cancelada| D[canceled] B -->|Pode ser pausada ou cancelada| E[canceled] C -->|Pode ser pausada ou cancelada| F[canceled] ``` #### Regras para Trials * ✅ **Permitido**: Cancelar a assinatura durante o trial * ❌ **Não permitido**: Pausar a assinatura durante o trial * ❌ **Não permitido**: Editar o campo `trial.endDate` após criação (enviar `trial` na atualização devolve HTTP 400) * ⚠️ **Automático**: Transição para `created` quando o trial expira ### Fluxo de processamento de cobranças ```mermaid theme={null} flowchart TD A[Assinatura iniciou o processo de cobrança] --> B{Status da assinatura é:
created, active ou unpaid?} B -->|NÃO| Z[FIM] B -->|SIM| C[Processar cobrança] C --> D{Cobrança foi autorizada?} D -->|SIM| E{Última fatura da assinatura?} E -->|SIM| F[Status da assinatura: expired] E -->|NÃO| G[Status da assinatura: active] D -->|NÃO| H{É a última tentativa?} H -->|NÃO| C H -->|SIM| I{cancelAfterAllRetries
habilitado?} I -->|SIM| J[Status da assinatura: canceled] I -->|NÃO| K[Status da assinatura: unpaid] ``` ### Regras de retentativas O motor de assinaturas segue regras específicas para retentativas baseadas no tipo de assinatura: #### Estratégia unificada para todos os intervalos (5 tentativas) **Para weekly, monthly, quarterly, yearly, biennial e triennial:** * **D+0**: Tentativa inicial (no vencimento da fatura) * **D+1**: 1ª retentativa * **D+4**: 2ª retentativa * **D+9**: 3ª retentativa * **D+16**: 4ª retentativa (última tentativa) Se todas as retentativas falharem, a fatura fica **failed**, e a assinatura ficará **unpaid**. A assinatura permanecerá neste estado e continuará tentando cobrar nas próximas faturas até que seja cancelada manualmente. ### Status das faturas Cada fatura de uma assinatura possui um status que indica seu estado atual no processo de cobrança: * **scheduled**: Fatura agendada para processamento futuro * **pending**: Fatura aguardando processamento de cobrança * **authorized**: Fatura processada com sucesso (estado final - não pode ser alterado) * **failed**: Fatura que falhou após todas as retentativas (estado final - não pode ser alterado) * **retrying**: Fatura em processo de retentativa após falha * **canceled**: Fatura "não faturada", marcada quando a assinatura é pausada ou cancelada (estado final - não será processada) **Estados finais**: Faturas com status `authorized`, `failed` ou `canceled` são estados finais e não podem ser alteradas ou processadas novamente pelo scheduler de cobranças. Faturas `authorized` e `failed` preservam o histórico de auditoria de cobranças já processadas ou falhas finais, enquanto `canceled` preserva o histórico de faturas que não foram faturadas devido a pausa ou cancelamento da assinatura. ### Status do PaymentHistory (cobrança) Cada cobrança registrada no `paymentHistory` de uma fatura possui um status que indica o resultado da tentativa individual: * **pending**: Status inicial quando uma cobrança é criada * **authorized**: Cobrança bem-sucedida, atualizada quando o pagamento é autorizado com sucesso * **failed**: Cobrança que falhou, atualizada quando o pagamento não foi autorizado > [!NOTE] > > **Importante**: O `PaymentHistory` representa tentativas individuais de pagamento e possui apenas 3 status possíveis (`pending`, `authorized`, `failed`). ### Ações disponíveis por estado | Estado | Pausar | Retomar | Cancelar | | - | - | - | - | | **created** | ❌ | ❌ | ✅ | | **trialing** | ❌ | ❌ | ✅ | | **active** | ✅ | ❌ | ✅ | | **paused** | ❌ | ✅ | ✅ | | **canceled** | ❌ | ❌ | ❌ | | **unpaid** | ❌ | ❌ | ✅ | | **expired** | ❌ | ❌ | ❌ | ### Transições de estado ```mermaid theme={null} stateDiagram-v2 [*] --> created [*] --> trialing : com trial trialing --> created : trial expirado trialing --> canceled : cancelamento manual created --> active : primeira cobrança aprovada created --> canceled : cancelamento manual created --> FailureDecision : falha após retentativas active --> paused : pausar active --> expired : última fatura completada active --> canceled : cancelamento manual active --> FailureDecision : falha após retentativas paused --> active : retomar paused --> canceled : cancelamento manual FailureDecision --> unpaid : cancelAfterAllRetries = false FailureDecision --> canceled : cancelAfterAllRetries = true unpaid --> active : cobrança aprovada unpaid --> canceled : cancelamento manual expired --> [*] canceled --> [*] state FailureDecision { [*] --> [*] : Decisão baseada em configuração } ``` ### Lógica de falha após retentativas O estado `FailureDecision` representa o ponto de decisão quando todas as tentativas de cobrança falharam: * **`cancelAfterAllRetries = false`** (padrão): A assinatura vai para status `unpaid` e continuará tentando cobrar nas próximas faturas * **`cancelAfterAllRetries = true`**: A assinatura é automaticamente cancelada e não processará mais cobranças Esta configuração é definida no [Client Settings](/documentations/more/recurrence/engine/client-settings) e se aplica a todas as assinaturas do cliente. ## Operações de gerenciamento > [card] [Atualizar uma assinatura](/api-reference/subscriptions/atualizar-assinatura/) > > Atualize uma assinatura recorrente com os métodos de pagamento disponíveis na Malga. > > Ao alterar `cycles`, o novo valor precisa ser **maior** do que a quantidade de faturas já executadas. O intervalo (`interval`) e o `referenceKey` não podem ser alterados. Se você enviar esses campos, a Malga os ignora. > [card] [Pausar uma assinatura](/api-reference/subscriptions/pausar-assinatura/) > > Pause uma assinatura recorrente. > [card] [Políticas de Retentativa](/documentations/more/recurrence/engine/custom-retry-policies/) > > Configure regras de retentativa personalizadas para suas assinaturas. > [card] [Configurar Webhooks](/documentations/more/recurrence/engine/webhooks/) > > Configure notificações em tempo real sobre mudanças de status. > [card] [Retomar Assinatura](/api-reference/subscriptions/reativar-assinatura/) > > Retomar uma assinatura recorrente. > [card] [Cancelar Assinatura](/api-reference/subscriptions/cancelar-assinatura/) > > Cancelar uma assinatura recorrente. > [card] [Cancelamento Agendado](/documentations/more/recurrence/engine/scheduled-cancellation) > > Agende o cancelamento da assinatura para o final do período atual, garantindo que o cliente tenha acesso completo até o fim do período já pago. > [!NOTE] > > **Pausar** e **cancelar** não interrompem uma fatura **já iniciada**, somente faturas **futuras** são afetadas. > > Ao pausar ou cancelar uma assinatura, faturas pendentes (scheduled, pending, retrying) são marcadas como `canceled` (não faturado) para preservar o histórico de auditoria. Faturas já finalizadas (authorized, failed) não são alteradas. # Cancelamento Agendado Source: https://docs.malga.io/documentations/more/recurrence/engine/scheduled-cancellation Agende o cancelamento de assinaturas para o final do período atual com cancelAtPeriodEnd, preservando o acesso do cliente até a data efetiva. # Resumo O Sistema de Cancelamento Agendado permite que você agende o cancelamento de uma assinatura para ocorrer ao final do período atual, garantindo que o cliente tenha acesso completo até o fim do período já pago. Diferente do cancelamento imediato, o cancelamento agendado preserva o acesso do cliente até a data efetiva de cancelamento. **Como usar?** Atualize a assinatura com `cancelAtPeriodEnd: true`: ```json theme={null} { "cancelAtPeriodEnd": true, "scheduledCancellationAt": "2025-12-31", // Opcional (YYYY-MM-DD) "scheduledCancellationReason": "Cliente solicitou cancelamento" // Opcional } ``` # Visão geral O cancelamento agendado é uma funcionalidade que permite marcar uma assinatura para ser cancelada automaticamente em uma data futura, sem interromper o acesso imediato do cliente. Isso é especialmente útil para: * Manter a satisfação do cliente ao permitir que ele use o serviço até o fim do período pago * Reduzir solicitações de reembolso * Melhorar a experiência do usuário ao oferecer flexibilidade no cancelamento ## Conceitos principais ### Cancelamento agendado O cancelamento agendado é ativado através dos campos `cancelAtPeriodEnd`, `scheduledCancellationAt` e `scheduledCancellationReason` no objeto de assinatura: * **`cancelAtPeriodEnd`** (boolean): Indica se a assinatura está agendada para cancelamento ao final do período atual * **`scheduledCancellationAt`** (date, opcional): Data específica agendada para o cancelamento (formato YYYY-MM-DD) * **`scheduledCancellationReason`** (string, opcional): Motivo do cancelamento agendado. Este campo permite armazenar uma descrição textual do motivo pelo qual o cancelamento foi agendado (ex.: "Cliente solicitou cancelamento", "Mudança de plano", etc.). É útil para auditoria e análise de cancelamentos. Quando `cancelAtPeriodEnd` é definido como `true`, a assinatura continuará ativa até a data efetiva de cancelamento, que é calculada com base em uma priorização de datas. ### Cálculo da data de cancelamento A data efetiva de cancelamento é determinada pela seguinte ordem de prioridade: 1. **`scheduledCancellationAt`** (se fornecido) 2. **`trial.endDate`** (se a assinatura estiver em trial) 3. **`nextDueDate`** (próxima data de vencimento) ```mermaid theme={null} flowchart TD A[Cancelamento Agendado Ativado] --> B{scheduledCancellationAt definido?} B -->|Sim| C[Usar scheduledCancellationAt] B -->|Não| D{Assinatura em trial?} D -->|Sim| E[Usar trial.endDate] D -->|Não| F[Usar nextDueDate] C --> G[Data Efetiva de Cancelamento] E --> G F --> G ``` ### Estados da Subscription com cancelamento agendado Quando uma assinatura tem cancelamento agendado, ela mantém seu status atual (`active`, `trialing`, etc.) até a data efetiva de cancelamento. Nesse momento, o scheduler processa o cancelamento e a assinatura muda para status `canceled`. ```mermaid theme={null} stateDiagram-v2 [*] --> active : Assinatura criada active --> active : cancelAtPeriodEnd = true active --> canceled : Data efetiva chegou (scheduler) trialing --> trialing : cancelAtPeriodEnd = true trialing --> canceled : Data efetiva chegou (scheduler) ``` ## Cenários de uso ### Cenário 1: Cancelamento ao final do período atual O caso mais comum é agendar o cancelamento para o final do período atual, sem especificar uma data: ```json theme={null} { "cancelAtPeriodEnd": true, "scheduledCancellationReason": "Mudança de plano" // Opcional } ``` Neste caso, a data efetiva será calculada automaticamente usando a priorização de datas (`trial.endDate` ou `nextDueDate`). ### Cenário 2: Cancelamento em data específica Para cancelar em uma data específica, forneça `scheduledCancellationAt`: ```json theme={null} { "cancelAtPeriodEnd": true, "scheduledCancellationAt": "2025-12-31", "scheduledCancellationReason": "Teste concluído" // Opcional } ``` A data fornecida terá prioridade sobre `trial.endDate` e `nextDueDate`. ### Cenário 3: Remover agendamento Para remover um cancelamento agendado e manter a assinatura ativa: ```json theme={null} { "cancelAtPeriodEnd": false } ``` Quando o agendamento é removido, os campos `scheduledCancellationAt` e `scheduledCancellationReason` são limpos e as faturas da assinatura são restauradas ao valor original. ## Regras de negócio ### Elegibilidade para cancelamento agendado Uma assinatura pode ter cancelamento agendado quando: * Status é `active`, `paused`, `trialing`, `created` ou `unpaid` * A assinatura não está já cancelada (`canceled`) ou expirada (`expired`) * A data de cancelamento (se especificada) não é anterior a **ontem** em relação à data atual em UTC (comparação por calendário) ### Validações implementadas * **`scheduledCancellationAt` (data mínima)**: Se fornecido, não pode ser anterior a **ontem** em relação à data atual em UTC (comparação por calendário **YYYY-MM-DD**). Datas mais antigas são rejeitadas com HTTP 400. É a mesma janela da validação de `recurrence.startAt` em [Cobrança instantânea](/documentations/more/recurrence/engine/instant-payment#atualização-de-startat-scheduler-e-validações). * **`cancelAtPeriodEnd` obrigatório com `scheduledCancellationAt`**: Se `scheduledCancellationAt` for fornecido, `cancelAtPeriodEnd` deve ser `true` * **Status elegível**: A assinatura deve estar em um status que permita cancelamento agendado ### Priorização de datas A priorização `scheduledCancellationAt > trial.endDate > nextDueDate` garante comportamento previsível: * **Assinatura em trial com data específica**: Se `scheduledCancellationAt` for anterior a `trial.endDate`, o cancelamento ocorrerá na data especificada (antes do fim do trial) * **Assinatura sem trial**: Se não houver `trial.endDate`, usa `nextDueDate` * **Data específica após próxima fatura**: Se `scheduledCancellationAt` for após `nextDueDate`, o cancelamento ocorrerá na data especificada (pode incluir mais uma fatura) ## Processamento automático O sistema processa automaticamente cancelamentos agendados diariamente. Quando a data efetiva de cancelamento chega, a assinatura é cancelada automaticamente e você receberá um webhook `subscription.canceled` notificando o cancelamento. > [!NOTE] > > O processamento automático já está configurado e ativo em ambientes gerenciados pela Malga. Você pode monitorar os cancelamentos através dos webhooks `subscription.canceled` que são disparados quando cancelamentos agendados são efetivados. ## Webhooks e eventos ### Evento: subscription.cancelation\_scheduled Disparado quando um cancelamento agendado é criado ou quando a data de cancelamento é atualizada. Veja a documentação completa em [Webhooks de Subscription](/documentations/more/recurrence/engine/webhooks#evento-subscription-cancelation_scheduled). ### Evento: subscription.cancelation\_scheduled\_removed Disparado quando um agendamento de cancelamento é removido (quando `cancelAtPeriodEnd` é definido como `false`). Veja a documentação completa em [Webhooks de Subscription](/documentations/more/recurrence/engine/webhooks#evento-subscription-cancelation_scheduled_removed). ### Evento: subscription.canceled Disparado quando uma assinatura é cancelada, seja manualmente ou automaticamente pelo scheduler. Quando o cancelamento vem de um agendamento, o campo `cancelAtPeriodEnd` estará presente e definido como `true` no payload. Veja a documentação completa em [Webhooks de Subscription](/documentations/more/recurrence/engine/webhooks#evento-subscription-canceled). ## Casos especiais ### Assinatura vitalícia Para assinaturas vitalícias (sem limite de faturas), o cancelamento agendado funciona normalmente: * O cancelamento ocorrerá na data efetiva calculada * Após cancelamento, a assinatura não gerará mais faturas ### Assinatura com número limitado de faturas Para assinaturas com número limitado de faturas: * O campo `cycles` pode ser ajustado para refletir o número de faturas restantes até o cancelamento * Ao remover o agendamento (`cancelAtPeriodEnd: false`), o valor de `cycles` é restaurado ### Assinatura em Trial Assinaturas em trial podem ter cancelamento agendado: * Se `scheduledCancellationAt` não for fornecido, usa `trial.endDate` como data efetiva * Se `scheduledCancellationAt` for fornecido, tem prioridade sobre `trial.endDate` * O cancelamento pode ocorrer antes ou depois do fim do trial, dependendo da data especificada ### Assinatura Unpaid com Retries Assinaturas com status `unpaid` podem ter cancelamento agendado: * O cancelamento ocorrerá na data efetiva, mesmo que a assinatura esteja inadimplente * Se a assinatura for paga antes da data de cancelamento, o agendamento permanece ativo * Para remover o agendamento após pagamento, defina `cancelAtPeriodEnd: false` ### Comportamento por status | Status | Pode Agendar Cancelamento | Comportamento | | - | - | - | | `active` | ✅ Sim | Cancelamento ocorre na data efetiva | | `trialing` | ✅ Sim | Usa `trial.endDate` se `scheduledCancellationAt` não fornecido | | `created` | ✅ Sim | Cancelamento ocorre antes da primeira cobrança | | `unpaid` | ✅ Sim | Cancelamento ocorre na data efetiva | | `paused` | ✅ Sim | Cancelamento ocorre na data efetiva | | `canceled` | ❌ Não | Assinatura já cancelada | | `expired` | ❌ Não | Assinatura já expirada | ### Faturas pendentes Quando uma assinatura tem cancelamento agendado e ainda possui faturas pendentes: * Faturas já agendadas (`scheduled`, `pending`, `retrying`) continuam sendo processadas normalmente * Faturas futuras após a data de cancelamento não serão geradas * A última fatura processada antes da data de cancelamento será a última fatura da assinatura ## Integração com outros sistemas ### Geração de faturas O sistema de geração de faturas respeita o cancelamento agendado: * Faturas são geradas normalmente até a data efetiva de cancelamento * Após a data efetiva, nenhuma nova fatura é gerada * Faturas pendentes na data de cancelamento são marcadas como `canceled` ### Processamento de pagamentos Pagamentos continuam sendo processados normalmente até a data de cancelamento: * Cobranças agendadas antes da data de cancelamento são processadas * Cobranças agendadas após a data de cancelamento não são criadas * Se uma cobrança falhar antes da data de cancelamento, as retentativas continuam normalmente ### Documentação relacionada * [Gerenciando suas assinaturas](/documentations/more/recurrence/engine/managing) - Operações gerais de gerenciamento * [Webhooks de Subscription](/documentations/more/recurrence/engine/webhooks) - Eventos e notificações * [Atualizar Assinatura](/api-reference/subscriptions/atualizar-assinatura) - Referência de API para atualização * [Cancelar Assinatura](/api-reference/subscriptions/cancelar-assinatura) - Referência de API para cancelamento imediato ## Dicas importantes * **Use cancelamento agendado para melhorar a experiência do cliente**: Permite que o cliente use o serviço até o fim do período pago * **Monitore através de webhooks**: Configure webhooks para receber notificações sobre agendamentos e cancelamentos * **Verifique a data efetiva**: Use a priorização de datas para entender quando o cancelamento ocorrerá * **Remova agendamentos quando necessário**: Se o cliente mudar de ideia, defina `cancelAtPeriodEnd: false` para remover o agendamento # Trial Source: https://docs.malga.io/documentations/more/recurrence/engine/trial-system Ofereça período de trial gratuito em assinaturas da Malga antes da primeira cobrança, configurando data de início, duração e cobrança automática. O motor de assinaturas da Malga oferece suporte completo a períodos de trial (teste gratuito), permitindo que você ofereça aos seus clientes um período experimental antes da primeira cobrança. ## Como funciona o Trial ### Configuração do Trial O trial é configurado na criação da assinatura através do objeto `trial`: ```json theme={null} { "name": "Assinatura Premium", "trial": { "endDate": "2025-02-15" }, "recurrence": { "interval": "monthly" }, // ... outros campos } ``` ### Características do sistema de Trial * **Opcional**: O trial pode ou não ser configurado na criação da assinatura * **Flexível**: Pode ter qualquer duração (dias, semanas, meses) * **Imutável**: Uma vez criado, o trial não pode ser editado * **Automático**: A transição para cobrança acontece automaticamente ### Comportamento do Trial #### Durante o período de Trial * Status da assinatura: `trialing` * **Nenhuma cobrança é realizada** * A assinatura permanece ativa para o cliente * Webhooks específicos são enviados #### Transição automática Quando o trial expira: 1. Status muda de `trialing` para `created` 2. Sistema agenda a primeira cobrança 3. Webhook `subscription.created` é enviado 4. Próxima fatura é gerada automaticamente ## Fluxo de Trial ```mermaid theme={null} flowchart TD A[Criar Assinatura com Trial] --> B{Trial definido?} B -->|SIM| C[Status: trialing] B -->|NÃO| D[Status: created] C --> E[Trial ativo - sem cobrança] E --> F{Trial expirou?} F -->|NÃO| E F -->|SIM| G[Status: created] G --> H[Gerar primeira fatura] H --> I[Processar primeira cobrança] I --> J{Cobrança aprovada?} J -->|SIM| K[Status: active] J -->|NÃO| L[Iniciar retentativas] ``` ## Exemplos de uso ### Criando uma assinatura com trial de 7 dias ```bash Request theme={null} curl --location 'https://api.malga.io/v1/subscriptions' \ --header 'Content-Type: application/json' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --data '{ "name": "Plano Premium - Trial 7 dias", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "trial": { "endDate": "2025-02-07" }, "recurrence": { "interval": "monthly" }, "paymentMethod": { "type": "credit", "card": { "cardId": "YOUR_CARD_ID" } }, "items": [ { "name": "Plano Premium", "amount": 2990, "quantity": 1 } ] }' ``` ## Webhooks do sistema de Trial ### Eventos específicos do trial | Evento | Descrição | | - | - | | `subscription.trial_started` | Enviado quando uma assinatura é criada com trial ativo | | `subscription.created` | Enviado quando o trial expira e a assinatura fica pronta para cobrança | ## Regras importantes ### Validações do Trial * **Data futura obrigatória**: `trial.endDate` deve ser no futuro (mínimo de 1 dia) * **Alinhamento com startAt**: Se `startAt` não for especificado, usa automaticamente `trial.endDate` * **Formato UTC**: O campo `startAt` deve ser informado em formato UTC (YYYY-MM-DD) * **Imutabilidade**: Trial não pode ser editado após a criação da assinatura ### Comportamento especial * **Prioridade de eventos**: Se trial definido, emite apenas `trial_started`, nunca `created` na criação ### Limitações * **Apenas na criação**: Trial só pode ser configurado durante a criação da assinatura * **Não editável**: Impossível modificar ou estender o período de trial * **Sem cobrança parcial**: Durante o trial, nenhuma cobrança é realizada ## Próximos passos > [card] [Gerenciar assinaturas](/documentations/more/recurrence/engine/managing) > > Aprenda como gerenciar assinaturas durante e após o período de trial > [card] [Configurar webhooks](/documentations/more/recurrence/engine/webhooks) > > Configure notificações para eventos de trial # Webhooks Source: https://docs.malga.io/documentations/more/recurrence/engine/webhooks Receba notificações em tempo real via webhooks sobre eventos do motor de assinaturas da Malga, como mudanças de status e novas cobranças. A Malga utiliza o serviço de webhooks para notificar o seu sistema sobre os eventos ocorridos no motor de assinaturas. Através de webhooks, você consegue atualizar seu sistema sempre que um evento importante acontece, como a criação de uma assinatura, mudança de status ou criação de cobranças automáticas. ## Fluxo básico para receber notificações via webhooks * Crie um serviço com um endpoint acessível dentro do seu sistema para receber as requisições de notificação dos eventos de assinatura. * Registre seu endpoint na Malga criando um webhook para receber notificações dos eventos desejados. * A Malga enviará uma requisição HTTP para seu endpoint com os dados do objeto alterado sempre que o determinado evento registrado no seu webhook acontecer. ## Criação de um webhook Realize a criação e gestão de webhooks usando o Serviço de Webhooks. ```bash Request theme={null} curl --location --request POST 'https://api.malga.io/v1/webhooks' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "event": "subscription.created", "endpoint": "https://seu-dominio.com/webhooks/recurrence", "version": 1.1, "status": true }' ``` ```json Response theme={null} { "id": "324d35fe-86da-4a7d-96f4-370b338d9c5e", "clientId": "d353deef-dacb-40a0-8cab-931ff773f274", "event": "subscription.created", "endpoint": "https://seu-dominio.com/webhooks/recurrence", "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAIda0HljovhG1yKez/Du7MUoKup/cbXqPgwyGOATOiJQ=\n-----END PUBLIC KEY-----\n", "version": 1.1, "status": true, "createdAt": "2021-07-06T21:03:36.590Z", "updatedAt": "2021-07-06T21:03:36.590Z" } ``` ## Evento de notificação enviado Quando um determinado evento ocorre no motor de assinaturas, a Malga cria um objeto do tipo `event` que é enviado através de uma requisição HTTP para o seu endpoint cadastrado. O evento é imutável dentro da estrutura de notificações da Malga, isso significa que os dados do objeto que sofreu alteração são gravados junto com o evento, representando o estado do objeto imediatamente após o evento que o alterou. **Exemplo de requisição de notificação de evento de uma assinatura enviada pela Malga para seu endpoint:** ```http theme={null} > POST HTTP/2 > Host: > User-Agent: axios/0.21.1 > Accept: application/json, text/plain, */* > Content-Type: application/json > X-Idempotency-Key: e46427e1-2516-49c1-bc7e-83a007fe1e83 > X-Plug-Date: 1660053072711 > X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75 > HTTP/2 { "id": "48fc6408-76e4-4b18-8767-cb1ae4409773", "apiVersion": "1.1", "object": "subscription", "event": "created", "data": { "subscription": { "id": "48fc6408-76e4-4b18-8767-cb1ae4409773", "name": "Test Subscription for Events", "clientId": "e6bcef06-e20e-4bf3-821f-8869b6fac5bc", "merchantId": "77dab296-f193-4bec-8574-53036246cbd0", "customerId": "f85f506f-480a-4a02-94ea-2d0e0faee9a1", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "e1e3dc1d-c9d3-4f93-a374-c018e81a8e0a" } }, "status": "created", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.348495Z", "updatedAt": "2025-10-30T17:35:04.348495Z" } }, "createdAt": "2025-10-30T17:36:16.718Z" } ``` ## Eventos suportados para notificação via webhooks | Evento | Descrição | | - | - | | **subscription.created** | Evento enviado quando uma nova assinatura é criada (exceto quando trial ativo) | | **subscription.trial\_started** | Evento enviado quando uma assinatura é criada com período de trial ativo | | **subscription.activated** | Evento enviado quando uma assinatura tem sua primeira cobrança aprovada | | **subscription.updated** | Evento enviado quando uma assinatura é atualizada (mudança de valor, produtos, etc.) | | **subscription.paused** | Evento enviado quando uma assinatura é pausada | | **subscription.resumed** | Evento enviado quando uma assinatura pausada é retomada | | **subscription.unpaid** | Evento enviado quando uma assinatura fica em situação de não paga | | **subscription.expired** | Evento enviado quando uma assinatura expira | | **subscription.canceled** | Evento enviado quando uma assinatura é cancelada manualmente ou automaticamente pelo scheduler de cancelamentos agendados | | **subscription.cancelation\_scheduled** | Evento enviado quando um cancelamento é agendado ou a data de agendamento é atualizada | | **subscription.cancelation\_scheduled\_removed** | Evento enviado quando um agendamento de cancelamento é removido | | **subscription.cycle\_failed** | Evento enviado quando uma fatura de cobrança falhar devido a inconsistência de dados | ## Exemplos de payloads ### Estrutura padrão do payload Todos os eventos de assinatura seguem a mesma estrutura base. A diferença está no campo `event` e nos dados específicos dentro de `data`. ```json theme={null} { "id": "e46427e1-2516-49c1-bc7e-83a007fe1e83", "apiVersion": "1.1", "object": "subscription", "event": "created", "createdAt": "2021-07-05T18:56:08.672Z", "data": { "subscription": { "id": "5e940dc9-e3a8-4422-bfe3-a6f8d8ed7da1", "name": "Assinatura Premium com Eventos", "status": "created", "amount": 29900, "currency": "BRL", "createdAt": "2025-07-30T20:14:12.191866Z", "updatedAt": "2025-07-30T20:14:12.191866Z" } } } ``` ### Evento subscription.trial\_started O evento `subscription.trial_started` inclui informações sobre a assinatura que iniciou o processo de trial: ```json theme={null} { "id": "f2498351-6aa1-4036-a613-9de93054a19f", "apiVersion": "1.1", "object": "subscription", "event": "trial_started", "data": { "subscription": { "id": "f2498351-6aa1-4036-a613-9de93054a19f", "name": "Test Subscription for Events", "clientId": "733719fb-f824-42c9-87c9-5c72e4533dfa", "merchantId": "3c92b69e-e1bd-47a6-b512-987da33b1e84", "customerId": "f740e798-98a8-47a7-b13d-306161b61cdf", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-11-30" }, "trial": { "endDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "39eda4b4-0f3c-4475-aeff-6c5e9cbcbb5a" } }, "status": "trialing", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349047Z", "updatedAt": "2025-10-30T17:35:04.349047Z" } }, "createdAt": "2025-10-30T17:38:07.132Z" } ``` ### Evento subscription.activated O evento `subscription.activated` inclui informações adicionais sobre a primeira fatura que foi processada com sucesso e vai para o status active: ```json theme={null} { "id": "cd954803-e930-4fbe-bd3f-86f71cd94903", "apiVersion": "1.1", "object": "subscription", "event": "activated", "data": { "subscription": { "id": "cd954803-e930-4fbe-bd3f-86f71cd94903", "name": "Assinatura Premium com Eventos", "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "merchantId": "90d64a51-d442-426c-bbf9-b66e000e5576", "customerId": "b99e159e-27d5-4927-b46e-ae7348f20131", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Ingresso VIP Mensal", "description": "Acesso VIP premium a eventos mensais", "amount": 29900, "quantity": 1, "sku": "VIP-EVENT-001", "risk": "Low", "categoryId": "entertainment", "locality": "São Paulo", "date": "2025-12-01", "type": 1, "genre": "Shows e Eventos", "tickets": { "quantityTicketSale": 1, "convenienceFeeValue": 15.5, "quantityFull": 1, "batch": 1 }, "location": { "street": "Av. Paulista", "number": "1000", "complement": "Centro de Convenções", "zipCode": "01310-100", "city": "São Paulo", "state": "SP", "country": "Brasil", "district": "Bela Vista", "reference": "Próximo ao MASP" } } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "bfb60d16-108c-440b-bdb8-bbe67140f936" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T13:11:34.882942Z", "updatedAt": "2025-10-30T13:11:35.921247966Z" }, "cycle": { "id": "a53e6b56-00a1-49a2-be06-9761556d22d4", "customerId": "b99e159e-27d5-4927-b46e-ae7348f20131", "merchantId": "90d64a51-d442-426c-bbf9-b66e000e5576", "cycle": 1, "status": "authorized", "amount": 29900, "scheduledAt": "2025-10-30", "paymentHistory": [ { "id": "2221df8f-5ac5-44b5-a48b-3be7d93081be", "createdAt": "2025-10-30T13:11:34.917233965Z", "executedAt": "2025-10-30T13:11:34.905674924Z", "chargeId": "6e7c4504-a689-4da6-bc19-e5f814de27af", "attemptNumber": 1, "paymentMethod": { "type": "credit", "card": { "cardId": "bfb60d16-108c-440b-bdb8-bbe67140f936" }, "installments": 1 }, "error": null } ], "createdAt": "2025-10-30T13:11:34.906418Z" } }, "createdAt": "2025-10-30T14:38:59.398Z" } ``` ### Evento subscription.unpaid O evento `subscription.unpaid` inclui informações adicionais com o histórico de cobranças da fatura que falhou na última tentativa e atualizou a assinatura para unpaid: ```json theme={null} { "id": "1853aada-231c-4e37-a785-b9329a2c4269", "apiVersion": "1.1", "object": "subscription", "event": "unpaid", "data": { "subscription": { "id": "1853aada-231c-4e37-a785-b9329a2c4269", "name": "Premium Subscription", "clientId": "fbaf6bbe-ae00-4128-bb76-8e55f6a93e09", "merchantId": "2056f5ec-c583-40d8-8528-bf0ef2239606", "customerId": "22f9ef95-f356-4a85-94f5-7de095d4e71a", "referenceKey": "premium-sub-ref", "currency": "BRL", "items": [ { "name": "Premium Plan", "description": "Monthly subscription plan", "amount": 29900, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "c8f5a505-7a9f-4f81-a4dc-5f60bb9206ce" }, "installments": 1 }, "status": "unpaid", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T18:05:30.401145Z", "updatedAt": "2025-10-30T18:05:30.401145Z" }, "cycle": { "id": "41c986fe-ea02-4da5-a028-031d0bc973b9", "customerId": "22f9ef95-f356-4a85-94f5-7de095d4e71a", "merchantId": "2056f5ec-c583-40d8-8528-bf0ef2239606", "cycle": 1, "status": "failed", "amount": 29900, "scheduledAt": "2025-10-31", "paymentHistory": [ { "id": "6d149bf5-9536-4e7b-9a1e-5b7e966e8fd9", "createdAt": "2025-10-30T18:05:30.401145Z", "executedAt": "2025-10-31T19:05:30.401145Z", "chargeId": null, "attemptNumber": 5, "paymentMethod": { "type": "credit", "card": { "cardId": "c8f5a505-7a9f-4f81-a4dc-5f60bb9206ce" }, "installments": 1 }, "error": { "message": "All retry attempts exhausted" } } ], "createdAt": "2025-10-30T18:05:30.401145Z" } }, "createdAt": "2025-10-30T18:07:00.288Z" } ``` ### Evento subscription.expired O evento `subscription.expired` avisa que a última fatura referente àquela assinatura já foi paga e ela foi para o status expired: ```json theme={null} { "id": "e3850022-0900-4092-a45a-c92dcf36fffb", "apiVersion": "1.1", "object": "subscription", "event": "expired", "data": { "subscription": { "id": "e3850022-0900-4092-a45a-c92dcf36fffb", "name": "Premium Subscription", "clientId": "2848e31a-da1c-4c6c-8d07-2291ce52754b", "merchantId": "4387d5de-fb37-47f0-9645-f55217fa7b92", "customerId": "19dc5a59-e257-4494-9724-0d20bbd38750", "referenceKey": "premium-sub-ref", "currency": "BRL", "items": [ { "name": "Premium Plan", "description": "Monthly subscription plan", "amount": 29900, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "d946096b-d5b8-429a-b7d4-ad637beae70e" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349231Z", "updatedAt": "2025-10-30T17:35:04.349231Z" }, "cycle": { "id": "7919335e-66b3-428e-85ae-871f89d31d3a", "customerId": "19dc5a59-e257-4494-9724-0d20bbd38750", "merchantId": "4387d5de-fb37-47f0-9645-f55217fa7b92", "cycle": 1, "status": "authorized", "amount": 29900, "scheduledAt": "2025-10-31", "paymentHistory": [ { "id": "9d5923d5-defb-4caa-854c-0ca4d1a856bd", "createdAt": "2025-10-30T17:35:04.349231Z", "executedAt": "2025-10-31T18:35:04.349231Z", "chargeId": "2c806ff5-fcbe-461f-9e3e-ab7b88ac131b", "attemptNumber": 1, "paymentMethod": { "type": "credit", "card": { "cardId": "d946096b-d5b8-429a-b7d4-ad637beae70e" }, "installments": 1 }, "error": null } ], "createdAt": "2025-10-30T17:35:04.349231Z" } }, "createdAt": "2025-10-30T17:39:54.264Z" } ``` ### Evento subscription.canceled O evento `subscription.canceled` é recebido quando uma assinatura é cancelada. Isso pode ocorrer de duas formas: 1. **Cancelamento manual**: Via endpoint de cancelamento ou atualização da assinatura 2. **Cancelamento agendado efetivado**: Quando o scheduler processa um cancelamento agendado e a data efetiva chega Quando o cancelamento vem de um agendamento, os campos `cancelAtPeriodEnd` e `scheduledCancellationReason` estarão presentes no payload (se `scheduledCancellationReason` foi fornecido durante o agendamento). **Exemplo de cancelamento manual:** ```json theme={null} { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "apiVersion": "1.1", "object": "subscription", "event": "canceled", "data": { "subscription": { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "name": "Test Subscription for Events", "clientId": "f2b8c4f0-2577-4dba-af2c-73b886493131", "merchantId": "17f9bdd6-cce8-4bc7-b77f-8a905ab0633f", "customerId": "b3e612c0-8763-4cb4-8295-5e6ea925cd3b", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "ca7dfd90-5cfc-4332-8644-c66046095c2b" } }, "status": "canceled", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349287Z", "updatedAt": "2025-10-30T17:35:04.349287Z" } }, "createdAt": "2025-10-30T17:40:50.786Z" } ``` **Exemplo de cancelamento agendado efetivado:** ```json theme={null} { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "apiVersion": "1.1", "object": "subscription", "event": "canceled", "data": { "subscription": { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "name": "Test Subscription for Events", "clientId": "f2b8c4f0-2577-4dba-af2c-73b886493131", "merchantId": "17f9bdd6-cce8-4bc7-b77f-8a905ab0633f", "customerId": "b3e612c0-8763-4cb4-8295-5e6ea925cd3b", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "ca7dfd90-5cfc-4332-8644-c66046095c2b" } }, "cancelAtPeriodEnd": true, "scheduledCancellationReason": "Mudança de plano", "status": "canceled", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349287Z", "updatedAt": "2025-10-30T17:40:50.786Z" } }, "createdAt": "2025-10-30T17:40:50.786Z" } ``` ### Evento subscription.cancelation\_scheduled O evento `subscription.cancelation_scheduled` é enviado quando: * Um cancelamento agendado é criado pela primeira vez * A data de cancelamento agendado (`scheduledCancellationAt`) é atualizada ```json theme={null} { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "apiVersion": "1.1", "object": "subscription", "event": "cancelation_scheduled", "data": { "subscription": { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "name": "Test Subscription for Events", "clientId": "f2b8c4f0-2577-4dba-af2c-73b886493131", "merchantId": "17f9bdd6-cce8-4bc7-b77f-8a905ab0633f", "customerId": "b3e612c0-8763-4cb4-8295-5e6ea925cd3b", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "ca7dfd90-5cfc-4332-8644-c66046095c2b" } }, "cancelAtPeriodEnd": true, "scheduledCancellationAt": "2025-12-31", "scheduledCancellationReason": "Teste concluído", "status": "active", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349287Z", "updatedAt": "2025-10-30T17:40:45.123456Z" } }, "createdAt": "2025-10-30T17:40:50.786Z" } ``` ### Evento subscription.cancelation\_scheduled\_removed O evento `subscription.cancelation_scheduled_removed` é enviado quando o agendamento de cancelamento é removido (por exemplo, quando `cancelAtPeriodEnd` é definido como `false`). ```json theme={null} { "id": "edb438e1-78ad-40d0-8035-dbbc6d7cf020", "apiVersion": "1.1", "object": "subscription", "event": "cancelation_scheduled_removed", "data": { "subscription": { "id": "3f7a8e8f-59c1-48f5-8d8f-ac564ea9154d", "name": "Test Subscription for Events", "clientId": "f2b8c4f0-2577-4dba-af2c-73b886493131", "merchantId": "17f9bdd6-cce8-4bc7-b77f-8a905ab0633f", "customerId": "b3e612c0-8763-4cb4-8295-5e6ea925cd3b", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "ca7dfd90-5cfc-4332-8644-c66046095c2b" } }, "cancelAtPeriodEnd": false, "status": "active", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349287Z", "updatedAt": "2025-10-30T17:45:30.654321Z" } }, "createdAt": "2025-10-30T17:45:35.123Z" } ``` > [!NOTE] > > Note que quando o agendamento é removido, os campos `scheduledCancellationAt` e `scheduledCancellationReason` não aparecem no payload (são removidos do objeto subscription). ### Evento subscription.paused O evento `subscription.paused` é recebido ao pausar uma assinatura: ```json theme={null} { "id": "9b9dd4c0-bbab-42de-829f-29586edfc6f8", "apiVersion": "1.1", "object": "subscription", "event": "paused", "data": { "subscription": { "id": "9b9dd4c0-bbab-42de-829f-29586edfc6f8", "name": "Test Subscription for Events", "clientId": "5d82ffae-a8fb-461d-80d1-c5e36c19f43d", "merchantId": "2d989993-7cf0-4a42-a1a9-e2cfb25fcaf7", "customerId": "0dc843a6-65a2-419a-96d0-f234fc174468", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "17aa54c0-fd75-4bbb-b077-2b37e9475e7c" } }, "status": "paused", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349722Z", "updatedAt": "2025-10-30T17:35:04.349722Z" } }, "createdAt": "2025-10-30T17:42:19.017Z" } ``` ### Evento subscription.resumed O evento `subscription.resumed` é recebido ao retomar uma assinatura que estava pausada: ```json theme={null} { "id": "2efffaff-ea42-4c3d-970f-93271e0c8901", "apiVersion": "1.1", "object": "subscription", "event": "resumed", "data": { "subscription": { "id": "2efffaff-ea42-4c3d-970f-93271e0c8901", "name": "Test Subscription for Events", "clientId": "83dc63f9-dc4b-463e-baf2-d03cbf3a887c", "merchantId": "a9a7c036-41cb-44c9-ad06-4b88cc921993", "customerId": "3eb4b8bd-385a-408e-a190-57b998d7dccd", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "00934211-95bf-4098-90ba-bc4e737e8c8e" } }, "status": "created", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349908Z", "updatedAt": "2025-10-30T17:35:04.349908Z" } }, "createdAt": "2025-10-30T17:43:36.043Z" } ``` ### Evento subscription.updated O evento `subscription.updated` é recebido ao atualizar dados de uma assinatura: ```json theme={null} { "id": "e5394ee5-fb6b-4ced-bb6f-50535708ed44", "apiVersion": "1.1", "object": "subscription", "event": "updated", "data": { "subscription": { "id": "e5394ee5-fb6b-4ced-bb6f-50535708ed44", "name": "Test Subscription for Events", "clientId": "c60c6c0a-2eb2-4aff-9a1d-74ee16f3051d", "merchantId": "d1cdcc52-cd3b-43b4-a65b-f9d143a2abf3", "customerId": "38cb207e-9e79-451d-87db-85497f2564b2", "referenceKey": "test-event-ref", "currency": "BRL", "items": [ { "name": "Test Product", "description": "Test Description", "amount": 2500, "quantity": 1 } ], "recurrence": { "interval": "monthly", "startAt": "2025-10-30", "nextDueDate": "2025-11-30" }, "paymentMethod": { "type": "credit", "card": { "cardId": "12313a40-8ddb-45e1-835c-e9832694ef3b" } }, "status": "created", "amount": 2500, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349987Z", "updatedAt": "2025-10-30T17:35:04.349987Z" } }, "createdAt": "2025-10-30T17:44:48.148Z" } ``` ### Evento subscription.cycle\_failed Este evento é enviado quando o processamento de uma nova fatura de cobrança falha devido a alguma inconsistência nos dados da assinatura. Um exemplo comum é quando o merchant vinculado à assinatura foi desativado.\ Nesses casos, `nenhuma transação é criada.` ```json theme={null} { "id": "webhook_event_id_example", "apiVersion": "1.1", "object": "subscription", "event": "cycle_failed", "data": { "subscription": { "id": "subscription_id_example", "name": "Assinatura Mensal Premium", "clientId": "YOUR_CLIENT_ID", "merchantId": "YOUR_MERCHANT_ID", "customerId": "YOUR_CUSTOMER_ID", "referenceKey": "SUB-PREMIUM-001", "currency": "BRL", "items": [ { "name": "Plano Premium", "description": "Acesso completo à plataforma com todos os recursos", "amount": 9990, "quantity": 1, "sku": "PREMIUM-MONTHLY", "risk": "low", "categoryId": "CAT-DIGITAL-SERVICES", "locality": "São Paulo - SP", "date": "2024-01-15", "type": "service", "genre": "subscription" } ], "recurrence": { "interval": "monthly", "cycles": null, "startAt": "2024-01-15", "endAt": null, "nextDueDate": "2024-04-15" }, "paymentMethod": { "type": "credit", "installments": 1, "card": { "cardId": "c8758346-34e9-4224-a0e6-2cb8917046ff" } }, "status": "active", "amount": 9990, "trial": null, "liveMode": true, "createdAt": "2024-01-15T08:00:00Z", "updatedAt": "2024-03-15T10:30:00Z", "lastCycle": { "id": "cycle_id_example", "customerId": "YOUR_CUSTOMER_ID", "merchantId": "YOUR_MERCHANT_ID", "cycle": 1, "attempts": 1, "status": "failed", "amount": 9990, "items": [ { "name": "Plano Premium", "description": "Acesso completo à plataforma com todos os recursos", "amount": 9990, "quantity": 1, "sku": "PREMIUM-MONTHLY" } ], "isEmulated": false, "createdAt": "2024-03-10T00:00:00Z", "scheduledAt": "2024-03-15", "executedAt": "2024-03-15", "nextAttemptAt": "" } }, "errorCode": 400 }, "createdAt": "2025-10-09T18:10:49.963Z" } ``` ### Comportamento especial para startAt sendo hoje Quando uma assinatura é criada com `startAt` definido como a data atual, o motor de assinaturas processa a primeira cobrança imediatamente.\ Nesse caso, você deve receber webhooks na ordem abaixo: > [!NOTE] > > **Ordem de eventos quando startAt é hoje**: > > 1. `subscription.created` - Assinatura criada > 2. `subscription.activated` (se sucesso) ou `subscription.cycle_failed` (caso haja alguma inconsistência de dados na assinatura) > 3. `subscription.unpaid` (se todas as tentativas de cobrança da fatura falharem) ## Webhooks de cobrança Quando o motor de assinaturas cria cobranças automaticamente, você também receberá os webhooks de cobrança padrão da Malga. Nestes casos, o `subscriptionId` estará presente no payload da cobrança para identificar a qual assinatura a cobrança pertence. ### Exemplo de webhook de cobrança com subscriptionId ```json theme={null} { "id": "e46427e1-2516-49c1-bc7e-83a007fe1e83", "apiVersion": "1.1", "object": "transaction", "event": "pending", "createdAt": "2021-07-05T18:56:08.672Z", "data": { "id": "chr_123456789", "amount": 29900, "currency": "BRL", "status": "pending", "customerId": "cus_123456789", "subscriptionId": "sub_123456789", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } } ``` Esta documentação fornece uma base sólida para implementar webhooks de assinatura seguindo os padrões da Malga. Lembre-se de adaptar os exemplos para sua stack tecnológica específica e sempre testar em ambiente de desenvolvimento antes de ir para produção. # Introdução Source: https://docs.malga.io/documentations/more/recurrence/intro Configure cobranças recorrentes e assinaturas na Malga via repasse ao provedor ou pelo motor próprio de assinaturas, com mais controle e flexibilidade. A Malga oferece suporte completo a **assinaturas**, permitindo que empresas configurem cobranças automatizadas com eficiência e flexibilidade. Atualmente, existem duas formas principais de implementar recorrência com a Malga, dependendo do nível de controle desejado e da infraestrutura do seu sistema: > [card] [Repasse de informações para o provedor](/documentations/more/recurrence/charges) > > Ideal para quem já possui lógica de agendamento. Essa abordagem utiliza o > parâmetro `recurrence` na criação de uma cobrança, informando ao provedor > que a transação faz parte de uma assinatura ou cobrança recorrente, o que > pode aumentar as chances de aprovação. > [card] [Motor de Assinaturas - Malga](/documentations/more/recurrence/engine) > > Pensado para quem deseja automatizar todo o processo de assinaturas. A Malga > cuida do agendamento, execução e retentativas das cobranças, permitindo um > controle centralizado, com monitoramento via Dashboard e webhooks para > notificações. Explore cada opção para entender qual delas se encaixa melhor no seu modelo de negócio. # Sessões Source: https://docs.malga.io/documentations/more/sessions Crie sessões na Malga para representar pedidos com um ou múltiplos pagamentos via Pix, boleto ou cartão, integrando ao Malga Checkout no front-end. O serviço de **Sessões** permite criar pedidos e links de pagamento processados pela Malga. Ele também pode ser combinado com o Malga Checkout para aumentar a segurança da implementação no front-end, usando uma `publicKey` de escopo restrito por sessão. Existem dois modos principais: * **Sessão 1:1 (legado):** quando `maxPayments` não é enviado na criação, a sessão segue o fluxo de um único pagamento. * **Sessão 1:N:** quando `maxPayments` é enviado na criação, a sessão permite múltiplos pagamentos no mesmo link, com limite finito (`1` a `99999`) ou ilimitado (`-1`). Você pode criar sessões com Pix, boleto, cartão de crédito e demais métodos aceitos pelo endpoint de criação. Para consultar o contrato completo, veja [Criar nova sessão](/api-reference/sessions/criar-nova-sessao). > [!WARNING] > > Pix e boleto **não são aceitos em links 1:N com limite finito maior que 1**. > Ao criar uma sessão com `paymentMethods` contendo `pix` ou `boleto` e > `maxPayments` finito `> 1`, a API responde `422` com `businessCode: > "pix_boleto_multiple_payments_not_allowed"`. Para pix/boleto, use > `maxPayments` omitido, `1` ou `-1` (ilimitado). Cartão de crédito continua > aceito em qualquer valor de `maxPayments` suportado. > > A mesma restrição vale na atualização (`PATCH /v1/sessions/{id}` com > `isActive: true`): elevar `maxPayments` para um valor finito `> 1` em uma > sessão pix ou boleto retorna `422` com `businessCode: > "pix_boleto_multiple_payments_not_allowed"`. A reativação de uma sessão pix ou > boleto 1:1 já paga também é bloqueada com `422` e `businessCode: > "pix_boleto_one_to_one_reactivation_blocked"`. ## Utilizando as sessões Para utilizar o serviço de Sessões, crie uma sessão definindo itens, valor, métodos de pagamento e, quando necessário, `maxPayments`. Depois, use a `publicKey` retornada na criação para chamar o endpoint de pagamento da sessão com uma chave de escopo restrito. > [!NOTE] > > O fluxo conceitual desta seção se aplica a sessões 1:1 e 1:N. Em sessões 1:N, > cada chamada de pagamento aceita representa uma tentativa individual dentro da > capacidade configurada em `maxPayments`. ### Criando uma sessão Realize a criação usando `POST /v1/sessions`. A resposta completa retorna a sessão, a `publicKey` de escopo restrito e, quando aplicável, o objeto `multiplePayments` com a disponibilidade agregada do link. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 100, "name": "Pedido 1", "merchantId": "", "dueDate": "2026-02-20T23:59:59.000Z", "createLink": true, "maxPayments": 5, "paymentMethods": [ { "paymentType": "pix", "expiresIn": 30 } ], "items": [ { "name": "Item", "description": "Item do carrinho", "unitPrice": 1000, "quantity": 1, "tangible": false } ] }' < HTTP/2 200 { "id": "7b978ea2-85d0-42f5-9039-5c56d4ecfa5b", "name": "Pedido 1", "status": "created", "isActive": true, "clientId": "c1a07dfe-b460-45ba-87d1-056f6c6c59e7", "orderId": null, "amount": 100, "currency": "BRL", "capture": true, "merchantId": "", "dueDate": "2026-02-20T23:59:59.000Z", "description": null, "statementDescriptor": null, "items": [ { "name": "Item 1", "description": "Item do carrinho", "unitPrice": 1000, "quantity": 1, "tangible": false } ], "paymentMethods": [ { "paymentType": "pix", "expiresIn": 30 } ], "paymentLink": "https://link.malga.io/7b978ea2-85d0-42f5-9039-5c56d4ecfa5b", "multiplePayments": { "allow": true, "maxPayments": 5, "paymentCount": 0, "pendingCount": 0, "status": "active" }, "createdAt": "2026-02-20T09:28:45.000Z", "updatedAt": "2026-02-20T09:28:45.000Z", "publicKey": "ef047626-7205-4dc9-a317-a20546a8cc83" } ``` Veja todos os campos aceitos em [Criar nova sessão](/api-reference/sessions/criar-nova-sessao). ### Pagando uma sessão Pague uma sessão usando `POST /v1/sessions/{id}/charge`. Use a `publicKey` retornada na criação da sessão no cabeçalho `X-Api-Key`. Em sessões 1:N, a resposta deste endpoint representa a cobrança criada para uma tentativa de pagamento. Para acompanhar a disponibilidade agregada do link após o pagamento, consulte [Recuperar detalhes de uma sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sessions/{id}/charge' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } } }' < HTTP/2 201 { "id": "a1d455eb-dafe-4a5c-b882-a5775422f850", "status": "pending", "clientId": "c1a07dfe-b460-45ba-87d1-056f6c6c59e7", "orderId": "0acc827b-0dbc-4228-a59c-96337535dca1", "customerId": "11edc7cf-1d4e-4e86-8530-361062eebecf", "amount": 100, "originalAmount": 100, "currency": "BRL", "capture": true, "merchantId": "a58fc6a2-c138-4566-9fa4-37871853e334", "statementDescriptor": "LOJA JOAO", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "a1d455eb-dafe-4a5c-b882-a5775422f850" }, "transactionRequests": [ { "id": "2405d3ad-886e-4541-bd2e-8489e6f54dd4", "idempotencyKey": "4ce7b3f5eb66499c96922fae84a8bf9e", "providerId": "3022c70f-650f-4ef6-86e3-3b876df8948a", "providerType": "STRIPE", "transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob", "amount": 100, "authorizationNsu": "83abd7e6-2223-4773-b1ef-aee98be1ee99", "requestStatus": "success", "requestType": "authorization", "responseTs": "2633ms", "createdAt": "2021-08-12T16:08:39.536Z", "updatedAt": "2021-08-12T16:08:42.212Z", "providerAuthorization": { "networkAuthorizationCode": "00", "networkResponseCode": "" } } ], "createdAt": "2022-10-25T22:49:06.588Z" } ``` Veja todos os campos aceitos em [Pagar uma sessão](/api-reference/sessions/pagar-uma-sessao). ## Fluxo 1:N e acompanhamento de status Em sessões 1:N, o status agregado do link não deve ser inferido apenas pela resposta de uma cobrança individual. Acompanhe a sessão completa por `GET /v1/sessions/{id}` e use o histórico apenas como trilha de eventos. | Campo | Como interpretar | | - | - | | `multiplePayments.allow` | Indica se a sessão foi criada como 1:N. | | `multiplePayments.maxPayments` | Indica o limite configurado. `-1` significa ilimitado e `null` indica sessão 1:1. | | `multiplePayments.paymentCount` | Quantidade de pagamentos já autorizados no link. | | `multiplePayments.pendingCount` | Quantidade de pagamentos pendentes de confirmação assíncrona, como Pix em aberto. | | `multiplePayments.status` | Disponibilidade conceitual do link para receber uma próxima cobrança. | > [!NOTE] > > Um pagamento individual não encerra necessariamente uma sessão 1:N. Consulte > [Recuperar detalhes de uma > sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao) para obter o > estado agregado atualizado e [Recuperar o histórico da > sessão](/api-reference/sessions/recuperar-o-historico-da-sessao) para auditar > eventos. ## Histórico da sessão O endpoint `GET /v1/sessions/{id}/history` expõe a **trilha de auditoria** da sessão, com os eventos mais recentes primeiro: criação, alterações de campos, tentativas de pagamento, confirmações assíncronas (Pix e boleto) e expirações por `dueDate` ou limite 1:N. Cada item da resposta traz `action`, `actions` e um objeto `diff` com o detalhe da mudança. O campo `status` em cada linha segue a semântica de produto — expirações automáticas podem aparecer como `disabled`, enquanto cancelamento manual permanece `canceled`. > [!WARNING] > > Não use o histórico como fonte do estado atual do link. Para `multiplePayments` e contadores atualizados, use `GET /v1/sessions/{id}`. Consulte [Recuperar o histórico da sessão](/api-reference/sessions/recuperar-o-historico-da-sessao) para o catálogo completo de ações, exemplos de `diff` e diagrama do fluxo. ## Integrando o MalgaCheckout com sessões Para utilizar o Malga Checkout com o serviço de Sessões de uma maneira mais segura, crie uma sessão pelo seu back-end e use a `publicKey` de escopo restrito na aplicação front-end. Assim, você configura o checkout sem expor a `publicKey` de escopo mais amplo usada normalmente. > [!NOTE] > > O fluxo com Malga Checkout vale para sessões 1:1 e 1:N. Em sessões 1:N, a > mesma sessão pode continuar disponível após uma tentativa aprovada, conforme o > limite configurado em `maxPayments` e o estado retornado em > `multiplePayments`. ### Usando o MalgaCheckout com sessões Depois de criar a sessão, use o `id` dela e a `publicKey` retornada para configurar o Malga Checkout. Para manter a integração segura, recomendamos que o front-end tenha acesso apenas à chave pública da sessão. ```html theme={null} Malga Checkout Components
``` # 3DS2 Agnóstico no Link de Pagamento Source: https://docs.malga.io/documentations/payment-link/3ds2 ## Como funciona o 3DS2? 3DS2 é um protocolo de autenticação de cartões que permite a autenticação de cartões de crédito e débito. O Link de Pagamento, caso configurado, irá solicitar a autenticação do cartão ao banco emissor através do 3DS2. Com ou sem o desafio, a responsabilidade de chargebacks é transferida para o banco emissor. > [!NOTE] > > A transferência de responsabilidade para o banco emissor **não** é feita em casos de desacordo comercial. Saiba mais sobre o 3DS2 [**aqui**](/documentations/3ds2-malga/intro). ## Configurando o 3DS2 no Link de Pagamento **1. Configure seu merchant** Garanta que seu merchant tenha suporte a 3DS2 Malga. Saiba mais [**aqui**](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao). **2. Fluxo Inteligente** Adicione um novo fluxo inteligente dentro do seu merchant para processar as transações com 3DS2. **3. Crie seu Link** Com as configurações corretas, tanto via API quanto no Dashboard, você poderá criar seu Link de Pagamento com 3DS2. ## Criando via API Dentro das configurações do método de pagamento `credit`, você poderá configurar o 3DS2. **enabled** `boolean` Indica se o 3DS2 está habilitado para o método de pagamento **liabilityShiftRequired** `boolean` (default: true) Indica se é necessário o liability shift para o método de pagamento. Se `true`, quando não houver transferência de responsabilidade para o emissor, a transação será rejeitada. ```bash Request theme={null} { "amount": 1000, "name": "Loja 1", "merchantId": "", "dueDate": "2030-10-25T09:28:45.000Z", "statementDescriptor": "", "paymentMethods": [ { "paymentType": "credit", "installments": 10, "threeDS": { "enabled": true, "liabilityShiftRequired": false } }, { "paymentType": "pix", "expiresIn": 10000 }, { "paymentType": "boleto", "expiresDate": "2026-01-01" } ], "items":[ { "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false }, { "name": "Caneca \"Code & Coffee\"", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 4500, "quantity": 1, "tangible": false }, { "name": "Kit de Anotações \"Inspire\"", "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.", "unitPrice": 8990, "quantity": 1, "tangible": false } ] } ``` ```bash Response theme={null} { "id": "afb524ef-1471-4e53-96f4-942ebbce06ee", "name": "Loja 1", "status": "created", "isActive": true, "clientId": "YOUR_CLIENT_ID", "orderId": null, "amount": 1000, "currency": "BRL", "capture": false, "merchantId": "YOUR_MERCHANT_ID", "dueDate": "2030-10-25T09:28:45.000Z", "description": null, "statementDescriptor": "", "paymentLink": "https://link.malga.io/afb524ef-1471-4e53-96f4-942ebbce06ee", "createdAt": "2025-11-24T09:41:10.129Z", "updatedAt": "2025-11-24T09:41:10.129Z", "publicKey": "7810b2c9-94c8-48eb-a74c-6c3b13601ce7", "items": [ { "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false, "categoryId": null }, { "name": "Caneca \"Code & Coffee\"", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 4500, "quantity": 1, "tangible": false, "categoryId": null }, { "name": "Kit de Anotações \"Inspire\"", "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.", "unitPrice": 8990, "quantity": 1, "tangible": false, "categoryId": null } ], "paymentMethods": [ { "paymentType": "pix", "expiresIn": 10000 }, { "paymentType": "credit", "installments": 10, "recurrence": null, "threeDS": { "enabled": true, "liabilityShiftRequired": false } }, { "paymentType": "boleto", "instructions": null, "expiresDate": "2026-01-01" } ] } ``` # Criando Links via API Source: https://docs.malga.io/documentations/payment-link/create-link-using-api Aprenda a criar links de pagamento via API da Malga criando uma sessão, que gera automaticamente o paymentLink para o cliente pagar no checkout pronto. ## Criando uma sessão Para criar um link de pagamento, basta criar uma sessão com todas as configurações necessárias. Em seguida, será gerado automaticamente um paymentLink, retornado tanto na resposta de criação quanto na rota de detalhes do link. Essa URL é o endereço onde o ambiente de pagamento ficará disponível para o cliente. Para mais informações sobre os parâmetros e configurações disponíveis, consulte a especificação da [API](/api-reference/sessions/criar-nova-sessao). > [!TIP] > > Você pode configurar o `paymentLink` para que ele tenha o seu domínio alterando o `companyUrl` na API de configurações do Link. Saiba mais [**aqui**](/documentations/payment-link/set-up-custom-theme-link). ## Campos principais Na criação da sessão, os campos abaixo controlam o comportamento do Link de Pagamento. | Campo | Uso | | - | - | | `amount` | Valor cobrado em cada pagamento do link. | | `paymentMethods` | Métodos de pagamento disponíveis para o comprador. | | `paymentLink` | URL retornada pela API para compartilhar o link com o comprador. | | `maxPayments` | Define se o link opera como 1:1 ou 1:N. Quando omitido, o link segue o fluxo 1:1. Quando enviado com um número positivo, limita a quantidade de pagamentos. Quando enviado como `-1`, permite pagamentos sem limite de quantidade. | | `multiplePayments` | Objeto retornado nas respostas completas de sessão para indicar disponibilidade agregada, quantidade de pagamentos e status do link 1:N. | Para oferecer **múltiplos cartões**, inclua em `paymentMethods` um item com `paymentType: "multiple"` e, em `methods`, a configuração do cartão: `quantity` é a quantidade máxima de cartões (`2` ou `3`) e `installments` é o limite de parcelas por cartão. > [!WARNING] > > Quando `maxPayments` for maior que 1, apenas Cartão de Crédito e múltiplos cartões podem ser configurados em `paymentMethods`. > > Pix pode ser usado em links sem limite (`maxPayments: -1`), mas Boleto não está disponível em nenhuma configuração de múltiplos pagamentos. > > Links com Pix ou Boleto que atingirem o limite configurado não podem ser reativados por quantidade — a tentativa é bloqueada via API e Dashboard. Reativação por expiração de data não é afetada. ## Criando um link de pagamento único (1:1) Quando maxPayments é omitido, o link aceita apenas um pagamento. Após o primeiro pagamento bem-sucedido, o link é encerrado automaticamente. ```bash Request theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "name": "Loja 1", "merchantId": "", "dueDate": "2030-10-25T09:28:45.000Z", "statementDescriptor": "", "paymentMethods": [ { "paymentType": "credit", "installments": 10 }, { "paymentType": "multiple", "methods": [ { "paymentType": "credit", "quantity": 2, "installments": 12 } ] }, { "paymentType": "pix", "expiresIn": 10000 }, { "paymentType": "boleto", "expiresDate": "2026-01-01", "instructions": "Não receber após o vencimento. Multa de 2% e juros de 1% ao mês." } ], "items": [ { "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false }, { "name": "Caneca \"Code & Coffee\"", "description": "Caneca de cerâmica para café, com estampa personalizada.", "unitPrice": 4500, "quantity": 1, "tangible": false } ] }' ``` ```json Response theme={null} { "id": "5b2ba64a-d77d-478b-b095-a8c452798dfb", "name": "Loja 1", "status": "created", "isActive": true, "clientId": "YOUR_CLIENT_ID", "orderId": null, "amount": 1000, "currency": "BRL", "capture": null, "merchantId": "YOUR_MERCHANT_ID", "dueDate": "2030-10-25T09:28:45.000Z", "description": null, "statementDescriptor": "YOUR_STATEMENT_DESCRIPTOR", "items": [ { "id": "7a671ce1-d849-438d-a71e-fb1e9e02221c", "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false, "categoryId": null }, { "id": "f2a8621f-6ce2-49de-b627-b84ad73a6128", "name": "Caneca \"Code & Coffee\"", "description": "Caneca de cerâmica para café, com estampa personalizada.", "unitPrice": 4500, "quantity": 1, "tangible": false, "categoryId": null }, ], "paymentLink": "https://link.malga.io/5b2ba64a-d77d-478b-b095-a8c452798dfb", "paymentMethods": [ { "paymentType": "pix", "expiresIn": 10000 }, { "paymentType": "credit", "installments": 10, "recurrence": null }, { "paymentType": "multiple", "methods": [ { "paymentType": "credit", "quantity": 2, "installments": 12 } ] }, { "paymentType": "boleto", "expiresDate": "2026-01-01T00:00:00.000Z", "instructions": null } ], "createdAt": "2025-11-24T09:18:01.000Z", "updatedAt": "2025-11-24T09:18:01.000Z", "publicKey": "db31a846-d48d-497f-ab8c-3fcb07223445" } ``` ## Criando um link com múltiplos pagamentos (1:N) Quando `maxPayments` é enviado com um número positivo, o link aceita até aquela quantidade de pagamentos. Quando enviado como `-1`, o link aceita pagamentos sem limite de quantidade, até a data de expiração definida em `dueDate`. > [!WARNING] > > Links 1:N com limite finito (`maxPayments > 1`) só aceitam **cartão de > crédito único e múltiplos cartões**. Se `paymentMethods` incluir `pix` ou `boleto` junto de > `maxPayments` finito maior que `1`, a API retorna `422` com `businessCode: > "pix_boleto_multiple_payments_not_allowed"`. Para links com pix ou boleto, > use `maxPayments` omitido (1:1), `1` ou `-1` (ilimitado). > > A mesma restrição vale na atualização (`PATCH /v1/sessions/{id}` com > `isActive: true`): elevar `maxPayments` para um valor finito `> 1` em um link > pix ou boleto retorna `422` com `businessCode: > "pix_boleto_multiple_payments_not_allowed"`. Reativar um link pix/boleto 1:1 > já pago também é bloqueado com `422` e `businessCode: > "pix_boleto_one_to_one_reactivation_blocked"`. ```bash Request theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "name": "Loja 1", "merchantId": "", "dueDate": "2030-10-25T09:28:45.000Z", "statementDescriptor": "", "paymentMethods": [ { "paymentType": "credit", "installments": 10 }, { "paymentType": "pix", "expiresIn": 10000 } ], "maxPayments": -1, "items": [ { "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false }, { "name": "Caneca \"Code & Coffee\"", "description": "Caneca de cerâmica para café, com estampa personalizada.", "unitPrice": 4500, "quantity": 1, "tangible": false }, { "name": "Kit de Anotações \"Inspire\"", "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.", "unitPrice": 8990, "quantity": 1, "tangible": false } ] }' ``` ```json Response theme={null} { "id": "5b2ba64a-d77d-478b-b095-a8c452798dfb", "name": "Loja 1", "status": "created", "isActive": true, "clientId": "YOUR_CLIENT_ID", "orderId": null, "amount": 1000, "currency": "BRL", "capture": null, "merchantId": "YOUR_MERCHANT_ID", "dueDate": "2030-10-25T09:28:45.000Z", "description": null, "statementDescriptor": "YOUR_STATEMENT_DESCRIPTOR", "items": [ { "id": "7a671ce1-d849-438d-a71e-fb1e9e02221c", "name": "Fone de Ouvido Bluetooth TWS-X1", "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.", "unitPrice": 35000, "quantity": 1, "tangible": false, "categoryId": null }, { "id": "f2a8621f-6ce2-49de-b627-b84ad73a6128", "name": "Caneca \"Code & Coffee\"", "description": "Caneca de cerâmica para café, com estampa personalizada.", "unitPrice": 4500, "quantity": 1, "tangible": false, "categoryId": null }, { "id": "18783d7e-b9a4-43ba-b4fc-e5b294e97d6f", "name": "Kit de Anotações \"Inspire\"", "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.", "unitPrice": 8990, "quantity": 1, "tangible": false, "categoryId": null } ], "paymentLink": "https://link.malga.io/5b2ba64a-d77d-478b-b095-a8c452798dfb", "paymentMethods": [ { "paymentType": "pix", "expiresIn": 10000 }, { "paymentType": "credit", "installments": 10, "recurrence": null }, { "paymentType": "boleto", "expiresDate": "2026-01-01T00:00:00.000Z", "instructions": null } ], "multiplePayments": { "allow": true, "maxPayments": 36, "paymentCount": 0, "pendingCount": 0, "status": "active" }, "createdAt": "2025-11-24T09:18:01.000Z", "updatedAt": "2025-11-24T09:18:01.000Z", "publicKey": "db31a846-d48d-497f-ab8c-3fcb07223445" } ``` > [!NOTE] > > O valor cobrado em cada pagamento é o **amount** da sessão, não a soma dos valores dos items. Os itens são exibidos no checkout apenas como descrição da compra. ## Pagando uma sessão Para pagar um Link de Pagamento, você deve utilizar o endpoint de pagamento de uma sessão. Você pode ler mais detalhes na [**especificação da API**](/api-reference/sessions/pagar-uma-sessao). Veja o contrato completo na [especificação de pagamento de sessão](/api-reference/sessions/pagar-uma-sessao). ```bash Request theme={null} curl --location 'https://api.malga.io/v1/sessions/{id}/charge' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } } }' ``` ## Acompanhando os pagamentos Após cada pagamento, consulte a sessão para verificar o estado agregado do link. O objeto `multiplePayments` retorna a contagem atualizada de pagamentos realizados e o status atual do link. Veja o contrato completo na [especificação de consulta de sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao). > [!NOTE] > > Deseja utilizar um de nossos serviços como autenticação 3DS2 ou usar o split nos pagamentos de seus links? Consulte as documentações completas: > > * [3DS2](/documentations/payment-link/3ds2) > * [Split](/documentations/payment-link/split) # Criando Links via Dashboard Source: https://docs.malga.io/documentations/payment-link/create-link-using-dashboard Crie links de pagamento pelo Dashboard Malga sem integração, definindo valor, métodos de pagamento, parcelas e limite de pagamentos para cada link gerado. ![Tela de criação de link com o controle de limite de pagamentos habilitado](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/payment-link/payment-link-create-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=512977b116f0af51405780ee167274a6) A criação manual de links é a forma mais rápida de gerar cobranças sem necessidade de integração técnica. Pelo Dashboard, você pode criar um link para pagamento único ou habilitar múltiplos pagamentos, definindo quantas vezes o mesmo link poderá ser pago. * **Times de vendas**: Para fechar negócios via WhatsApp ou e-mail. * **Recuperação de carrinho**: Para enviar uma oferta personalizada. * **No-code**: basta um clique para que seu link esteja pronto para compartilhar com seu cliente. ## Dados da venda Saiba sobre os dados solicitados e o que você precisa preencher em cada um: ### 1. Informações básicas Aqui você deverá informar os seguintes campos obrigatórios: * O **nome deste link**. Útil para diferenciar na identificação da listagem de links e facilitar nas análises. * **Moeda** em que a cobrança será gerada. Confira [aqui](/documentations/type-tables/currency-not-supportted) a lista de tipos aceitos. > [!NOTE] > > O link é criado na **subconta ativa** no seletor de contexto do menu lateral. É ela que determina quais métodos de pagamento estarão disponíveis e se a cobrança pode ser operada em [split](/documentations/split/intro), envolvendo mais de um recebedor sobre o valor total. Para criar um link em outra subconta, troque o contexto antes de clicar em **Novo Link**. Dos campos opcionais, você poderá preencher: * **Descrição** do link, contendo informações adicionais que julgue necessárias. * **ID do pedido na loja**, aqui você pode indicar o id do pedido a que este link se refere na sua loja. * A **data de validade do link e horário**, que ao ativar, o link será expirado automaticamente no horário e data informados. * A **quantidade de pagamentos**, que indica quantas vezes o link poderá ser pago. ![Campos opcionais da criação de link: descrição, ID do pedido, validade e quantidade de pagamentos](https://mintcdn.com/malga/1sH_FynYn2mOWqhC/assets/images/dashboard/payment-link/optionals-light.png?fit=max\&auto=format\&n=1sH_FynYn2mOWqhC\&q=85\&s=24ae15fb1607084b78dbeb6ff6d02642) ### 2. Informações de itens Aqui funciona como o carrinho de itens do seu link, onde é necessário inserir pelo menos 1 item, contendo: * **Nome:** nome do item na sua loja que será comprado neste link. * **Descrição:** campo opcional para incrementar informações como uma observação importante sobre aquele item. * **Valor unitário:** valor da unidade do item inserido. * **Quantidade:** indica quantos itens estão sendo cobrados neste link. É essa informação que, multiplicada pelo valor unitário, resultará no valor total da cobrança a ser gerada pelo link. ### 3. Divisão de recebíveis Você poderá dividir o recebimento do pagamento do link para mais de um recebedor. Confira todas as informações em [Split de Pagamentos](/documentations/payment-link/split). * **Tipo de divisão:** indica se será definido em % ou R\$. * [**Recebedor:**](/documentations/split/seller) você deverá indicar quem vai compartilhar o valor desta compra. * **Porcentagem ou valor do recebimento:** é o quanto cada recebedor ganhará nesta compra. Caso não atinja 100% do valor total, o montante restante ficará para você. ### 4. Informações de pagamento Neste passo, você deverá ativar quais métodos deseja disponibilizar para o pagamento do link. Para cada um deles, valem as seguintes regras: * Caso o método ativado seja **boleto**, será necessário indicar a data de vencimento, além dos juros e da multa, caso haja. * Se for **cartão de crédito**, indique a quantidade de parcelas ou se será à vista. * Se for **múltiplos cartões de crédito**, indique a quantidade de cartões que serão utilizados para o pagamento e o limite de parcelas. * E para o **Pix**, o tempo de validade, que pode ser segundos, minutos, horas ou dias. > [!NOTE] > > Atenção: os métodos Pix e Boleto só podem ser escolhidos para a moeda real brasileiro (BRL), assim como o split de pagamento. Agora que você já sabe de quais informações precisa, basta seguir o passo a passo: #### Passo a passo Siga os passos abaixo para gerar seu link de pagamento em poucos segundos: 1. Acesse sua conta no **Dashboard da Malga** 2. Clique no nome da empresa no topo do menu lateral e selecione a subconta em que o link será criado 3. No menu lateral, navegue até **Links de Pagamento** (o item aparece apenas na visão de uma subconta) 4. Clique no botão **"Novo Link"** no canto superior direito 5. Preencha os dados da venda no formulário 6. Em **Mais opções**: * adicione uma data de expiração * defina um limite de quantidade de pagamentos. Se o limite for maior que 1, Pix será desabilitado automaticamente. Boleto não está disponível em nenhuma configuração de múltiplos pagamentos 7. Revise as informações no resumo e clique em **Criar Link** Após seguir todos os passos, você verá uma tela de resumo com tudo o que foi configurado para o funcionamento do link. Após revisar os dados, confirme a criação e o link será exibido. Copie e cole diretamente para o seu cliente! Na listagem, você o verá com o status de criado e a situação de ativa, pois ainda está dentro da validade definida. Não se esqueça de que você poderá acompanhar o pagamento e as tentativas de pagamento acessando a página de detalhes do link. Basta clicar na linha em que ele se encontra na listagem ou buscar pelo ID da sessão. Nos detalhes de um link, você pode acompanhar à direita o histórico de tentativas de pagamento e mudanças de status em geral. Já no lado esquerdo, você terá o resumo das configurações definidas durante a criação, como informações básicas, itens, métodos de pagamento, split e assim por diante. Aproveite e faça bom uso dessas informações! ![Detalhes de um Link](https://mintcdn.com/malga/PO5KJ8oQaRK6_xvH/assets/images/dashboard/payment-link/payment-link-details-light.png?fit=max\&auto=format\&n=PO5KJ8oQaRK6_xvH\&q=85\&s=44243a01827b48373bfd05c5756c7f53) Nessa tela também é possível cancelar, desativar ou reativar um link, caso o mesmo tenha atingido o limite de pagamentos ou tenha sido expirado ao atingir a data e hora informadas. Não se esqueça de que você poderá acompanhar o pagamento e as tentativas de pagamento no histórico de operações, onde serão mostrados todos os dados da requisição feita pelo cliente, seguidos da data e hora. > [!NOTE] > > Ficou com dúvida ou necessita de ajuda? Ficaremos felizes em ajudar! > Envie um email para [suporte@malga.io](mailto:suporte@malga.io). # Introdução aos Links de Pagamento da Malga Source: https://docs.malga.io/documentations/payment-link/intro Crie Links de Pagamento na Malga pelo Dashboard ou via API com checkout pronto e personalizável, ideais para vendas avulsas e cobranças rápidas. O Link de Pagamento Malga é uma forma rápida e prática de gerar cobranças para produtos e serviços por meio de uma página de checkout segura, personalizável e ideal para vendas únicas, cobranças avulsas ou clientes que não concluíram o pagamento no fluxo principal. Pela [**Dashboard**](https://dashboard.malga.io/) ou via integração com o serviço de Sessions, é possível criar links com opções de pagamento como Pix, Boleto e Cartão de Crédito, além de definir um limite máximo de pagamentos e data de expiração por link — recurso útil para promoções, eventos ou cobranças específicas. Para o cliente final, a experiência ocorre em um checkout white-label e agnóstico, personalizado com a identidade visual da sua empresa, como cores e logotipo. ## Por que usar o Link de Pagamento? * **No-code**: Comece a vender imediatamente criando links através da nossa Dashboard, sem escrever uma linha de código. * **Checkout otimizado**: Ofereça uma experiência de compra fluida em desktop e mobile, com suporte aos principais métodos de pagamento. * **Segurança**: Todo o manuseio de dados sensíveis de cartão é feito no ambiente seguro da Malga (PCI DSS). * **Recuperação de vendas**: Configure expiração de links e gerencie o status de cada cobrança em tempo real. ## Funcionalidades disponíveis Considerando as funcionalidades disponíveis, você pode criar um Link de Pagamento com as seguintes opções: | Funcionalidade | Disponível | | :- | :- | | Criação via API | | | Criação via Dashboard | | | Definição de data de expiração | | | Pagamento com cartão de crédito | | | Pagamento com múltiplos cartões | | | 3DS2 da Malga | | | Split de pagamentos | | | Pagamento com boleto | | | Pagamento com Pix | | | Pagamento com Drip | | | Pagamento com NuPay | | | Pagamento com Apple Pay | | | Pagamento com Click to Pay | | | Personalização de tema | | > [!NOTE] > > A disponibilidade de Pix e Boleto varia conforme a configuração de limite do link: > > * **Cartão de Crédito único e múltiplos cartões**: disponível em qualquer configuração. > * **Pix**: disponível em links de pagamento único e em links sem limite de quantidade (`maxPayments` ausente ou `-1`). Bloqueado quando `maxPayments > 1`. > * **Boleto**: disponível apenas em links de pagamento único. Não disponível em nenhuma configuração de múltiplos pagamentos. > > Links com Pix ou Boleto que atingirem o limite configurado não podem ser reativados por quantidade — o botão Ativar ficará desabilitado. A reativação por expiração de data não é afetada. > [card] [Criando via API](/documentations/payment-link/create-link-using-api) > > Saiba como criar um Link de Pagamento via API. > [card] [Criando via Dashboard](/documentations/payment-link/create-link-using-dashboard) > > Saiba como criar um Link de Pagamento via Dashboard. > [card] [Tema personalizado](/documentations/payment-link/set-up-custom-theme-link) > > Saiba como configurar o tema personalizado para o Link de Pagamento. > [card] [3DS2 Agnóstico](/documentations/payment-link/3ds2) > > Saiba como configurar o 3DS2 Agnóstico para o Link de Pagamento. > [!NOTE] > > No Dashboard, o menu **Links de pagamento** fica disponível na visão de uma subconta. Selecione a subconta no seletor do menu lateral. # Tema personalizado para o Link Source: https://docs.malga.io/documentations/payment-link/set-up-custom-theme-link Configure o tema personalizado do Link de Pagamento da Malga via API de Settings: defina cores, logo e URL para refletir a identidade da sua marca. Para configurar o tema personalizado para o Link de Pagamento, você deve utilizar a API de Settings. Você pode ler mais detalhes sobre a configuração de um Link de Pagamento na [**especificação da API**](/api-reference/settings/criar-configuracao-de-link-de-pagamento). ```bash Request theme={null} curl --request POST \ --url https://api.malga.io/v1/settings \ --header 'Content-Type: multipart/form-data' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --form 'mainColor=#000000' \ --form 'SecondaryColor=#FFFFFF' \ --form 'attentionColor=#FF0000' \ --form 'errorColor=#FF0000' \ --form 'successColor=#00FF00' \ --form 'backgroundColor=#FFFFFF' \ --form 'logo=@"/C:/Users/caminho/para/a/imagem/logo.jpg"' \ --form companyUrl=https://www.company.com ``` ```bash Response theme={null} { "id": "id da setting", "clientId": "id da setting", "mainColor": "#000000", "SecondaryColor": "#FFFFFF", "attentionColor": "#FF0000", "errorColor": "#FF0000", "successColor": "#00FF00", "backgroundColor": "#FFFFFF", "logo": "https://url.com/logo.jpg", "companyUrl": "https://www.company.com" "merchantId": "" } ``` ![Detalhes da personalização](https://mintcdn.com/malga/IOVOnIAezUBL8DiW/assets/images/dashboard/payment-link/payment-link-theme-light.png?fit=max\&auto=format\&n=IOVOnIAezUBL8DiW\&q=85\&s=336d034873fa05d0914a6e3d91e00808) ## Tema por Merchant Se você possui múltiplos merchants, é possível configurar um tema específico para cada um. Para isso, envie o header `X-Merchant-Id` na chamada de criação ou atualização de settings. Quando um Link de Pagamento é gerado para uma sessão com `merchantId`, o sistema busca automaticamente a configuração do merchant. Caso não exista configuração específica, o tema padrão do cliente é utilizado como fallback. ```bash Request theme={null} curl --request POST \ --url https://api.malga.io/v1/settings \ --header 'Content-Type: multipart/form-data' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --header 'X-Merchant-Id: ' \ --form 'mainColor=#39BFAD' \ --form 'SecondaryColor=#FFFFFF' \ --form 'attentionColor=#FFA500' \ --form 'errorColor=#FF0000' \ --form 'successColor=#00AA00' \ --form 'backgroundColor=#F5F5F5' \ --form 'logo=@"/caminho/para/logo-merchant.png"' \ --form companyUrl=https://www.merchant.com ``` ```bash Response theme={null} { "id": "uuid-da-setting", "clientId": "id-do-cliente", "mainColor": "#39BFAD", "SecondaryColor": "#FFFFFF", "attentionColor": "#FFA500", "errorColor": "#FF0000", "successColor": "#00AA00", "backgroundColor": "#F5F5F5", "logo": "https://url.com/logo-merchant.png", "companyUrl": "https://www.merchant.com", "merchantId": "066e3625-7c1d-4234-8681-f0ea8e023c79" } ``` > [!NOTE] > > O campo `merchantId` na resposta indica se a configuração retornada é específica do merchant (id do merchant) ou a configuração padrão do cliente (nesse caso sem valor). ## Personalizando a URL do Link Para personalizar a URL do Link de Pagamento, utilize o parâmetro `companyUrl` na API de Settings. Além disso, entre em contato com o time de atendimento Malga para configurar o domínio do Link de Pagamento. Para **atualizar** apenas a URL (sem reenviar logo ou cores), use `PATCH` com JSON: ```bash Request (JSON) theme={null} curl --request PATCH \ --url https://api.malga.io/v1/settings \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --data '{ "companyUrl": "https://www.company.com" }' ``` ```bash Request (multipart) theme={null} curl --request PATCH \ --url https://api.malga.io/v1/settings \ --header 'Content-Type: multipart/form-data' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --form 'companyUrl=https://www.company.com' ``` > [!NOTE] > > Enviar `companyUrl` vazio ou um body JSON `{}` retorna **422** (`No fields to update`) — a API não interpreta isso como remoção do valor. Para alterar a URL, envie o novo valor completo. # Split no Link de Pagamentos Source: https://docs.malga.io/documentations/payment-link/split Saiba como dividir o valor de um link de pagamento entre recebedores com split na Malga, usando subcontas com provedores compatíveis e regras de recebedores. ## Como funciona o Split de pagamentos? Ao criar um link via API de sessions ou via dashboard, a Malga possibilita que o recebimento do valor da compra seja dividido entre recebedores. Para usar essa funcionalidade, é necessário atender aos seguintes itens: 1. Ter uma [subconta](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) com provedores que suportem split de pagamentos. No Dashboard, o link é criado na subconta ativa no seletor de contexto. 2. Defina um ou mais [**recebedores de pagamento**](/api-reference/sellers/criacao-de-um-novo-recebedor). É importante especificar quem será o responsável pelo pagamento das taxas do provedor e pelos reembolsos em caso de chargeback. Essas regras podem ser configuradas individualmente para cada recebedor via API. Caso nenhuma configuração seja informada, por padrão consideramos que os recebedores parceiros não são responsáveis por essas obrigações — nesse cenário, a responsabilidade pelas taxas e chargebacks será da sua empresa. > [!NOTE] > > * Não é necessário criar um recebedor para sua empresa. Sempre que a divisão configurada não totalizar 100% do valor da compra, o valor remanescente será automaticamente direcionado para a sua empresa. > * Só é possível criar links de pagamento com split para recebedores com status igual a **active** ou **parcial** Abaixo, você confere todos os provedores que oferecem suporte ao split e quais deles cobram taxas de processamento e chargeback, sendo configuráveis na [criação do recebedor](/api-reference/sellers/criacao-de-um-novo-recebedor). | Provedor | Taxa processingFee | Taxa de chargeBack | Taxa MDR | Taxa Fee | | - | - | - | - | - | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/zoop.svg) Zoop | | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagarme.svg) Pagarme V5 | | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagseguro.svg) PagSeguro | | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/braspag.svg) Braspag | | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/malga.svg) Malga | | | | | Taxa configurável, você escolhe qual dos recebedores definidos será responsável por ela. A taxa é fixa e não suporta a definição durante a transação, apenas diretamente com o provedor. A taxa é feita via tarifas (MDR e Fee), sendo necessário configurá-las no cadastro do recebedor. Com tudo preparado, basta definir como deseja que a divisão do recebimento aconteça, indicando as seguintes configurações: * **Tipo de divisão:** indica sob qual valor da compra será calculado o repasse para cada um dos recebedores. Pode ser escolhido definir o valor em porcentagem (%) ou em reais (BRL). * [**Recebedor:**](/documentations/split/seller) você deverá indicar quem vai compartilhar o valor desta compra. * **Porcentagem ou valor do recebimento:** é o quanto cada recebedor ganhará nesta compra, podendo ser no mínimo `1%` ou `R$ 0,1` e no máximo `100%` ou o `total dos itens do pedido em R$`. > [!NOTE] > > **Precedência das regras de split:** se você definir regras de responsabilidade (taxas/chargeback) diretamente na criação do link (transação), elas terão prioridade sobre as regras configuradas no cadastro do recebedor. Isso garante flexibilidade para cenários específicos de venda. > [!NOTE] > > O split de pagamentos só funcionará caso a moeda definida na criação do link seja Real Brasileiro (BRL). Confira como fica a criação de uma sessão com split: ```bash Request theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "name": "Marketplace Order #123", "merchantId": "", "paymentMethods": [ { "paymentType": "pix", "expiresIn": 10000 } ], "items": [ { "name": "Serviço de Consultoria", "unitPrice": 1000, "quantity": 1, "tangible": false } ], "splitRules": [ { "sellerId": "", "percentage": 80, "liable": true, "chargeEntireFee": true }, { "sellerId": "", "percentage": 20, "liable": false, "chargeEntireFee": false } ] }' ``` ```bash Response theme={null} { "id": "5b2ba64a-d77d-478b-b095-a8c452798dfb", "paymentLink": "https://link.malga.io/5b2ba64a-d77d-478b-b095-a8c452798dfb", "splitRules": [ { "sellerId": "", "percentage": 80, "liable": true, "chargeEntireFee": true }, { "sellerId": "", "percentage": 20, "liable": false, "chargeEntireFee": false } ], ... } ``` Se desejar mais facilidade e praticidade, não deixe de usar o nosso [**dashboard**](https://dashboard.malga.io/). Por lá, basta um clique e seu link de pagamento com split estará pronto para ser compartilhado com seu cliente! Saiba mais em [Links com split via dashboard](/documentations/payment-link/create-link-using-dashboard). ![Split na dashboard](https://mintcdn.com/malga/fXEgRvys0jL21ddH/assets/images/dashboard/payment-link/split-step-dashboard.gif?s=611d4baacd18da4f8266444dcc24adf9) > [!NOTE] > > Ficou com dúvida ou necessita de ajuda? Ficaremos felizes em ajudar! > Fale conosco através do email [suporte@malga.io](mailto:suporte@malga.io). # Configuração de certificados Source: https://docs.malga.io/documentations/payment-methods/apple-pay/certificates-setup Para conseguir transacionar com Apple Pay é necessário ter uma conta de desenvolvedor do Apple, caso não tenha, acesse o [Apple Developer](https://developer.apple.com/account/resources/) e crie uma conta. ## Criando um Merchant Identifier na Apple Um Merchant identifica você como um comerciante que pode aceitar pagamentos de Apple Pay. Para criar um Merchant, você precisa de um Apple Developer Account, acessar sua conta e seguir os passos abaixo: 1. Na seção "Certificates, Identifiers & Profiles", selecione "Identifiers" e clique em "Register an App ID":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-1.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=bd82f1a8b55e564752ae90cb6e31139e) 2. Selecione a opção "Merchant IDs":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-2.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=826e2f17815dd600deb5ac7972061c41) 3. Preencha os campos "Description" e "Identifier":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-3.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=d2e8a5f93c41e9a51a31933ab9e55a0c) 4. Finalize clicando em "Continue" e depois "Register". ## Criando um certificado de processamento de pagamento Um certificado de processamento de pagamento é associado ao seu identificador e usado para criptografar as informações de pagamento. O certificado expira a cada 25 meses, quando revogado, você poderá gerar um novo certificado. Para criar um certificado, você precisará de um certificado ".CSR", [que pode ser gerado na sua máquina](https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request). Com o ".CSR" em mãos: 1. Na seção "Certificates, Identifiers & Profiles", selecione "Identifiers"; 2. Utilizando o filtro "App IDs", selecione "Merchant IDs":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-1.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=0933ebad14baba3933e0591e16f2d0dc) 3. Selecione o identifier criado anteriormente:![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-2.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=f4531093dafcc304a88c45206d4cb1d7) 4. Na seção "Apple Pay Payment Processing Certificate", clique no botão "Create Certificate":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-3.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=26a7c2901bc0ae6e18b9c1ce627a39cd) 5. Escolha a opção "No" em "Edit or Configure Merchant ID":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-4.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=30e1c94a0cea908fb1b943754891940f) 6. Em "Choose File", faça upload do certificado ".CSR" gerado anteriormente:![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-5.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=f419453d3d0c2180e2ad85fc37522c55) 7. Clique em "Continue" e depois em "Download" para baixar o certificado de pagamento: ![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/payment-6.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=e7b2136dfa948bf70338556f4c0c7d63) ## Registro de domínio Caso você ofereça o Apple Pay através do seu site, será necessário registrar o domínio do site na Apple para que possa receber pagamentos. 1. Na seção "Certificates, Identifiers & Profiles", selecione "Identifiers" e filtre no "App IDs" por "Merchant IDs":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/domain-1.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=0e130543723ab448671d5eb8b0cbc9e1) 2. Selecione o identificador do seu merchant:![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/domain-2.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=7af5851a3d1d633fcd354370439743bc) 3. Em "Merchant Domains", clique em "Add Domain":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/domain-3.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=18ad6c2aee8beecec1abce971282558e) 4. Preencha o domínio e clique em "Save":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/domain-4.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=3a6b615873c43b2cb63c3ccd9fa204ad) 5. Clique em "Download" para baixar o arquivo de verificação; 6. Disponibilize o arquivo seguindo as próprias instruções da Apple; 7. Após disponibilizar, clique em "Verify":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/domain-5.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=cda838bab51a8e81281c6500ad68a504) ## Criando um certificado de identidade do Merchant 1. Na seção "Certificates, Identifiers & Profiles", selecione "Identifiers" e filtre no "App IDs" por "Merchant IDs":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-id-1.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=00fb65ad8611292a09e0a986a400ff65) 2. Selecione o identificador do seu merchant:![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-id-2.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=298359ada0608c3a17cfd1e12f5502df) 3. Em "Apple Pay Merchant Identity Certificate", clique em "Create Certificate":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-id-3.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=20c35731dcf3abd383a22172484d2053) 4. Em "Choose File", faça upload do certificado ".CSR" gerado e clique em "Continue":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-id-4.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=9952548e98829ec6a36a000878688bfc) 5. Baixe o certificado de identificação do merchant gerado em "Download":![Apple Developer Account](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/apple-pay/merchant-id-5.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=7de8b38b2fcb3bdfdfe56516c8f5cb42) # Guia de integração Source: https://docs.malga.io/documentations/payment-methods/apple-pay/getting-started Antes de transacionar com Apple Pay na Malga, você precisará gerar alguns certificados disponibilizados pela Apple que permitirão que a Malga possa processar seus pagamentos, sendo eles: * [Certificado de identidade de comerciante;](/documentations/payment-methods/apple-pay/certificates-setup#criando-um-certificado-de-identidade-do-merchant) * [Certificado de processamento de pagamento.](/documentations/payment-methods/apple-pay/certificates-setup#criando-um-certificado-de-processamento-de-pagamento) ## Configurando o Apple Pay na Malga e no seu provedor O certificado de processamento de pagamento deverá ser enviado no suporte do time Malga, enquanto que o certificado de identidade de comerciante deverá ser enviado para o seu provedor, também via suporte. Com os dois configurados adequadamente na Malga e no provedor, você já poderá enviar transações Apple Pay via Malga, configurando seu fluxo inteligente via Dashboard da maneira desejada. ## Criando uma cobrança Apple Pay * Para criar uma transação com Apple Pay basta o cliente informar o meio de pagamento *apple\_pay* na criação de uma cobrança e os tokens provenientes da wallet; * Uma cobrança é feita no cartão através do provedor configurado no fluxo inteligente; * Após confirmação do pagamento, o provedor enviará uma notificação para a Malga informando que o pagamento foi realizado; * Posteriormente o cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso. Realize uma cobrança a partir dos dados do cartão de crédito sem tokenizar usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). > [accordion] Requisição para criar cobrança com Apple Pay > > ```bash theme={null} > curl --location --request POST 'https://api.malga.io/v1/charges' \ > --header 'X-Client-Id: ' \ > --header 'X-Api-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": false, > "paymentMethod": { > "paymentType": "apple_pay", > "installments": 1 > }, > "paymentSource": { > "sourceType": "wallet", > "walletPayment": "credit", > "paymentData": { > "data": "/ZCUzCmr236kDnnXb9cZsvG1JJOqe8GOuRDfCgJ...7haAXX9ml5c7eCIf+IQa1MSGUZYgawepPy", > "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTAL...s9BerKDnL1zoEcmcybKzgAAAAAAAA==", > "header": { > "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKo...ixBMa1KGjnGapsQih+Kdbg2fA==" > }, > "version": "EC_v1" > } > } > }' > > < HTTP/2 201 > < content-type: application/json; charset=utf-8 > { > "id": "49d8a8cd-5d84-43f0-a2d7-c39950711892", > "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", > "clientId": "d353deef-dacb-40a0-8cab-931ff773f274", > "createdAt": "2021-03-23T15:12:38.379Z", > "amount": 150, > "originalAmount": 150, > "currency": "BRL", > "statementDescriptor": "Pedido #231 loja joão", > "capture": false, > "status": "pre_authorized", > "paymentMethod": { > "paymentType": "apple_pay", > "installments": 1 > }, > "paymentSource": { > "sourceType": "wallet", > "cardId": "a1d455eb-dafe-4a5c-b882-a5775422f850" > }, > "transactionRequests": [{ > "id": "fcbc7c8e-9e01-4de5-aee3-a3e14832c804", > "updatedAt": "2021-03-23T15:12:42.799Z", > "createdAt": "2021-03-23T15:12:38.392Z", > "idempotencyKey": "4473cbec-f4e4-4604-a472-a897cba8607f", > "requestId": null, > "providerId": "cb39fc36-8c4b-4deb-b0c1-2fdd8db2e1ab", > "providerType": "CIELO", > "amount": 150, > "authorizationCode": "", > "authorizationNsu": "1616512362092", > "responseCode": "20000", > "requestStatus": "success", > "requestType": "pre_authorization", > "responseTs": null > }] > } > > ``` > [!NOTE] > > Os dados que são enviados dentro da `paymentData` são disponibilizados pelos SDK's de carteira digital, podendo ser, na web, o [Payment Request API](https://www.w3.org/TR/payment-request/) ou o [Apple Pay JS API](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api) e, no mobile, com o [PassKit](https://developer.apple.com/documentation/passkit/offering-apple-pay-in-your-app). Quando criada na Malga, a cobrança do tipo Apple Pay `credit`: * É registrada com status `authorized`, `pre_authorized` ou `failed`; * É possível realizar o estorno total ou parcial da cobrança; * É possível realizar a pré-autorização e captura da cobrança. ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é criada na Malga | | *transaction* | *pre\_authorized* | Evento enviado quando é pré-autorizado o pagamento, com reserva de saldo | | *transaction* | *authorized* | Evento enviado quando é autorizado o pagamento | | *transaction* | *failed* | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *canceled* | Evento enviado quando a cobrança é cancelada antes de ter sido capturada, não produzindo um estorno financeiro | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | | *transaction* | *charged\_back* | Evento enviado quando a cobrança é contestada por fraude | | | | | ## Pré-autorização e captura No fluxo de pagamentos por cartão é possível realizar uma autorização que reserva o saldo e fica pendente de uma captura posterior, ou você pode já autorizar o pagamento de maneira definitiva. A vantagem de estornar uma transação que ainda não tenha sido "capturada" é que o estorno é feito imediatamente na fatura do comprador, em alguns casos quando você tenta estornar uma transação já capturada pode levar até 30 dias para constar o estorno na fatura, por isso muitos lojistas optam por não capturar automaticamente e fazer isso manualmente depois. O flag de `capture` serve para indicar se a transação deve ou não ser capturada. Na nossa API caso você envie o atributo `capture: false` iremos retornar a transação autorizada (saldo reservado no cartão) com status `pre_authorized` sendo necessário que você faça um request no [Serviço de Captura](/api-reference/charges/capturar-cobranca-pre-autorizada) para forçar manualmente a captura da transação e liberar para liquidação na conta do provedor. Se a transação não for capturada em 7 dias o adquirente pode desfazer automaticamente a transação. Caso você envie o atributo `capture: true` iremos retornar a transação autorizada com status `authorized`, não sendo necessária mais nenhuma ação, a transação já fica liberada para liquidação no adquirente e não precisa chamar o Serviço de Captura. Em nosso dashboard, também é possível *capturar*. ## Estorno total ou parcial No fluxo de pagamento por Apple Pay, é possível realizar um estorno no valor total ou parcial da cobrança. No caso de estorno parcial, o lojista opta por realizar um estorno com valor inferior ao valor da venda, sendo feito o reembolso do valor parcial estornado para o comprador, permanecendo a cobrança como autorizada para liquidação do valor restante para o lojista. Para realizar um estorno parcial, basta enviar na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) um `amount` inferior ao valor original da transação, sendo este `amount` do estorno o valor a ser estornado. Uma vez aprovada a solicitação de estorno parcial junto ao emissor do cartão, o `amount` da transação é então atualizado para o valor residual da transação após o estorno (valor da cobrança - valor estornado). > [!WARNING] > > O atributo `originalAmount` do objeto `charge` se mantém como o valor > originalmente autorizado na transação, é o valor inicial da transação quando > aprovada. Já o atributo `amount` do objeto `charge` é alterado a cada > solicitação de estorno parcial, mantendo o saldo residual a receber pelo > lojista. Importante ressaltar que podem ser realizadas diversas requisições de estorno parcial para uma mesma transação, sendo que a cada requisição nosso sistema verifica se o valor a ser estornado (o valor enviado na requisição de `void`) é menor ou igual ao valor residual da transação, não sendo possível estornar um valor superior. O histórico de requisições de estorno pode ser encontrado na listagem de `transactionRequests` do objeto `charge`. O status da transação permanecerá como `authorized` ou `pre_authorized` enquanto restar valor a ser pago ao lojista, sendo alterado para `voided` somente quando o estorno zera todo o valor a receber do lojista. > [!NOTE] > > Embora raro, um reembolso pode falhar após você ter recebido um webhook de REEMBOLSO com success: true. Um webhook de REEMBOLSO bem-sucedido significa que nossas validações foram bem-sucedidas e enviamos a solicitação de reembolso para o esquema do cartão. No entanto, o esquema do cartão ainda pode rejeitar o reembolso. Isso pode acontecer mesmo alguns dias após você enviar a solicitação de reembolso. > > Na maioria das vezes, a Adyen pode corrigir o problema, para que o comprador eventualmente receba os fundos. Às vezes, no entanto, você precisa tomar medidas por conta própria. Para saber por que um reembolso pode falhar e o que, se necessário, você precisa fazer em cada caso, consulte Reembolsos falhados. ## Tratando erros na captura e estorno As modificações feitas em uma cobrança para fins de estorno total, estorno parcial, ou captura podem retornar com erro no provedor. A fim de garantir o correto tratamento dos casos de exceção retornado pelos provedores nestas operações, nossa API, ao receber erro na captura/estorno, retorna HTTP Status Code 201, sendo criado um novo transactionRequest com o status `failed`, porém não é modificado o status original da transação. **É recomendado que você verifique o status do objeto charge retornado, ou o status do primeiro objeto da lista de transactionRequests para se certificar que a operação foi realizada com sucesso.** # Começando em ApplePay Source: https://docs.malga.io/documentations/payment-methods/apple-pay/intro O Apple Pay é uma solução de pagamento móvel desenvolvida pela Apple que combina conveniência e segurança para transações realizadas online ou em dispositivos habilitados. Com o Apple Pay, os usuários podem realizar compras de forma simples e rápida, utilizando cartões de crédito armazenados de forma segura em seus dispositivos Apple. > [card] [Guia de integração](/documentations/payment-methods/apple-pay/getting-started) > > Comece agora mesmo a usar Apple Pay na Malga > [card] [Provedores suportados](/documentations/type-tables/payment-methods-by-providers) > > Confira a lista de provedores que suportam cobranças Apple Pay > [card] [Configurando um fluxo inteligente](/documentations/flow-guide/new) > > Configure o fluxo inteligente para cobranças com Apple Pay # Pagamentos com boleto bancário na Malga Source: https://docs.malga.io/documentations/payment-methods/boleto Entenda como funciona o pagamento com boleto bancário na Malga: participantes, fluxo de emissão e registro pelo provedor, e criação da cobrança via API. 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](/api-reference/customers/criacao-de-novo-customer-para-cobranca); * Criar um novo [charge](/api-reference/charges/realizar-nova-cobranca) 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](/documentations/type-tables/payment-methods-by-providers). 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. > [!WARNING] > > **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. > [!WARNING] > > 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. > [!WARNING] > > **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 | > [!WARNING] > > É 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](https://requestbin.com/) ou [pipedream.com](https://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** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-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](/api-reference/charges/realizar-nova-cobranca). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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" } } ``` # Integração via API de Cobranças com Click to Pay Source: https://docs.malga.io/documentations/payment-methods/click-to-pay/integracao-api-charges Se você deseja controlar totalmente a experiência de checkout no seu site ou app, pode integrar o **Mastercard Click to Pay (C2P)** diretamente na API transacional da Malga usando o endpoint `/v1/charges`. Neste modelo: * O **front-end** integra os **SDKs de Click to Pay da Mastercard**, responsáveis por: * Apresentar a UI de seleção/cadastro de cartão C2P para o comprador; * Realizar a autenticação com o emissor, quando aplicável; * Retornar identificadores como `correlationId`, `flowId` e `merchantTransactionId`; * o **back-end** chama a **API da Malga** com `paymentType: "click_to_pay"` e o objeto `walletClickToPay` preenchido. Para detalhes da jornada de usuário, componentes de UI e fluxos de autenticação, consulte a documentação oficial da Mastercard: * Guia de experiência do cliente: [`https://developer.mastercard.com/click-to-pay-customer-experience-guide/documentation`](https://developer.mastercard.com/click-to-pay-customer-experience-guide/documentation) * Visão geral do produto Click to Pay: [`https://developer.mastercard.com/product/click-to-pay/`](https://developer.mastercard.com/product/click-to-pay/) ## Pré-requisitos * **SDKs da Mastercard integrados no seu front-end**: * Eles são responsáveis por obter `dpaId`, `correlationId`, `flowId` e `merchantTransactionId` da jornada de Click to Pay. * Em caso de dúvidas ou se desejar suporte para a integração ponta a ponta, entre em contato com o time Malga. * **Credenciais de API Malga** válidas (`x-api-key`, `x-client-id`); * **Validação da jornada**: em caso de implementação ponta a ponta, a Mastercard precisará homologar a jornada do cliente para atender os padrões da bandeira. * **Liability shift (opcional)**: * Para ter **100% de liability shift** quando houver autenticação, recomendamos configurar um `merchant` Malga onde **todos os provedores/adquirentes** suportem autenticação externa (MPI externo). Em cenário com provedores mistos, fallbacks podem direcionar a transação para um adquirente sem esse suporte e a transação poderá ficar **sem liability**. * Para esse cenário de liability shift, é requerido que MIDs estejam cadastrados nas configurações dos provedores/adquirentes dentro do `merchant` na Malga. * Saiba mais em [Liability shift](/documentations/payment-methods/click-to-pay/intro#liability-shift-troca-de-responsabilidade). ### Exemplo completo de requisição cURL ```bash theme={null} curl --request POST 'https://api.malga.io/v1/charges' \ --header 'x-api-key: ' \ --header 'x-client-id: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "", "amount": 10000, "currency": "BRL", "capture": true, "statementDescriptor": "Pedido 1234 - C2P", "paymentMethod": { "paymentType": "click_to_pay", "installments": 1 }, "paymentSource": { "sourceType": "wallet", "walletPayment": "credit", "walletClickToPay": { "dpaId": "694428e3-97e6-49df-a77d-16bac173e955", "correlationId": "34f4a04b.f28f13d9-79f9-4c88-aca5-3f04888f03a3", "flowId": "34f4a04b.f28f13d9-79f9-4c88-aca5-3f04888f03a3.1754052884", "merchantTransactionId": "0a4e0d3.34f4a04b.96dc7ec48081fda8c31f541fdcaca8325080d575" } } }' ``` > **Importante:** os valores de `correlationId`, `flowId` e `merchantTransactionId` do exemplo são ilustrativos. Na integração real, esses dados virão diretamente dos SDKs de Click to Pay da Mastercard durante a jornada do comprador. Já o `dpaId` é fornecido pelo time Malga. ## Quando usar Link de Pagamento x Integração direta * **Link de Pagamento com C2P**: * Ideal para começar rápido, sem precisar integrar o SDK da Mastercard; * Ótimo para vendas em canais sem checkout próprio (WhatsApp, redes sociais, atendimento humano). * **Integração via API de Cobranças com C2P (esta página)**: * Ideal para checkouts proprietários (web/app) que exigem controle total de UI/UX; * Permite personalizar completamente a jornada de Click to Pay, integrando diretamente os SDKs Mastercard e orquestrando a autenticação conforme suas regras de negócio. Caso você queira realizar uma integração ponta a ponta com os SDKs da Mastercard e tenha dúvidas sobre o desenho da solução, entre em contato com o time Malga para apoio técnico. # Começando em Click to Pay Source: https://docs.malga.io/documentations/payment-methods/click-to-pay/intro O **Click to Pay** (C2P) da Mastercard é uma experiência de pagamento digital que permite que clientes paguem em poucos cliques, sem digitar todos os dados do cartão a cada compra. A solução combina conveniência, segurança avançada e autenticação forte, aproveitando os recursos de tokenização e 3DS para reduzir fraude e melhorar conversão. Na Malga, o Click to Pay é exposto como um novo método de pagamento, totalmente integrado ao ecossistema Malga. Você pode utilizá-lo tanto via **Link de Pagamento** quanto via **integração direta na API de cobranças**. ![Click to Pay](https://mintcdn.com/malga/WKvAjWB9gShm652n/assets/images/payment-methods/click-to-pay/c2p-payment-link.png?fit=max\&auto=format\&n=WKvAjWB9gShm652n\&q=85\&s=b6eda8451d3ed9fd2af534f65a778d9d) > [card] [Link de Pagamento com Click to Pay](/documentations/payment-methods/click-to-pay/link-de-pagamento) > > Crie sessões (links) de pagamento que oferecem Click to Pay automaticamente > [card] [Integração via API de Charges](/documentations/payment-methods/click-to-pay/integracao-api-charges) > > Use Click to Pay diretamente pela API de cobranças > [card] [Guia oficial Mastercard](https://developer.mastercard.com/product/click-to-pay/) > > Consulte os detalhes completos da experiência Click to Pay ## Principais benefícios * **Experiência de checkout simplificada**: o cliente escolhe o cartão salvo em poucos cliques, sem precisar digitar número de cartão, validade e CVV em toda compra. Isso reduz atrito e abandono de carrinho. Consulte também o [guia de experiência oficial](https://developer.mastercard.com/click-to-pay-customer-experience-guide/documentation) da Mastercard. * **Segurança e autenticação forte**: o Click to Pay utiliza tokenização de bandeira e autenticação do portador, ajudando a reduzir fraude e aumentar a **taxa de aprovação**. * **Liability shift (troca de responsabilidade)**: quando a transação é autenticada, a responsabilidade por um eventual **chargeback** deixa de ser do lojista e passa a ser, em regra, do **emissor do cartão**. Isso reduz o risco financeiro do merchant e dá mais previsibilidade ao negócio. * **Integração flexível na Malga**: * via **Link de Pagamento**, para começar rápido ou vender em canais não estruturados (WhatsApp, redes sociais, etc.); * via **API de cobranças**, para um fluxo totalmente integrado ao seu front-end usando os SDKs de Click to Pay da Mastercard. > [!WARNING] > > Como o Click to Pay utiliza tokenização de bandeira, é necessário ter provedores suportados para a tokenização de bandeira. Consulte a [tabela de provedores e meios de pagamento suportados](/documentations/type-tables/payment-methods-by-providers) para mais informações. ## Liability shift (troca de responsabilidade) O Click to Pay pode oferecer liability shift quando há autenticação do portador. No entanto, para garantir a cobertura de responsabilidade em 100% das transações que passam por autenticação, observe as recomendações abaixo: * Recomendamos configurar um `merchant` Malga cujo conjunto de provedores/adquirentes suporte autenticação externa (MPI externo) em todos os fluxos. Assim, quando houver autenticação, o liability shift se mantém independentemente das retentativas internas. * Em cenários de `merchant` com provedores mistos (alguns adquirentes aceitam autenticação externa e outros não), durante fallbacks/retentativas a transação pode ser roteada para um adquirente sem suporte a autenticação externa. Nesses casos, mesmo que tenha havido autenticação prévia, a transação poderá não ter liability. * Caso o seu `merchant` Malga utilize apenas adquirentes que não suportam autenticação externa, as transações com Click to Pay continuarão funcionando normalmente, porém não haverá liability shift. ## Como o Click to Pay funciona na Malga De forma simplificada, o fluxo com C2P na Malga é dividido em duas partes: 1. **Configuração do dpaId** * Para usar Click to Pay via **Link de Pagamento**, é necessário configurar o `dpaId` (Digital Payment Application ID) nas configurações de `settings` através do endpoint `/v1/settings`. O campo `mastercardClickToPayDpaid` é opcional e pode ser configurado no POST ou atualizado via PATCH. * Para **integração via API de cobranças**, o `dpaId` é fornecido pelo time Malga e enviado diretamente no contrato da API de cobranças. 2. **Criação da transação com Click to Pay** * **Link de Pagamento**: você cria uma sessão, envia que usará Click To Pay como método e o front do Link identifica automaticamente o Click to Pay disponível quando o `dpaId` está configurado em `settings`, exibindo a experiência compatível com a Mastercard. * **API de Cobranças**: você cria a cobrança com o método `click_to_pay` preenchendo o objeto `walletClickToPay` com os dados retornados pelo SDK da Mastercard (`correlationId`, `flowId`, `merchantTransactionId`) e com o `dpaId` fornecido pelo time Malga. Detalharemos esses dois cenários nas próximas páginas desta seção. # Link de Pagamento com Click to Pay Source: https://docs.malga.io/documentations/payment-methods/click-to-pay/link-de-pagamento Ative o Mastercard Click to Pay no Link de Pagamento da Malga configurando o dpaId em settings e incluindo click_to_pay nos paymentMethods da sessão. O **Link de Pagamento da Malga** pode expor automaticamente a experiência **Mastercard Click to Pay (C2P)** quando o `dpaId` está configurado em settings e o método `click_to_pay` está incluído na lista de `paymentMethods` da sessão. ![Link de Pagamento com Click to Pay](https://mintcdn.com/malga/WKvAjWB9gShm652n/assets/images/payment-methods/click-to-pay/c2p.gif?s=e191c91b2b4510232c23889bd793fc53) ## Pré-requisitos * **Configuração do dpaId em Settings**: * É necessário configurar o `dpaId` (Digital Payment Application ID) nas configurações de settings através do endpoint `/v1/settings`. * O campo `mastercardClickToPayDpaid` é opcional e pode ser configurado no POST ou atualizado via PATCH. * O `dpaId` é fornecido pela equipe Malga em conjunto com o seu provedor/adquirente. * **Credenciais de API Malga** válidas (`x-api-key`, `x-client-id`). * **Liability shift (opcional)**: * Para ter **100% de liability shift** quando houver autenticação, recomendamos configurar um `merchant` Malga onde **todos os provedores/adquirentes** suportem autenticação externa (MPI externo). Em cenário com provedores mistos, fallbacks podem direcionar a transação para um adquirente sem esse suporte e a transação poderá ficar **sem liability**. * Para esse cenário de liability shift, é requerido que MIDs estejam cadastrados nas configurações dos provedores/adquirentes dentro do `merchant` na Malga. * Saiba mais em [Liability shift](/documentations/payment-methods/click-to-pay/intro#liability-shift-troca-de-responsabilidade). ## Configurando o dpaId em Settings Para habilitar o Click to Pay no Link de Pagamento, é necessário configurar o `dpaId` nas configurações de settings. O campo `mastercardClickToPayDpaid` pode ser configurado no momento da criação (POST) ou atualizado posteriormente (PATCH). ### Exemplo de criação de settings com dpaId ```bash theme={null} curl --location 'https://api.malga.io/v1/settings' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: multipart/form-data' \ --form 'mainColor="#000000"' \ --form 'secondaryColor="#FFFFFF"' \ --form 'mastercardClickToPayDpaid="694428e3-97e6-49df-a77d-16bac173e955"' ``` ### Exemplo de atualização de settings com dpaId Via **multipart** (com ou sem outros campos): ```bash theme={null} curl --location --request PATCH 'https://api.malga.io/v1/settings' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: multipart/form-data' \ --form 'mastercardClickToPayDpaid="694428e3-97e6-49df-a77d-16bac173e955"' ``` Via **JSON** (somente campos textuais, sem logo): ```bash theme={null} curl --location --request PATCH 'https://api.malga.io/v1/settings' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "mastercardClickToPayDpaid": "694428e3-97e6-49df-a77d-16bac173e955" }' ``` > **Importante:** O `dpaId` é fornecido pela equipe Malga. Entre em contato com o suporte Malga para obter o `dpaId` do seu ambiente. ## Benefícios de usar C2P via Link de Pagamento * **Onboarding rápido**: você não precisa implementar o SDK de front-end da Mastercard imediatamente; basta configurar o `dpaId` em settings e usar o Link. * **Menos atrito no checkout**: principalmente em canais onde o cliente está em dispositivos móveis, o Click to Pay reduz o tempo para concluir a compra. * **Experiência refinada**: o Link de Pagamento passou pela homologação da Mastercard para oferecer a melhor experiência possível para o cliente. Se você deseja ter controle total da experiência de checkout e integrar diretamente o SDK da Mastercard no seu front-end, consulte a página de [**Integração via API de Charges com Click to Pay**](/documentations/payment-methods/click-to-pay/integracao-api-charges). ## Criando uma sessão (Link de Pagamento) com suporte a Click to Pay Depois de ter o `dpaId` configurado em settings, você pode criar uma **sessão de pagamento** que será usada como Link através do endpoint `/v1/sessions`. Se o `dpaId` estiver configurado e o método `click_to_pay` estiver incluído nos `paymentMethods`, o front do Link irá identificar a disponibilidade de C2P automaticamente. > [!NOTE] > > Caso o SDK do Click to Pay não esteja funcionando corretamente no momento, por indisponibilidade das bandeiras, o Link de Pagamento irá exibir o fluxo de cartão de crédito comum. Além disso, sempre que Click to Pay for um método de pagamento, ele não será obrigatório para o cliente, ele poderá optar por seguir com o fluxo de cartão de crédito comum. > > Para ter **cobertura completa de risco**, é possível combinar o Click to Pay com o 3ds agnóstico Malga, assim quando o cliente optar por não usar Click to Pay, usará cartão de crédito comum e cairá no fluxo de 3ds agnóstico. Exemplo de criação de sessão: ```bash theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "test", "merchantId": "", "amount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethods": [ { "paymentType": "click_to_pay", "installments": 1 }, { "paymentType": "credit", "installments": 1, "threeDS": { "enabled": true, "liabilityShiftRequired": false } }, { "paymentType": "pix", "expiresIn": 232 } ], "dueDate": "2025-12-11T09:28:45.000Z", "items": [ { "name": "Item", "description": "Item do carrinho", "unitPrice": 1000, "quantity": 1, "tangible": false } ] }' ``` ### Campos importantes * **`paymentMethods`**: * Obrigatório enviar o método `credit` junto com o `click_to_pay` para caso necessite de fallback ou o cliente não possua Click to Pay disponível; * As parcelas (`installments`) podem ser ajustadas conforme sua regra de negócio. ## Como o Link identifica que deve exibir Click to Pay? O front do Link de Pagamento da Malga verifica: 1. Se o `dpaId` está configurado em **settings** através do campo `mastercardClickToPayDpaid`. 2. Se o método de pagamento `click_to_pay` está incluído na lista de `paymentMethods` da sessão. 3. Se o usuário possui cartões de crédito compatíveis salvos ou o inserido é compatível. > [!NOTE] > > O Click to Pay dentro da Malga funciona com cartões de crédito **Visa e Mastercard.** Quando essas condições são atendidas, o Link passa a levar o usuário para a jornada Click to Pay, permitindo que o cliente selecione cartões já cadastrados na carteira C2P ou faça seu cadastro na carteira das bandeiras. # Pagamentos com cartão de crédito na Malga Source: https://docs.malga.io/documentations/payment-methods/credit-card Entenda como processar pagamentos com cartão de crédito na Malga, com o fluxo de cobrança via API de charges e a lista de adquirentes e PSPs suportados. A Malga realiza o papel de hub de pagamentos, porém não realiza a liquidação financeira, sendo necessário conta em uma instituição financeira integrante do sistema de pagamentos. Dessa forma, recebemos os dados enviados pelo cliente no [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca) e fazemos a comunicação com os adquirentes e PSPs. Confira abaixo a lista de provedores suportados para cobranças com Cartão de Crédito. ## Fluxo de pagamento * Para criar uma transação com Cartão basta o cliente informar o meio de pagamento *credit* na criação de uma cobrança e os dados que identifiquem o cartão; * Uma cobrança é feita no cartão através da instituição de pagamentos escolhida; * Após a confirmação do pagamento, o provedor de pagamento irá realizar a transferência de fundos para a conta do recebedor; * Posteriormente o cliente recebedor poderá ser notificado de que o pagamento foi cancelado ou contestado por suspeita de fraude diretamente pelo pagador junto ao seu banco emissor. ## Fluxo de pagamento associado ao customer * Criar um [customer](/api-reference/customers/criacao-de-novo-customer-para-cobranca); * Criar a [tokenização do cartão](/api-reference/tokens/criar-um-novo-token); * Criar um [card](/api-reference/cards/criar-novo-cartao-a-partir-de-token) através do token gerado; * Realizar a [associação](/api-reference/customers/adicionar-cartao-de-credito-ao-customer) do *card* com o *customer*; * Para verificar a associação do cartão ao customer, basta realizar a consulta por meio do [Serviço de card](/api-reference/cards/recuperar-detalhes-de-cartao); ## Provedores suportados Veja os provedores que suportam cobrança com cartão de crédito na nossa [tabela de provedores e meios de pagamento suportados](/documentations/type-tables/payment-methods-by-providers). Quando criada na Malga, a cobrança do tipo CARTÃO credit: * É registrada com status `authorized`, `pre_authorized` ou `failed`; * É possível realizar o estorno total ou parcial da cobrança; * É possível realizar a pré-autorização e captura da cobrança. ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é criada na Malga | | *transaction* | *pre\_authorized* | Evento enviado quando é pré-autorizado o pagamento, com reserva de saldo | | *transaction* | *authorized* | Evento enviado quando é autorizado o pagamento | | *transaction* | *failed* | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *canceled* | Evento enviado quando a cobrança é cancelada antes de ter sido capturada, não produzindo um estorno financeiro | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | | *transaction* | *charged\_back* | Evento enviado quando a cobrança é contestada por fraude | ## Exemplo de cobrança Realize uma cobrança a partir dos dados do cartão de crédito sem tokenizar usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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": false, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "4929564637987814", "cardCvv": "320", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "49d8a8cd-5d84-43f0-a2d7-c39950711892", "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "clientId": "d353deef-dacb-40a0-8cab-931ff773f274", "createdAt": "2021-03-23T15:12:38.379Z", "amount": 150, "originalAmount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": false, "status": "pre_authorized", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "a1d455eb-dafe-4a5c-b882-a5775422f850" }, "transactionRequests": [{ "id": "fcbc7c8e-9e01-4de5-aee3-a3e14832c804", "updatedAt": "2021-03-23T15:12:42.799Z", "createdAt": "2021-03-23T15:12:38.392Z", "idempotencyKey": "4473cbec-f4e4-4604-a472-a897cba8607f", "requestId": null, "providerId": "cb39fc36-8c4b-4deb-b0c1-2fdd8db2e1ab", "providerType": "STRIPE", "amount": 150, "authorizationCode": "", "authorizationNsu": "1616512362092", "responseCode": "20000", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": null }] } ``` ## Pré-autorização e captura > [!NOTE] > > Se o seu fluxo tem um provedor antifraude configurado, quem decide a captura > deixa de ser apenas o `capture` da cobrança: as opções do provedor antifraude > passam a definir se a transação é capturada, cancelada ou mantida > pré-autorizada depois da avaliação de risco. Veja > **[Começando em Antifraude](/documentations/anti-fraud/intro)** antes de > desenhar a sua conciliação. No fluxo de pagamentos por cartão é possível realizar uma autorização que reserva o saldo e fica pendente de uma captura posterior, ou você pode já autorizar o pagamento de maneira definitiva. Alguns lojistas optam por não capturar imediatamente a transação para poderem rodar um antifraude próprio após reservar o saldo no cartão, e dependendo do resultado da análise confirmar ou não a transação. A vantagem de estornar uma transação que ainda não tenha sido "capturada" é que o estorno é feito imediatamente na fatura do comprador. Em alguns casos, quando você tenta estornar uma transação já capturada, pode levar até 30 dias para constar o estorno na fatura. Por isso, muitos lojistas optam por não capturar automaticamente e fazer isso manualmente depois. O flag de `capture` serve para indicar se a transação deve ou não ser capturada. Na nossa API, caso você envie o atributo `capture: false`, iremos retornar a transação autorizada (saldo reservado no cartão) com status `pre_authorized`, sendo necessário que você faça um request no [Serviço de Captura](/api-reference/charges/capturar-cobranca-pre-autorizada) para forçar manualmente a captura da transação e liberar para liquidação na conta do provedor. Se a transação não for capturada em 7 dias o adquirente pode desfazer automaticamente a transação. Caso você envie o atributo `capture: true`, iremos retornar a transação autorizada com status `authorized`, não sendo necessária mais nenhuma ação. A transação já fica liberada para liquidação no adquirente e não precisa chamar o Serviço de Captura. Se o seu fluxo tem antifraude configurado e não usa fluxo de pagamentos, o `capture: true` funciona de outra forma. A Malga pré-autoriza a cobrança, que aparece como `pre_authorized` com `capture: false` durante a análise. Quando o antifraude aprova, a Malga captura sozinha, mesmo com `captureOnApproved: false`. Depois da captura, a transação fica `authorized` com `capture: true`. A aprovação precisa chegar em até 72 horas, e a Malga cancela automaticamente uma pré-autorização sem veredito nesse prazo. Esse recurso está em liberação gradual. Enquanto a sua conta não for liberada, a API responde `400` com a mensagem "The capture cannot be true in this operation". Fale com o suporte para habilitar. Veja os detalhes em **[Começando em Antifraude](/documentations/anti-fraud/intro)**. Em nosso dashboard, também é possível *capturar*. ## Estorno total ou parcial No fluxo de pagamento por cartão, é possível realizar um estorno no valor total ou parcial da cobrança. No caso de estorno parcial, o lojista opta por realizar um estorno com valor inferior ao valor da venda, sendo feito o reembolso do valor parcial estornado para o comprador, permanecendo a cobrança como autorizada para liquidação do valor restante para o lojista. Para realizar um estorno parcial, basta enviar na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) um `amount` inferior ao valor original da transação, sendo este `amount` do estorno o valor a ser estornado. Uma vez aprovada a solicitação de estorno parcial junto ao emissor do cartão, o `amount` da transação é então atualizado para o valor residual da transação após o estorno (valor da cobrança - valor estornado). > [!WARNING] > > O atributo `originalAmount` do objeto `charge` se mantém como o valor > originalmente autorizado na transação, é o valor inicial da transação quando > aprovada. Já o atributo `amount` do objeto `charge` é alterado a cada > solicitação de estorno parcial, mantendo o saldo residual a receber pelo > lojista. Importante ressaltar que podem ser realizadas diversas requisições de estorno parcial para uma mesma transação, sendo que a cada requisição nosso sistema verifica se o valor a ser estornado (o valor enviado na requisição de `void`) é menor ou igual ao valor residual da transação, não sendo possível estornar um valor superior. O histórico de requisições de estorno pode ser encontrado na listagem de `transactionRequests` do objeto `charge`. O status da transação permanecerá como `authorized` ou `pre_authorized` enquanto restar valor a ser pago ao lojista, sendo alterado para `voided` somente quando o estorno zera todo o valor a receber do lojista. ## Reversão automática de um estorno (revert\_void) Os estornos recusados são eventos relativamente raros, mas podem ocorrer em circunstâncias específicas. A causa principal desses casos está muitas vezes relacionada com a abertura de chargebacks pouco tempo antes do estorno ser solicitado. Isso pode resultar em processamentos assíncronos, especialmente em sistemas legados de emissores, nos quais as transações não são tratadas de forma síncrona. Um dos provedores que implementa essa funcionalidade de reversão de estorno é a ADYEN. > [!NOTE] > > Embora raro, um reembolso pode falhar após você ter recebido um webhook de REEMBOLSO com success: true. Um webhook de REEMBOLSO bem-sucedido significa que nossas validações foram bem-sucedidas e enviamos a solicitação de reembolso para o esquema do cartão. No entanto, o esquema do cartão ainda pode rejeitar o reembolso. Isso pode acontecer mesmo alguns dias após você enviar a solicitação de reembolso. > > Na maioria das vezes, a Adyen pode corrigir o problema, para que o comprador eventualmente receba os fundos. Às vezes, no entanto, você precisa tomar medidas por conta própria. Para saber por que um reembolso pode falhar e o que, se necessário, você precisa fazer em cada caso, consulte Reembolsos falhados. Veja mais em [https://docs.adyen.com/online-payments/refund/#refund-failed](https://docs.adyen.com/online-payments/refund/#refund-failed) ### Como a Malga trata os eventos de reversão de estorno? Quando a Malga recebe um evento de reversão de estorno por parte de algum provedor, criamos um novo evento requestType `revert_void` dentro da `transactionRequests` da charge. Esse evento é disparado via webhook através do evento `transaction.revert_void`. Consulte todos os [eventos de webhook disponíveis](/documentations/webhooks/webhook1-1#eventos-suportados-para-notificação-via-webhooks). Exemplo estorno total | # | Tipo de operação | Valor da operação | Valor atual da charge (amount) | Status | | - | - | - | - | - | | 1 | Autorização/Captura | 100 | 100 | authorized | | 2 | Estorno Parcial | 10 | 90 | authorized | | 3 | Estorno Total | 90 | 0 | voided | | 4 | Provedor solicitou reversão do estorno | 10 | 10 | authorized | Exemplo estorno parcial | # | Tipo de operação | Valor da operação | Valor atual da charge (amount) | Status | | - | - | - | - | - | | 1 | Autorização/Captura | 100 | 100 | authorized | | 2 | Estorno Parcial | 10 | 90 | authorized | | 3 | Estorno Parcial | 20 | 70 | authorized | | 4 | Provedor solicitou reversão do estorno | 10 | 80 | authorized | ## Tratando erros na captura e estorno As modificações feitas em uma cobrança para fins de estorno total, estorno parcial, ou captura podem retornar com erro no provedor. A fim de garantir o correto tratamento dos casos de exceção retornados pelos provedores nestas operações, nossa API, ao receber erro na captura/estorno, retorna HTTP Status Code 201, sendo criado um novo transactionRequest com o status `failed`, porém não é modificado o status original da transação. **É recomendado que você verifique o status do objeto charge retornado, ou o status do primeiro objeto da lista de transactionRequests para se certificar de que a operação foi realizada com sucesso.** > [!NOTE] > > Se o provedor recusar o estorno de uma cobrança muitas vezes, a Malga passa a recusar novas tentativas com os erros `429` ou `422`. Veja o que fazer em [Limite de falhas no estorno](/documentations/more/limite-falhas-estorno). ## Cobrando em outras moedas A Malga suporta realização de cobranças em diferentes moedas, possibilitando você processar o pagamento na moeda de preferência do comprador. Caso a moeda informada na cobrança seja diferente da moeda de origem do cartão do comprador, o mesmo pode ter que pagar taxa adicional no seu banco para compras no exterior. O comprador pode ainda ser cobrado uma taxa adicional pelo banco caso o cartão e o lojista estejam em países diferentes, mesmo a moeda sendo a mesma. A moeda deve ser enviada no campo `currency` do objeto `charge`, sendo a moeda `BRL` o valor default caso não seja informado pelo solicitante. O código da moeda deve ser enviado no padrão [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217), com todas as letras em maiúsculo. > [!NOTE] > > Importante: a aceitação da moeda é condicionada ao provedor de pagamentos > escolhido. Somente alguns provedores suportam cobrança em diferentes moedas. > Consulte o nosso suporte para saber se seu provedor suporta pagamentos em > outras moedas. Consulte a [tabela de moedas aceitas](/documentations/type-tables/currency-not-supportted). ## Split Consulte como criar uma transação utilizando **Split** [clicando aqui](/documentations/split/intro). # Drip Source: https://docs.malga.io/documentations/payment-methods/drip **[Drip](https://usedrip.com.br)** é uma solução de pagamento online que permite o pagamento de cobranças parceladas utilizando Pix e com cashback para os seus clientes. Para pagar com a Drip, o consumidor precisa abrir uma conta no sistema da Drip durante o processo de compra. A Malga realiza o papel de intermediador de pagamentos, portanto não realiza a liquidação financeira, sendo necessária conta ativa da Drip para utilizar este método de pagamento. ## Participantes de uma transação Drip * O recebedor, cliente da Malga que deve possuir uma conta ativa da Drip. * O pagador, um comprador que é um cliente pessoa física. ## Fluxo de pagamento Drip utilizando a API de cobranças com integração direta * Para criar uma transação com Drip basta informar o meio de pagamento `DRIP` na criação de uma cobrança e adicionar as informações dos itens presentes no checkout; * Uma cobrança é registrada diretamente no sistema da Drip e é retornada uma URL de redirecionamento para o fluxo de cadastro e pagamento dentro da plataforma da Drip; * O pagador deve realizar a confirmação da cobrança diretamente na plataforma da Drip; * Após confirmação do pagamento, a Drip enviará uma notificação para a Malga informando que o pagamento foi realizado; * Posteriormente o Cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso. Este processo está descrito nos diagramas a seguir: ![Fluxo Drip](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/drip-flux-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=98b0b5f829d84da3915d22de3ab1bd66) ![Fluxo Drip com Checkout](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/drip-flux-checkout-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=26c0f52a170060da3a582570cb29882a) Você pode consultar mais informações sobre a integração com checkout [neste link](/sdks/intro-sdk). > [!NOTE] > > As cobranças Drip são assíncronas por natureza, ou seja, ao criar uma nova > cobrança você terá a confirmação apenas da criação da cobrança e não de sua > conclusão. A autorização ou reprovação de uma cobrança é notificada através > dos [webhooks](/documentations/webhooks/webhook1-1). ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é registrada e o link de pagamento na Drip está disponível | | *transaction* | *authorized* | Evento enviado quando é reconhecida a confirmação do pagamento da cobrança na Drip | | *transaction* | *failed* | Evento enviado quando a cobrança não pôde ser registrada por motivo de falha durante a criação | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | ## Testando recebimento de notificação de cobrança Drip paga Para testar sua integração com os webhooks da Malga você pode desenvolver direto 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` e `voided`, dessa forma você consegue criar uma transação e simular o evento desejado. **Requisição para atualizar manualmente uma cobrança Drip como paga em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "authorized" }' ``` ## Exemplo de cobrança Realize uma cobrança Drip a partir dos dados do comprador usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). > [!WARNING] > > Caso deseje informar a quantidade máxima de parcelas para determinada > transação, basta informar o atributo "maxInstallments" no objeto de > paymentMethod. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "fd172279-e7cd-497b-8b7c-b74b428ed4a9", "amount": 100, "currency": "BRL", "orderId": "98848683521", "paymentMethod": { "paymentType": "drip", "maxInstallments": 12, "totalInstallments": 6, "firstInstallmentsDate": "2023-08-01", "items": [ { "id": "123", "quantity": 1, "title": "item title", "unitPrice": 100 } ], "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750" }, "successRedirectUrl": "http://your-service.com/success", "cancelRedirectUrl": "http://your-service.com/cancel" }, "paymentSource": { "sourceType": "customer", "customer": { "name": "Nome do Comprador", "phoneNumber": "xx999999999", "email": "email@docomprador.com", "document": { "number": "11111111111", "type": "cpf" }, "address": { "street": "Rua do Comprador", "streetNumber": "1", "zipCode": "00000-140", "country": "BR", "state": "RJ", "district": "Bairro", "city": "Cidade", "complement": "complemento" } } } }' < HTTP/2 201 { "id": "a2ab5b6c-157e-4614-96b5-3528c266f7ac", "clientId": "", "merchantId": "fd172279-e7cd-497b-8b7c-b74b428ed4a9", "description": null, "orderId": "98848683521", "createdAt": "2023-07-18T23:03:53.035Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": null, "capture": false, "isDispute": false, "status": "pending", "paymentMethod": { "paymentType": "drip", "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/192ff886-6421-4050-8bc8-916bde89cb5e", "items": [ { "id": "123", "quantity": 1, "title": "item title", "unitPrice": 100 } ], "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750" }, "successRedirectUrl": "http://your-service.com/success", "cancelRedirectUrl": "http://your-service.com/cancel" }, "paymentSource": { "sourceType": "customer", "customerId": "9fc04ce8-1de0-4ae6-b246-761ff84236fd" }, "transactionRequests": [ { "id": "ca47a4ae-9f2c-4f06-9d17-4a099d6fa575", "createdAt": "2023-07-18T23:03:53.048Z", "updatedAt": "2023-07-18T23:03:55.501Z", "idempotencyKey": "24428aba-e7a6-41cd-afdc-e8edff36ceb7", "providerId": "6c694668-5966-44c7-b720-c844fddab8a4", "providerType": "DRIP", "transactionId": "24428aba-e7a6-41cd-afdc-e8edff36ceb7", "amount": 100, "authorizationCode": "c428729c-6f38-4893-8cc3-3f2f5f608bf7", "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "2436ms", "drip": { "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/192ff886-6421-4050-8bc8-916bde89cb5e", "items": [ { "id": "123", "quantity": 1, "title": "item title", "unitPrice": 100 } ], "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750" }, "successRedirectUrl": "http://your-service.com/success", "cancelRedirectUrl": "http://your-service.com/cancel" } } ] } ``` > [!WARNING] > > Para criação de transações Drip é obrigatório o envio de paymentSource com > customer ou identificador de um customer que contenha endereço completo e > válido. ## Estorno Drip Requisições de estorno para cobranças Drip são tratadas de forma síncrona, ou seja, ocorrem no momento da requisição feita para a API da Malga. Em caso de estornos parciais do valor da compra, a transação permanecerá com status `authorized` caso ainda haja valor na cobrança a ser estornado. Quando o valor restante em uma cobrança é 0 seu status é atualizado para `voided`. ## Exemplo de solicitação de estorno Drip Quando uma requisição de estorno é feita, a API retorna uma transação com o status `voided` e uma `transactionRequest` do tipo `void` com o status `success`. Quando a requisição de estorno falha por algum motivo, a transação continua com o status `authorized` contendo uma `transactionRequest` do tipo `void` com o status `failed`. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges//void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 1200 }' < HTTP/2 201 { "id": "e531a709-6e45-45d4-8c0d-5331b94c6ee0", "clientId": "", "merchantId": "fd172279-e7cd-497b-8b7c-b74b428ed4a9", "description": null, "orderId": "98848683521", "createdAt": "2023-07-26T12:26:03.938Z", "amount": 1200, "originalAmount": 1200, "currency": "BRL", "statementDescriptor": null, "capture": false, "isDispute": false, "status": "voided", "paymentMethod": { "paymentType": "drip", "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/28ed14f9-27a6-4e2c-9663-55417f7587a7", "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "ab123cd456ef789" }, "items": [ { "id": "12345", "title": "Product 1", "quantity": 1, "unitPrice": 300 } ], "successRedirectUrl": "https://service-example.com/success", "cancelRedirectUrl": "https://service-example.com/cancel" }, "paymentSource": { "sourceType": "customer", "customerId": "3ca53fad-be06-4a30-94b6-2158ee4fc824" }, "transactionRequests": [ { "id": "d9ccba5f-f81f-4793-b3e1-2dd8e76364f7", "createdAt": "2023-07-26T12:40:32.489Z", "updatedAt": "2023-07-26T12:40:32.489Z", "idempotencyKey": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "providerId": "3a07f3b4-2ba4-4e41-9d1c-182f4824f3bc", "providerType": "DRIP", "transactionId": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "amount": 1200, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "responseTs": "460ms" }, { "id": "9a28b53d-b37f-4d72-af61-b02feeeba754", "createdAt": "2023-07-26T12:26:53.557Z", "updatedAt": "2023-07-26T12:26:53.557Z", "idempotencyKey": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "providerId": "3a07f3b4-2ba4-4e41-9d1c-182f4824f3bc", "providerType": "DRIP", "transactionId": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "amount": 1200, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null }, { "id": "a0a7f787-5e6a-4f5e-9e42-eef3af312c18", "createdAt": "2023-07-26T12:26:03.998Z", "updatedAt": "2023-07-26T12:26:04.717Z", "idempotencyKey": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "providerId": "3a07f3b4-2ba4-4e41-9d1c-182f4824f3bc", "providerType": "DRIP", "transactionId": "d4d69dd3-467f-4184-bbf7-7c2d2d2845c5", "amount": 1200, "authorizationCode": "1ec69ee3-072e-414c-8b54-442482be32de", "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "627ms", "drip": { "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/28ed14f9-27a6-4e2c-9663-55417f7587a7", "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "ab123cd456ef789" }, "items": [ { "id": "12345", "title": "Product 1", "quantity": 1, "unitPrice": 300 } ], "successRedirectUrl": "https://service-example.com/success", "cancelRedirectUrl": "https://service-example.com/cancel" } } ] } ``` ## Testando atualização de estorno Para testar uma atualização de estorno no sandbox da Malga você deve atualizar manualmente a transação com uma requisição, conforme descrito na seção de [recebimento de notificações](/documentations/payment-methods/drip#testando-recebimento-de-notificação-de-cobrança-drip-paga). **Requisição para atualizar manualmente uma cobrança Drip como estornada em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "voided" }' ``` # Começando em meios de pagamento Source: https://docs.malga.io/documentations/payment-methods/intro Conheça os meios de pagamento da Malga, como cartão de crédito, Pix e boleto, e os parâmetros de paymentMethod e paymentSource usados em cada cobrança. As cobranças podem ser feitas através de diferentes meios de pagamento, devendo ser informado o meio desejado no objeto `paymentSource` da cobrança. Cada meio de pagamento utiliza um conjunto específico de parâmetros condicionais que são descritos a seguir: Um `paymentMethod` representa o meio de cobrança escolhido para processar a transação, os métodos suportados são: | PaymentMethod | Descrição | | - | - | | **credit** | Cobrança feita a partir de um cartão de crédito, suporta como sourceType: `card`, `token` ou `customer` | | **pix** | Cobrança feita a partir de QR Code dinâmico no formato Pix, suporta como sourceType: `customer` | | **boleto** | Cobrança feita a partir de Boleto registrado, suporta como sourceType: `customer` | | **nupay** | Cobrança feita a partir de Fluxo Transparente da Nupay for Business API, suporta como sourceType: `customer` | | **drip** | Cobrança feita a partir de Pix parcelado utilizando a Drip como provedor de processamento. Suporta como sourceType: `customer` | | **picpay** | Cobrança feita a partir de Wallet da PicPay Negócios API, suporta como sourceType: `customer` | | **click\_to\_pay** | Cobrança feita a partir de Click to Pay, suporta como sourceType: `wallet` | | **apple\_pay** | Cobrança feita a partir de Apple Pay, suporta como sourceType: `wallet` | Um `sourceType` representa os dados do pagador que serão utilizados para processar a transação, podendo ser um cartão, um token de cartão temporário, ou dados de um comprador: | SourceType | Descrição | | - | - | | **card** | Cobrança feita a partir de um cartão tokenizado usando o `cardId` ou com os dados abertos do cartão (cardNumber, cardHolderName, cardCvv, cardExpirationDate) | | **token** | Cobrança feita a partir de um token de cartão para cobrança sem recorrência usando `tokenId` | | **customer** | Cobrança feita a partir de comprador cadastrado usando o `customerId` | | **wallet** | Cobrança feita a partir de uma carteira de pagamento, suporta como sourceType: `click_to_pay`, `apple_pay` | ## Status da transação > Os status possíveis para uma transação na Malga são: | Status | Descrição | | - | - | | **pending** | Transação criada porém não concluiu processamento | | **pre\_authorized** | Transação pré autorizada com sucesso pendente a 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 da mercadoria | ## Rastreabilidade de cobranças O atributo `appInfo`, representa informações referentes a rastreabilidade sobre cobrança, tais como transações do produto, do dispositivo e sobre o sistema operacional, auxiliando na identificação, mapeamento e rastreabilidade dos recursos gerados nas transações. > [!WARNING] > > A passagem desse atributo é opcional. [Saiba mais no serviço de Charges](/api-reference/charges/realizar-nova-cobranca). | Atributo | Descrição | | - | - | | **Platform** | Informações sobre produto das transações (checkout-sdk, vtex, etc.) | | **Device** | Informações sobre o dispositivo (ios, android, windows, linux) | | **System** | Informações sobre o sistema proprietário de captura do merchant | # Múltiplos cartões Source: https://docs.malga.io/documentations/payment-methods/multiple-cards Cobre um pedido em 2 ou 3 cartões de crédito em uma única Venda (purchase), com captura automática ou explícita, cancelamento e estorno pela API da Malga. Com múltiplos cartões, você cobra um mesmo pedido em 2 ou 3 cartões de crédito em uma única operação. A cobrança é representada por uma **Venda** (`purchase`), que reúne o valor total e o valor de cada cartão. A Malga realiza o papel de hub de pagamentos, porém não realiza a liquidação financeira. Você envia os dados da Venda para o [serviço de Purchases](/api-reference/purchases/criar-nova-venda) e a Malga processa a cobrança de cada cartão com os adquirentes e PSPs. ## Regras da Venda * A Venda tem de 2 a 3 cartões em `payments`. * Todos os cartões são de crédito (`paymentType: credit`) e a moeda é `BRL`. * O valor total (`amount`) deve ser igual à soma dos valores dos cartões. O mínimo é de 200 centavos para a Venda e de 100 centavos para cada cartão. * Cada cartão é informado por referência, com `cardId` (cartão salvo) ou `tokenId` (token de cartão). Dados de cartão em claro são recusados com `pan_not_allowed`. * Cada cartão define o próprio número de parcelas em `paymentMethod.installments`. * A Malga processa os cartões na ordem em que eles aparecem em `payments`, a partir do `slotIndex` 0. ## Fluxo de pagamento * Crie a Venda em [`POST /v1/purchases`](/api-reference/purchases/criar-nova-venda), enviando o header `X-Idempotency-Key`. A resposta `202` traz `status: pending`, porque o processamento é assíncrono. * Consulte a Venda em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda) até ela chegar a `paid`, `failed` ou `cancelled`. * Acompanhe os marcos da Venda em [`GET /v1/purchases/{id}/history`](/api-reference/purchases/recuperar-o-historico-da-venda). ## Pagamento de um link ou de uma Session Para cobrar por um link de pagamento ou por uma Session, crie a Session com um item `paymentType: "multiple"` em `paymentMethods`. A configuração está em [Criar link de pagamento via API](/documentations/payment-link/create-link-using-api). Depois, pague a Session em [`POST /v1/sessions/{id}/purchase`](/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes). O valor, o merchant, a moeda, o modo de captura e as regras de split vêm da Session. Você informa apenas os cartões em `payments`, de 2 até o `quantity` configurado, e cada cartão respeita o limite de `installments` da Session. A chamada cria uma Venda e segue o mesmo fluxo descrito nesta página. > [!NOTE] > > Uma Session com múltiplos cartões não aceita `paymentType: multiple` em `POST /v1/sessions/{id}/charge`. Use sempre o endpoint `/purchase`. ## Captura O campo `capture` da criação define o que acontece depois das autorizações: | `capture` | Comportamento | | - | - | | `true` | A Malga captura automaticamente os cartões pré-autorizados. Se todos os cartões já estiverem `authorized`, a Venda vai direto para `paid`. | | `false` | A Venda permanece `pending` com os cartões `pre_authorized`. Você captura em [`POST /v1/purchases/{id}/capture`](/api-reference/purchases/capturar-venda-pre-autorizada), quando quiser. | > [!NOTE] > > A captura explícita só vale para Vendas criadas com `capture: false`. Em uma Venda criada com `capture: true`, a rota de captura devolve `409` com `purchase_invalid_state`. ## Status da Venda | Status | Descrição | | - | - | | **pending** | Venda em processamento ou com cartões pré-autorizados aguardando captura | | **paid** | Venda paga | | **failed** | Venda não concluída. Consulte `payments[].declineReason` para identificar o motivo | | **cancelled** | Pré-autorizações da Venda canceladas | Cada cartão da Venda também tem um status próprio em `payments[].status`: `pending`, `processing`, `undetermined`, `pre_authorized`, `authorized`, `failed`, `voided`, `canceled` ou `charged_back`. O status `authorized` indica cartão capturado. > [!WARNING] > > Se uma Venda `pending` trouxer o campo `pendingReview`, interrompa o polling automático. O campo indica uma anomalia no processamento (`reconciliation_failed`, `amount_mismatch` ou `claims_exhausted`) e a Venda permanece `pending`. ## Exemplo de cobrança O exemplo a seguir cria uma Venda de R\$ 150,00 em dois cartões, com captura automática. ```bash cURL theme={null} curl --request POST 'https://api.malga.io/v1/purchases' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'X-Idempotency-Key: checkout-pedido-1001-attempt-1' \ --header 'Content-Type: application/json' \ --data '{ "amount": 15000, "currency": "BRL", "capture": true, "merchantId": "6d5b0464-090b-480b-a4e9-e1a0fb60a495", "orderId": "pedido-1001", "payments": [ { "amount": 10000, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "3fd63170-ffa4-4b33-9d45-c3ab8fe6ce61", "cardCvv": "123" } }, { "amount": 5000, "paymentMethod": { "paymentType": "credit", "installments": 3 }, "paymentSource": { "sourceType": "token", "tokenId": "c9783dec-0900-401c-8946-58e1b626f85a" } } ] }' ``` A resposta `202` traz a Venda com `status: pending` e a operação `authorize` em andamento: ```json Resposta 202 theme={null} { "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "merchantId": "6d5b0464-090b-480b-a4e9-e1a0fb60a495", "amount": 15000, "currency": "BRL", "capture": true, "status": "pending", "orderId": "pedido-1001", "payments": [ { "slotIndex": 0, "amount": 10000, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "status": "pending", "refundedAmount": 0, "paymentSource": { "sourceType": "card", "cardId": "3fd63170-ffa4-4b33-9d45-c3ab8fe6ce61" } }, { "slotIndex": 1, "amount": 5000, "paymentMethod": { "paymentType": "credit", "installments": 3 }, "status": "pending", "refundedAmount": 0, "paymentSource": { "sourceType": "token", "tokenId": "c9783dec-0900-401c-8946-58e1b626f85a" } } ], "operation": { "id": "74739f85-1bfa-40ae-a003-1c464c8e3c94", "type": "authorize", "status": "pending" }, "createdAt": "2026-07-27T18:00:00Z", "updatedAt": "2026-07-27T18:00:00Z" } ``` ## Notificações por webhook Em vez de consultar a Venda continuamente, você pode receber os eventos `purchase.*` no seu endpoint: `purchase.created`, `purchase.charge_authorized`, `purchase.pre_authorized`, `purchase.paid`, `purchase.failed`, `purchase.cancelled` e `purchase.void_failed`. Cadastre o webhook na versão 1.1. Uma versão anterior não recebe eventos de Venda. Use a notificação como gatilho e confirme o estado em `GET /v1/purchases/{id}` antes de liberar o pedido. O formato de cada evento está em [Webhooks v1.1](/documentations/webhooks/webhook1-1#purchase). ## Idempotência O header `X-Idempotency-Key` é obrigatório na criação, na captura e no cancelamento de uma Venda. * Reenviar a mesma chave com o mesmo corpo devolve `202` com o estado atual da Venda. * Reenviar a mesma chave com um corpo diferente, ou com uma chave já usada em outra operação, devolve `409` com `idempotency_key_payload_mismatch`. ## Cancelamento e estorno Use [`POST /v1/purchases/{id}/void`](/api-reference/purchases/cancelar-ou-estornar-venda) para desfazer uma Venda, com o campo opcional `intent`: * `cancel`: cancela as pré-autorizações de uma Venda `pending`. A Venda termina `cancelled`. * `refund`: estorna o valor integral de uma Venda `paid`. A Venda permanece `paid`. Envie `intent` explicitamente para garantir que um cancelamento nunca vire estorno, caso a Venda seja capturada entre a sua leitura e a chamada. ## Split A Venda aceita `splitRules` no nível raiz, informado uma única vez para o pedido. A resposta devolve a parcela correspondente a cada cartão em `payments[].splitRules`. # NuPay Source: https://docs.malga.io/documentations/payment-methods/nupay NuPay é uma solução de pagamento online disponibilizada pela Nubank que visa reduzir custos operacionais e melhorar a experiência de compra com parcelamento, sem atrito e sem cartão de crédito. Para pagar com a NuPay, o consumidor precisa ser um cliente do Nubank e possuir pelo menos um cartão de crédito emitido pela instituição em seu nome. A Malga realiza o papel de intermediador de pagamentos, portanto não realiza a liquidação financeira, sendo necessária conta ativa da NuPay for Business para utilizar este método de pagamento. > [!WARNING] > > O processo de credenciamento da NuPay ainda está restrito para credenciamento > de muitos negócios. Caso tenha interesse em utilizar este método de pagamento > entre em contato com [suporte@malga.io](mailto:suporte@malga.io). ## Os participantes de uma transação NuPay * O recebedor, cliente da Malga que deve possuir uma conta ativa da NuPay for Business. * O pagador, um comprador que é um cliente Nubank. ## Fluxo de pagamento NuPay * Para criar uma transação com NuPay basta informar o meio de pagamento `NUPAY` na criação de uma cobrança, sua data de expiração e documentos que identifiquem o comprador; * Uma cobrança é registrada diretamente no sistema da NuPay e uma notificação é enviada para o celular do comprador; * O pagador deve realizar o pagamento da cobrança diretamente em seu aplicativo Nubank; * Após confirmação do pagamento, a NuPay enviará uma notificação para a Malga informando que o pagamento foi realizado; * Posteriormente o Cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso. Este processo está descrito no diagrama a seguir. ![Fluxo NuPay](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/nupay-flux-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=8c0edea4b6033801e25f5b8d540b3b59) > [!NOTE] > > As cobranças NuPay são assíncronas por natureza, ou seja, ao criar uma nova > cobrança você terá a confirmação apenas da criação da cobrança e não de sua > conclusão. A autorização ou reprovação de uma cobrança é notificada através > dos [webhooks](/documentations/webhooks/webhook1-1). ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é registrada e a notificação de cobrança foi enviada para o pagador | | *transaction* | *authorized* | Evento enviado quando é reconhecida a confirmação do pagamento da cobrança | | *transaction* | *failed* | Evento enviado quando a cobrança é negada pela NuPay antes de ter sido criada, sem estorno financeiro | | *transaction* | *canceled* | Evento enviado quando a cobrança é negada pela NuPay antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | ## Testando recebimento de notificação de cobrança NuPay paga Para testar sua integração com os webhooks da Malga você pode desenvolver direto 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 uma cobrança NuPay como paga em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "authorized" }' ``` ## Exemplo de cobrança Realize uma cobrança NuPay a partir dos dados do comprador usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "ad267927-1164-40d8-9f08-278584ed839a", "orderId": "5556", "amount": 100, "currency": "BRL", "paymentMethod": { "paymentType": "nupay", "taxValue": 1, "delayToAutoCancel": 200, "orderUrl": "https://order.com.br", "returnUrl": "https://return-url.com.br", "cancelUrl": "https://cancel-url.com.br" }, "paymentSource": { "sourceType": "customer", "customer": { "document": { "number": "36436702067", "type": "cpf" }, "name": "Jose das Flores", "email": "jose@gmail.com", "phoneNumber": "11998324141", "address": { "street": "Rua 1", "streetNumber": "120", "zipCode": "01714140", "state": "SP", "city": "São Paulo" } } }, "fraudAnalysis": { "customer": { "browser": { "ipAddress": "127.0.0.1" } }, "cart": { "items": [ { "sku": "123", "name": "desc", "quantity": 1, "unitPrice": 1, "risk": "Low" } ] } } }' < HTTP/2 201 { "id": "28d78514-1202-4509-8a21-5052b34d2b04", "clientId": "02bfba40-dd8f-481b-b298-69d7438d548e", "merchantId": "ab957580-33f4-45d2-9d1a-254234126c66", "description": null, "orderId": "8222", "createdAt": "2022-09-30T21:33:42.955Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": null, "status": "pending", "paymentMethod": { "paymentType": "nupay" }, "paymentSource": { "sourceType": "customer", "customerId": "310fb8ac-c74c-4016-b9f0-e8ab018d4ccb" }, "transactionRequests": [ { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "NUPAY", "transactionId": "775bae33-8083-482d-82ea-bd45028446bd", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "1084ms", "nupay": { "expiresIn": 200 } } ] } ``` > [!WARNING] > > Para criação de transações NuPay é obrigatório o envio das informações de > `cart`. ## Campos de redirecionamento, notificação e timeout do NuPay #### `delayToAutoCancel`: `number` (em segundos) Define o tempo máximo que o consumidor tem para aprovar o pagamento. * Após esse tempo expirar, o pagamento é automaticamente cancelado. * Valor padrão da Nubank: **1800 segundos (30 minutos)**. * Exemplo: `200`. #### `orderUrl`: `string` (URL) URL que direciona o consumidor a uma página de detalhes do pedido. * Deve conter as informações da compra relacionadas à transação. * Exemplo: `"https://order.com.br"`. #### `returnUrl`: `string` (URL) URL para a qual o consumidor será redirecionado após finalizar o pagamento com sucesso. * Idealmente, essa URL deve levar o consumidor de volta para o site onde ele iniciou a compra. * Um botão de "Retornar ao site" será exibido para o consumidor clicar. * Exemplo: `"https://return-url.com.br"`. #### `cancelUrl`: `string` (URL) URL que será acionada caso o consumidor decida cancelar a operação de pagamento. * Essa URL pode ser usada para registrar o cancelamento e redirecionar o usuário. * Exemplo: `"https://cancel-url.com.br"`. #### `callbackUrl`: `string` (URL) Endpoint do e-commerce que receberá notificações da plataforma **NuPay for Business** sobre atualizações do status do pagamento. * O protocolo (`https`) é obrigatório. * Exemplo: `"https://sua-loja.com.br/nupay/callback"`. ## Beneficiário final O beneficiário final é o destinatário efetivo dos valores de uma transação de pagamento. Informar os beneficiários finais atende às exigências da Circular BACEN 3.978/2020 sobre prevenção à lavagem de dinheiro e financiamento do terrorismo (PLDFT). Para informar os beneficiários finais de uma cobrança NuPay, envie o campo `recipients` dentro de `paymentMethod` na criação da cobrança. Trata-se de um array opcional, em que cada item representa um beneficiário final da transação. #### `referenceId`: `string` Identificador único do beneficiário final. * Exemplo: `"1c6381d1-9fcd-4e9a-a012-93cf0457dcb9"`. #### `name`: `string` Nome ou razão social do beneficiário final. * Exemplo: `"Example Company LTDA"`. #### `document`: `object` Documento de identificação do beneficiário final, composto por: * `country`: país de emissão do documento, no padrão ISO 3166-1 alpha-2. Exemplo: `"BR"`. * `type`: tipo do documento. Exemplo: `"cnpj"`. * `number`: número do documento conforme o tipo selecionado. Exemplo: `"12345678000195"`. #### `amount`: `number` (em centavos) Valor atribuído ao beneficiário final, em centavos. * Exemplo: `100`. ### Exemplo de cobrança com beneficiário final ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "ad267927-1164-40d8-9f08-278584ed839a", "orderId": "5556", "amount": 100, "currency": "BRL", "paymentMethod": { "paymentType": "nupay", "delayToAutoCancel": 200, "orderUrl": "https://order.com.br", "returnUrl": "https://return-url.com.br", "cancelUrl": "https://cancel-url.com.br", "recipients": [ { "referenceId": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "name": "Example Company LTDA", "document": { "country": "BR", "type": "cnpj", "number": "12345678000195" }, "amount": 100 } ] }, "paymentSource": { "sourceType": "customer", "customer": { "document": { "number": "36436702067", "type": "cpf" }, "name": "Jose das Flores", "email": "jose@gmail.com", "phoneNumber": "11998324141", "address": { "street": "Rua 1", "streetNumber": "120", "zipCode": "01714140", "state": "SP", "city": "São Paulo" } } } }' ``` ## Estorno NuPay O estorno NuPay, assim como a cobrança, acontece de forma assíncrona. Isto significa que uma vez solicitado é iniciado o processo de estorno, que terá seu prazo máximo para finalização determinado na propriedade `delayToCompose`, em dias. Isto acontece pois o processo de liquidação da NuPay é diário e é necessário utilizar saldo gerado em transações posteriores para compor o valor necessário do estorno. Caso queira mais informações sobre este processo, consulte a [documentação da NuPay sobre estorno](https://docs.nupaybusiness.com.br/#/checkout/guide/api/refunds/). O fluxo de um estorno está representado no diagrama a seguir. ![Fluxo de Estorno NuPay](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/nupay-void-flux-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=43c7ba28e2541278f553565668a22327) ## Exemplo de solicitação de estorno NuPay Quando uma solicitação de estorno é feita, é recebida de volta uma transação com status `refund_pending` e uma `transactionRequest` do tipo `void` com status `processing` informando que o estorno está sendo processado. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges//void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 100, "delayToCompose": 100 }' < HTTP/2 201 { "id": "28d78514-1202-4509-8a21-5052b34d2b04", "clientId": "02bfba40-dd8f-481b-b298-69d7438d548e", "merchantId": "ab957580-33f4-45d2-9d1a-254234126c66", "description": null, "orderId": "8222", "createdAt": "2022-09-30T21:33:42.955Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": null, "status": "refund_pending", "paymentMethod": { "paymentType": "nupay" }, "paymentSource": { "sourceType": "customer", "customerId": "310fb8ac-c74c-4016-b9f0-e8ab018d4ccb" }, "transactionRequests": [ { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "NUPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "1123ms", "nupay": { "refundId": "01a3df53-5360-448a-8622-2e6d63d3fead" } }, { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "NUPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null, "nupay": { "installmentsNumber": 1, "paymentType": "spintest-link" } }, { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "NUPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "1084ms", "nupay": { "expiresIn": 200 } } ] } ``` ## Testando atualização de estorno Ao criar um estorno para uma transação NuPay em nosso sandbox, o mesmo será criado com o status `refund_pending`. Para testar uma atualização de estorno no sandbox da Malga você deve atualizar manualmente a transação com uma requisição, conforme descrito na seção de [recebimento de notificações](/documentations/payment-methods/nupay#testando-recebimento-de-notificação-de-cobrança-nupay-paga). **Requisição para atualizar manualmente uma cobrança NuPay como estornada em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "voided" }' ``` # PicPay Source: https://docs.malga.io/documentations/payment-methods/picpay PicPay é uma solução que permite a realização de pagamentos online através do saldo disponível na carteira do aplicativo. ## Os participantes de uma transação PicPay * O recebedor, cliente da Malga que deve possuir uma conta ativa da PicPay Negócios. * O pagador, um comprador que é um cliente PicPay. ## Fluxo de pagamento PicPay * Para criar uma transação com picpay basta informar o meio de pagamento `picpay` na criação de uma cobrança, e os documentos que identifiquem o comprador; * Uma cobrança é registrada diretamente no sistema da PicPay; * O pagador deve realizar o pagamento da cobrança diretamente em seu aplicativo PicPay, através do qrcode ou código copia e cola, retornados pela PicPay; * Após confirmação do pagamento, a PicPay enviará uma notificação para a Malga informando que o pagamento foi realizado; * Posteriormente o Cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso. Este processo está descrito no diagrama a seguir. ![Fluxo PicPay](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/picpay-flux-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=a09ae9950fcd85ffbd3c515e894b2e16) > [!NOTE] > > As cobranças PicPay são assíncronas por natureza, ou seja, ao criar uma nova > cobrança você terá a confirmação apenas da criação da cobrança e não de sua > conclusão. A autorização ou reprovação de uma cobrança é notificada através > dos [webhooks](/documentations/webhooks/webhook1-1). ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é registrada e a notificação de cobrança foi enviada para o pagador | | *transaction* | *authorized* | Evento enviado quando é reconhecida a confirmação do pagamento da cobrança | | *transaction* | *failed* | Evento enviado quando a cobrança não é criada com sucesso, sem estorno financeiro | | *transaction* | *canceled* | Evento enviado quando a cobrança é negada pela PicPay antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *voided* | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | ## Testando recebimento de notificação de cobrança PicPay paga Para testar sua integração com os webhooks da Malga você pode desenvolver direto 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 uma cobrança PicPay como paga em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "authorized" }' ``` ## Exemplo de cobrança Realize uma cobrança PicPay a partir dos dados do comprador usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "ad267927-1164-40d8-9f08-278584ed839a", "orderId": "5556", "amount": 100, "currency": "BRL", "paymentMethod": { "paymentType": "picpay", }, "paymentSource": { "sourceType": "customer", "customer": { "document": { "number": "36436702067", "type": "cpf" }, "name": "Jose das Flores", "email": "jose@gmail.com", "phoneNumber": "11998324141", "address": { "street": "Rua 1", "streetNumber": "120", "zipCode": "01714140", "state": "SP", "city": "São Paulo" } } }, "fraudAnalysis": { "customer": { "browser": { "ipAddress": "127.0.0.1" } }, "cart": { "items": [ { "sku": "123", "name": "desc", "quantity": 1, "unitPrice": 1, "risk": "Low" } ] } } }' < HTTP/2 201 { "id": "28d78514-1202-4509-8a21-5052b34d2b04", "clientId": "02bfba40-dd8f-481b-b298-69d7438d548e", "merchantId": "ab957580-33f4-45d2-9d1a-254234126c66", "description": null, "orderId": "8222", "createdAt": "2024-08-10T21:33:42.955Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": null, "status": "pending", "paymentMethod": { "paymentType": "picpay", "qrCodeData": "00020101021226860014COM.PICPAY.P2B0164https://app.picpay.com/checkout/NjY4YmZhNjA5OTdhNTU2YTNmMGRmZTIy5204000053039865802BR5906PICPAY6009SAO PAULO62280524668bfa60997a556a3f0dfe2280580020COM.PICPAY.ECOMMERCE0107nc=true0219checkout=stepbystep6304B9EE", "qrCodeImageUrl": "https://...." "expiresIn": 1722971550 }, "paymentSource": { "sourceType": "customer", "customerId": "310fb8ac-c74c-4016-b9f0-e8ab018d4ccb" }, "transactionRequests": [ { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2024-08-10T21:33:42.969Z", "updatedAt": "2024-08-10T21:33:44.105Z", "idempotencyKey": "775bae33-8083-482d-82ea-bd45028446bd", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "43a107b3", "transactionId": "775bae33-8083-482d-82ea-bd45028446bd", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "requestStatusReason": null, "responseTs": "778ms" } ] } ``` ## Estorno PicPay O estorno PicPay, assim como a cobrança, acontece de forma assíncrona. Isto significa que uma vez solicitado é iniciado o processo de estorno, que terá seu prazo máximo para finalização determinado na propriedade `delayToCompose`, em dias. O fluxo de um estorno está representado no diagrama a seguir. ![Fluxo de Estorno PicPay](https://mintcdn.com/malga/irqyGqIoiWFdcZsU/assets/images/payment-methods/picpay-void-flux-ptbr.png?fit=max\&auto=format\&n=irqyGqIoiWFdcZsU\&q=85\&s=865d2f3c58d5d9b52d34b05b30443021) ## Exemplo de solicitação de estorno PicPay Quando uma solicitação de estorno é feita, é recebida de volta uma transação com status `refund_pending` e uma `transactionRequest` do tipo `void` com status `processing` informando que o estorno está sendo processado. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges//void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 100, "delayToCompose": 100 }' < HTTP/2 201 { "id": "28d78514-1202-4509-8a21-5052b34d2b04", "clientId": "02bfba40-dd8f-481b-b298-69d7438d548e", "merchantId": "ab957580-33f4-45d2-9d1a-254234126c66", "description": null, "orderId": "8222", "createdAt": "2022-09-30T21:33:42.955Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": null, "status": "refund_pending", "paymentMethod": { "paymentType": "picpay" "qrCodeData": "00020101021226860014COM.PICPAY.P2B0164https://app.picpay.com/checkout/NjY4YmZhNjA5OTdhNTU2YTNmMGRmZTIy5204000053039865802BR5906PICPAY6009SAO PAULO62280524668bfa60997a556a3f0dfe2280580020COM.PICPAY.ECOMMERCE0107nc=true0219checkout=stepbystep6304B9EE", "qrCodeImageUrl": "https://...." "expiresIn": 1722971550 }, "paymentSource": { "sourceType": "customer", "customerId": "310fb8ac-c74c-4016-b9f0-e8ab018d4ccb" }, "transactionRequests": [ { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "PICPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "1123ms" }, { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "PICPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null }, { "id": "170db522-7cae-4187-9577-2a8d295d85af", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "14bb5348-84b2-45e8-84cd-8c794e0d627c", "providerId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "providerType": "PICPAY", "transactionId": "bc8e72d2-88bf-4373-b53a-4f2ae34d4fe0", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "1084ms" } ] } ``` ## Testando atualização de estorno Ao criar um estorno para uma transação PicPay em nosso sandbox, o mesmo será criado com o status `refund_pending`. Para testar uma atualização de estorno no sandbox da Malga você deve atualizar manualmente a transação com uma requisição, conforme descrito na seção de [recebimento de notificações](/documentations/payment-methods/picpay#testando-recebimento-de-notificação-de-cobrança-picpay-paga). **Requisição para atualizar manualmente uma cobrança PicPay como estornada em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "voided" }' ``` # Pagamentos instantâneos com Pix na Malga Source: https://docs.malga.io/documentations/payment-methods/pix Aceite pagamentos instantâneos via Pix com a Malga como hub de pagamentos, integrando adquirentes e PSPs por QR Code dinâmico e API de charges. Pix é o pagamento instantâneo brasileiro. O meio de pagamento criado pelo Banco Central (BC) em que os recursos são transferidos entre contas em poucos segundos, a qualquer hora ou dia. É prático, rápido e seguro. O Pix pode ser realizado a partir de uma conta corrente, conta poupança ou conta de pagamento pré-paga. O Pix foi criado para ser um meio de pagamento bastante amplo. Qualquer pagamento ou transferência que hoje é feito usando diferentes meios (TED, cartão, boleto etc.), poderá ser feito com o Pix, simplesmente com o uso do aparelho celular. A Malga realiza o papel de hub de pagamentos, porém não realiza a liquidação financeira sendo necessário conta em uma instituição financeira integrante do sistema de pagamentos. Dessa forma, recebemos os dados enviados pelo cliente no [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca) e fazemos a comunicação com os adquirentes e PSPs. ## Os participantes do Pix * O recebedor, cliente da Malga que deve possuir uma conta em instituição financeira parceira para receber pagamentos via Pix. * Provedor de pagamento, instituição financeira onde o cliente possui conta, responsável pela emissão de um QR Code dinâmico com os dados bancários do recebedor e dados do produto ofertado. * O pagador, um comprador qualquer que deverá realizar o scan do QR Code dinâmico no aplicativo de instituição financeira de sua escolha para realizar o pagamento. ## Fluxo de pagamento Pix * Para criar uma transação com Pix basta o cliente informar o meio de pagamento Pix 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 pagamentos instantâneos do banco central e fica disponível para pagamento. Os dados do QR Code são retornados no formato de imagem, que pode ser escaneado pelo pagador, e código, que pode ser copiado pelo pagador; * O Cliente deve apresentar os dados da cobrança (imagem do qrcode ou código para copia e cola) 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 QR Code em instituição financeira de sua escolha; * Após confirmação do pagamento, o provedor de pagamento irá realizar a transferência de fundos via novo sistema de pagamentos instantâneos 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](/api-reference/customers/criacao-de-novo-customer-para-cobranca); * Criar um novo [charge](/api-reference/charges/realizar-nova-cobranca) 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 Pix Veja os provedores que suportam cobrança via pix na nossa [tabela de provedores e meios de pagamento suportados](/documentations/type-tables/payment-methods-by-providers). > [!TIP] > > A cobrança tipo Pix 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. ## 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 | | *transaction* | *refund\_pending* | Evento enviado quando é solicitado o estorno do Pix e ele ainda está em processamento | | *transaction* | *voided* | Evento enviado quando é recebida a confirmação de sucesso de estorno total ou parcial do Pix | > [!WARNING] > > É possível que o valor de pagamento de uma *transaction* Pix com status > *authorized* seja diferente do valor original de emissão do mesmo, como em > caso de juros, multa ou desconto sendo aplicados. Sempre verifique o campo > `amount` informado nas atualizações de *transactions* para confirmar o valor > pago. ## Estorno total ou parcial No fluxo de pagamento por Pix é possível realizar um estorno no valor total ou parcial da cobrança, dependendo da instituição financeira. No caso de estorno parcial o lojista opta por realizar um estorno com valor inferior ao valor da venda, sendo feito o reembolso do valor parcial estornado para o comprador, permanecendo a cobrança como autorizada para liquidação do valor restante para o lojista. Para realizar um estorno parcial, basta enviar na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) um `amount` inferior ao valor original da transação, sendo este `amount` do estorno o valor a ser estornado. Uma vez concluído o estorno parcial pelo provedor, o `amount` da transação é atualizado para o valor residual da transação após o estorno. > [!WARNING] > > O atributo `originalAmount` do objeto `charge` se mantém como o valor > originalmente autorizado na transação, é o valor inicial da transação quando > aprovada. Já o atributo `amount` do objeto `charge` é alterado a cada > solicitação de estorno parcial, mantendo o saldo residual a receber pelo > lojista. É importante ressaltar que podem ser realizadas diversas requisições de estorno parcial para uma mesma transação, e o valor a ser estornado não pode ser superior ao valor residual existente na transação, não sendo possível estornar um valor superior. O histórico de requisições de estorno pode ser encontrado na listagem de `transactionRequests` do objeto `charge`. > [!NOTE] > > O status da transação permanecerá como `authorized` enquanto restar valor a > ser recebido pelo lojista, sendo alterado para `voided` somente quando todo o > valor original da transação for estornado. Quando é feita a solicitação do estorno do Pix será adicionada no `transactionRequests` uma nova request com `requestType` `void` e `requestStatus` `processing`. Quando o estorno for finalizado será adicionada à lista de `transactionRequests` uma request com `requestType` `void` e `requestStatus` `success`. A operação de estorno de Pix é realizada de forma assíncrona. Quando recebida a requisição para solicitar estorno, o status da transação passa a ser `refund_pending` e é automaticamente atualizado para `voided` quando somos notificados pela instituição financeira da confirmação do estorno. ![Fluxo Estorno do Pix](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/payment-methods/pix-chargeback-flux-ptbr.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=72bb01b65fef8436e6cea34b66720ced) ## Provedores suportados para estorno de Pix | Provedor | Estorno total | Estorno parcial | | - | :-: | :-: | | ![](%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A>) Mercado Pago | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagarme-v5.svg) Pagar.me v5 | | | | ![](%0A\%0A\%0A\%0A\%0A\%0A>) BS2 | | | | ![](%0A\%0A\%0A\%0A>) Banco do Brasil | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/zoop.svg) Zoop | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagseguro.svg) PagSeguro | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/adyen.svg) Adyen | | | | ![](%0A\%0A\%0A>) SafraPay | | | ## Testando recebimento de notificação de Pix pago Para testar sua integração com os webhooks da Malga você pode desenvolver direto 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, refund\_pending e charged\_back. Desta forma você consegue criar uma transação e simular o evento desejado. **Requisição para atualizar manualmente um Pix como pago em sandbox** ```bash theme={null} curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "status": "authorized" }' ``` ## Exemplo de cobrança Realize uma cobrança Pix a partir dos dados do comprador usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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": "pix", "expiresIn": 3600 }, "paymentSource": { "sourceType": "customer", "customer": { "name": "Jose Bonifacio Da Silveira", "phoneNumber": "21 98889999099", "email": "jose@gmail.com", "document": { "number": "72912053013", "type": "cpf", "country": "BR" } } } }' < HTTP/2 201 { "id": "a1d455eb-dafe-4a5c-b882-a5775422f850", "clientId": "", "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": "pix", "expiresIn": 3600, "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0", "qrCodeImageUrl": "https://...." }, "paymentSource": { "sourceType": "customer", "customerId": "abe2d98a-0dc8-4c70-b108-c98eb24364ad" } } ``` ## Exemplo de estorno do Pix Realize um estorno do Pix a partir do id da transação usando a [Requisição de Estorno](/api-reference/charges/estornar-cobranca-aprovada). ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges//void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 150 }' < HTTP/2 200 { "id": "479718ee-2bd1-48fa-8a52-73320d0a05c2", "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "clientId": "", "description": null, "orderId": null, "createdAt": "2022-09-08T15:27:44.245Z", "amount": 150, "originalAmount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "status": "refund_pending", "paymentMethod": { "paymentType": "pix" }, "paymentSource": { "sourceType": "customer", "customerId": "4e0c085c-82c3-4585-a762-900758d22b51" }, "transactionRequests": [ { "id": "4a4a1cbf-fed7-4c88-8d42-276211372fa1", "createdAt": "2022-09-08T15:29:26.950Z", "updatedAt": "2022-09-08T15:29:26.950Z", "idempotencyKey": "f993ae69207a4c01a6fd0e5da343834c", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "MERCADO_PAGO", "transactionId": null, "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "713ms" }, { "id": "a0442940-85e3-4bb4-a3a4-84852a3f7dd0", "createdAt": "2022-09-08T15:28:48.199Z", "updatedAt": "2022-09-08T15:28:48.199Z", "idempotencyKey": "f993ae69207a4c01a6fd0e5da343834c", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": null, "transactionId": null, "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null, "pix": { "expiresIn": 3600, "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0", "qrCodeImageUrl": "https://...." } }, { "id": "086378e6-9776-461c-a287-f069491c789b", "createdAt": "2022-09-08T15:27:45.893Z", "updatedAt": "2022-09-08T15:27:52.406Z", "idempotencyKey": "f993ae69207a4c01a6fd0e5da343834c", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "MERCADO_PAGO", "transactionId": "25593931617", "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "1356ms" } ] } ``` ## Exemplo de retorno do Webhook Retorno do webhook quando é solicitado o estorno do Pix e o status do Pix é atualizado. ```bash theme={null} { "clientId":"", "event":"transaction.voided", "payload":{ "status":"voided", "id":"479718ee-2bd1-48fa-8a52-73320d0a05c2", "updatedAt":"2022-09-08T15:31:13.462Z", "createdAt":"2022-09-08T15:27:44.245Z", "idempotencyKey":null, "requestId":null, "orderId":null, "amount":150, "originalAmount":150, "currency":"BRL", "installments":null, "clientId":"", "statementDescriptor":"Pedido #231 loja joão", "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "capture":true, "isProcessing":false, "customerId":null, "description":null, "fee":null, "feeAmount":null, "transactionRequests":[ { "id":"086378e6-9776-461c-a287-f069491c789b", "updatedAt":"2022-09-08T15:27:52.406Z", "createdAt":"2022-09-08T15:27:45.893Z", "idempotencyKey":"f993ae69207a4c01a6fd0e5da343834c", "requestId":null, "providerId":"ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType":"MERCADO_PAGO", "networkTransactionId":"25593931617", "amount":150, "authorizationCode":null, "authorizationNsu":null, "requestStatus":"success", "requestType":"void", "responseTs":"1356ms", "pix":null, "boleto":null, "providerError":null, "providerAuthorization":null, "fraudAnalysis":null }, { "id": "4a4a1cbf-fed7-4c88-8d42-276211372fa1", "createdAt": "2022-09-08T15:29:26.950Z", "updatedAt": "2022-09-08T15:29:26.950Z", "idempotencyKey": "f993ae69207a4c01a6fd0e5da343834c", "providerId": "ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType": "MERCADO_PAGO", "transactionId": null, "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "713ms" }, { "id":"a0442940-85e3-4bb4-a3a4-84852a3f7dd0", "updatedAt":"2022-09-08T15:28:48.199Z", "createdAt":"2022-09-08T15:28:48.199Z", "idempotencyKey":"f993ae69207a4c01a6fd0e5da343834c", "requestId":null, "providerId":"ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType":null, "networkTransactionId":null, "amount":150, "authorizationCode":null, "authorizationNsu":null, "requestStatus":"success", "requestType":"authorization", "responseTs":null, "pix":{ "id":"3da31d03-8c11-4817-89a6-d18eec08f66a", "updatedAt":"2022-09-08T15:28:48.199Z", "createdAt":"2022-09-08T15:27:49.543Z", "qrCodeData": "00020101021126510014BR.GOV.BCB.PIX0129K89VdiUgWN1B3p0IHrgHkNHg9tX5F52040000530398654040.155802BR5913Customer test600062070503***630431C0", "qrCodeImageUrl": "https://....", "expiresIn":3600 }, "boleto":null, "providerError":null, "providerAuthorization":null, "fraudAnalysis":null }, { "id":"cd5d9ecf-0af5-4cdf-af57-2ca7aaf9f03d", "updatedAt":"2022-09-08T15:31:13.488Z", "createdAt":"2022-09-08T15:31:13.488Z", "idempotencyKey":"f993ae69207a4c01a6fd0e5da343834c", "requestId":null, "providerId":"ad2eb0c4-ea7b-4774-9ac9-3295b083b1cb", "providerType":"MERCADO_PAGO", "networkTransactionId":null, "amount":150, "authorizationCode":null, "authorizationNsu":null, "requestStatus":"success", "requestType":"void", "responseTs":null, "pix":null, "boleto":null, "providerError":null, "providerAuthorization":null, "fraudAnalysis":null } ], "transactionError":null, "fraudAnalysisMetadata":null } } ``` # Voucher Source: https://docs.malga.io/documentations/payment-methods/voucher São cartões de benefícios que as empresas dão aos seus colaboradores, utilizados para compras de produtos específicos como: **vale refeição** e **vale alimentação**. Antes o voucher só era utilizado por meio de maquininhas de cartões em compras presenciais, mas se tornou um método de pagamento muito requisitado no varejo online. Sua aceitação é uma forma de atender a essa demanda e oferecer mais comodidade e liberdade para os consumidores, fazendo com que os negócios tenham diversificação em suas opções de pagamento, ampliando assim seus potenciais clientes e aumentando as suas conversões. ## Fluxo do Voucher * Para uma transação com Cartão utilizando o método *Voucher*, é necessário informar o método de pagamento que seria voucher, source type card e os dados de identificação do cartão, em sua criação; * A cobrança será realizada no cartão através da instituição de pagamentos escolhida no caso o VR; * Após a confirmação do pagamento, o provedor de pagamento irá realizar a transferência de fundos para a conta do recebedor; * Posteriormente o cliente recebedor poderá ser notificado de que o pagamento foi realizado com sucesso e/ou estornado caso solicitado. ## Status do pagamento | objeto | evento | descrição | | - | - | - | | *transaction* | *authorized* | Status enviado quando é autorizado o pagamento | | *transaction* | *failed* | Status enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro | | *transaction* | *voided* | Status enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro | ## Provedores e voucher suportados Veja os provedores que suportam cobrança via voucher na nossa [tabela de provedores e meios de pagamento suportados](/documentations/type-tables/payment-methods-by-providers). ## Estorno total É possível realizar um estorno no valor total da cobrança. O histórico de requisições de estorno pode ser encontrado na listagem de `transactionRequests` do objeto `charge`. > [!WARNING] > > Não é possível realizar o *estorno parcial* no provedor VR. ## Exemplo de transação do voucher realizada com sucesso > [!WARNING] > > O voucher não utiliza o *capture*, portanto não precisa ser informado. ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "merchantId": "", "amount": 100, "currency": "BRL", "statementDescriptor": "Voucher", "orderId": "87f3464b-50b7-4651-a473-f885896dac00", "description": "87f3464b-50b7-4651-a473-f885896dac00", "paymentMethod": { "customer": { "name": "Jose das Flores", "identity": "11111111111", "billingAddress": { "zipCode": "01714140", "city": "São Paulo", "state": "SP", "country": "BR", "complement": "complement" } }, "paymentType": "voucher", "items": [ { "id": "123", "title": "ItemTeste1", "quantity": 1, "unitPrice": 100 } ] }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "Jose das Flores", "cardNumber": "4000000000000010", "cardCvv": "351", "cardExpirationDate": "12/2024" } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "3372a6bf-093a-4723-b1d8-9ac8abbea8f1", "clientId": "", "merchantId": "", "orderId": "87f3464b-50b7-4651-a473-f885896dac00", "createdAt": "2023-07-17T19:46:08.597Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Voucher", "capture": true, "isDispute": false, "status": "authorized", "paymentMethod": { "paymentType": "voucher" }, "paymentSource": { "sourceType": "card" }, "transactionRequests": [ { "id": "ed67074e-6b80-40c7-b2b0-9b1fbec8e0bb", "createdAt": "2023-07-17T19:46:08.627Z", "updatedAt": "2023-07-17T19:46:10.861Z", "idempotencyKey": "7ed5f493-b215-4980-b163-ef675e395f45", "providerId": "39a44f1c-18b4-43ff-8dff-ea9439a8ad06", "providerType": "SANDBOX", "transactionId": "e9244789-8a8c-44c8-a632-f9b66d359299", "amount": 100, "authorizationCode": "011056", "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": "2212ms" } ] } ``` ## Exemplo de transação do voucher realizada com falha ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "merchantId": "", "amount": 100, "currency": "BRL", "statementDescriptor": "Voucher", "capture": true, "orderId": "87f3464b-50b7-4651-a473-f885896dac00", "description": "87f3464b-50b7-4651-a473-f885896dac00", "paymentMethod": { "paymentType": "voucher" }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "ARACHANE CORTAS", "cardNumber": "6274160007023102", "cardCvv": "527", "cardExpirationDate": "12/2024" } } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "1525554e-7052-4613-a15c-6a4823e6feb6", "clientId": "", "merchantId": "", "description": "87f3464b-50b7-4651-a473-f885896dac00", "orderId": "87f3464b-50b7-4651-a473-f885896dac00", "createdAt": "2023-07-17T22:09:53.502Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Voucher", "capture": true, "isDispute": false, "status": "failed", "paymentMethod": { "paymentType": "voucher" }, "paymentSource": { "sourceType": "card" }, "transactionRequests": [ { "id": "3b66e42a-17f4-425f-b81c-ec1c436de736", "createdAt": "2023-07-17T22:09:53.542Z", "updatedAt": "2023-07-17T22:09:55.048Z", "idempotencyKey": "f0806ea8-59ac-4645-a503-f289937bbc8f", "providerId": "39a44f1c-18b4-43ff-8dff-ea9439a8ad06", "providerType": "SANDBOX", "transactionId": "22f62e40-3211-4dd1-b088-4174652347ba", "amount": 100, "authorizationCode": "011056", "authorizationNsu": null, "requestStatus": "failed", "requestType": "authorization", "responseTs": "1413ms" } ] } ``` ## Exemplo de transação do voucher com estorno realizado com sucesso ```bash theme={null} curl --location 'https://api.malga.io/v1/charges/3372a6bf-093a-4723-b1d8-9ac8abbea8f1/void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 100 }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { { "id": "a79fdcab-67cb-4c3c-bf16-e0bf12238474", "clientId": "", "merchantId": "", "description": "87f3464b-50b7-4651-a473-f885896dac00", "orderId": "87f3464b-50b7-4651-a473-f885896dac00", "createdAt": "2023-07-18T12:52:48.393Z", "amount": 0, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Voucher", "capture": true, "isDispute": false, "status": "voided", "paymentMethod": { "paymentType": "voucher" }, "paymentSource": { "sourceType": "card", "cardId": "e02ee38d-8619-4ff2-b4a7-dc8f6431a959" }, "transactionRequests": [ { "id": "181af4cd-c3de-4b64-80e4-c19fb763e100", "createdAt": "2023-07-18T12:53:16.692Z", "updatedAt": "2023-07-18T12:53:16.692Z", "idempotencyKey": null, "providerId": "1dd6be9a-df9b-4114-8c52-9152edee4727", "providerType": "VR", "transactionId": "128898e2ab7d41df99960859", "amount": 100, "authorizationCode": "011043", "authorizationNsu": "128898e2ab7d41df99960859", "requestStatus": "success", "requestType": "void", "responseTs": "2157ms", "providerAuthorization": { "networkAuthorizationCode": "011043", "networkResponseCode": "00" } }, { "id": "fd9ab999-2297-4735-8cf7-4c120632668b", "createdAt": "2023-07-18T12:52:48.579Z", "updatedAt": "2023-07-18T12:52:52.857Z", "idempotencyKey": "504bd233-03c3-457e-8024-ca63ba924bb1", "providerId": "1dd6be9a-df9b-4114-8c52-9152edee4727", "providerType": "VR", "transactionId": "128898e2ab7d41df99960859", "amount": 100, "authorizationCode": "011056", "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": "4236ms" } ] } ``` ## Exemplo de transação do voucher com estorno realizado com falha ```bash theme={null} curl --location 'https://api.malga.io/v1/charges/2af7f5f4-5e09-41c8-906c-cb31c89a49d9/void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 500 }' < HTTP/2 422 < content-type: application/json; charset=utf-8 { "error": { "type": "unprocessable_entity", "code": 422, "message": "Transaction failed" } } ``` # B2E Source: https://docs.malga.io/documentations/providers-antifraud/b2e Integração com o provedor de antifraude B2E na Malga, com análise assíncrona de risco para prevenção de fraudes em transações online. Provedor de soluções de prevenção a fraudes com foco em análise de risco para transações online. Em nossa integração, a B2E atua em modo assíncrono para avaliação das transações. [Mais informações.](https://www.b2egroup.com.br) ## Funcionalidades suportadas pelo antifraude | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/b2e.png) B2E group | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica ## Integrando a B2E ao seu checkout Esta seção guia você passo a passo para integrar a B2E ao seu fluxo de checkout, garantindo a correta prevenção de fraudes. ### 1. Obtenha seus dados de integração Após solicitar e receber os dados de integração com a B2E, configure-os no merchant da Malga. Estes dados são essenciais para autenticar e habilitar o serviço. * **api-key** e **client-id**: dúvidas sobre api-key e client-id consulte a página sobre [autenticação](/api-reference/authentication) para mais detalhes * **merchant-id**, **user**, **password**: converse com nosso time para obter as credenciais ```bash theme={null} curl --location 'https://api.malga.io/v1/merchants' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mcc": "4789", "providers": [ { "name": "B2E", "priority": 1, "credentials": { "type": "B2E", "merchantId": "", "user": "", "password": "" }, "options": { "type": "ANTIFRAUD", "captureOnApproved": true, "refundOnReproved": true, "runBeforeCharge": false } } ] }' ``` ### 2. Adicione os SDKs da B2E no seu checkout Inclua as bibliotecas necessárias para tracking e identificação do cliente no arquivo HTML do seu checkout. Estes SDKs são responsáveis por coletar dados importantes para análise antifraude. ```html index.html lines icon="html" theme={null} ``` Após a inclusão, os objetos \$infoReader (TrackMe) e a função capturar (Identity) estarão disponíveis globalmente no objeto window. ### 3. Configure a identificação do cliente Para realizar a identificação do pedido, serão necessárias 3 informações para a captura. * **sid**: Identificador numérico do cliente (ex: CPF ou CNPJ) * **key**: Chave fornecida pela B2E para autenticação no Identity SDK * **domain**: Identificação da página, com prefixo fixo fornecido junto com as chaves da B2E (ex: "MALGA\_CHECKOUT") ```javascript index.js lines icon="javascript" theme={null} // Identificador do cliente (CPF, CNPJ, etc.) let sid = 12345678900; // Chave de autenticação fornecida pela B2E let key = 4b884656-707d-46a2-9ff0-20a4be0772b5; // Prefixo para identificar o domínio/página atual let prefix = "MALGA_" // Executa o tracking com o SDK TrackMe $infoReader.run(sid, null, `${prefix}CHECKOUT`); // Executa a captura de identidade com o SDK Identity capturar({ sid: sid, key: key, domain: `${prefix}CHECKOUT`}); ``` Substitua os valores de sid e key pelos dados reais fornecidos para sua integração. ### 4. Envie os dados para análise B2E Após configurar os SDKs e o seu merchant Malga, a B2E realizará a análise dos dados coletados junto com as informações da compra enviadas via integração. ### 5. Crie uma transação com a API da Malga Adicione o objeto de [fraudAnalysis](/api-reference/charges/realizar-nova-cobranca#body-fraud-analysis) ao body quando realizar nova cobrança. ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --data-raw '{ "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "amount": 150, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "df8d2258-bf33-44e7-97d1-c4b9d0bedf7f", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964851", "identityType": "CPF", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", "cookiesAccepted": false, "email": "comprador@test.com.br", "hostName": "google.com", "ipAddress": "127.0.0.1", "type": "Chrome" } }, "cart": { "items": [ { "name": "ItemTeste1", "quantity": 1, "sku": "20170511", "unitPrice": 100, "risk": "High", "locality": "Local do evento", "date": "2017-03-21T22:36:53", "type": 1, "genre": "Concerto de música", "tickets": { "quantityTicketSale": 800, "quantityEventHouse": 2, "convenienceFeeValue": 0, "quantityFull": 100, "quantityHalf": 50, "batch": 1234123 }, "location": { "country": "BR", "street": "Rua Um", "number": "2", "zipCode": "02417140", "city": "Sao Paulo", "state": "SP", "district": "Bairro" } } ] } } }' ``` Para mais detalhes sobre como realizar uma nova cobrança, consulte a página de [novas cobranças](/api-reference/charges/realizar-nova-cobranca). Se você possui interesse em receber cotações e avaliar este provedor antifraude para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # ClearSale Source: https://docs.malga.io/documentations/providers-antifraud/clearsale Integração com o provedor de antifraude ClearSale na Malga, com análise de risco em modo realtime e assíncrono para e-commerce e pagamentos. A ClearSale é uma empresa brasileira especializada em soluções de prevenção e gestão de fraudes para e-commerce e meios de pagamento. Em nossa integração, pode atuar em modo realtime e/ou assíncrono para análise de risco de transações. [Mais informações.](https://www.clearsale.com.br/) ## Funcionalidades suportadas pelo antifraude | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Realtime Decision | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Tickets | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Total | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica ## Integrando a ClearSale ao seu checkout Esta seção guia você passo a passo para integrar a ClearSale ao seu fluxo de checkout, garantindo a correta prevenção de fraudes. ### 1. Obtenha seus dados de integração Após solicitar e receber os dados de integração, configure-os no merchant da Malga. Estes dados são essenciais para autenticar e habilitar o serviço. * **api-key** e **client-id**: dúvidas sobre api-key e client-id consulte a página sobre [autenticação](/api-reference/authentication) para mais detalhes * **merchant-id**, **username**, **password**: converse com nosso time para obter as credenciais * **app** (opcional): identifica o APP na ClearSale quando necessário para o [link de pagamento da Malga](/documentations/anti-fraud/malga-checkout) ```bash theme={null} curl --location 'https://api.malga.io/v1/merchants' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mcc": "4789", "providers": [ { "name": "CLEARSALE", "priority": 1, "credentials": { "type": "CLEARSALE", "name": "", "password": "", "app": "" }, "options": { "type": "ANTIFRAUD", "captureOnError": false, "captureOnApproved": true, "refundOnError": false, "refundOnReproved": true, "runBeforeCharge": false } } ] }' ``` O campo `credentials.app` é opcional e usado pelo fluxo de link de pagamento hospedado pela Malga. Ele não substitui a configuração do script de tracking no passo 2 quando você integra checkout ou link de pagamento próprio. Para mais detalhes sobre cadastro de merchants, consulte a página [criação de novos merchants](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) ### 2. Configure o script de tracking Se você usa checkout ou link de pagamento próprio, **deve** incluir o script de fingerprint da ClearSale no HTML. Para a captura, serão necessárias 2 informações: * **SEU\_APP**: nome do APP na ClearSale (obtido junto com eles) * **SEU\_SESSION\_ID**: valor que você enviará na cobrança em `fraudAnalysis.customer.browser.browserFingerprint`. Toda vez que o usuário deixar a página sem concluir a transação e retornar posteriormente esse valor deve ser atualizado. ```html index.html lines icon="html" theme={null} ``` Substitua os placeholders pelos valores reais da sua integração. ### 3. Crie uma transação com a API da Malga Adicione o objeto de [fraudAnalysis](/api-reference/charges/realizar-nova-cobranca#body-fraud-analysis) ao body quando realizar nova cobrança. Preencha `fraudAnalysis.customer.browser.browserFingerprint` com o `sessionId` obtido no passo 2. ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --data-raw '{ "merchantId": "", "amount": 150, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } }, "fraudAnalysis": { "mfa": { "smsOtpUsed": true, "emailOtpUsed": true }, "customer": { "name": "John Doe", "identity": "12345678909", "identityType": "CPF", "secondaryIdentity": "11222333000181", "secondaryIdentityType": "CNPJ", "email": "john.doe@example.com", "birthdate": "1990-01-01", "registrationDate": "2023-01-01 10:00:00", "phone": "+5511999999999", "maritalStatus":"Solteiro", "education":"Ensino Superior Completo", "billingAddress": { "street": "Rua A", "number": "123", "complement": "Apto 45", "zipCode": "01000-000", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Centro", "reference": "Próximo à praça" }, "deliveryAddress": { "street": "Rua B", "number": "456", "complement": "Casa", "zipCode": "02000-000", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Vila X", "reference": "Portão azul" }, "browser": { "browserFingerprint": "fp-abc-123", "cookiesAccepted": true, "email": "john.browser@example.com", "hostName": "example.com", "ipAddress": "203.0.113.10", "type": "Chrome" }, "gender": "male" }, "cart": { "items": [ { "name": "Produto 1", "quantity": 1, "sku": "SKU-001", "unitPrice": 1000, "risk": "Low", "description": "Descrição do produto", "categoryId": "123", "locality": "SP", "date": "2025-09-10 12:00:00", "type": 1, "genre": "xpto" } ], "isGift": true, "giftMessage": "Parabéns!" }, "device": { "id": "device-123", "os": { "type": "iOS", "version": "16.5" }, "model": "iPhone 14", "resolution": "1170x2532", "ramCapacity": 4096, "diskCapacity": 128000, "freeDiskSpace": 64000, "vendors": [ { "name": "carrier", "value": "Vivo" } ], "vendorAttributes": { "flash": true, "phoneCalls": true, "sendSms": true, "videoCamera": true, "cpuCount": 8, "simulator": false, "retinaDisplay": true, "frontCamera": true, "camera": true, "language": "pt-BR", "idiom": "pt-BR", "platform": "mobile", "name": "Apple", "family": "iPhone", "model": "14" } }, "airline": { "passengers": [ { "name": "John Doe", "companyMileCard": "LATAM", "mileCard": "MILE-12345", "identityType": "CPF", "identityNumber": "12345678909", "gender": "male", "birthdate": "1990-01-01", "cpf": "12345678909" } ], "connections": [ { "company": "LATAM", "identificationNumber": 1234, "date": "2025-09-15 10:00:00", "seatClass": "Economy", "origin": "GRU", "destination": "GIG", "boarding": "2025-09-15 09:30:00", "arriving": "2025-09-15 11:30:00", "fareClass": "Y" } ], "reservation": "2025-09-01" }, "orderOrigin": "web", "operationalSystem": "iOS 16.5", "marketplaceType": "b2c", "purchaseInformation": { "lastDateInsertedMail": "2025-06-01", "lastDateChangePassword": "2025-07-01", "lastDateChangePhone": "2025-06-15", "lastDateChangeMobilePhone": "2025-06-16", "lastDateInsertedAddress": "2025-05-20", "purchaseLogged": true, "email": "user@example.com", "login": "userlogin" }, "socialNetwork": { "optInCompreConfie": true, "socialNetworkType": "facebook", "authenticationToken": "token-abc" }, "giftList": { "type": "wedding_list", "id": "list-123" }, "hotels": [ { "name": "Hotel ABC", "city": "São Paulo", "state": "SP", "country": "BR", "reservationDate": "2025-10-01", "reserveExpirationDate": "2025-09-20", "checkInDate": "2025-10-05", "checkOutDate": "2025-10-10" } ], "country": "BR" } }' ``` Para mais detalhes sobre como realizar uma nova cobrança, consulte a página de [novas cobranças](/api-reference/charges/realizar-nova-cobranca). # Koin Source: https://docs.malga.io/documentations/providers-antifraud/koin Integre o antifraude Koin à Malga, com análise de risco realtime e assíncrona de transações online e funcionalidades suportadas pela API. Provedor de soluções de prevenção a fraudes especializado em análise de risco para transações online. A Koin oferece avaliação em tempo real e assíncrona, utilizando inteligência artificial para identificar e mitigar fraudes. [Mais informações.](https://www.koin.com.br) ## Funcionalidades suportadas pelo antifraude | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/koin.svg) Koin | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica ## Integrando a Koin ao seu checkout Esta seção guia você passo a passo para integrar a Koin ao seu fluxo de checkout, garantindo a correta prevenção de fraudes. ### 1. Obtenha seus dados de integração Após solicitar e receber os dados de integração com a Koin, configure-os no merchant da Malga. Estes dados são essenciais para autenticar e habilitar o serviço. * **api-key** e **client-id**: dúvidas sobre api-key e client-id consulte a página sobre [autenticação](/api-reference/authentication) para mais detalhes * **secret-key**: chave secreta de API fornecida pela Koin para autenticação * **org-id**: identificador da organização na Koin * **store-name**: identificador da loja utilizado para segmentar a análise de risco na Koin ```bash theme={null} curl --location 'https://api.malga.io/v1/merchants' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mcc": "4789", "providers": [ { "name": "KOIN", "priority": 1, "credentials": { "type": "KOIN", "secretKey": "", "orgId": "", "storeName": "" }, "options": { "type": "ANTIFRAUD", "captureOnApproved": true, "refundOnReproved": true, "runBeforeCharge": false } } ] }' ``` ### 2. Configure o fingerprint do dispositivo A Koin exige a integração do seu SDK JavaScript para coleta de fingerprint do dispositivo. Esta etapa é obrigatória para transações web e deve ser executada antes de enviar a requisição de cobrança. Inclua o script da Koin nas páginas de checkout do seu site. Utilize a URL de **sandbox** enquanto estiver testando a integração e altere para a URL de **produção** somente quando o merchant estiver configurado com as credenciais reais da Koin: ```html index.html lines icon="html" theme={null} ``` * **org-id**: identificador da organização fornecido pela Koin Após a inclusão, capture o `sessionId` gerado pelo SDK e envie-o no campo `browser.browserFingerprint` da requisição: ```javascript index.js lines icon="javascript" theme={null} // Gera e captura o session ID da Koin getSessionID(function (sessionId) { // Utilize o sessionId como browserFingerprint na requisição de cobrança console.log("Koin Session ID:", sessionId); }); ``` Alternativamente, se você já possui um session ID, pode passá-lo diretamente no atributo `session_id` da tag script (o exemplo abaixo utiliza a URL de sandbox; substitua pela URL de produção quando necessário): ```html theme={null} ``` Para mais detalhes, consulte a [documentação oficial da Koin](https://api-docs.koin.com.br/reference/javascript-integration). ### 3. Crie uma transação com a API da Malga Adicione o objeto de [fraudAnalysis](/api-reference/charges/realizar-nova-cobranca#body-fraud-analysis) ao body quando realizar nova cobrança. O campo `browser.browserFingerprint` deve ser preenchido com o session ID capturado pelo SDK da Koin. ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --data-raw '{ "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "amount": 15000, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "df8d2258-bf33-44e7-97d1-c4b9d0bedf7f", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964851", "identityType": "CPF", "birthdate": "1990-01-15T00:00:00.000Z", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "", "ipAddress": "127.0.0.1" } }, "cart": { "items": [ { "name": "Tênis Esportivo", "description": "Tênis esportivo masculino tamanho 42", "quantity": 1, "sku": "TNS-42-ESP", "unitPrice": 15000 } ] } } }' ``` Para mais detalhes sobre como realizar uma nova cobrança, consulte a página de [novas cobranças](/api-reference/charges/realizar-nova-cobranca). Se você possui interesse em receber cotações e avaliar este provedor antifraude para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Konduto Source: https://docs.malga.io/documentations/providers-antifraud/konduto Integração com o provedor de antifraude Konduto na Malga, com análise de risco baseada em machine learning em modo realtime e assíncrono. Provedor de soluções de prevenção a fraudes com foco em análise de risco para transações online, utilizando machine learning para avaliação do comportamento do comprador. A Konduto atua em modo realtime e assíncrono para avaliação das transações. [Mais informações.](https://www.konduto.com) ## Funcionalidades suportadas pelo antifraude | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/konduto.svg) Konduto | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica ## Integrando a Konduto ao seu checkout Esta seção guia você passo a passo para integrar a Konduto ao seu fluxo de checkout, garantindo a correta prevenção de fraudes. ### 1. Obtenha seus dados de integração Após solicitar e receber os dados de integração com a Konduto, configure-os no merchant da Malga. Estes dados são essenciais para autenticar e habilitar o serviço. * **api-key** e **client-id**: dúvidas sobre api-key e client-id consulte a página sobre [autenticação](/api-reference/authentication) para mais detalhes * **secret-key**: chave secreta de API fornecida pela Konduto para autenticação * **public-key**: chave pública da Konduto cadastrada no merchant Malga (`credentials.publicKey`) > [!NOTE] > > O campo `credentials.publicKey` identifica a sua loja na Konduto no contrato server-side com a Malga. **Não** é a chave pública do [Malga Checkout](/documentations/anti-fraud/malga-checkout), do [client-token](/documentations/welcome/authentication) nem da [Sessions API](/documentations/more/sessions). ```bash theme={null} curl --location 'https://api.malga.io/v1/merchants' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "mcc": "4789", "providers": [ { "name": "KONDUTO", "priority": 1, "credentials": { "type": "KONDUTO", "secretKey": "", "publicKey": "" }, "options": { "type": "ANTIFRAUD", "captureOnApproved": true, "refundOnReproved": true, "runBeforeCharge": false } } ] }' ``` ### 2. Configure o fingerprint do navegador A Konduto utiliza o fingerprint do navegador para enriquecer a análise de risco. Inclua o SDK da Konduto no HTML do seu checkout e capture o identificador do visitante antes de realizar a transação. Se você usa checkout ou link de pagamento próprio, **deve** configurar o fingerprint do navegador. O placeholder `` abaixo vem do portal da Konduto e alimenta apenas o script client-side. Para configurar o script de tracking, você precisa de **1 informação**: * **PUBLIC\_KEY**: chave pública obtida junto à Konduto ```html index.html lines icon="html" theme={null} ``` Após a inclusão do script, capture o identificador do visitante com `Konduto.getVisitorID()` e envie-o em `fraudAnalysis.customer.browser.browserFingerprint` na requisição de cobrança: ```javascript index.js lines icon="javascript" theme={null} // Aguarda a captura do fingerprint pela Konduto var period = 300; var limit = 20 * 1000 / period; var attempts = 0; var interval = setInterval(function() { var kId = Konduto.getVisitorID(); if (kId || attempts >= limit) { clearInterval(interval); // Utilize o kId como browserFingerprint na requisição de cobrança console.log("Konduto Visitor ID:", kId); } attempts++; }, period); ``` ### 3. Crie uma transação com a API da Malga Adicione o objeto de [fraudAnalysis](/api-reference/charges/realizar-nova-cobranca#body-fraud-analysis) ao body quando realizar nova cobrança. O campo `browser.browserFingerprint` deve ser preenchido com o visitor ID capturado pelo SDK da Konduto. ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'Content-Type: application/json' \ --header 'X-Api-Key: ' \ --header 'X-Client-Id: ' \ --data-raw '{ "merchantId": "38f43103-24b3-4349-9358-25d7c3975038", "amount": 15000, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "df8d2258-bf33-44e7-97d1-c4b9d0bedf7f", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardNumber": "5261424250184574", "cardCvv": "321", "cardExpirationDate": "06/2028", "cardHolderName": "JOAO DA SILVA" } }, "fraudAnalysis": { "sla": 10, "customer": { "name": "Joao Torres", "phone": "11 99329899", "email": "joao@gmail.com", "identity": "45762964851", "identityType": "CPF", "birthdate": "1990-01-15T00:00:00.000Z", "registrationDate": "2022-07-26T16:11:35.756Z", "billingAddress": { "street": "Rua Um", "number": "200", "zipCode": "02010010", "country": "BR", "state": "SP", "district": "Jardim Paraiso", "city": "Sao Paulo", "complement": "ap 10" }, "browser": { "browserFingerprint": "57d07c77f87f4cb38063dc4cb9fcb750", // kid Konduto "ipAddress": "127.0.0.1" } }, "cart": { "items": [ { "name": "Tênis Esportivo", "description": "Tênis esportivo masculino tamanho 42", "quantity": 1, "sku": "TNS-42-ESP", "unitPrice": 15000 } ] } } }' ``` Para mais detalhes sobre como realizar uma nova cobrança, consulte a página de [novas cobranças](/api-reference/charges/realizar-nova-cobranca). Se você possui interesse em receber cotações e avaliar este provedor antifraude para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Adyen Source: https://docs.malga.io/documentations/providers/adyen Métodos de pagamento e funcionalidades do provedor Adyen na Malga, com a tabela de suporte de cada recurso pela API. Plataforma global de pagamentos operando no Brasil desde 2011 como provedor de pagamentos, permite que as empresas aceitem moedas internacionais e processem alto volume de vendas em qualquer parte do mundo, com uma solução integrada de 3DS e diversos métodos como Cartão de crédito, PIX e boleto. [Mais informações.](https://docs.adyen.com/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2](/documentations/3ds2-malga/intro) > > Protocolo que permite prevenir e eliminar o risco de fraude em pagamentos > online ao permitir que o pagador se autentique durante o processo de compra > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Banco do Brasil Source: https://docs.malga.io/documentations/providers/banco-do-brasil Métodos de pagamento e funcionalidades do provedor Banco do Brasil na Malga, com a tabela de suporte de cada recurso pela API. Operando desde 1808, o Banco do Brasil fornece soluções robustas e completas de pagamento online, contando com o PIX na Malga, entrega serviços com segurança para e-commerces processarem seus transações. [Mais informações.](https://www.bb.com.br/site/developers/apis-para-o-seu-negocio/api-cobranca/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Banrisul Source: https://docs.malga.io/documentations/providers/banrisul Métodos de pagamento e funcionalidades do provedor Banrisul na Malga, com a tabela de suporte de cada recurso pela API. O Banrisul é o banco estatal do Rio Grande do Sul e atua como provedor de soluções financeiras e de pagamentos para empresas, oferecendo adquirência, cartões, crédito e gestão financeira. Suas soluções apoiam a eficiência operacional e a integração dos meios de pagamento dos clientes. [Mais informações.](https://developers.banrisul.com.br/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Barte Source: https://docs.malga.io/documentations/providers/barte Métodos de pagamento e funcionalidades do provedor Barte na Malga, com a tabela de suporte de cada recurso pela API. Em operação desde 2018, a Barte atua como plataforma de pagamentos focada em PMEs e também como provedor de crédito em até 21x, especializado em e-commerces com soluções para melhorar o fluxo de caixa e a liquidez para negócios B2B. [Mais informações.](https://barte.notion.site/Guia-de-Integra-o-d25d74ee606f4b9ab33efd9e6a4ea22e) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Bolt Source: https://docs.malga.io/documentations/providers/bolt Métodos de pagamento e funcionalidades do provedor Bolt na Malga, com a tabela de suporte de cada recurso pela API. Bolt é uma adquirente e operadora de cartões, que credencia estabelecimentos para aceitar transações com cartões de crédito e débito, comunicando-se com bandeiras e bancos para autorizar, capturar e liquidar pagamentos ao lojista. Além disso, oferece antecipação de recebíveis, de forma pontual ou automática, possibilitando maior flexibilidade e liquidez ao negócio. [Mais informações.](https://bolt.github.io/bolt-docs-ms-ecommerce-checkout/docs/introduction) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Braintree Source: https://docs.malga.io/documentations/providers/braintree Métodos de pagamento e funcionalidades do provedor Braintree na Malga, com a tabela de suporte de cada recurso pela API. A Braintree é uma empresa do grupo PayPal, com operação desde 2014 no Brasil, e que atua globalmente oferecendo soluções para pagamento online com recursos avançados de prevenção à fraude, conhecida pela flexibilidade e robustez das suas operações. [Mais informações.](https://developer.paypal.com/braintree/docs/start/overview) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Braspag Source: https://docs.malga.io/documentations/providers/braspag Métodos de pagamento e funcionalidades do provedor Braspag na Malga, com a tabela de suporte de cada recurso pela API. Integrante da Cielo, a Braspag oferece soluções de processamento de pagamentos na América Latina contando com Split e integrando diversos métodos de pagamento para e-commerces e marketplaces. Operando desde 2005, oferece segurança e praticidade para seus clientes operarem com Split e políticas financeiras de acordo com suas necessidades. [Mais informações.](https://www.braspag.com.br/docs) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [Split](/documentations/split/intro) > > Serviço que divide recebíveis de maneira automática, entre duas ou mais > partes envolvidas em uma transação # BS2 Source: https://docs.malga.io/documentations/providers/bs2 Métodos de pagamento e funcionalidades do provedor BS2 na Malga, com a tabela de suporte de cada recurso pela API. O BS2 nasceu em 2017 e é um banco digital inovador que oferece uma gama de serviços financeiros, incluindo pagamentos e soluções para vendas online, disponibilizando adquirência em métodos como PIX e boleto bancário, disponíveis através da Malga. [Mais informações.](https://devs.bs2.com/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Cielo Source: https://docs.malga.io/documentations/providers/cielo Métodos de pagamento e funcionalidades do provedor Cielo na Malga, com a tabela de suporte de cada recurso pela API. A Cielo atua desde 1995, e é referência em processamento de pagamentos no Brasil. Oferece soluções completas para vendas online por cartão de crédito, disponibilizando recursos com segurança e eficiência para lojas gerenciarem e operarem de forma flexível. [Mais informações.](https://desenvolvedores.cielo.com.br/api-portal/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Drip Source: https://docs.malga.io/documentations/providers/drip Funcionalidades do método de pagamento Drip na Malga, com a tabela de suporte de cada recurso pela API. Solução de pix parcelado, a Drip oferece uma forma inovadora de pagamento, facilitando o acesso a crédito e aumentando as opções para os consumidores e a conversão de vendas na loja. [Mais informações.](https://usedrip.com.br/para-e-comms) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] Pix Parcelado > > Forma de pagamento com parcelamento para Pix, permitindo a divisão da compra > em prestações de acordo com a opção mais conveniente para o cliente e a > loja. # Getnet SEP Source: https://docs.malga.io/documentations/providers/getnet-sep Métodos de pagamento e funcionalidades do provedor Getnet SEP na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo Santander e em operação desde 2003, a Getnet oferece diversos métodos de pagamento como crédito, PIX e boleto, para processamento de vendas online, com taxas atrativas para seus clientes e suportando altos volumes de venda através da sua solução. [Mais informações.](https://devportalgetnet.sensedia-eng.com/pt/products/online-payments/regional-api) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Itaú Source: https://docs.malga.io/documentations/providers/itau Métodos de pagamento e funcionalidades do provedor Itaú na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo Itaú Unibanco, o banco Itaú é conhecido pela confiabilidade e robustez no mercado brasileiro, oferecendo soluções financeiras e pagamentos para lojas online. Contando com taxas atrativas para os clientes que utilizam seu ecossistema bancário, proporciona vantagens com segurança para as lojas que optam pela sua adquirência. [Mais informações.](https://devportal.itau.com.br/baas/#/catalog/home-product/p/pix) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Klap Source: https://docs.malga.io/documentations/providers/klap Métodos de pagamento e funcionalidades do provedor Klap na Malga, com a tabela de suporte de cada recurso pela API. A Klap atua como provedor de pagamentos por cartão de crédito no Chile, oferecendo suporte a diferentes moedas para América Latina. Disponibiliza recursos com facilidade de uso e segurança para operações internacionais. [Mais informações.](https://www.klap.cl/developers/docapi) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Malga Source: https://docs.malga.io/documentations/providers/malga Métodos de pagamento e funcionalidades do provedor Malga na Malga, com a tabela de suporte de cada recurso pela API. Provedor próprio de pagamentos desenvolvido pela Malga, oferece uma solução nativa dentro da infraestrutura de orquestração da empresa. Suporta transações por crédito e PIX, oferecendo uma experiência segura, eficiente e com visibilidade completa das operações. É a escolha ideal para empresas que buscam uma experiência segura, com facilidade e bom desempenho. [Mais informações.](https://docs.malga.io/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [Split](/documentations/split/intro) > > Serviço que divide recebíveis de maneira automática, entre duas ou mais > partes envolvidas em uma transação # MapInvest Source: https://docs.malga.io/documentations/providers/mapinvest Métodos de pagamento e funcionalidades do provedor MapInvest na Malga, com a tabela de suporte de cada recurso pela API. A MapInvest é uma empresa de consultoria financeira com escritórios em Itajaí-SC e São Paulo-SP. Fundada em 1999, a empresa possui mais de 25 anos de experiência e oferece uma ampla gama de serviços financeiros para pessoas jurídicas, sempre agindo para facilitar a vida de outras empresas, pensando em somar e unir forças para o crescimento e fortalecimento de todos. [Mais informações.](https://developers.onz.software) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # Mercado Pago Source: https://docs.malga.io/documentations/providers/mercado-pago Métodos de pagamento e funcionalidades do provedor Mercado Pago na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo Mercado Livre e em operação desde 2004, a Mercado Pago atua como adquirente e plataforma de pagamentos para múltiplos métodos e moedas em transações online e offline, possuindo ampla participação de mercado no Brasil e América Latina. Oferece taxas atrativas e condições facilitadas para as lojas. [Mais informações.](https://www.mercadopago.com.br/developers/pt) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # NuPay Source: https://docs.malga.io/documentations/providers/nupay Métodos de pagamento e funcionalidades do provedor NuPay na Malga, com a tabela de suporte de cada recurso pela API. A NuPay é a plataforma de pagamento desenvolvida pelo Nubank, uma das maiores fintechs da América Latina. Ela foi criada para oferecer aos clientes uma maneira fácil e segura de realizar transações financeiras online. A NuPay integra-se diretamente com o aplicativo do Nubank, permitindo aos usuários fazer compras em lojas parceiras sem a necessidade de inserir dados de cartão de crédito, utilizando apenas a autenticação pelo app. [Mais informações.](https://docs.nupaybusiness.com.br/checkout/docs/openapi/#tag/Pagamentos/operation/PaymentsPost) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] Wallet > > Forma de pagamento facilitada através de carteiras digitais, com alta > conversão no checkout da loja devido à conveniência e segurança para o > cliente final. # Pagar.me v5 Source: https://docs.malga.io/documentations/providers/pagarme-v5 Métodos de pagamento e funcionalidades do provedor Pagar.me v5 na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo StoneCo, o Pagar.me atua desde 2013, oferecendo soluções avançadas de pagamento por crédito, boleto, PIX, voucher, contando com Split e outros recursos para lojas online. Conhecida pela flexibilidade e pela gama de serviços, entrega uma experiência segura para o processamento de vendas e prevenção de fraudes. [Mais informações.](https://docs.pagar.me/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [Split](/documentations/split/intro) > > Serviço que divide recebíveis de maneira automática, entre duas ou mais > partes envolvidas em uma transação > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # PagSeguro Source: https://docs.malga.io/documentations/providers/pagseguro Métodos de pagamento e funcionalidades do provedor PagSeguro na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo UOL e em operação desde 2006, o PagSeguro oferece soluções completas de pagamento para transações online, através de métodos como cartão de crédito e PIX, contando com ampla participação no mercado brasileiro. Destaca-se pela flexibilidade das suas soluções que atendem a negócios em diferentes estágios e segmentos. [Mais informações.](https://developer.pagbank.com.br/docs/o-pagbank) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Observações de integração ### Escolha da API da PagBank no cartão de crédito A PagBank tem duas APIs para cobrança no cartão de crédito. A API de Orders é a recomendada por ela. A PagBank trata a API de Charges como antiga, e essa API pode ser descontinuada. A Malga escolhe a API em cada cobrança a partir dos dados do comprador: * A cobrança vai para a API de Orders quando traz nome, e-mail e CPF ou CNPJ do comprador preenchidos. * A cobrança vai para a API de Charges quando algum desses dados não está preenchido. * O formato dos dados não muda a escolha da API. Se o e-mail ou o documento estiverem em formato inválido, a cobrança vai para a API de Orders e a PagBank a recusa com uma mensagem de erro. Nesse caso, corrija o dado e envie a cobrança novamente. Alguns provedores PagSeguro podem ter configuração específica combinada com a Malga. Nesse caso, a escolha da API segue essa configuração. ### Dados do comprador Cada dado do comprador vem do cadastro informado em `customerId`. Se o cadastro não tiver o dado, a Malga usa o que veio em `fraudAnalysis.customer`. Para a cobrança ir para a API de Orders, os três dados precisam estar preenchidos: | Dado | Cadastro do `customerId` | `fraudAnalysis.customer` | | - | - | - | | Nome | `name` | `name` | | E-mail | `email` | `email` | | CPF ou CNPJ | `document.type` e `document.number` | `identityType` e `identity` | Em compras entre empresas, informe como documento o CNPJ da empresa compradora. Os itens do pedido são opcionais e só são enviados à PagBank quando a cobrança vai para a API de Orders. Nesse caso, a Malga repassa os itens de `fraudAnalysis.cart.items`, o que ajuda na análise de risco do pedido. > [!NOTE] > > Na API de Orders, a PagBank aplica a própria análise de risco ao pedido, > independentemente do antifraude que você contratou na Malga. ### Como usar a API recomendada Envie em toda cobrança no cartão o `customerId` de um comprador [cadastrado](/api-reference/customers/criacao-de-novo-customer-para-cobranca) com nome, e-mail e documento: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "", "amount": 15000, "currency": "BRL", "capture": true, "customerId": "", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2030" } } }' ``` Ou envie os dados do comprador na própria cobrança, em `fraudAnalysis.customer`: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "", "amount": 15000, "currency": "BRL", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "120", "cardExpirationDate": "12/2030" } }, "fraudAnalysis": { "customer": { "name": "Jose das Neves", "email": "jose@exemplo.com.br", "identity": "72912053013", "identityType": "CPF" }, "cart": { "items": [ { "name": "Camiseta", "quantity": 1, "sku": "CAM-001", "unitPrice": 15000 } ] } } }' ``` ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # PayPal Source: https://docs.malga.io/documentations/providers/paypal Métodos de pagamento e funcionalidades do provedor PayPal na Malga, com a tabela de suporte de cada recurso pela API. O PayPal é uma das plataformas globais pioneiras em pagamentos digitais, atuando desde o fim dos anos 1990 na facilitação de transações online seguras entre consumidores e empresas. Presente em dezenas de países, oferece soluções para pagamentos com cartões, saldo digital e transferências internacionais, sendo amplamente utilizado em e-commerce e serviços digitais. [Mais informações.](https://developer.paypal.com/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # PicPay Source: https://docs.malga.io/documentations/providers/picpay Métodos de pagamento e funcionalidades do provedor PicPay na Malga, com a tabela de suporte de cada recurso pela API. O PicPay é a solução ideal para lojistas que desejam realizar vendas online de forma segura e eficiente. Vem dar mais pique no seu negócio com o Picpay! [Mais informações.](https://picpay.github.io/picpay-docs-ms-ecommerce-checkout/docs/introduction) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] Wallet > > Forma de pagamento facilitada através de carteiras digitais, com alta > conversão no checkout da loja devido à conveniência e segurança para o > cliente final. # Rede Source: https://docs.malga.io/documentations/providers/rede Métodos de pagamento e funcionalidades do provedor Rede na Malga, com a tabela de suporte de cada recurso pela API. A Rede é pioneira em meios de pagamento online no Brasil, oferecendo serviços para transações com cartões de crédito desde 1996. Parte do grupo Itaú, é referência em confiabilidade e suporte às lojas. [Mais informações.](https://developer.userede.com.br/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # SafraPay Source: https://docs.malga.io/documentations/providers/safrapay Métodos de pagamento e funcionalidades do provedor SafraPay na Malga, com a tabela de suporte de cada recurso pela API. Em operação desde 2014 e parte do grupo Safra, a SafraPay atua em soluções como provedor de pagamento por cartão de crédito e PIX, oferecendo tecnologia para lojas processarem vendas com segurança. > [!NOTE] > > A **notificação de abertura de disputa** na **SafraPay** está disponível em > **Beta**. Neste momento, a Malga recebe apenas o **webhook de início da > operação de disputa** (`transaction.dispute`); **não há integração com a API > completa de chargeback** do provedor. [Mais informações.](https://www.safrapay.com.br/venda-online/api-ecommerce.html) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Sandbox Source: https://docs.malga.io/documentations/providers/sandbox Métodos de pagamento e funcionalidades do provedor Sandbox na Malga, com a tabela de suporte de cada recurso pela API. Provedor disponibilizado pela Malga para realização de testes de integração e validação dos fluxos de pagamento, disponível para todas as operações e métodos suportados pela Malga. [Mais informações.](https://docs.malga.io/documentations/welcome/testing) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica ## Veja mais > [card] [3DS2](/documentations/3ds2-malga/intro) > > Protocolo que permite prevenir e eliminar o risco de fraude em pagamentos > online ao permitir que o pagador se autentique durante o processo de compra > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Stripe Source: https://docs.malga.io/documentations/providers/stripe Métodos de pagamento e funcionalidades do provedor Stripe na Malga, com a tabela de suporte de cada recurso pela API. A Stripe é uma plataforma de pagamentos global que opera no Brasil desde 2019, oferecendo infraestrutura completa para lojas processarem transações por cartão de crédito em diferentes países, além de métodos como o boleto. Referência internacional em segurança e robustez em pagamentos, possui uma ampla gama de serviços. [Mais informações.](https://docs.stripe.com/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # VR Source: https://docs.malga.io/documentations/providers/vr Métodos de pagamento e funcionalidades do provedor VR na Malga, com a tabela de suporte de cada recurso pela API. A VR oferece soluções de pagamento para benefícios de funcionários, incluindo vouchers de refeição, alimentação e transporte. Operando no Brasil desde 1977, é referência no mercado, conhecida pela diversidade de seus serviços em empresas. [Mais informações.](https://dev.vr.com.br/api-portal/content/primeiros-passos) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. # WorldPay Source: https://docs.malga.io/documentations/providers/worldpay Métodos de pagamento e funcionalidades do provedor WorldPay na Malga, com a tabela de suporte de cada recurso pela API. Parte do grupo FIS, a Worldpay oferece soluções de pagamento global, incluindo processamento de cartões, prevenção de fraudes e suporte a múltiplas moedas. Operando no Brasil desde 2015, destaca-se pela cobertura global e tecnologia avançada. > [!NOTE] > > O **Apple Pay** na **WorldPay** está disponível em **Beta**. A funcionalidade > já pode ser utilizada, mas o fluxo e a integração podem evoluir nas próximas > versões. [Mais informações.](https://developer.worldpay.com/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Zoop Source: https://docs.malga.io/documentations/providers/zoop Métodos de pagamento e funcionalidades do provedor Zoop na Malga, com a tabela de suporte de cada recurso pela API. Operando desde 2013, a Zoop oferece diversas soluções de pagamento para e-commerces e marketplaces, incluindo processamento de crédito, PIX, boleto e Split, reconhecida pela flexibilidade de seus serviços financeiros como provedor de pagamento. [Mais informações.](https://docs.zoop.co/) ## Funções por métodos de pagamento suportados | Serviços | Crédito | Pix | Boleto | Voucher | Apple Pay | | - | :-: | :-: | :-: | :-: | :-: | | Cobrança | | | | | | | Pré-autorização | | | | | | | Captura parcial | | | | | | | Estorno parcial | | | | | | | Estorno total | | | | | | | Split | | | | | | | Antifraude próprio | | | | | | | 3DS | | | | | | | Token de Bandeira | | | | | | | Validação de cartão (zero dollar auth) | | | | | | | Flag de recorrência | | | | | | | Notificação de abertura de disputa | | | | | | | Notificação de chargeback | | | | | | | Suporte a moedas internacionais | | | | | | Este serviço ou método é oferecido pelo provedor e suportado pela API da Malga Este serviço ou método não é oferecido pelo provedor Este serviço ou método é oferecido pelo provedor e ainda não é suportado pela API da Malga. Caso tenha interesse em utilizar este recurso, contate o nosso time de atendimento pelo e-mail [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io). Não se aplica Se você possui interesse em receber cotações e avaliar este provedor para o seu fluxo de pagamentos, entre em contato com o nosso time para avaliar. ## Veja mais > [card] [Split](/documentations/split/intro) > > Serviço que divide recebíveis de maneira automática, entre duas ou mais > partes envolvidas em uma transação > [card] [3DS2 Malga](/documentations/3ds2-malga/intro) > > Protocolo que reduz o risco de fraude ao autenticar o pagador durante a > compra, permitindo transações com múltiplos provedores sem nova autenticação > em retentativas # Começando em Split de pagamentos Source: https://docs.malga.io/documentations/split/intro Conheça os modos de uso do split de pagamentos na Malga: cobrança direta via POST /v1/charges ou regras configuradas na criação da sessão e link. O **Split de Pagamentos** é um serviço que divide recebíveis de maneira automática, entre duas ou mais partes envolvidas em uma transação, usado por marketplaces, franquias, aplicativos de delivery, entre outros tipos de negócios que têm a necessidade de fazer a divisão de recebíveis. ## Métodos de pagamento suportados Os métodos de pagamento suportados pelo serviço de split são: | Provedor | Cartão | Pix | Boleto | | - | - | - | - | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/braspag.svg) Braspag | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagarme-v5.svg) Pagarme v5 | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/pagseguro.svg) PagSeguro | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/zoop.svg) Zoop | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/malga.svg) Sandbox | | | | ## Recebedores do Split Os **recebedores (sellers)** precisam estar **cadastrados antes** de aparecer em `splitRules`. Na cobrança **direta** e na **criação da sessão** com split, os identificadores de seller informados devem corresponder a recebedores já existentes. O serviço de **sessions** valida essa existência ao criar a sessão; no fluxo da transação, a Malga trata o encadeamento com o provedor e o status do seller para a captura. Para cadastro e gestão, veja [**Recebedor (seller)**](/documentations/split/seller) e a [API de sellers](/api-reference/sellers/criacao-de-um-novo-recebedor). ## Dois modos de uso do split O split pode ser utilizado de duas formas; em ambas, cada regra referencia um `sellerId` válido. ### 1. Cobrança direta (`POST /v1/charges`) Você envia **`splitRules` no corpo** da criação da cobrança. A Malga aplica essas regras nessa transação. Guia completo: [Cobrança com Split](/documentations/split/split). ### 2. Sessão ou link de pagamento Você envia **`splitRules` ao criar a sessão** (`POST /v1/sessions`). As regras ficam **armazenadas na sessão**. No pagamento (`POST /v1/sessions/{id}/charge`), você **não** reenvia `splitRules`; a cobrança **herda** o split definido na sessão. Detalhes e exemplos: [Split em sessão ou link de pagamento](/documentations/split/split-em-sessao-link). > [!WARNING] > > Em pagamento de sessão, **não** inclua `splitRules` no corpo da requisição de cobrança. Configure o split apenas na criação da sessão. # Taxa da plataforma (platform-fee) no split Source: https://docs.malga.io/documentations/split/platform-fee Configure a taxa da plataforma (platform-fee) na Malga para cobrar uma comissão automática por método de pagamento sobre transações com split de sellers. Configure uma comissão sobre as transações da subconta, com ou sem split, aplicada automaticamente em cada cobrança. A taxa da plataforma (`platform-fee`) permite que intermediadores — marketplaces, SaaS de pagamentos e plataformas B2B — configurem uma comissão persistente sobre as transações dos seus sellers. Em vez de incluir a própria conta nas `splitRules` de cada cobrança, a plataforma define a taxa uma vez na subconta e a Malga aplica automaticamente antes de distribuir o valor restante entre os recebedores. > [!NOTE] > > O `platform-fee` é uma camada sobre o split de provedor. Na cobrança com `splitRules`, a taxa sai da parte dos sellers do split. Na cobrança **sem** `splitRules`, com a taxa ligada, a Malga cobra a taxa do único seller ativo da subconta, como descrito em [Venda sem split](#venda-sem-split). ## Como funciona A taxa da plataforma é simples de configurar e opera em três níveis: * Ativação: Uma flag no merchant habilita ou desabilita a aplicação das taxas. Enquanto desativada, nenhuma regra é aplicada nas transações, dando total controle sobre quando começar a cobrar. * Regras por método de pagamento: Cada regra define a taxa para um método específico (`credit`, `pix`, `boleto`). Não existe regra genérica: cada método que você vende precisa de regra própria. Para cartão de crédito, a taxa é definida por parcela: cada número de parcelas, de 1x a 24x, pode ter um valor diferente. A venda Apple Pay não paga a taxa da plataforma, com ou sem split. * Regras por seller: Um seller da subconta pode ter taxa própria em um ou mais métodos. Onde ele não tem regra própria, vale a regra da subconta. Veja [Taxa por seller](#taxa-por-seller). Quando uma cobrança é criada com `splitRules` e a subconta tem a taxa ligada, a Malga executa o seguinte antes de enviar ao provedor: 1. Calcula o valor da taxa sobre o montante bruto da transação 2. Subtrai esse valor para obter o valor líquido 3. Distribui o valor líquido entre os sellers declarados nas `splitRules` 4. O valor não declarado nos `splitRules` vai para a conta da plataforma O cliente nunca precisa incluir a própria conta nas `splitRules` — a fatia da plataforma é retida automaticamente. Quando algum seller da cobrança tem regra própria para o método e a parcela, a conta é feita seller a seller, como descrito em [Conta por seller](#conta-por-seller). Sem `splitRules`, a cobrança paga a taxa pelo único seller ativo da subconta, como descrito em [Venda sem split](#venda-sem-split). ## Configurando as regras As regras são configuradas no nível da subconta via API. Cada regra define o método de pagamento e o valor da taxa: percentual, valor fixo ou os dois combinados. | Campo | Descrição | | - | - | | `paymentMethod` | Método ao qual a regra se aplica: credit, pix ou boleto. A regra genérica `default` foi descontinuada e é recusada com `400`. | | `percentage` | Percentual da taxa (0-100), com até 2 casas decimais. | | `fixedAmount` | Valor fixo em centavos, de 0 a 2147483647. Pode coexistir com percentage na mesma regra. | | `installment` | Número exato de parcelas, de 1 a 24. Obrigatório na regra avulsa de credit; proibido nos demais métodos. | | `installmentRates` | Somente credit. Lista de percentuais em que a posição é o número de parcelas. | | `installments` | Somente credit. Lista de parcelas, cada uma com `installment`, `percentage` e `fixedAmount`. | | `maxInstallments`, `base`, `growth`, `surcharges`, `overrides`, `cap` | Somente credit. Fórmula que gera a tabela de parcelas. | O corpo da requisição aceita um array de regras ou um objeto com a lista em `rules`, com até 50 objetos de regra. Uma tabela ou fórmula de crédito conta como um objeto. Um corpo com mais de 50 é recusado com `400`. Os dois exemplos abaixo têm o mesmo efeito: ```json Array theme={null} [ { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 }, { "paymentMethod": "boleto", "fixedAmount": 109 } ] ``` ```json Objeto theme={null} { "rules": [ { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 }, { "paymentMethod": "boleto", "fixedAmount": 109 } ] } ``` > [!NOTE] > > Cadastre regra para cada método que você vende e, no crédito, para cada parcela. Com a taxa ligada, a venda, com ou sem split, num método ou numa parcela que não tem regra na subconta nem no seller é recusada com `422` e `platform_fee_rule_not_configured`, como descrito em Parcela sem regra própria. Consulte o contrato completo em [Criar regras de platform fee](/api-reference/merchants/criar-regras-de-platform-fee). ### Regra default descontinuada A regra genérica `paymentMethod: default` não existe mais. Antes de ela sair, a Malga converteu cada regra `default` em regras por método, com o mesmo valor, nos métodos que a subconta oferece. No crédito, a conversão gravou uma regra sem `installment`, que vale para toda parcela sem regra própria da subconta. Essa regra aparece em `rules` sem o campo `installment`, e não é criada pela API: a regra avulsa de crédito exige `installment`. `POST` e `PUT` com `paymentMethod: default`, na subconta ou no seller, respondem `400` com `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`, e nada é gravado. Cadastre regra para todo método e parcela que você vende, na subconta ou no seller, e use `coverage` para conferir o que falta. ## Taxa de crédito por parcela No cartão de crédito, cada número de parcelas tem a própria taxa, de 1x a 24x. Uma regra com `installment: 3` vale só para vendas em 3x, e a taxa de 3x pode ser diferente da taxa de 2x e da de 4x. A taxa incide sobre o valor total da venda, e não sobre o valor de cada parcela: ```text theme={null} fee = floor(amount * percentage / 100) + fixedAmount ``` Numa venda de R\$ 1.000,00 em 12x com taxa de 24,30%, a plataforma retém R\$ 243,00 e os recebedores dividem R\$ 757,00. Você pode cadastrar a tabela de crédito parcela a parcela ou por fórmula. Nos dois casos, a Malga grava uma regra por parcela, e é essa tabela que a cobrança usa. ### Cadastrando a tabela parcela a parcela A mesma tabela pode ser escrita de três formas. Use uma forma por objeto de regra. > [tab] Tabela curta > > Use `installmentRates` quando a tabela só tem percentual. A posição na lista é o número de parcelas: o primeiro item vale para 1x, o segundo para 2x, e assim por diante, até 24 itens. > > ```bash theme={null} > curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ > --header 'X-Client-Id: YOUR_CLIENT_ID' \ > --header 'X-Api-Key: YOUR_API_KEY' \ > --header 'Content-Type: application/json' \ > --data '{ > "rules": [ > { "paymentMethod": "pix", "percentage": 1.09, "fixedAmount": 30 }, > { "paymentMethod": "boleto", "fixedAmount": 109 }, > { > "paymentMethod": "credit", > "installmentRates": [2.99, 5.11, 6.86, 8.64, 10.45, 12.29, 14.45, 16.35, 18.29, 20.26, 22.26, 24.30] > } > ] > }' > ``` > > A requisição grava 12 regras de crédito, de 1x a 12x. As parcelas gravadas por `installmentRates` ficam sem valor fixo. > > A regra de tabela curta aceita só `paymentMethod` e `installmentRates`. Qualquer outra chave no mesmo objeto recusa a requisição com `400`, em vez de ser ignorada. > [tab] Tabela longa > > Use `installments` quando alguma parcela tem valor fixo ou quando você quer cadastrar só algumas parcelas. Cada entrada informa `installment` e ao menos um entre `percentage`, com até 2 casas decimais, e `fixedAmount`. A entrada não aceita outras chaves: um campo com grafia diferente, como `fixedamount`, recusa a requisição com `400`. A regra em volta também aceita só `paymentMethod` e `installments`. > > ```bash theme={null} > curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ > --header 'X-Client-Id: YOUR_CLIENT_ID' \ > --header 'X-Api-Key: YOUR_API_KEY' \ > --header 'Content-Type: application/json' \ > --data '{ > "rules": [ > { > "paymentMethod": "credit", > "installments": [ > { "installment": 1, "percentage": 2.99 }, > { "installment": 2, "percentage": 5.11, "fixedAmount": 50 }, > { "installment": 3, "percentage": 6.86, "fixedAmount": 50 } > ] > } > ] > }' > ``` > > A requisição grava 3 regras de crédito: 1x só com percentual, 2x e 3x com percentual e R\$ 0,50 fixos. > [tab] Regra avulsa > > Cada objeto descreve uma parcela, com `installment` e o valor da taxa. > > ```bash theme={null} > curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ > --header 'X-Client-Id: YOUR_CLIENT_ID' \ > --header 'X-Api-Key: YOUR_API_KEY' \ > --header 'Content-Type: application/json' \ > --data '[ > { "paymentMethod": "credit", "installment": 1, "percentage": 2.99 }, > { "paymentMethod": "credit", "installment": 2, "percentage": 5.11 }, > { "paymentMethod": "credit", "installment": 3, "percentage": 6.86 } > ]' > ``` A mesma parcela não pode aparecer duas vezes no corpo. O mesmo método também não pode aparecer duas vezes como tabela, nem como tabela e regra avulsa, na mesma requisição. Se alguma parcela já tiver regra, o `POST` retorna `409`: para alterar uma tabela existente, use o `PUT`, descrito em Atualizando a tabela de crédito. ### Cadastrando a tabela por fórmula Quando a taxa segue uma regra de crescimento, envie a fórmula e a Malga gera a tabela. A fórmula é calculada no cadastro: o que fica gravado é uma regra por parcela, de 1x até `maxInstallments`, e a fórmula em si não é armazenada. | Campo | Descrição | | - | - | | `maxInstallments` | Obrigatório. Última parcela gerada, de 1 a 24. | | `base` | Obrigatório. `percentage` (obrigatório) e `fixedAmount` de partida de todas as parcelas. | | `growth` | Como o percentual cresce: `mode`, `step`, `rate` e `from`. | | `surcharges` | Sobretaxas com `fromInstallment`, `percentage` e `fixedAmount`. Valem da parcela indicada em diante e se acumulam. | | `overrides` | Valor final de parcelas específicas, com `installment`, `percentage` e `fixedAmount`. Substitui o valor calculado. | | `cap` | Teto do percentual (`percentage`) e do valor fixo (`fixedAmount`) calculados. | Os modos de crescimento em `growth.mode`: | Modo | Efeito | Campos | | - | - | - | | `none` | Todas as parcelas ficam com o percentual da base. É o padrão. | Não aceita `step`, `rate` nem `from`. | | `linear` | Soma `step` pontos percentuais a cada parcela, a partir de `from`. | `step` obrigatório. `from` vai de 2 até `maxInstallments`, e o padrão é 2. | | `exponential` | Multiplica o percentual da base por `1 + rate` a cada parcela, a partir de `from`. `rate` é uma fração, e não um percentual: com 0.06, cada parcela fica 6% acima da anterior, e com 10, 1000% acima. | `rate` e `cap.percentage` obrigatórios. `from` como no `linear`. | Para cada parcela, a conta segue esta ordem: 1. Parte da `base`. 2. Aplica o crescimento, se a parcela for igual ou maior que `growth.from`. 3. Soma as sobretaxas cujo `fromInstallment` já foi alcançado. 4. Limita ao `cap`. 5. Substitui pelo `overrides` da parcela, se houver. 6. Arredonda o percentual para 2 casas decimais, com meio para cima. Exemplo com crescimento linear, uma sobretaxa a partir de 7x e teto: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "credit", "maxInstallments": 8, "base": { "percentage": 2.79 }, "growth": { "mode": "linear", "step": 0.20, "from": 2 }, "surcharges": [{ "fromInstallment": 7, "percentage": 0.50 }], "cap": { "percentage": 4.60 } } ] }' ``` A requisição grava oito regras de crédito: | Parcela | 1x | 2x | 3x | 4x | 5x | 6x | 7x | 8x | | - | - | - | - | - | - | - | - | - | | Percentual | 2,79% | 2,99% | 3,19% | 3,39% | 3,59% | 3,79% | 4,49% | 4,60% | Em 7x entra a sobretaxa de 0,50 ponto. Em 8x a conta daria 4,69%, e o teto limita o valor a 4,60%. A configuração inteira é recusada com `400` quando: * `growth.mode` é `exponential` e falta `cap.percentage`; * um item de `overrides` fica acima do `cap`; * alguma parcela calculada passa de 100%; * `maxInstallments` está ausente ou fora de 1 a 24; * uma sobretaxa não tem `percentage` nem `fixedAmount`, ou `surcharges` e `overrides` repetem a mesma parcela; * a regra ou algum objeto da fórmula traz uma chave desconhecida, como `capp` no lugar de `cap`. A regra de fórmula aceita só `paymentMethod`, `maxInstallments`, `base`, `growth`, `surcharges`, `overrides` e `cap`; * a fórmula vem fora de `credit` ou junto com `installmentRates`, `installments`, `installment`, `percentage` ou `fixedAmount`. ### Parcela sem regra própria Com a taxa ligada, a venda no crédito, com ou sem split, precisa de regra para a parcela vendida, na subconta ou no seller. Quando nenhuma das duas cobre a parcela, a cobrança é recusada com `422` e `platform_fee_rule_not_configured`, e `error.context` diz o seller, o método e a parcela. Vale o mesmo para Pix e boleto sem regra. Cadastre a tabela de crédito de 1x a 24x, ou ao menos até o maior número de parcelas que você vende. Por exemplo, com regras de crédito só em 1x, 2x e 7x: | Parcelas | Na cobrança | Na consulta | | - | - | - | | 1x, 2x e 7x | Usa a regra da própria parcela | `accepted: true` e `source: rule` | | 3x a 6x e 8x a 24x | Recusada com `platform_fee_rule_not_configured` | `accepted: false` e `reason: no_rule_configured` | Resposta da cobrança com split em 18x, sem regra para 18x na subconta nem no seller: ```json theme={null} { "error": { "type": "unprocessable_entity", "code": 422, "declined_code": "platform_fee_rule_not_configured", "details": ["No platform fee rule configured for seller 3b6ab810-6687-4ee2-ba72-2c1c71385512, payment method credit and installment 18."], "context": { "sellerId": "3b6ab810-6687-4ee2-ba72-2c1c71385512", "paymentMethod": "credit", "installment": 18 }, "message": "No platform fee rule is configured for this charge payment method and installment." } } ``` A consulta descrita em Consultando a taxa calculada mostra, parcela por parcela, qual regra a cobrança usa e quais parcelas ficam sem regra. ### Atualizando a tabela de crédito O `PUT /v1/merchants/{merchantId}/platform-fee` aceita o mesmo corpo do `POST`, e o efeito depende da forma: * Com `installmentRates`, `installments` ou fórmula, o `PUT` substitui a tabela de crédito inteira: atualiza as parcelas que já existem, cria as que faltam e remove as que ficaram de fora. As regras de `pix` e `boleto` não mudam, nem a regra de crédito sem `installment`, quando a subconta tem uma, como descrito em [Regra default descontinuada](#regra-default-descontinuada). * Com regra avulsa, o `PUT` atualiza só a regra da mesma parcela e só os campos enviados. Se a parcela não tiver regra, a resposta é `404`. O `PUT` é aplicado por inteiro ou não é aplicado. Se qualquer regra avulsa do corpo não existir, a resposta é `404` e nada muda, nem a tabela enviada na mesma requisição. A resposta de sucesso traz as regras como ficaram gravadas. > [!WARNING] > > Na substituição, a tabela enviada passa a ser a tabela inteira. Enviar três parcelas numa subconta que tinha doze deixa a subconta com três. As parcelas removidas deixam de ter regra própria na subconta e, sem outra regra que as cubra, a venda nelas é recusada com a taxa ligada, como descrito em Parcela sem regra própria. ```bash theme={null} curl --location --request PUT 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "credit", "installmentRates": [3.49, 5.90, 7.80] } ] }' ``` ## Consultando a taxa calculada O `GET /v1/merchants/{merchantId}/platform-fee` devolve as regras gravadas em `rules` e, junto, a conta feita: quanto a plataforma retém e quanto sobra para os recebedores em cada método e em cada parcela. Informe em `simulationAmount` o valor da venda simulada, em centavos. ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/platform-fee?simulationAmount=1000000' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Os blocos `simulation` e `methods` só vêm quando `simulationAmount` é enviado. `platformFeeEnabled`, `rules`, `sellerRules` e `coverage` vêm sempre. `sellerRules` e o estado por seller estão descritos em [Consultando as regras dos sellers](#consultando-as-regras-dos-sellers). Resposta para a tabela curta de 1x a 12x cadastrada acima, numa venda de R\$ 10.000,00. A lista `installments` traz sempre as 24 parcelas. A subconta não tem regra de 13x a 24x, e essas parcelas vêm com `accepted: false`, `reason: no_rule_configured` e sem os campos de taxa. O trecho abaixo omite `rules`, `sellerRules` e `coverage.merchant.methods` e mostra 1x, 2x, 12x e 13x: ```json theme={null} { "platformFeeEnabled": true, "simulation": { "amount": 1000000, "currency": "BRL" }, "methods": [ { "paymentMethod": "pix", "accepted": true, "source": "rule", "percentage": 1.09, "fixedAmount": 30, "fee": 10930, "sellerNet": 989070 }, { "paymentMethod": "boleto", "accepted": true, "source": "rule", "percentage": 0, "fixedAmount": 109, "fee": 109, "sellerNet": 999891 }, { "paymentMethod": "credit", "accepted": true, "installments": [ { "installment": 1, "accepted": true, "source": "rule", "percentage": 2.99, "fixedAmount": 0, "fee": 29900, "sellerNet": 970100, "buyerInstallmentAmount": 1000000 }, { "installment": 2, "accepted": true, "source": "rule", "percentage": 5.11, "fixedAmount": 0, "fee": 51100, "sellerNet": 948900, "buyerInstallmentAmount": 500000 }, { "installment": 12, "accepted": true, "source": "rule", "percentage": 24.3, "fixedAmount": 0, "fee": 243000, "sellerNet": 757000, "buyerInstallmentAmount": 83333 }, { "installment": 13, "accepted": false, "reason": "no_rule_configured" } ] } ], "coverage": { "merchant": { "missing": [], "warnings": ["credit sem regra em 13x a 24x; com a taxa ligada, a venda é recusada por falta de regra"] } } } ``` Campos de cada parcela em `installments`: | Campo | Descrição | | - | - | | `installment` | Número de parcelas, de 1 a 24. | | `accepted` | Indica se a venda nessa parcela, no valor simulado, passaria com a taxa calculada. | | `reason` | Presente quando `accepted` é `false`: `fee_exceeds_amount` quando a taxa é maior ou igual ao valor simulado, e `no_rule_configured` quando nenhuma regra cobre a parcela. Com `no_rule_configured`, a parcela vem sem os campos de taxa. | | `source` | De onde vem a taxa da parcela. É sempre `rule`, a regra cadastrada para a parcela. | | `percentage` e `fixedAmount` | Percentual e valor fixo aplicados. | | `fee` | Taxa sobre o valor total simulado, em centavos. | | `sellerNet` | Valor simulado menos a taxa, em centavos. É o que fica para os recebedores. | | `buyerInstallmentAmount` | Valor de cada parcela para o comprador, em centavos, arredondado para baixo. | Em `pix` e `boleto`, os campos de taxa vêm no próprio item do método, com `source: rule`. Sem regra, o item vem só com `{ "paymentMethod": "boleto", "accepted": false, "reason": "no_rule_configured" }`, e o método entra em `coverage.merchant.missing`. No crédito, a origem de cada parcela está em `installments[].source`. Em `coverage.merchant`, `missing` lista os métodos sem nenhuma regra aplicável, `warnings` traz avisos em texto, como a flag de ativação desligada ou as parcelas de crédito sem regra, e `methods` traz o estado de cada método e faixa de parcelas. Os avisos são para leitura humana: para tratar esses casos no código, use `source`, `accepted`, `reason` e `coverage.merchant.methods`. Consulte todos os campos da resposta em [Listar regras de platform fee](/api-reference/merchants/listar-regras-de-platform-fee). ## Taxa por seller Um seller da subconta pode ter taxa própria, diferente da taxa da subconta. A regra do seller substitui a regra da subconta para ele, método a método e só nas parcelas que ela cobre. O que a regra do seller não cobre continua seguindo a regra da subconta. Por exemplo, um seller com regra própria só no Pix paga a própria taxa no Pix e a taxa da subconta no boleto e no crédito. Um seller com tabela de crédito própria de 1x a 4x, numa subconta com tabela de 1x a 12x, paga a própria taxa de 1x a 4x e a da subconta de 5x a 12x. Antes de começar: * O seller precisa estar cadastrado na subconta em que você vai criar a regra. Seller de outra subconta, sem subconta ou de outro cliente responde `404` com `PLATFORM_FEE_SELLER_NOT_FOUND`. * A flag de ativação continua sendo da subconta e vale para todos os sellers dela. Não existe flag por seller. * Cada subconta pode ter até 200 sellers com regra própria, com a taxa ligada ou desligada. Só um seller novo conta: alterar as regras de quem já tem regra continua livre, e apagar todas as regras de um seller libera a vaga dele. Acima do limite, o `POST` de regra para um seller novo e o `PUT` com tabela de crédito para um seller novo respondem `422` com `PLATFORM_FEE_SELLER_LIMIT_REACHED`, e nada é gravado. O `PUT` de regra avulsa para um seller sem regra continua respondendo `404` com `PLATFORM_FEE_RULE_NOT_FOUND`. O limite é o mesmo para todas as subcontas. * Para ligar a taxa, a subconta precisa ter ao menos uma regra própria. Regras de seller não contam. Com a taxa ligada, a última regra da subconta não pode ser apagada: o `DELETE` responde `400` com `PLATFORM_FEE_RULES_REQUIRED_WHILE_ENABLED`. ### Criando as regras de um seller As regras do seller usam as mesmas formas de corpo das regras da subconta: regra avulsa, `installmentRates`, `installments` e fórmula, em array ou em objeto com a lista em `rules`, com o mesmo limite de 50 objetos. Como na subconta, `paymentMethod: default` é recusado com `400` e `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`. A diferença está no crédito: a regra do seller é só percentual por parcela. Qualquer `fixedAmount` diferente de 0 no crédito do seller recusa a requisição com `400`. No Pix e no boleto, o seller aceita percentual, valor fixo ou os dois. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/merchants/YOUR_MERCHANT_ID/sellers/YOUR_SELLER_ID/platform-fee' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "paymentMethod": "pix", "percentage": 0, "fixedAmount": 0 }, { "paymentMethod": "credit", "installmentRates": [1.99, 2.49] } ] }' ``` Resposta `201`, com as regras gravadas e um aviso fixo sobre assinaturas: ```json theme={null} { "sellerId": "27ae4860-55ac-4e48-a417-1038dbdf1049", "rules": [ { "id": "88ccd2aa-c3cb-4ff6-bca7-3bc3812da801", "percentage": 0, "fixedAmount": 0, "paymentMethod": "pix", "createdAt": "2026-09-29T14:49:54.612Z", "updatedAt": "2026-09-29T14:49:54.612Z" }, { "id": "7f28ac5a-05d5-4a40-997d-2f172702a369", "percentage": 1.99, "fixedAmount": 0, "paymentMethod": "credit", "installment": 1, "createdAt": "2026-09-29T14:49:54.612Z", "updatedAt": "2026-09-29T14:49:54.612Z" }, { "id": "2d0d8935-6b77-4fef-8ec9-625986f38ab4", "percentage": 2.49, "fixedAmount": 0, "paymentMethod": "credit", "installment": 2, "createdAt": "2026-09-29T14:49:54.612Z", "updatedAt": "2026-09-29T14:49:54.612Z" } ], "warnings": [ "assinaturas aceitam split só em percentual, e com a taxa desta subconta ligada, uma assinatura com split por valor que inclua este seller tem as cobranças recusadas com platform_fee_requires_percentage_split quando a regra própria dele vale para o método e a parcela da cobrança" ] } ``` Neste exemplo, o seller fica isento no Pix, paga 1,99% em 1x e 2,49% em 2x, e segue a subconta no boleto e de 3x a 24x. O `GET` na mesma rota lista as regras próprias do seller, e o `PUT` altera as regras dele com as mesmas regras do `PUT` da subconta: a regra avulsa altera só os campos enviados, e a tabela de crédito substitui a tabela do seller inteira, sem mexer na da subconta. Consulte o contrato completo em [Criar regras de platform fee do seller](/api-reference/merchants/criar-regras-de-platform-fee-do-seller). ### Isentando um seller ou devolvendo à regra da subconta * **Isentar** num método: regra do seller com `percentage: 0` e `fixedAmount: 0`, os dois na mesma requisição. Um `PUT` só com `percentage: 0` numa regra que tinha valor fixo continua cobrando o valor fixo. * **Voltar à regra da subconta**: apague a regra do seller pelo `id`, com `DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}`. A mesma rota apaga regras da subconta e de seller. Mudanças nas regras valem a partir da próxima cobrança. Cobranças já feitas não mudam. ### Como a cobrança escolhe a regra de cada seller Para cada seller do split, na ordem: 1. A regra do seller para o método e a parcela da cobrança. 2. A regra da subconta para o método e a parcela. No crédito, sem regra para a parcela, vale a regra de crédito sem `installment` da subconta, quando ela existe. 3. Nenhuma: a cobrança é recusada com `422` e `platform_fee_rule_not_configured`, dizendo o seller, o método e a parcela. ### Conta por seller Quando algum seller da cobrança tem regra própria para o método e a parcela, a conta é feita seller a seller: ```text theme={null} parte = floor(amount * percentual_do_split / 100) taxa = floor(parte * percentage / 100) + fixo recebe = parte - taxa plataforma = amount - soma do que os sellers recebem ``` * O percentual da regra incide sobre a parte bruta de cada seller, e a taxa de cada seller arredonda para baixo. O centavo do arredondamento fica com o seller. * O valor fixo da regra do seller é cobrado inteiro dele. * O valor fixo da regra da subconta é cobrado uma vez por cobrança e rateado, proporcional à parte bruta, só entre os sellers que usam a regra da subconta. O centavo que sobra do rateio fica com os sellers. * Cada seller precisa receber ao menos R\$ 0,01. Senão, a cobrança é recusada com `platform_fee_exceeds_amount`. Exemplo: Pix de R\$ 100,00 com split de 50%, 30% e 20%. A subconta cobra 1,09% mais R\$ 0,30 no Pix. O seller A tem regra própria de Pix só com R\$ 0,39 fixos. | Seller | Regra | Parte bruta | Taxa | Recebe | | - | - | - | - | - | | A | Própria: R\$ 0,39 | R\$ 50,00 | R\$ 0,39 | R\$ 49,61 | | B | Subconta: 1,09% de R\$ 30,00 mais R\$ 0,18 do fixo rateado | R\$ 30,00 | R\$ 0,50 | R\$ 29,50 | | C | Subconta: 1,09% de R\$ 20,00 mais R\$ 0,12 do fixo rateado | R\$ 20,00 | R\$ 0,33 | R\$ 19,67 | | Plataforma | | | R\$ 1,22 | | Sem a regra do seller A, a mesma cobrança seguiria a conta de sempre, com a taxa da subconta sobre o valor total: R\$ 1,39. No boleto, com a subconta e o seller A cobrando R\$ 1,09 fixos cada, A paga R\$ 1,09 e os R\$ 1,09 da subconta são rateados entre B e C: R\$ 0,65 e R\$ 0,43. O centavo que sobra do rateio não é cobrado, e a plataforma fica com R\$ 2,17. ### Split por percentual Quando algum seller da cobrança tem regra própria para o método e a parcela, o split precisa ser por percentual. Split por valor nessa cobrança é recusado com `platform_fee_requires_percentage_split`. Sem regra de seller na cobrança, o split por valor continua como hoje. ### Validações com a taxa ligada Com a flag de ativação da subconta ligada, a cobrança com split também é recusada nestes casos: * **Seller repetido** (`platform_fee_duplicate_seller`): o mesmo seller aparece em mais de uma linha do split. Some as partes numa linha só. * **Seller fora da subconta** (`platform_fee_seller_not_in_merchant` e `platform_fee_seller_without_merchant`): um seller do split está cadastrado em outra subconta ou não tem subconta. Cadastre-o na subconta da cobrança. * **Split diferente entre provedores** (`platform_fee_split_differs_by_provider`): a cobrança manda a lista `provider` e os provedores não têm o mesmo split. Conta como diferente ter outros sellers, os mesmos sellers com percentuais ou valores diferentes, ou um provedor sem split ao lado de outro com split. Mande o mesmo split para todos os provedores ou use só o `splitRules` do topo. * **Seller que receberia menos de R\$ 0,01** (`platform_fee_exceeds_amount`): no split por percentual, depois da taxa, algum seller ficaria com menos de R\$ 0,01. Aumente a parte dele ou o valor da cobrança, ou revise a regra. Essas validações valem para toda cobrança com split da subconta com a flag ligada, com ou sem regra de seller. Com a flag desligada, nenhuma delas roda e a cobrança segue como hoje. ### A taxa na resposta da cobrança O objeto `platformFee` da cobrança mantém os campos de sempre e, quando algum seller tem regra própria, ganha `lines`, um item por seller, com a regra usada, a parte bruta, a taxa e o que ele recebe. Nesse caso, `amount` é a soma de `lines[].feeAmount`, e os campos do topo trazem a regra da subconta quando alguma linha a usa. Se nenhuma linha usa a regra da subconta, eles trazem a regra da primeira linha que tem regra. Cobranças sem regra de seller e cobranças antigas não têm `lines`. O `platformFee` do webhook 1.1 da cobrança traz os mesmos campos, com `lines`. Trecho da resposta da cobrança Pix do exemplo acima: ```json theme={null} { "amount": 10000, "splitRules": [ { "sellerId": "3b6ab810-6687-4ee2-ba72-2c1c71385512", "percentage": 50, "amount": 4961 }, { "sellerId": "542922b6-c46a-4415-8c13-383ef1fe8a42", "percentage": 30, "amount": 2950 }, { "sellerId": "996ad317-bdf5-4be3-a30a-99081a05d12b", "percentage": 20, "amount": 1967 } ], "platformFee": { "ruleId": "2b6ecb77-7106-48d2-a213-e284b18aa19a", "percentage": 1.09, "fixedAmount": 30, "paymentMethod": "pix", "installment": null, "amount": 122, "appliedAt": "2026-09-29T18:44:22.627Z", "lines": [ { "sellerId": "3b6ab810-6687-4ee2-ba72-2c1c71385512", "scope": "seller", "ruleId": "a0b647fd-347e-4ff2-987a-cd0c1d4056c3", "percentage": 0, "fixedAmount": 39, "grossAmount": 5000, "feeAmount": 39, "netAmount": 4961 }, { "sellerId": "542922b6-c46a-4415-8c13-383ef1fe8a42", "scope": "merchant", "ruleId": "2b6ecb77-7106-48d2-a213-e284b18aa19a", "percentage": 1.09, "fixedAmount": 30, "grossAmount": 3000, "feeAmount": 50, "netAmount": 2950 }, { "sellerId": "996ad317-bdf5-4be3-a30a-99081a05d12b", "scope": "merchant", "ruleId": "2b6ecb77-7106-48d2-a213-e284b18aa19a", "percentage": 1.09, "fixedAmount": 30, "grossAmount": 2000, "feeAmount": 33, "netAmount": 1967 } ] } } ``` | Campo de `lines` | Descrição | | - | - | | `sellerId` | Seller da linha. | | `scope` | `seller` quando vale a regra do próprio seller, `merchant` quando vale a regra da subconta. | | `ruleId`, `percentage` e `fixedAmount` | A regra aplicada e os valores configurados nela. O valor fixo efetivamente cobrado da linha está dentro de `feeAmount`. | | `grossAmount` | Parte bruta do seller, em centavos. | | `feeAmount` | Taxa cobrada do seller, em centavos. | | `netAmount` | O que o seller recebe, em centavos. É o `amount` do split dele. | ### Consultando as regras dos sellers O `GET /v1/merchants/{merchantId}/platform-fee` traz, além das regras da subconta em `rules`: * `sellerRules`: um item por seller com ao menos uma regra própria, com as regras dele no mesmo formato de `rules`. * `coverage.merchant.methods` e `coverage.sellers[].methods`: o estado de `pix`, `boleto` e de cada faixa de parcelas de `credit`, para a subconta e para cada seller. | Estado | Significado | | - | - | | `own` | Regra própria que cobra algo. | | `exempt` | Regra própria com `percentage: 0` e `fixedAmount: 0`. | | `inherits` | Só em seller. Sem regra própria, segue a regra da subconta. | | `missing` | Sem regra em nenhum nível. Com a taxa ligada, a venda é recusada com `platform_fee_rule_not_configured`. | Um seller sem regra própria num método ou parcela em que a subconta está em `missing` também aparece como `missing`, e não como `inherits`. Trecho de `coverage` de uma subconta com Pix, boleto e crédito de 1x a 2x próprios, sem regra de 3x a 24x, e um seller com Pix e crédito 1x próprios: ```json theme={null} { "merchant": { "missing": [], "warnings": ["credit sem regra em 3x a 24x; com a taxa ligada, a venda é recusada por falta de regra"], "methods": [ { "paymentMethod": "pix", "state": "own" }, { "paymentMethod": "boleto", "state": "own" }, { "paymentMethod": "credit", "installments": [ { "from": 1, "to": 2, "state": "own" }, { "from": 3, "to": 24, "state": "missing" } ] } ] }, "sellers": [ { "sellerId": "e7357ea5-73be-4cab-a0b5-d47d36feb55c", "warnings": [], "methods": [ { "paymentMethod": "pix", "state": "own" }, { "paymentMethod": "boleto", "state": "inherits" }, { "paymentMethod": "credit", "installments": [ { "from": 1, "to": 1, "state": "own" }, { "from": 2, "to": 2, "state": "inherits" }, { "from": 3, "to": 24, "state": "missing" } ] } ] } ] } ``` Com `simulationAmount`, cada item de `sellerRules` ganha `methods`, com a taxa calculada como se o seller recebesse o valor simulado inteiro. Em cada método e parcela, `scope` diz se vale a regra do seller ou a da subconta. ## Venda sem split Com a taxa ligada, a cobrança sem `splitRules`, no topo e na lista `provider`, também paga a taxa da plataforma. A Malga usa como recebedor o único seller ativo da subconta, calcula a taxa como se ele recebesse o valor inteiro da cobrança e envia ao provedor o split com esse seller e o valor já líquido da taxa. A plataforma fica com a taxa. * Seller ativo é o seller da subconta com status `active` ou `partial` e ao menos um provedor ativo. Ele também precisa estar ativo em cada provedor da cobrança. * A regra é escolhida como na cobrança com split: a regra do seller para o método e a parcela e, sem ela, a da subconta. Sem regra em nenhum nível, a cobrança é recusada com `platform_fee_rule_not_configured`. Taxa maior ou igual ao valor da cobrança é recusada com `platform_fee_exceeds_amount`. * Na resposta, `splitRules` traz o seller com `amount` igual ao que ele recebe, e `platformFee` traz a taxa. Quando vale a regra própria do seller, `platformFee` tem `lines`, com uma linha. * A venda Apple Pay continua sem taxa. * Com a taxa desligada, nada muda: a cobrança sem split segue sem taxa e sem split. Quando a subconta não tem exatamente um seller ativo, a cobrança é recusada com `422` e `platform_fee_seller_not_active`, antes de ir ao provedor. `error.context.reason` diz o motivo, e `error.context` traz também `paymentMethod` e, no crédito, `installment`: | `reason` | Quando | Campos a mais em `context` | | - | - | - | | `no_active_seller` | A subconta não tem seller ativo. | Nenhum | | `multiple_active_sellers` | A subconta tem mais de um seller ativo, e a Malga não escolhe entre eles. | `sellerIds`, com até dois dos sellers ativos | | `seller_not_active_in_provider` | O seller ativo da subconta não está ativo em algum provedor da cobrança. | `sellerId` e `providers`, os provedores em que ele não está ativo | Para escolher quem recebe numa subconta com mais de um seller ativo, envie `splitRules` na cobrança. Exemplo de recusa numa subconta com dois sellers ativos: ```json theme={null} { "error": { "type": "unprocessable_entity", "code": 422, "declined_code": "platform_fee_seller_not_active", "details": ["Merchant c6637a11-951a-4fa8-a60b-7d3da5be803d has 2 active sellers (3b6ab810-6687-4ee2-ba72-2c1c71385512, 542922b6-c46a-4415-8c13-383ef1fe8a42). Send splitRules to choose who receives."], "context": { "reason": "multiple_active_sellers", "paymentMethod": "pix", "sellerIds": ["3b6ab810-6687-4ee2-ba72-2c1c71385512", "542922b6-c46a-4415-8c13-383ef1fe8a42"] }, "message": "A charge without split under an enabled platform fee requires exactly one active seller in the merchant, in every provider of the charge. Activate one seller of the merchant in those providers or send splitRules in the charge." } } ``` ## Estornos Em estornos totais ou parciais, o `platform-fee` é revertido proporcionalmente ao valor estornado. A devolução de cada seller é proporcional ao que ele recebeu na cobrança, e a plataforma devolve o restante. Exemplo: * transação de R\$ 1.000,00 com platformFee de 2% (plataforma reteve R\$ 20,00, seller recebeu R\$ 980,00). * Estorno parcial de R\$ 500,00: * Plataforma devolve: R\$ 10,00 * Seller devolve: R\$ 490,00 Com taxa por seller, a conta é a mesma. No estorno de R\$ 50,00 da cobrança Pix do exemplo de [Conta por seller](#conta-por-seller), A devolve R\$ 24,80, B devolve R\$ 14,75, C devolve R\$ 9,83 e a plataforma devolve R\$ 0,62. ## Erros ### Na configuração | Código | HTTP | Quando | O que fazer | | - | - | - | - | | `PLATFORM_FEE_INVALID_RULE` | 400 | Regra inválida. Na regra de seller, também valor fixo diferente de 0 no crédito. | Corrija o campo indicado em `message`. No crédito do seller, envie só `percentage`. | | `PLATFORM_FEE_INSTALLMENT_REQUIRED` | 400 | Regra avulsa de `credit` sem `installment`. | Informe a parcela ou use uma tabela. | | `PLATFORM_FEE_DUPLICATE_RULE` | 400 | A mesma parcela ou o mesmo método repetido no corpo. | Envie cada parcela uma vez. | | `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED` | 400 | `paymentMethod: default` no `POST` ou no `PUT`, da subconta ou do seller, mesmo junto de regras válidas. Nada é gravado. | Troque a `default` por uma regra para cada método que você vende. | | `PLATFORM_FEE_RULES_REQUIRED_WHILE_ENABLED` | 400 | `DELETE` da última regra da subconta com a taxa ligada. A regra continua. | Crie outra regra da subconta antes ou desligue a taxa. | | `PLATFORM_FEE_RULES_REQUIRED_TO_ENABLE` | 400 | Ligar a taxa numa subconta sem regra própria, mesmo com regras de seller. | Crie ao menos uma regra da subconta antes de ligar. | | `PLATFORM_FEE_SELLER_NOT_FOUND` | 404 | Seller de outro cliente, de outra subconta ou sem subconta. | Cadastre o seller na subconta e crie a regra nela. | | `PLATFORM_FEE_RULE_NOT_FOUND` | 404 | `PUT` de regra avulsa que não existe, ou `DELETE` de `id` que não existe. | Crie a regra com `POST` ou confira o `id`. | | `PLATFORM_FEE_RULE_ALREADY_EXISTS` | 409 | Já existe regra para o método ou a parcela, no mesmo escopo. | Use o `PUT` para alterar. | | `PLATFORM_FEE_SELLER_LIMIT_REACHED` | 422 | `POST` de regra, ou `PUT` com tabela de crédito, para um seller sem regra própria, numa subconta que já tem 200 sellers com regra, com a taxa ligada ou desligada. Nada é gravado. | Altere as regras de um seller que já tem, ou apague todas as regras de um seller para liberar a vaga. | | `SELLER_SERVICE_UNAVAILABLE` | 503 | O serviço de sellers não respondeu na escrita de regra de seller. Nada foi gravado. | Tente de novo. | ### Na cobrança A recusa vem em `error.declined_code`. Nas recusas de seller, `error.details` traz um texto em inglês com os valores, e `error.context` traz os mesmos valores em campos, para você montar a sua mensagem. | Código | HTTP | Quando | O que fazer | | - | - | - | - | | `platform_fee_rule_not_configured` | 422 | Nenhuma regra cobre um seller no método e na parcela da cobrança, com ou sem split. `context` traz `sellerId`, `paymentMethod` e `installment`. | Cadastre a regra na subconta ou no seller. | | `platform_fee_seller_not_active` | 422 | Cobrança sem split com a taxa ligada, sem exatamente um seller ativo na subconta em todos os provedores da cobrança. `context.reason` traz `no_active_seller`, `multiple_active_sellers` ou `seller_not_active_in_provider`. | Ative um seller da subconta nos provedores da cobrança ou envie `splitRules`. | | `platform_fee_exceeds_amount` | 422 | Algum seller receberia menos de R\$ 0,01, ou a taxa total não é menor que o valor da cobrança. Na recusa por seller, `context` traz `sellerId`, `splitAmount`, `feeAmount` e `leftoverAmount`. | Aumente a parte do seller ou o valor da cobrança, ou revise a regra. | | `platform_fee_requires_percentage_split` | 422 | Split por valor com seller que tem regra própria. | Mande o split em percentual. | | `platform_fee_duplicate_seller` | 422 | O mesmo seller em mais de uma linha do split, com a taxa ligada. | Some as partes numa linha só. | | `platform_fee_seller_not_in_merchant` | 422 | Seller de outra subconta, com a taxa ligada. `context` traz `sellerMerchantId`. | Cadastre o seller na subconta da cobrança. | | `platform_fee_seller_without_merchant` | 422 | Seller sem subconta, com a taxa ligada. | Vincule o seller à subconta da cobrança. | | `platform_fee_split_differs_by_provider` | 422 | Provedores da lista `provider` com split diferente, com a taxa ligada. `context` traz `providers`. | Mande o mesmo split para todos os provedores. | | `platform_fee_preview_split_percentage_sum_invalid` | 422 | Percentuais do split somando mais de 100, com a taxa ligada. | Ajuste os percentuais. | | `split_amount_mismatch` | 422 | Split por valor, sem regra de seller, cuja soma passa do valor da cobrança menos a taxa. | Envie os valores já líquidos da taxa. | | `platform_fee_config_unavailable` | 503 | A configuração da taxa não pôde ser lida nesta cobrança. Só acontece na cobrança com split. | Tente de novo. O erro é temporário. | Exemplo de recusa por seller: ```json theme={null} { "error": { "type": "unprocessable_entity", "code": 422, "declined_code": "platform_fee_exceeds_amount", "details": ["Seller 3b6ab810-6687-4ee2-ba72-2c1c71385512 would receive 0 cents: split amount 39 cents, platform fee 39 cents. Each seller must receive at least 1 cent."], "context": { "sellerId": "3b6ab810-6687-4ee2-ba72-2c1c71385512", "splitAmount": 39, "feeAmount": 39, "leftoverAmount": 0 }, "message": "Each seller must receive at least 1 cent after the platform fee." } } ``` # Revisão cadastral de recebedores Source: https://docs.malga.io/documentations/split/revisao-cadastral Como responder às revisões cadastrais que o provedor abre para os seus recebedores, dentro do prazo e com dados coletados de forma ativa. Periodicamente, e sempre que encontra uma inconsistência, o provedor exige que os dados cadastrais de um recebedor sejam confirmados. Quando isso acontece, a Malga abre um **processo de revisão cadastral** com prazo e com a lista dos campos a coletar, e avisa você por webhook. Responder ao processo é responsabilidade sua: cabe a você coletar os dados **diretamente com o recebedor** e enviá-los pela API antes do prazo. Um processo que vence sem envio leva o provedor a bloquear o recebedor — e com ele o repasse do Split. > [!NOTE] > > A revisão cadastral está disponível hoje para recebedores vinculados ao provedor **Zoop**. ## Os dois tipos de revisão | Tipo | Sigla | Quando acontece | | - | - | - | | Periódica | `acp` | Em intervalos definidos pelo provedor, independentemente de qualquer suspeita | | Por inconsistência | `aci` | Quando o provedor encontra divergência nos dados do recebedor | A diferença prática está no ritmo. A revisão periódica nasce em `pending`, com uma fase inicial em que o recebedor responde no seu próprio tempo, e passa a `overdue` — cobrança ativa — antes do vencimento. A revisão por inconsistência **já nasce em cobrança**, sem fase inicial, porque o provedor já identificou um problema. Você não precisa acompanhar essa virada: ela se reflete no `status` do processo, e o que delimita a sua janela de resposta é o `deadlineAt`. Ambos vêm na consulta. ## A regra de coleta ativa Esta é a regra que mais costuma ser violada na integração, e a que mais custa caro. > [!WARNING] > > O provedor **proíbe** preencher uma revisão cadastral com dado que você já tinha. Não vale usar bureau de crédito, a sua própria base, o que foi informado no onboarding nem o que foi enviado em uma revisão anterior. A coleta precisa ser **ativa**: feita com o recebedor, agora, por causa deste processo. A Malga não tem como provar que a coleta foi ativa, mas se recusa a transportar um envio que nem sequer afirme isso. Por essa razão, todo envio carrega um bloco `collection` que descreve como você obteve os dados: | Campo | Obrigatório | Descrição | | - | - | - | | `channel` | Sim | Canal pelo qual você falou com o recebedor (`in_app`, `email`, `phone`, o que se aplicar) | | `collectedAt` | Sim | Quando a coleta aconteceu. Precisa ser **posterior à abertura do processo** | | `journeyId` | Sim | Identificador da jornada de coleta do seu lado, para você reencontrar o registro depois | | `sourceIp` | Não | Endereço de onde o recebedor enviou os dados | | `userAgent` | Não | Agente do cliente usado na coleta | A data de coleta é validada contra o momento em que o processo abriu: dado coletado antes de o provedor pedir é, por definição, dado que já estava guardado. Um envio nessas condições é recusado com `400`. A Malga guarda o que foi declarado. É esse registro que você apresenta caso o provedor audite a origem dos dados. ## O fluxo de ponta a ponta **1. Você é avisado** O provedor abre o processo e a Malga publica `seller.registration_review.required` no seu webhook. Enquanto o processo continuar aberto, você recebe lembretes periódicos. **2. Você descobre o que coletar** Consulte o processo e leia `requestedFields.fields`. Cada item traz o caminho do campo no vocabulário da Malga, o rótulo para exibir no formulário e, quando existe, o formato esperado. **3. Você coleta com o recebedor** Monte o formulário a partir dessa lista e apresente ao recebedor. Registre o momento e a jornada da coleta. **4. Você envia** Faça o `POST` de envio com os dados coletados e a evidência da coleta. A resposta é `202`: a Malga aceitou a coleta e vai encaminhá-la ao provedor. **5. Você acompanha o desfecho** O resultado chega por webhook: `seller.registration_review.finished` quando o provedor confirma, ou `seller.registration_review.failed` quando recusa. Enquanto houver prazo, um envio recusado pode ser corrigido e reenviado. ## Consultar os processos abertos ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/sellers/registration-reviews?status=pending,overdue' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' < HTTP/2 200 { "items": [ { "processId": "710d84ca-950d-49fd-9747-c3d33301c6cb", "sellerId": "9d160f4f-717b-4e93-8520-044bd228ec37", "provider": "ZOOP", "providerId": "663f7f0c-9cad-4d7a-959c-c64ce904016e", "reviewType": "acp", "status": "pending", "deadlineAt": "2026-09-15T23:59:59.000Z", "daysRemaining": 18, "requestedFields": { "raw": ["revenue", "owner.address.postal_code"], "fields": [ { "path": "revenue", "type": "enum", "required": true, "providerField": "revenue", "label": { "pt-br": "Faixa de faturamento", "en": "Revenue range" }, "allowedValues": ["10000_to_50000", "50000_to_100000", "100000_to_500000"] }, { "path": "owner.address.zipCode", "type": "string", "required": true, "providerField": "owner.address.postal_code", "label": { "pt-br": "CEP", "en": "Postal code" }, "format": { "pt-br": "8 dígitos, sem pontuação", "en": "8 digits, no punctuation" }, "pattern": "^[0-9]{8}$" } ] }, "requestedFieldsPending": false, "createdAt": "2026-08-28T13:04:11.320Z" } ], "meta": { "totalItems": 1, "itemCount": 1, "itemsPerPage": 100, "totalPages": 1, "currentPage": 1 } } ``` Para restringir a um recebedor, use `GET /v1/sellers/{sellerId}/registration-reviews`. Um recebedor com mais de um vínculo ao provedor recebe um item por vínculo, distinguidos pelo campo `providerId`. ### A lista de campos O bloco `requestedFields` traduz para o vocabulário da Malga o que o provedor pediu no vocabulário dele. Você lê `fields` e ignora `raw`, que existe apenas para rastrear a origem de cada item. Vale conhecer três detalhes da lista: * **Um item de `raw` pode virar dois em `fields`.** O endereço é o caso típico: onde o provedor pede um campo só, a Malga separa logradouro e número. Os dois aparecem em `fields` e você coleta os dois; a junção acontece na borda. * **`pattern` é a mesma expressão que valida o envio.** Se o seu formulário validar por ela, o envio não é recusado por formato. * **`allowedValues` é informativo.** Um valor fora da lista não é recusado pela Malga, porque o provedor pode aceitar opções que ainda não publicou. Enquanto o provedor não informa o que pedir, `requestedFields` vem ausente e `requestedFieldsPending` vem `true` — com o prazo já correndo. Nessa situação não há o que coletar ainda, e um envio é recusado com `409`. ## Enviar os dados coletados O bloco `data` deve conter **exatamente** os campos listados em `requestedFields.fields`: nem um a menos, nem um que não tenha sido pedido. Os caminhos seguem o formato de `path`, aninhados. ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sellers/9d160f4f-717b-4e93-8520-044bd228ec37/registration-reviews/710d84ca-950d-49fd-9747-c3d33301c6cb/submit' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "collection": { "channel": "in_app", "collectedAt": "2026-08-28T14:20:00.000Z", "journeyId": "jr_8f14e45fceea", "sourceIp": "200.150.10.22", "userAgent": "Mozilla/5.0" }, "data": { "revenue": "10000_to_50000", "owner": { "address": { "zipCode": "01310200" } } } }' < HTTP/2 202 ``` A resposta `202` significa que a Malga aceitou a coleta, e não que o provedor já a confirmou. O envio ao provedor acontece em segundo plano, justamente para que uma indisponibilidade do lado dele não vire um erro na sua chamada. Acompanhe o desfecho pelos webhooks ou pela listagem. ### Erros de envio Todos os problemas encontrados vêm juntos em `error.details`, e não um por vez. Isso é deliberado: a coleta já foi feita com o recebedor, e descobrir um campo errado por tentativa significaria voltar até ele várias vezes, com o prazo cada vez menor. | Código | `error.key` | Causa | | - | - | - | | `400` | `invalid_registration_review_payload` | O `data` não corresponde à lista de campos: falta um, sobra um que não foi pedido, ou o formato não bate | | `400` | — | A evidência de coleta está incompleta, ou a data de coleta é anterior à abertura do processo | | `404` | `registration_review_not_found` | O processo não existe para esse recebedor | | `409` | `invalid_registration_review_transition` | O processo está em uma situação que não aceita envio, por exemplo já encerrado | | `409` | `registration_review_fields_unavailable` | A lista de campos do processo ainda não está utilizável | Exemplo de recusa por campos fora da lista: ```json theme={null} { "error": { "type": "bad_request", "code": 400, "key": "invalid_registration_review_payload", "details": [ "missing requested field: owner.address.zipCode", "field not requested by the provider: business.email" ] } } ``` ## Situações do processo | Status | Descrição | | - | - | | **pending** | Dentro da fase inicial, apenas na revisão periódica | | **overdue** | Em cobrança ativa — na periódica após a fase inicial, na inconsistência desde o início | | **submitting** | Coleta recebida, envio ao provedor em curso | | **submit\_failed** | Envio recusado ou falho, aguardando correção ou nova tentativa | | **expired** | Prazo vencido. O envio continua sendo aceito, e continua sendo o melhor caminho | | **finished** | O provedor confirmou o recebimento | | **canceled** | Processo invalidado, por exemplo com a remoção do recebedor | | **unmatched** | A Malga não conseguiu identificar a qual recebedor o processo se refere. É um incidente operacional, tratado pelo nosso time, com o prazo correndo | Um processo `expired` não é um processo perdido. O envio continua sendo aceito, e segue sendo a única ação que reduz a exposição do recebedor ao bloqueio. ## Prazos e lembretes O prazo é definido pelo provedor e chega no campo `deadlineAt`. O campo `daysRemaining` traz os dias inteiros que faltam, e fica negativo depois que o prazo passa. Enquanto o processo continuar aberto, a Malga o lembra por webhook em uma cadência que aperta conforme o prazo se aproxima: | Tempo até o prazo | Intervalo entre lembretes | | - | - | | Mais de 30 dias | A cada 7 dias | | Entre 8 e 30 dias | A cada 3 dias | | 7 dias ou menos | Diário | | Prazo vencido | A cada 7 dias | ## Eventos de webhook Os seis eventos do processo viajam pelo mesmo webhook em que você já recebe `seller.active` e `seller.inactive`. Veja o payload e a lista completa em [Webhooks](/documentations/webhooks/webhook1-1#seller). > [card] [Gerenciar recebedores](/documentations/split/seller) > > Criação, edição e status dos recebedores usados no Split. > [card] [Webhooks](/documentations/webhooks/webhook1-1) > > Payload, eventos e configuração das notificações. # Cadastrar e gerenciar recebedores (sellers) para Split Source: https://docs.malga.io/documentations/split/seller Cadastre recebedores (sellers) vinculados a um merchantId para uso em splitRules de cobranças e sessões nos provedores suportados pela Malga. Para a utilização do **Split** na cobrança ou em **sessões com split**, utilizamos o serviço de **Sellers** para cadastrar recebedores e política de recebimento nos provedores suportados pela Malga. É necessário cadastrar previamente os recebedores associados à sua subconta (**merchant**) antes de referenciá-los em `splitRules` — tanto em `POST /v1/charges` quanto em `POST /v1/sessions`. Na sessão, a existência dos sellers é validada na criação; na captura da cobrança, o fluxo de transações efetiva o vínculo com o provedor de acordo com o estado do recebedor. > [!NOTE] > > Todo recebedor deve estar vinculado a um **`merchantId`** válido. A listagem de sellers sem merchant e o **split agnóstico** foram descontinuados. Veja os detalhes na [release de jun/2026](/release-notes/2026-06-12-Release-Notes). > [!NOTE] > > **Precedência das regras de split:** as regras de responsabilidade por taxas e chargebacks definidas no momento da transação (via API ou Link de Pagamento) sempre terão prioridade sobre as regras configuradas aqui, no cadastro do recebedor. > [!NOTE] > > O cadastro e a edição de recebedores são feitos via API (`POST /v1/sellers` e `PATCH /v1/sellers/{id}`). No Dashboard, o menu **Recebedores** permite visualizar, filtrar e buscar os recebedores cadastrados e consultar os detalhes de cada um. Veja as permissões por perfil em [Usuários e permissões](/documentations/dashboard/users). ## Status de recebedor A criação de um Seller nos provedores ocorre de forma assíncrona, e além disso não é realizada de forma imediata, uma vez que critérios precisam ser analisados, assim como uma transação financeira. Para ser notificado sobre atualizações nesse processo, utilize os [webhooks](/documentations/webhooks/webhook1-1#seller). Os status possíveis para um seller são: | Status | Descrição | | - | - | | **pending** | Informações recebidas e pendentes de validação no provedor | | **active** | Recebedor ativo para transações e saque dos valores | | **partial** | Apenas parte dos provedores está ativa para o recebedor | | **inactive** | Recebedor não pode transacionar nem sacar valores | | **blocked** | Recebedor bloqueado | ## Provedores suportados Veja os provedores que suportam criação de `Sellers` na nossa [tabela de provedores e meios de pagamento suportados](/documentations/type-tables/payment-methods-by-providers). ## Exemplo de criação de recebedor Caso precise cadastrar um recebedor do tipo **pessoa física**, utilize a propriedade **owner**: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sellers' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "owner": { "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27", "document": { "type": "cpf", "number": "36243319067", "country": "BR" }, "address": { "street": "Rua Nova Lua", "streetNumber": "30", "complement": "apto 208 bloco c", "zipCode": "61000-320", "country": "BR", "state": "CE", "city": "Maracanaú", "district": "AB" }, "businessCategory": "OTHER_SERVICES" }, "mcc": 1, "bankAccount": { "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "metadata": {[ "key": "768093", "value": "informação adicional" ]}, "transferPolicy": { "transferDay": 5, "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": "", "automaticAnticipationType": "", "automaticAnticipationDays": "", "automaticAnticipation1025Delay": "" } }' < HTTP/2 201 { "id": "1585791a-b3e1-4003-9b5c-69ce57b4e8f9", "providers": [], "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "metadata": null, "owner": { "id": "acbe3336-efea-4e32-a3b0-98686105effa", "updatedAt": "2023-07-11T22:06:14.078Z", "createdAt": "2023-07-11T22:06:14.078Z", "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27T02:00:00.000Z", "address": { "country": "BR", "id": "010e3696-b096-4e07-936d-a7fce8973f48", "updatedAt": "2023-07-11T22:06:14.080Z", "createdAt": "2023-07-11T22:06:14.080Z", "street": "Rua Nova Lua", "streetNumber": "30", "complement": "apto 208 bloco c", "zipCode": "61000-320", "state": "CE", "city": "Maracanaú", "district": "AB", } "document": { "country": "BR", "id": "02d9cc98-6276-4d4b-aa5b-df7b69c64bc8", "updatedAt": "2022-12-21T23:10:13.334Z", "createdAt": "2022-12-21T23:10:13.334Z", "type": "cpf", "number": "36243319067" } }, "business": null, "bankAccount": { "id": "4563e058-a6ba-4178-97d7-ef2b86f493c1", "updateAT": "2023-02-28T18:00:00.573Z", "createdAt": "2023-02-28T18:00:00.573Z", "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "transferPolicy": { "id": "e4ee0583-4b8d-4360-8fe4-8534ff96ace9", "updatedAt": "2023-07-05T18:55:29.809Z", "createdAt": "2023-07-05T18:55:29.809Z", "transferDay": 5, "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": null, "automaticAnticipationType": null, "automaticAnticipationDays": null, "automaticAnticipation1025Delay": null }, "mcc": 1, "status": "active" } ``` ## Identificador do banco: `bank` e `ispb` A `bankAccount` aceita dois identificadores da instituição financeira: * **`bank`** — código **COMPE** de 3 dígitos do banco (ex.: `077` para Banco Inter). Consulte a [tabela de códigos COMPE dos principais bancos](/documentations/type-tables/main-banks). * **`ispb`** — identificador **ISPB** da instituição no Sistema de Pagamentos Brasileiro, com 8 dígitos numéricos. A relação canônica de ISPBs é publicada pelo Banco Central (BCB). Regras de uso: * **Pelo menos um obrigatório.** Na criação (`POST /v1/sellers`), envie `bank`, `ispb` ou ambos — não vale omitir os dois. * **`ispb` tem precedência.** Quando os dois forem enviados, o roteamento downstream usa o `ispb`; o `bank` permanece aceito como fallback/auxiliar. * **Semântica PATCH.** Em `PATCH /v1/sellers/{id}`, omitir a chave preserva o valor persistido; enviar `null` em um dos identificadores limpa aquele valor. A invariante "ao menos um identificador" é validada considerando o estado mesclado (payload + persistido). * **Erro.** Se o merge final ficar sem `bank` e sem `ispb`, a API responde `400` com `error.key = bank_identifier_required`. ### Exemplo de criação identificando o banco apenas por `ispb` ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sellers' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "owner": { "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27", "document": { "type": "cpf", "number": "36243319067", "country": "BR" }, "address": { "street": "Rua Nova Lua", "streetNumber": "30", "complement": "apto 208 bloco c", "zipCode": "61000-320", "country": "BR", "state": "CE", "city": "Maracanaú", "district": "AB" }, "businessCategory": "OTHER_SERVICES" }, "mcc": 1, "bankAccount": { "holderName": "Seller name", "holderDocument": "36243319067", "ispb": "60746948", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" } }' ``` ### Exemplo de PATCH trocando `bank` por `ispb` A troca é aceita porque o estado mesclado mantém ao menos um identificador (`ispb`): ```bash theme={null} curl --location --request PATCH 'https://api.malga.io/v1/sellers/1585791a-b3e1-4003-9b5c-69ce57b4e8f9' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "bankAccount": { "bank": null, "ispb": "60746948" } }' ``` Caso precise cadastrar um recebedor do tipo **pessoa jurídica**, utilize as propriedades **owner** e **business**: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/sellers' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "owner": { "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27", "document": { "type": "cpf", "number": "36243319067", "country": "BR" }, "address": { "street": "Rua Nova Lua", "streetNumber": "30", "complement": "casa 4", "zipCode": "61000-320", "country": "BR", "state": "CE", "city": "Maracanaú", "district": "AB" }, "businessCategory": "OTHER_SERVICES" }, "business": { "name": "Seller business", "corporateReason": "Company social reason", "phoneNumber": "85988350264", "email": "sellerbusiness@email.com", "website": "www.sellerbusiness.com.br", "description": "Seller business", "facebook": "facebook Seller business", "twitter": "twitter Seller business", "openingDate": "1995-01-27", "address": { "street": "Rua Nova Lua", "streetNumber": "30", "complement": "sala 100", "zipCode": "61000-320", "country": "BR", "state": "CE", "city": "Maracanaú", "district": "AB" }, "document": { "type": "cnpj", "number": "94938591000196", "country": "BR" } }, "mcc": 4040, "bankAccount": { "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "transferPolicy": { "transferDay": 5, "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": "", "automaticAnticipationType": "", "automaticAnticipationDays": "", "automaticAnticipation1025Delay": "" } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "1585791a-b3e1-4003-9b5c-69ce57b4e8f9", "providers": [] "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "clientid": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "metadata": null, "owner": { "id": "c30cfb43-a748-4822-9449-57563d2a1de5", "updatedAt": "2023-07-11T23:02:51.581Z", "createdAt": "2023-07-11T23:02:51.581Z", "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27T02:00:00.000Z", "address": { "country": "BR", "id": "55cc95c1-9c63-4755-a836-d9db74c8fd72", "updatedAt": "2023-07-11T23:02:51.585Z", "createdAt": "2023-07-11T23:02:51.585Z", "street": "Rua Nova Lua", "streetNumber": "30", "complement": "casa 4", "zipCode": "61000-320", "state": "CE", "city": "Maracanaú", "district": "AB" }, "document": { "country": "BR", "id": "116d80a5-b204-4861-84c6-2189ee0ac6c7", "updatedAt": "2023-07-11T23:02:51.588Z", "createdAt": "2023-07-11T23:02:51.588Z", "type": "cpf", "number": "36243319067" }, }, "business": { "id": "fb950b1a-bfa2-40e1-8446-18d2dace84d5", "updatedAt": "2023-07-11T23:02:51.571Z", "createdAt": "2023-07-11T23:02:51.571Z", "name": "Seller business", "corporateReason": "Company social reason", "phoneNumber": "85988350264", "email": "seller@email.com", "website": "www.sellerbusiness.com.br", "description": "Seller business", "facebook": "facebook Seller business", "twitter": "twitter Seller business", "openingDate": "1995-01-27", "address": { "country": "BR", "id": "4f58d047-3f3b-49a8-843e-496a8d7f6135", "updatedAt": "2023-07-11T23:02:51.574Z", "createdAt": "2023-07-11T23:02:51.574Z", "street": "Rua Nova Lua", "streetNumber": "30", "complement": "sala 100", "zipCode": "61000-320", "state": "CE", "city": "Maracanaú", "district": "AB" }, "document": { "country": "BR", "id": "319894f0-1cac-4675-8857-54c0310fedc4", "updatedAt": "2023-07-11T23:02:51.578Z", "createdAt": "2023-07-11T23:02:51.578Z", "type": "cnpj", "number": "94938591000196" } }, "bankAccount": { "id": "4afa0d0b-466b-4ec7-a772-60559ec489c0", "updatedAt": "2023-07-11T23:02:51.563Z", "createdAt": "2023-07-11T23:02:51.563Z", "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "transferPolicy": { "id": "5dc4c08d-66b7-490c-b005-dfc0fb79a12f", "updatedAt": "2023-07-11T23:02:51.567Z", "createdAt": "2023-07-11T23:02:51.567Z", "transferDay": "5", "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": "", "automaticAnticipationType": "", "automaticAnticipationDays": "", "automaticAnticipation1025Delay": "" }, "mcc": 1, "status": "active" } ``` Consulte a [tabela de códigos COMPE dos principais bancos](/documentations/type-tables/main-banks) para preencher `bankAccount.bank`. Como alternativa, o campo `bankAccount.ispb` pode ser usado para identificar a instituição financeira pelo código publicado pelo Banco Central (BCB). ## Busca de recebedor pelo ID ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/sellers/1585791a-b3e1-4003-9b5c-69ce57b4e8f9' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' < HTTP/2 201 { "id": "1585791a-b3e1-4003-9b5c-69ce57b4e8f9", "providers": { "providerType": "SANDBOX", "externalId": "1966811", "externalStatus": "active", "externalStatusReason": "ok", "status": "pending", "createdAt": "2022-12-21T23:10:13.498Z", "updatedAt": "2022-12-21T20:10:13.951Z" } "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "clientid": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "metadata": null, "owner": { "id": "5970864a-579a-44a1-96aa-b44fc5a0b969", "updatedAt": "2023-07-11T23:16:10.101Z", "createdAt": "2023-07-11T23:16:10.101Z", "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27", "address": { "country": "BR", "id": "7a4977fd-a550-4da1-962a-2905976b596b", "updatedAt": "2023-07-11T23:16:10.103Z", "createdAt": "2023-07-11T23:16:10.103Z", "street": "Rua Nova Lua", "streetNumber": "30", "complement": "casa 4", "zipCode": "61000-320", "state": "CE", "city": "Maracanaú", "district": "AB" }, "document": { "country": "BR", "id": "91bab5f1-a8ab-4707-8d0f-7c4d4e18ab49", "updatedAt": "2023-07-11T23:16:10.105Z", "createdAt": "2023-07-11T23:16:10.105Z", "type": "cpf", "number": "36243319067" }, "businessCategory": "OTHER_SERVICES" }, "business": { "id": "ebe3a81d-deae-4f6d-895c-824000c7a6c0", "updatedAt": "2023-07-11T23:16:10.094Z", "createdAt": "2023-07-11T23:16:10.094Z", "name": "Seller business", "corporateReason": "Company social reason", "phoneNumber": "85988350264", "email": "sellerbusiness@email.com", "website": "www.sellerbusiness.com.br", "description": "Seller business", "facebook": "facebook Seller business", "twitter": "twitter Seller business", "openingDate": "1995-01-27", "address": { "country": "BR", "id": "9480f1c4-d378-488c-a993-c9041300c08f", "updatedAt": "2023-07-11T23:16:10.096Z", "createdAt": "2023-07-11T23:16:10.096Z", "street": "Rua Nova Lua", "streetNumber": "30", "complement": "sala 100", "zipCode": "61000-320", "state": "CE", "city": "Maracanaú", "district": "AB" }, "document": { "country": "BR", "id": "2dc46761-17f9-4743-b637-e12820103304", "updatedAt": "2023-07-11T23:16:10.099Z", "createdAt": "2023-07-11T23:16:10.099Z", "type": "cnpj", "number": "94938591000196" } }, "bankAccount": { "id": "fb2919d9-55ad-4008-836c-0fdad9770ce1", "updatedAt": "2023-07-11T23:16:10.089Z", "createdAt": "2023-07-11T23:16:10.089Z", "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "transferPolicy": { "id": "52dafc52-1874-4cf0-a9c5-19dec0a5ffa9", "updatedAt": "2023-07-11T23:16:10.092Z", "createdAt": "2023-07-11T23:16:10.092Z", "transferDay": "5", "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": "", "automaticAnticipationType": "", "automaticAnticipationDays": "", "automaticAnticipation1025Delay": "" }, "mcc": 1, "status": "active" } ``` ## Edição de um recebedor A atualização é **parcial**: envie apenas os campos que deseja alterar. Campos omitidos permanecem inalterados. Para recebedores do tipo **pessoa física**, utilize a propriedade **owner**. Para **pessoa jurídica**, utilize **owner** e **business** conforme necessário. ```bash theme={null} curl --location --request PATCH 'https://api.malga.io/v1/sellers/4101ad7b-caf7-4065-9fbc-74461715bff8' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "owner": { "name": "Seller", "email": "seller@email.com", "phoneNumber": "85988350264", "birthdate": "1995-01-27", "document": { "type": "cpf", "number": "36243319067", "country": "BR" }, "address": { "street": "Rua Nova Lua", "streetNumber": "30", "complement": "apto 208 bloco c", "zipCode": "61000-320", "country": "BR", "state": "CE", "city": "Maracanaú", "district": "AB" }, "businessCategory": "OTHER_SERVICES" }, "mcc": 1, "bankAccount": { "holderName": "Seller name", "holderDocument": "36243319067", "bank": "077", "branchNumber": "492", "branchCheckDigit": "1", "accountNumber": "4929", "accountCheckDigit": "22", "type": "conta_corrente" }, "metadata": {[ "key": "768093", "value": "informação adicional" ]}, "transferPolicy": { "transferDay": 5, "transferEnabled": true, "transferInterval": "weekly", "automaticAnticipationEnabled": false, "anticipatableVolumePercentage": "", "automaticAnticipationType": "", "automaticAnticipationDays": "", "automaticAnticipation1025Delay": "" } }' ``` ## Exclusão de um recebedor ```bash theme={null} curl --location --request DELETE 'https://api.malga.io/v1/sellers/e6e04d54-ff69-4ea3-b2da-964b131fd0a0' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "bc570631-ec8e-4067-a4d1-62c639b142c1" }' ``` # Cobrança com Split Source: https://docs.malga.io/documentations/split/split Configure split em cobranças diretas via POST /v1/charges enviando splitRules no corpo da requisição para repasse automático entre recebedores. O **Split de pagamentos** foi criado com o objetivo de fazer o repasse automático dos valores de uma transação entre diversos recebedores com as regras estabelecidas pelo cliente Malga. Esta página descreve o fluxo de **cobrança direta**: `POST /v1/charges` com **`splitRules` no corpo**. Para **sessão ou link de pagamento**, o split é configurado **na criação da sessão** e **não** vai no corpo do pagamento da sessão — veja [Split em sessão ou link de pagamento](/documentations/split/split-em-sessao-link). ## Criando uma cobrança com Split Uma configuração de Split contém uma ou mais regras que definem taxas de comissão e condições, de acordo com a política comercial acordada entre a loja e o recebedor. Para criar uma transação com split, basta adicionar o campo **splitRules** que representará as regras daquela cobrança, dentro do corpo da requisição da [criação de uma transação](/api-reference/charges/realizar-nova-cobranca). ### Regras de split Cada regra (**splitRules**) em uma configuração dividida deve ter: * **Identificador do destinatário (sellerId)**: O valor de ID dentro de **splitRules** deve ser correspondente ao ID gerado na [criação de seller](/api-reference/sellers/criacao-de-um-novo-recebedor). * **Porcentagem (percentage)**: porcentagem do valor da transação original que será enviada ao destinatário. * **Valor (amount)**: valor que será enviado ao destinatário. * **Sinalizador de taxa de processamento (processingFee)**: o destinatário será cobrado pelas taxas de processamento, que serão descontadas de seu saldo, definido como falso para desconto do marketplace. * **Taxa integral (chargeEntireFee)**: indica se o recebedor será cobrado pela taxa inteira da transação. Disponível na Zoop. Em sessões e links de pagamento, não pode ser `true` junto com `chargeRemainderFee`. * **Taxa restante (chargeRemainderFee)**: indica se o recebedor será cobrado pela taxa restante da transação. Disponível na Pagar.me v5. * **Responsável pela transação (transactionOwner)**: campo booleano que indica se o recebedor é o responsável pela transação. Disponível na Zoop. Esse sinalizador não altera quanto cada recebedor recebe, definido por `percentage` ou `amount`, nem quem assume o risco de chargeback, definido por `liable`. * **Responsabilidade por reembolso (liable)**: o destinatário será responsável pelo reembolso (charge\_back), que será descontado de seu saldo, definido como falso para desconto do marketplace. * **Tarifas (fares)**: o destinatário será responsável pelas tarifas, que serão descontadas de seu saldo, definido como falso para desconto do marketplace. * **mdr (Merchant Discount Rate)**: percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento. * **Tarifa fixa (fee)**: também chamada de fee transacional. Valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira. > [!WARNING] > > * Não é possível realizar uma transação com split misto, isto é, utilizando as duas regras de divisão: porcentagem e valor; > * A informação de tarifas (mdr e fee) é específica para transações no provedor Braspag. > [!NOTE] > > **Precedência das regras de split:** se você definir regras de responsabilidade (taxas/chargeback) diretamente na transação (no campo `splitRules`), elas terão prioridade sobre as regras configuradas no cadastro do recebedor (seller). Isso garante flexibilidade para cenários específicos de venda. ### Exemplo de cobrança com Split aprovado usando o campo percentage ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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": false, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOAO DA SILVA", "cardNumber": "4929564637987814", "cardCvv": "320", "cardExpirationDate": "06/2028" } }, "splitRules": [{ "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "percentage": 10, "processingFee": true, "liable": true }, { "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "percentage": 10, "processingFee": false, "liable": false, }] }' < HTTP/2 201 { "id": "ca891189-6498-4ae3-a0f6-fc4ea72c8cb6", "clientId": "", "merchantId": "bc570631-ec8e-4067-a4d1-62c639b142c1", "description": null, "orderId": null, "createdAt": "2023-02-04T19:02:36.769Z", "amount": 150, "originalAmount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": false, "isDispute": false, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "ee6d344d-ed72-4895-a2fd-b7768418659f" }, "splitRules": [ { "id": "0db92aa7-1144-49b4-b501-483a21b7ae6c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "percentage": 10, "amount": null, "processingFee": true, "liable": true, "fareMdr": null, "fareFee": null }, { "id": "edcfe569-9b05-4a7b-a5d8-19d76a46a3d5", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "percentage": 10, "amount": null, "processingFee": false, "liable": false, "fareMdr": null, "fareFee": null } ], "transactionRequests": [ { "id": "9a28efab-5987-4287-8b02-fad1912513d3", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "a5f43d30-8254-48f8-ba89-f6bc27fe14cb", "providerId": "d9df60b3-fb97-4b30-9013-c08623944207", "providerType": "SANDBOX", "transactionId": "aca87a14-49d0-46ae-88d1-14f83a1e66fd", "amount": 150, "authorizationCode": "9301661", "authorizationNsu": "4244270", "requestStatus": "success", "requestType": "authorization", "responseTs": "62ms", "providerAuthorization": { "networkAuthorizationCode": "7909027", "networkResponseCode": "8168918" } } ], "appInfo": null } } ``` ### Exemplo de cobrança com Split aprovado usando o campo amount ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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": false, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOAO DA SILVA", "cardNumber": "4929564637987814", "cardCvv": "320", "cardExpirationDate": "06/2028" } }, "splitRules": [{ "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "amount": 50, "processingFee": true, "liable": true }, { "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "amount": 50, "processingFee": false, "liable": false, }] }' < HTTP/2 201 { "id": "ca891189-6498-4ae3-a0f6-fc4ea72c8cb6", "clientId": "", "merchantId": "bc570631-ec8e-4067-a4d1-62c639b142c1", "description": null, "orderId": null, "createdAt": "2023-02-04T19:02:36.769Z", "amount": 150, "originalAmount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": false, "isDispute": false, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "ee6d344d-ed72-4895-a2fd-b7768418659f" }, "splitRules": [ { "id": "0db92aa7-1144-49b4-b501-483a21b7ae6c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "percentage": null, "amount": 50, "processingFee": true, "liable": true, "fareMdr": null, "fareFee": null }, { "id": "edcfe569-9b05-4a7b-a5d8-19d76a46a3d5", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "percentage": null, "amount": 50, "processingFee": false, "liable": false, "fareMdr": null, "fareFee": null } ], "transactionRequests": [ { "id": "9a28efab-5987-4287-8b02-fad1912513d3", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "a5f43d30-8254-48f8-ba89-f6bc27fe14cb", "providerId": "d9df60b3-fb97-4b30-9013-c08623944207", "providerType": "SANDBOX", "transactionId": "aca87a14-49d0-46ae-88d1-14f83a1e66fd", "amount": 150, "authorizationCode": "9301661", "authorizationNsu": "4244270", "requestStatus": "success", "requestType": "authorization", "responseTs": "62ms", "providerAuthorization": { "networkAuthorizationCode": "7909027", "networkResponseCode": "8168918" } } ], "appInfo": null } } ``` ### Exemplo de cobrança com Split aprovado usando o campo de tarifa ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-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": false, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOAO DA SILVA", "cardNumber": "4929564637987814", "cardCvv": "320", "cardExpirationDate": "06/2028" } }, "splitRules": [{ "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "amount": 50, "processingFee": true, "liable": true, "fares": { "mdr": 2, "fee": 100 } }, { "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "amount": 50, "processingFee": false, "liable": false, "fares": { "mdr": 2, "fee": 100 } }] }' < HTTP/2 201 { "id": "ca891189-6498-4ae3-a0f6-fc4ea72c8cb6", "clientId": "", "merchantId": "bc570631-ec8e-4067-a4d1-62c639b142c1", "description": null, "orderId": null, "createdAt": "2023-02-04T19:02:36.769Z", "amount": 150, "originalAmount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": false, "isDispute": false, "status": "authorized", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "ee6d344d-ed72-4895-a2fd-b7768418659f" }, "splitRules": [ { "id": "0db92aa7-1144-49b4-b501-483a21b7ae6c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08", "percentage": null, "amount": 50, "processingFee": true, "liable": true, "fareMdr": "2.00", "fareFee": 100 }, { "id": "edcfe569-9b05-4a7b-a5d8-19d76a46a3d5", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "30ecebe3-2e31-4d4d-8cda-75c3691100ea", "percentage": null, "amount": 50, "processingFee": false, "liable": false, "fareMdr": "2.00", "fareFee": 100 } ], "transactionRequests": [ { "id": "9a28efab-5987-4287-8b02-fad1912513d3", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "a5f43d30-8254-48f8-ba89-f6bc27fe14cb", "providerId": "d9df60b3-fb97-4b30-9013-c08623944207", "providerType": "SANDBOX", "transactionId": "aca87a14-49d0-46ae-88d1-14f83a1e66fd", "amount": 150, "authorizationCode": "9301661", "authorizationNsu": "4244270", "requestStatus": "success", "requestType": "authorization", "responseTs": "62ms", "providerAuthorization": { "networkAuthorizationCode": "7909027", "networkResponseCode": "8168918" } } ], "appInfo": null } } ``` ## Estorno total ou parcial É possível realizar um estorno no valor total ou parcial da cobrança com split. O indicador **payout eligible** (`isPayoutEligible`) foi descontinuado; use `splitRules` no void conforme documentado abaixo e não dependa desse campo. Saiba mais na [release de jun/2026](/release-notes/2026-06-12-Release-Notes). Para um estorno parcial, é necessário determinar o valor a ser cancelado para cada participante da transação. Esta informação deve ser inserida na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada), adicionando o nó `splitRules` com os dados de `sellerId` e `amount` que se deseja estornar para o seller específico. > [!NOTE] > > Para estorno total, não é necessário adicionar o nó de `splitRules`, basta enviar o valor total da transação. O nó `splitRules` dentro da requisição de estorno contém: * **Identificador do destinatário (sellerId)**: O valor de ID dentro de **splitRules** deve ser correspondente ao ID do seller para o qual se pretende fazer o estorno. * **Valor (amount)**: valor que se pretende estornar > [!WARNING] > > O somatório dos valores de estorno definidos para cada sellerId deve ser igual ao valor contido no campo amount que fica fora do nó de `splitRules` ### Exemplo de requisição com falha na especificação do amount ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges/363bb85e-1ccb-4599-8072-b4090958a173/void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 15, "splitRules": [ { "sellerId": "sellerId", "amount": 12 }, { "sellerId": "sellerId-2", "amount": 5 } ] }' < HTTP/2 400 < content-type: application/json; charset=utf-8 { "error": { "type": "bad_request", "code": 400, "message": "Split sum amount must be equal to transaction amount" } } ``` ### Exemplo de requisição de estorno parcial com Split ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges/3e9763f8-ca8c-4b5a-a085-e6cb6deb2a9f/void' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 20, "splitRules": [ { "sellerId": "sellerId", "amount": 10 }, { "sellerId": "sellerId-2", "amount": 10 } ] }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "2fed2037-8c8d-4f9b-be9c-d2cbfadd5c78", "clientId": "", "merchantId": "", "description": null, "orderId": "orderId", "providerReferenceKey": null, "createdAt": "2024-06-18T18:33:46.801Z", "amount": 980, "originalAmount": 1000, "currency": "BRL", "statementDescriptor": "Descrição do Pedido", "capture": true, "isDispute": false, "status": "authorized", "responsibleProviderType": "SANDBOX", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "a70b22e1-91fc-4fb6-96b8-6747e77bd918" }, "splitRules": [ { "sellerId": "sellerId", "amount": 500, "processingFee": true, "liable": true }, { "sellerId": "sellerId-2", "amount": 500, "processingFee": false, "liable": false, } ], "transactionRequests": [ { "id": "a4b0c251-1bf1-4bf6-acc3-f281ec3545aa", "createdAt": "2024-06-18T18:33:47.096Z", "updatedAt": "2024-06-18T18:33:47.250Z", "idempotencyKey": "36d90c45-9d20-4178-9745-4c77f0fd7f58", "providerId": "ad520776-88c7-42fb-9159-fbff9bd3f187", "providerType": "SANDBOX", "transactionId": "68158434-c97c-420c-b4dd-cf59854a48cb", "amount": 20, "authorizationCode": "3969942", "authorizationNsu": "2052745", "requestStatus": "success", "requestType": "void", "requestStatusReason": null, "responseTs": "98ms", "providerAuthorization": { "networkAuthorizationCode": "4583340", "networkResponseCode": "4953708" }, "split": [ { "amount": 10, "sellerId": "sellerId" }, { "amount": 10, "sellerId": "sellerId-2" } ] }, { "id": "fef29ba4-b507-4c26-b55a-f26da8218eee", "createdAt": "2024-06-17T14:20:15.689Z", "updatedAt": "2024-06-17T14:20:18.854Z", "idempotencyKey": "2aeba00b-822c-4144-ad70-6d2af44af9b7", "providerId": "eef33a73-d6eb-4c2f-b118-33d93253c1be", "providerType": "SANDBOX", "transactionId": "68158434-c97c-420c-b4dd-cf59854a48cb", "amount": 1000, "authorizationCode": "133937", "authorizationNsu": "68158434-c97c-420c-b4dd-cf59854a48cb", "requestStatus": "success", "requestType": "authorization", "requestStatusReason": null, "responseTs": "3088ms", "providerAuthorization": { "networkAuthorizationCode": "133937", "networkResponseCode": "00" } } ], "appInfo": null } ``` ### Exemplo de requisição de estorno total de transação com split ```bash theme={null} curl -X POST 'https://api.malga.io/v1/charges/0a4613aa-b943-462d-ae35-2b67afe63891/void' \ --header 'X-Client-Id: 44109d98-91ad-4a8d-83e6-17f4c2b94ad8' \ --header 'X-Api-Key: 4caeef91-8732-4f58-95a3-47904bd20fb3' \ --header 'Content-Type: application/json' \ --data '{ "amount": 140 }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "0a4613aa-b943-462d-ae35-2b67afe63891", "clientId": "", "merchantId": "", "description": null, "orderId": "orderId", "providerReferenceKey": null, "createdAt": "2024-06-21T14:58:00.522Z", "amount": 0, "originalAmount": 140, "currency": "BRL", "statementDescriptor": "Descrição do Pedido", "capture": true, "isDispute": false, "status": "voided", "responsibleProviderType": "BRASPAG", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "b1aaaca0-8b74-48f5-83b1-3060f872627c" }, "transactionRequests": [ { "id": "24fcd905-7f97-4c91-babb-ab0f707be37f", "createdAt": "2024-06-21T15:00:41.973Z", "updatedAt": "2024-06-21T15:00:41.973Z", "idempotencyKey": "c3afdffe-2b80-4b4d-8729-ff10bd9e6ea4", "providerId": "c6a8e509-4f02-4393-9f76-d71176ff86e9", "providerType": "BRASPAG", "transactionId": "6670c0f9-f768-4873-8e1c-34c2ea3049b2", "amount": 140, "authorizationCode": "", "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "requestStatusReason": null, "responseTs": "3400ms", "providerAuthorization": { "networkAuthorizationCode": null, "networkResponseCode": 0 } }, { "id": "3c46e05c-85cd-41f3-963a-d27c73f73afa", "createdAt": "2024-06-21T14:58:00.663Z", "updatedAt": "2024-06-21T14:58:04.512Z", "idempotencyKey": "fc124b62-53c0-4ae2-8c58-1fc0a5188aa3", "providerId": "c6a8e509-4f02-4393-9f76-d71176ff86e9", "providerType": "BRASPAG", "transactionId": "6670c0f9-f768-4873-8e1c-34c2ea3049b2", "amount": 140, "authorizationCode": "040535", "authorizationNsu": "462906", "requestStatus": "success", "requestType": "authorization", "requestStatusReason": null, "responseTs": "3823ms", "providerAuthorization": { "networkAuthorizationCode": "040535", "networkResponseCode": "2" } } ], "appInfo": null } ``` # Split em sessão ou link de pagamento Source: https://docs.malga.io/documentations/split/split-em-sessao-link Configure regras de splitRules na criação da sessão na Malga; o pagamento da sessão ou link herda automaticamente o split já definido. ## Visão geral No fluxo por **sessão** ou **link de pagamento**, o split não é definido no corpo da requisição de pagamento (`POST /v1/sessions/{id}/charge`). Você envia **`splitRules` ao criar a sessão** (`POST /v1/sessions`). O serviço armazena as regras; na cobrança, a Malga recupera os dados da sessão e **aplica o split já configurado** na transação. Para cobrança **direta** com split no mesmo request, use [`POST /v1/charges`](/api-reference/charges/realizar-nova-cobranca) conforme [Cobrança com Split](/documentations/split/split). > [!NOTE] > > O roteamento de pagamento da sessão obtém os dados da sessão internamente e > aplica o split armazenado. **Não** envie `splitRules` no corpo ao pagar a > sessão. ## Pré-requisitos Os **recebedores (sellers)** precisam existir e estar válidos **antes** de referenciá-los em `splitRules`. Na criação da sessão, o serviço de sessões valida a existência dos recebedores; no momento da cobrança, o fluxo de transações e sellers trata mapeamento com o provedor e status para a captura. Veja [Recebedor (seller)](/documentations/split/seller). ## Fluxo resumido 1. Crie os sellers necessários. 2. **Crie a sessão** com `splitRules` no JSON (junto a `amount`, `items`, `paymentMethods`, etc.). 3. **Pague a sessão** enviando apenas método e origem do pagamento (por exemplo `paymentMethod` e `paymentSource`). **Sem** `splitRules` no corpo. ```mermaid theme={null} %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1f2937', 'primaryTextColor': '#e5e7eb', 'primaryBorderColor': '#475569', 'lineColor': '#64748b', 'background': '#0b1220', 'mainBkg': '#111827', 'nodeBorder': '#334155', 'textColor': '#cbd5e1' }}}%% flowchart TD sellers[Crie os sellers] --> session[Crie a sessão com splitRules] session --> payment[Pague a sessão sem splitRules] payment --> charge[A cobrança herda o split da sessão] ``` ## Exemplo: criar sessão com split ```bash theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "Marketplace - 2 sellers", "merchantId": "", "amount": 1000, "currency": "BRL", "capture": true, "paymentMethods": [ { "paymentType": "credit", "installments": 1 } ], "dueDate": "2026-02-20", "items": [ { "name": "Produto", "unitPrice": 1000, "quantity": 1, "tangible": true } ], "splitRules": [ { "sellerId": "", "percentage": 60, "processingFee": true, "chargeEntireFee": true, "liable": true }, { "sellerId": "", "percentage": 40, "processingFee": false, "chargeEntireFee": false, "chargeRemainderFee": false, "liable": false } ] }' ``` A resposta da sessão pode incluir `splitRules` persistidos (como em outros recursos de cobrança). Consulte a [especificação de sessões](/api-reference/sessions/criar-nova-sessao). ## Exemplo: pagar sessão (sem split no corpo) ```bash theme={null} curl --location 'https://api.malga.io/v1/sessions//charge' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "customer", "customerId": "" } }' ``` O split aplicado na transação é o **definido na criação da sessão**, não o deste corpo. ## Regras de validação (split na sessão) * Em cada regra, use **exatamente um** entre `percentage` ou `amount`. * Não misture regras **só em valor** e **só em percentual** na mesma sessão. * Soma de **percentuais** pode ser **até 100%**. * Soma de **valores** em centavos não pode **ultrapassar** o valor da sessão ou da transação. * `chargeEntireFee` e `chargeRemainderFee` **não** podem ser `true` ao mesmo tempo. Para o detalhamento dos campos de regra, veja [Cobrança com Split](/documentations/split/split#regras-de-split) (mesmo modelo de regra, aplicado na criação da sessão em vez do `POST /v1/charges`). # Migração de cartões Source: https://docs.malga.io/documentations/tokenization/card-migrations A Malga oferece a possibilidade de transferir a base de dados sensíveis de cartão de crédito de forma segura entre os Vaults de provedores de pagamentos. ## Possíveis cenários para migração dos dados ### Importando cartões de um provedor existente Passos para importar a base de cartões de crédito para Malga. 1. Entre em contato com o time de CS ([suporte@malga.io](mailto:suporte@malga.io)) da Malga para obter a última versão do nosso Attestation of Compliance (AoC) do PCI DSS. 2. Contate a solução do provedor (Vault/Gateway) existente e faça um pedido de exportação da base de cartões. Por favor, envie junto o nosso Attestation of Compliance (AoC) do PCI DSS, e a nossa [chave PGP](#chave-pgp). Uma boa mensagem para o provedor seria: > Olá \[Provedor], Eu gostaria de exportar toda a minha base de cartões de crédito para o Vault da Malga que é certificado no PCI DSS Level 1. Segue em anexo o AoC da Malga. > > Quando a exportação estiver concluída, por favor envie as informações de como acessar os dados para o email [security@malga.io](mailto:security@malga.io) passando o nome do Merchant. O time de Customer Success da Malga pode ajudar com eventuais dúvidas. A chave PGP da Malga se encontra nesta página: [https://docs.malga.io/documentations/tokenization/card-migrations#chave-pgp](https://docs.malga.io/documentations/tokenization/card-migrations#chave-pgp) 3. Passe a informação para o nosso time de CS com o clientId que os dados serão importados. 4. A transferência dos dados depende do processo do gateway e de como eles fazem a exportação. * Se o Gateway prefere configurar o SFTP do lado deles para transferir, então eles precisam enviar as credenciais para o nosso time ([security@malga.io](mailto:security@malga.io)) usando a nossa PGP Key. * Se o Gateway prefere acessar nosso servidor SFTP, então eles precisam passar a chave pública SSH deles para o nosso time ([security@malga.io](mailto:security@malga.io)) configurar um usuário no nosso SFTP, e em seguida passamos essa informação para o Gateway. Se necessário, nós iremos trabalhar diretamente com o Gateway ou serviço de Vault para ajudar no processo de importação. Nossos clientes são responsáveis por autorizar a exportação dos dados para nosso Vault. ### Exportando dados da Malga para outro provedor 1. Contate o time de Customer Success (CS) da Malga pedindo os dados que vão ser exportados, e passando junto o AoC do PCI DSS do provedor de pagamentos que a base de dados será enviada, a chave PGP que precisa constar no site do provedor de pagamentos, e o endereço de email para envio das credenciais. 2. Assim que nosso time exportar a base de dados, vamos enviar as credenciais do nosso servidor SFTP para o endereço de email informado com as credenciais criptografadas com a chave PGP enviada pelo provedor. 3. Os dados ficam disponíveis no servidor SFTP por 30 dias. ## Formato dos dados A exportação de cartões é gerada em formato CSV com separador `;` (ponto e vírgula). O arquivo contém os seguintes campos: | Campo | Descrição | | - | - | | `card_id` | Identificador único do cartão no Vault da Malga | | `card_customer_id` | Identificador do cliente associado ao cartão | | `card_number` | Número completo do cartão (descriptografado) | | `card_expiration_date` | Data de vencimento do cartão | | `card_holdername` | Nome do titular do cartão | | `card_first6_digits` | Primeiros 6 dígitos do cartão (BIN) | | `card_last4_digits` | Últimos 4 dígitos do cartão | Exemplo do formato gerado em CSV: ```csv theme={null} card_id;card_customer_id;card_number;card_expiration_date;card_holdername;card_first6_digits;card_last4_digits f76a763d-0f06-4b66-a7e0-a7a42af99e7a;cus_abc123;526607******1234;10/2030;NOME DE TESTE;526607;1234 ``` Somente cartões com status `active` são incluídos na exportação. > [!NOTE] > > O arquivo exportado possui dado sensível sob o escopo do PCI DSS. É criptografado com a chave PGP do provedor destino, que deve possuir certificação PCI DSS válida, e fica disponível no servidor SFTP por 30 dias. Trate o arquivo com restrição de acesso e descarte-o de forma segura após o uso. ## Chave PGP A nossa chave pública PGP usada para transferência está disponível para [download](/assets/files/sec-malga-pgp-57D3319106E84B23-2026-04-30.txt) e reproduzida abaixo. ```text theme={null} pub ed25519/57D3319106E84B23 2026-04-30 [SC] [expires: 2028-04-29] Key fingerprint = 0F4C C087 286F 768E D03C 8A25 57D3 3191 06E8 4B23 uid Malga Security Team sub cv25519/FFBF8BD6E12AF63B 2026-04-30 [E] [expires: 2028-04-29] -----BEGIN PGP PUBLIC KEY BLOCK----- mDMEafPADRYJKwYBBAHaRw8BAQdAltOSv7hMbwvgYYqxDjHOJ26G3TTXJoIENZb/ DD3Cqfe0J01hbGdhIFNlY3VyaXR5IFRlYW0gPHNlY3VyaXR5QG1hbGdhLmlvPoiZ BBMWCgBBFiEED0zAhyhvdo7QPIolV9MxkQboSyMFAmnzwA0CGwMFCQPCZwAFCwkI BwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQV9MxkQboSyOT0wEA5oT/3x3EI8fq j77Xw5EOdF7v+sVkQ1YyZ6Mi9RpLtowBAMm/t6n8QDLztaTXdlRGhcs/ZGxLVWiL 1rQnakNbkmsHuDgEafPADRIKKwYBBAGXVQEFAQEHQChTt1EnSdvFFMSaO1DNDQrJ YrCswk9DnpyTZKBdQJBNAwEIB4h+BBgWCgAmFiEED0zAhyhvdo7QPIolV9MxkQbo SyMFAmnzwA0CGwwFCQPCZwAACgkQV9MxkQboSyP/8AD+LeNPKza5J4VsQ6EkBfeA Vl+3RpzO6BaJT50Ucq6HWbwBAP/EzA6kbj3GNLmu9sjGIVLnCCjgoWzdPl+PO9zR ZZEI =TJTN -----END PGP PUBLIC KEY BLOCK----- ``` # Serviço de Tokenização da Malga Source: https://docs.malga.io/documentations/tokenization/intro Conheça o Serviço de Tokenização da Malga: processe dados sensíveis de cartões de forma segura usando tokens criptografados em vez do número real. Malga criou este [Serviço de Tokenização](/api-reference/tokens/criar-um-novo-token) para permitir que os dados sensíveis de cartão sejam processados de maneira segura. Através da [Tokenização](/api-reference/tokens/criar-um-novo-token), é possível garantir que os dados sensíveis do cartão (holder name, pan, cvv) não passem pelo seu backend e possam ser enviados para os servidores da Malga diretamente da sua aplicação cliente. Um token representa dados sensíveis de cartão armazenados de maneira segura na Malga, seguindo as melhores práticas do PCI, sendo os dados enviados direto do seu frontend para os servidores da Malga. É extremamente recomendado que você realize o processo de tokenização diretamente no lado do cliente, coletando os dados sensíveis de cartão na sua interface e enviando diretamente para o Serviço de Tokenização, a partir de um client token criado para essa funcionalidade, enviando para seu backend o identificador do token gerado que não guarda dados sensíveis e pode ser trafegado normalmente pelos seus servidores. > [!WARNING] > > Os Tokens são invalidados após o primeiro uso, não sendo possível armazenar o > token gerado para uso futuro em compras recorrentes. Caso queira salvar os > dados de um cartão para uso futuro, você deve realizar a criação de um token e > na sequência solicitar a criação de um cartão a partir do token criado, dessa > forma o cartão ficará armazenado em definitivo no nosso *vault*, servidor de > armazenamento seguro de cartões, bastando enviar somente o card id gerado nas > transações futuras. ![Fluxo de criação de token](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/tokenization/fluxotokennovo.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=a6bc7dc7759e114b8791b90c7bea36bd) Você pode criar cartões a partir de tokens gerados, sendo possível associar múltiplos cartões a um mesmo comprador, de maneira a possibilitar cobrança futura. > [!WARNING] > > O **token** gerado na tokenização é temporário e expira em 2 > horas. Esse token guarda os dados sensíveis (como o CVV) usados para criar o > cartão. O **`cardId`**, gerado a partir do token, é **permanente** e não > expira, ele identifica o cartão salvo em definitivo no vault da Malga. ## Criando um Card ID Uma vez criado um cartão é gerado um identificador único `cardId` que pode ser armazenado no seu sistema, já que não contém dados sensíveis de cartão, somente um identificador de um cartão salvo de maneira segura no vault da Malga. A partir de um `cardId` gerado é possível realizar cobranças recorrentes, bastando enviar esse identificador no momento da criação do `charge`. ## Por que uma cobrança é aceita após a expiração do token? Uma dúvida comum é por que um `cardId` continua aceitando cobranças mesmo depois das 2 horas de expiração do token. O motivo é que **o que expira é o token (e o CVV nele guardado), não o cartão**: o `cardId` permanece válido no vault e segue disponível para cobranças. Após a expiração do token, a cobrança com `cardId` ainda pode ser aprovada quando: * **Você envia o `cvv` na própria cobrança.** O campo `cvv` é opcional no `paymentSource` e, quando informado, é repassado ao provedor, não dependendo do token tokenizado. * **O merchant está habilitado a cobrar sem CVV.** Nesse cenário, a transação segue para o provedor sem o código de segurança e a aprovação depende das regras do emissor. * **O cartão está com status `active` ou `pending`.** Ambos seguem utilizáveis no fluxo transacional (veja [Status de cartão](#status-de-cartão)). > [!NOTE] > > Durante a janela de 2 horas após a tokenização, a Malga ainda consegue > recuperar o CVV a partir do token para aumentar a chance de aprovação. Passado > esse prazo, o CVV não está mais disponível pelo token, mas a cobrança com > `cardId` continua possível pelos caminhos descritos acima. Por isso o > comportamento pode parecer diferente conforme o merchant exija ou não o CVV na > cobrança. > [!WARNING] > > O código de segurança (cvv) do cartão, que foi enviado na tokenização, é > validado através de uma transação de valor zero junto ao emissor do cartão, > dessa maneira a Malga consegue validar se os dados tokenizados do cartão são > válidos sem que seja necessário realizar uma cobrança efetiva. Após a > validação com sucesso dos dados do cartão, o mesmo fica com status:active e > disponível para compras futuras, caso contrário, o cartão ficará com > status:failed e invalidado, devendo ser gerado um novo token e um novo cartão. ## Status de cartão 1. O atributo `cvvchecked` identifica se o cartão teve ou não seus dados validados na tokenização. Algumas bandeiras não permitem validação zero dollar; nesse caso, o cartão passa a ser criado como `status=active` e `cvvchecked=false`. 2. O status `active` continua identificando se o cartão está disponível para uso no fluxo transacional, porém não é garantia de que um cartão `status=active` retornará sucesso na cobrança, é possível retorno de falha na cobrança por parte dos bancos. 3. O status `failed` continua identificando um cartão que NÃO pode ser usado no fluxo transacional, é um token já identificado como inválido e não poderá ser utilizado. 4. O status `pending` passa a identificar os casos de impossibilidade de validação dos dados do cartão na sua criação. Enquanto o status estiver pending o cartão pode ser usado para criar transação *durante a janela de validade do token (2 horas)*, garantindo maior resiliência do transacional. Um cartão `status=pending` *ao ser utilizado para uma cobrança*, tem seu status atualizado para `active` se os dados do cartão forem válidos, e atualizado para `failed` se os dados do cartão forem inválidos. Os status possíveis para um `card` na Malga são: | Status | Descrição | | - | - | | **active** | Caso os dados do cartão sejam validados, o status é retornado como active e cvvchecked true | | **failed** | Caso os dados do cartão não sejam validados, o status é retornado como failed e cvvchecked false | | **pending** | Caso o Serviço de Validação dos dados do cartão esteja indisponível, o status é retornado como pending e cvvchecked: false; Enquanto o status estiver pending o cartão pode ser usado para criar transação, garantindo maior resiliência do transacional. | > [!TIP] > > É possível enviar o `cvv` do cartão como opcional na requisição de cobrança, > sendo útil nos cenários onde o cartão está com status pending ou active, sendo > este `cvv` repassado para o provedor aumentando assim as chances de aprovação > nos casos onde você pode solicitar o código de segurança no momento da > cobrança. ## Bandeiras aceitas As bandeiras aceitas para transações na plataforma da Malga, de acordo com o método de pagamento, são: | | Bandeira | Crédito | Débito | Voucher | | - | - | - | - | - | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/american-express.svg) | Amex | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/dinners.svg) | Dinners | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/discover.svg) | Discover | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/elo.svg) | Elo | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/jcb.svg) | JCB | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/maestro.svg) | Maestro | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/mastercard.svg) | Mastercard | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/mir.svg) | MIR | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/sodexo.svg) | Sodexo | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/ticket.svg) | Ticket | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/union-pay.svg) | Union Pay | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/visa.svg) | Visa | | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/vr.svg) | VR | | | | > [!WARNING] > > **Importante:** Apesar do suporte à tokenização para o método de pagamento > voucher, é importante observar limitações próprias em cartões desse método de > pagamento, que impossibilitam transações sem CVV. Em decorrência disso, o > cartão tokenizado só pode ser utilizado em uma única transação. # Tokenização de Bandeira Source: https://docs.malga.io/documentations/tokenization/network-tokens Tokenização de Bandeira na Malga: substitua dados sensíveis por tokens criptografados registrados diretamente nas bandeiras dos cartões. A Tokenização de Bandeira é um sistema de segurança que substitui os dados sensíveis de um cartão de crédito por um token criptografado registrado diretamente na bandeira do cartão. Cada transação feita após a tokenização do cartão passará a utilizar o token, dispensando o uso dos dados do cartão como nome do portador do cartão, data de validade, CVV, entre outros. Com a Tokenização de Bandeira Malga é possível gerar tokens de cartões de crédito utilizados para processar pagamentos na Malga diretamente nas bandeiras. Este processo é automático e faz parte do ciclo de vida dos cartões de crédito na Malga. > [!NOTE] > > Para habilitar a funcionalidade de tokenização de bandeira na sua conta Malga entre em contato com o nosso time de suporte. ## Provedores com suporte a tokens de bandeira > [!WARNING] > > Atualmente a Malga só suporta tokenização das bandeiras Visa e Master. | Provedor | Bandeiras Suportadas | | - | - | | Adyen | Visa, Master | | Cielo | Visa, Master | | Getnet SEP | Visa, Master | | Mercado Pago | Visa, Master | | PagSeguro | Visa, Master | | Rede | Visa, Master | | WorldPay | Visa, Master | ## Transações com Tokens de Bandeira Transações com Token de Bandeira se comportam da mesma forma que transações de [Cartão de Crédito](/documentations/payment-methods/credit-card). Durante o processo de geração de uma transação com Token de Bandeira é gerado obrigatoriamente um Criptograma para fazer a comunicação com os provedores de cobrança, aumentando a segurança da transação. > [!NOTE] > > O criptograma é gerado automaticamente, de forma interna na Malga, e não é necessária nenhuma alteração em sua integração para que ele seja gerado. ### Ciclo de vida do Token de Bandeira O token de bandeira na Malga possui um ciclo de vida composto por quatro status diferentes: | Status | Descrição | | - | - | | `active` | O token está disponível para gerar criptogramas e transacionar. | | `suspended` | Token está temporariamente indisponível para transacionar. Um token suspenso pode ser reativado. | | `deleted` | O Token deletado não pode transacionar e não pode mais ser reabilitado. | | `failed` | O Token não chegou a ser criado e encontrou uma falha durante sua tentativa de criação. | ### Quais cartões são tokenizados? São tokenizados na bandeira apenas cartões **válidos**. São considerados cartões **válidos** cartões que tenham tido uma transação bem-sucedida ou uma validação de [Zero Dollar](/documentations/tokenization/zero-dollar) bem-sucedida no passado e que não tenha um token de bandeira associado ao seu fingerprint. Você também pode definir quais bandeiras gostaria de habilitar ou desabilitar o processo de tokenização individualmente. ### Atualizações de tokens A bandeira pode atualizar seus tokens através de um evento de ciclo de vida do token. Estes eventos ficam registrados na Malga e os tokens são atualizados automaticamente. # Token CVV Source: https://docs.malga.io/documentations/tokenization/token-cvv O CVV (Valor de verificação do cartão), é o código de segurança composto por três ou quatro dígitos, utilizado nas compras online, o código substitui a senha usada em estabelecimentos físicos. Com a finalidade de garantir que no ato da compra o cliente tenha o seu cartão em mãos, evitando fraudes. A tokenização é um método de substituição dos dados sensíveis do portador (CVV), por um token, para que a experiência de pagamento digital seja mais segura. ## Cenário de utilização O recurso de tokenização do CVV é normalmente utilizado em transações usando dados de cartão de crédito já armazenados no cofre, no qual os clientes desejam passar o CVV de forma segura através de um token, ao invés do CVV em texto plano. Para isso, utiliza-se a solução de `Token CVV`, garantindo que a aplicação dos clientes não consiga enxergar o conteúdo desse token. > [!WARNING] > > O token é invalidado após o seu uso e/ou pelo tempo de expiração, sendo > impossível utilizá-lo futuramente. Para isso é necessário gerar um novo token > e informar esse na transação. ## Exemplo de tokenização do CVV ```bash theme={null} curl --location 'https://api.malga.io/v1/tokens' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "cvvUpdate": "410" }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "tokenId": "72964dfb-4a81-43c6-a231-1944c54adc7f" } ``` ## Exemplo de transação utilizando a tokenização CVV ```bash theme={null} curl --location 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "merchantId": "147d838e-2507-47cd-b371-0379be09c904", "amount": 150, "currency": "BRL", "statementDescriptor": "Pedido #231 loja joão", "capture": true, "orderId": "7171717171", "description": "descrição" "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "f2e362f3-2527-485f-8bc7-483289436a89", "tokenCvv": "72964dfb-4a81-43c6-a231-1944c54adc7f" } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "985d784f-24c5-4faa-ba6a-cb8f2d21b49c", "clientId": "1b2c2ef7-03cd-4012-9d1c-aff50551fae3", "merchantId": "95d89ff9-751b-4cc7-b45c-d4d886cf6589", "description": "0a95395b-f12f-4d13-8c00-9f76133645e7", "orderId": "231ef650-65c5-457f-937c-bb2ef8961ca8", "createdAt": "2023-08-04T14:02:05.082Z", "amount": 100, "originalAmount": 100, "currency": "BRL", "statementDescriptor": "Token CVV", "capture": true, "isDispute": false, "status": "failed", "paymentMethod": { "installments": 1, "paymentType": "credit" }, "paymentSource": { "sourceType": "card", "cardId": "4c5da4c4-c3c4-4c7f-bc00-7bfddec13dbc" }, "transactionRequests": [ { "id": "0d42ceca-1443-4e39-a852-0276dc217980", "createdAt": "2023-08-04T14:02:05.166Z", "updatedAt": "2023-08-04T14:02:05.271Z", "idempotencyKey": "a50a659f-1851-4d7f-b7c4-cd6a307d40bb", "providerId": "00e1997a-5204-465e-bc77-1b675ac8757e", "providerType": "SANDBOX", "transactionId": "2767078", "amount": 100, "authorizationCode": "1547251", "authorizationNsu": "6783923", "requestStatus": "failed", "requestType": "authorization", "responseTs": "41ms", "providerError": { "retryable": false, "declinedCode": "invalid_cvv", "message": null, "networkDeniedMessage": "Invalid CVV", "networkDeniedReason": "sandbox invalid cvv" } } ] } ``` > [!TIP] > > Para saber mais sobre a Tokenização confira em [nossa > documentação](/documentations/tokenization). # Validação de cartões com zero dollar Source: https://docs.malga.io/documentations/tokenization/zero-dollar Valide cartões de crédito com zero dollar na Malga sem gerar cobranças ao portador, criando um merchant com provedor compatível ao salvar o cartão. Uma transação de validação de cartões, também conhecida como zero dollar ou zero dólar, é uma funcionalidade usada para verificar se o cartão de crédito é válido sem gerar cobranças ao portador do cartão. Para usar essa funcionalidade você precisa informar o número do cartão, o nome impresso no cartão, o CVV e a data de expiração. ## Validar um cartão via zero dollar A funcionalidade de zero dollar funciona no momento de salvar um cartão de crédito. Abaixo detalhamos o passo a passo: ### Passo 1 - Criar um merchant Crie um merchant com pelo menos 1 provedor com suporte a validação de zero dollar. > [!NOTE] > > Esse passo é importante porque o merchant criado será usado no passo 3 > (validar e salvar o cartão) ```bash theme={null} curl --location 'https://sandbox-api.malga.io/v1/merchants' \ --header 'x-api-key: ' \ --header 'x-client-id: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "zero dollar validator", "mcc": "4040", "providers": [{ "priority": 1, "name": "SANDBOX", "credentials": { "type": "SANDBOX", "apiKey": "123" } }] }' ``` Resultado: ```bash theme={null} { "id": "5ce1c068-8073-43e6-abfb-b995aa0e8551", "name": "zero dollar validator", "mcc": "4040", "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "status": false, "createdAt": "2023-05-30T13:16:06.979Z", "updatedAt": "2023-05-30T13:16:06.979Z", "providers": [ { "id": "49630f05-5ce4-4455-ac27-15f66a848d93", "name": "SANDBOX", "priority": 1, "credentials": { "type": "SANDBOX", "apiKey": "******" }, "options": null, "createdAt": "2023-05-30T13:16:06.979Z", "updatedAt": "2023-05-30T13:16:06.979Z" } ] } ``` Nesse exemplo acima criamos um merchant usando nosso adapter de sandbox. > [!WARNING] > > É importante dizer que nosso adapter sandbox não faz uma verificação real do > cartão. Usamos mocks para emular cenários. ### Passo 2 - Tokenização Agora precisamos tokenizar os dados do cartão para trafegar os dados de forma segura. ```bash theme={null} curl --location 'https://api.malga.io/v1/tokens' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "cardHolderName": "JOAO DA SILVA", "cardNumber": "4929564637987814", "cardCvv": "320", "cardExpirationDate": "12/2026" }' ``` Resultado: ```bash theme={null} { "tokenId": "1f0d571b-6baf-4cbd-bf22-49f0c5b50565" } ``` > [!NOTE] > > Se você estiver usando um merchant com nosso provedor SANDBOX de testes, você pode variar o CVV para testar um cenário de cartão válido e outro de cartão inválido. > > Para testar um cenário válido basta que o CVV termine com 0 (zero), por exemplo, 320. > > Para testar um cenário que o cartão não é válido basta que o CVV não termine com 0 (zero), por exemplo, 321 Se tiver dúvidas sobre tokenização de cartão [clicando aqui](/documentations/tokenization/intro) você acessa nossa documentação sobre esse assunto. ### Passo 3 - Validar e salvar o cartão O processo de verificação do cartão ocorre no momento que o cartão será salvo no cofre (vault) de cartões. Para validar o cartão usando zero dollar precisamos informar 3 propriedades no payload: * **merchantId:** Merchant contendo pelo menos 1 provedor com validação de zero dollar. * **tokenId:** Token que contém os dados do cartão * **cvvCheck:** `true` ou `false` para indicar o desejo de verificar ou não o cartão via zero dollar. Importante dizer que se você optar por não verificar o cartão, o mesmo será criado com status `pending`, permitindo que você tente validar esse cartão via uma transação. ```bash theme={null} curl --location 'https://api.malga.io/v1/cards' \ --header 'x-client-id: ' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "merchantId": "", "tokenId": "", "cvvCheck": true }' ``` Resultado: ```bash theme={null} { "id": "dc5c9317-2fa3-48a5-b759-1a2583feb2b3", "status": "active", "statusReason": null, "createdAt": "2023-05-30T16:18:11.045Z", "clientId": "567265cb-fa7f-419f-9c1c-8e878dd2faf7", "brand": "Visa", "cardHolderName": "JOAO DA SILVA", "cvvChecked": true, "fingerprint": "p5hgkYxaw5EXgim3GbJ7KzDUhdtxo1O2+qkLFj/Qyoo=", "first6digits": "492956", "last4digits": "7814", "expirationMonth": "12", "expirationYear": "2026", "transactionRequests": [ { "id": "5325ecea-3009-41c3-9f3e-51b787ccdec8", "createdAt": "2023-09-25T18:09:59.001Z", "providerId": "ad520776-88c7-42fb-9159-fbff9bd3f187", "providerType": "SANDBOX", "requestStatus": "success", "requestType": "zero_dollar", "responseTs": "32ms" } ] } ``` ## Provedores com suporte a zero dollar | Provedor | Detalhes | | - | - | | Sandbox | Somente para testes. Use para emular comportamentos de cartão válido / inválido | | Bolt | — | | Braspag | — | | Cielo | Suporta somente bandeiras Visa, Master e Elo | | Getnet Sep | [https://devportalgetnet.sensedia-eng.com/pt/products/online-payments/regional-api?doc=api-ref-card-verification](https://devportalgetnet.sensedia-eng.com/pt/products/online-payments/regional-api?doc=api-ref-card-verification) | | Klap | [https://api.pasarela.multicaja.cl/docs/apitarjetas#operation/Demorado%20(Modelo%20PSP)](https://api.pasarela.multicaja.cl/docs/apitarjetas#operation/Demorado%20\(Modelo%20PSP\)) | | PagSeguro | [https://dev.pagbank.uol.com.br/docs/validando-um-cart%C3%A3o](https://dev.pagbank.uol.com.br/docs/validando-um-cart%C3%A3o) | | Rede | — | | SafraPay | — | # Provedores de antifraude suportados pela Malga Source: https://docs.malga.io/documentations/type-tables/antifraude-providers Tabela comparativa dos provedores de antifraude disponíveis na Malga, como Clearsale, Konduto e Koin, com análise realtime e assíncrona. Aqui você encontra uma visão geral dos produtos de antifraude disponíveis para integração: | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Realtime Decision | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Tickets | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/clearsale.svg) Clearsale Total | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/b2e.png) B2E group | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/konduto.svg) Konduto | | | | ![](https://malga-docs-prod.s3.amazonaws.com/icons/koin.svg) Koin | | | # Tabela tipos de moedas aceitas Source: https://docs.malga.io/documentations/type-tables/currency-not-supportted | Currency Code | Currency | | - | - | | *BRL* | Brazilian real | | *USD* | United States dollar | | *EUR* | Euro | | *YER* | Yemeni rial | | *ZAR* | South African rand | | *AED* | United Arab Emirates dirham | | *AFN* | Afghan afghani | | *ALL* | Albanian lek | | *AMD* | Armenian dram | | *ANG* | Netherlands Antillean guilder | | *AOA* | Angolan kwanza | | *ARS* | Argentine peso | | *AUD* | Australian dollar | | *AWG* | Aruban florin | | *AZN* | Azerbaijani manat | | *BAM* | Bosnia and Herzegovina convertible mark | | *BBD* | Barbados dollar | | *BDT* | Bangladeshi taka | | *BGN* | Bulgarian lev | | *BIF* | Burundian franc | | *BMD* | Bermudian dollar | | *BND* | Brunei dollar | | *BOB* | Boliviano | | *BSD* | Bahamian dollar | | *BWP* | Botswana pula | | *BZD* | Belize dollar | | *CAD* | Canadian dollar | | *CDF* | Congolese franc | | *CHF* | Swiss franc | | *CLP* | Chilean peso | | *CNY* | Chinese yuan\[8] | | *COP* | Colombian peso | | *CRC* | Costa Rican colon | | *CVE* | Cape Verdean escudo | | *CZK* | Czech koruna | | *DJF* | Djiboutian franc | | *DKK* | Danish krone | | *DOP* | Dominican peso | | *DZD* | Algerian dinar | | *EGP* | Egyptian pound | | *ETB* | Ethiopian birr | | *ZMW* | Zambian kwacha | | *FJD* | Fiji dollar | | *FKP* | Falkland Islands pound | | *GBP* | Pound sterling | | *GEL* | Georgian lari | | *GIP* | Gibraltar pound | | *GMD* | Gambian dalasi | | *GNF* | Guinean franc | | *GTQ* | Guatemalan quetzal | | *GYD* | Guyanese dollar | | *HKD* | Hong Kong dollar | | *HNL* | Honduran lempira | | *HRK* | Croatian kuna | | *HTG* | Haitian gourde | | *HUF* | Hungarian forint | | *IDR* | Indonesian rupiah | | *ILS* | Israeli new shekel | | *INR* | Indian rupee | | *ISK* | Icelandic króna | | *JMD* | Jamaican dollar | | *JPY* | Japanese yen | | *KES* | Kenyan shilling | | *KGS* | Kyrgyzstani som | | *KHR* | Cambodian riel | | *KMF* | Comoro franc | | *KRW* | South Korean won | | *KYD* | Cayman Islands dollar | | *KZT* | Kazakhstani tenge | | *LAK* | Lao kip | | *LBP* | Lebanese pound | | *LKR* | Sri Lankan rupee | | *LRD* | Liberian dollar | | *LSL* | Lesotho loti | | *MAD* | Moroccan dirham | | *MDL* | Moldovan leu | | *MGA* | Malagasy ariary | | *MKD* | Macedonian denar | | *MMK* | Myanmar kyat | | *MNT* | Mongolian tögrög | | *MOP* | Macanese pataca | | *MRO* | Macanese pataca | | *MUR* | Mauritian rupee | | *MVR* | Maldivian rufiyaa | | *MWK* | Malawian kwacha | | *MXN* | Mexican peso | | *MYR* | Malaysian ringgit | | *MZN* | Mozambican metical | | *NAD* | Namibian dollar | | *NGN* | Nigerian naira | | *NIO* | Nicaraguan córdoba | | *NOK* | Norwegian krone | | *NPR* | Nepalese rupee | | *NZD* | New Zealand dollar | | *PAB* | Panamanian balboa | | *PEN* | Peruvian sol | | *PGK* | Papua New Guinean kina | | *PHP* | Philippine peso\[12] | | *PKR* | Pakistani rupee | | *PLN* | Polish złoty | | *PYG* | Paraguayan guaraní | | *QAR* | Qatari riyal | | *RON* | Romanian leu | | *RSD* | Serbian dinar | | *RUB* | Russian ruble | | *RWF* | Rwandan franc | | *SAR* | Saudi riyal | | *SBD* | Solomon Islands dollar | | *SCR* | Seychelles rupee | | *SEK* | Swedish krona/kronor | | *SGD* | Singapore dollar | | *SHP* | Saint Helena pound | | *SLL* | Sierra Leonean leone | | *SOS* | Somali shilling | | *SRD* | Surinamese dollar | | *STD* | South Sudanese pound | | *SZL* | Swazi lilangeni | | *THB* | Thai baht | | *TJS* | Tajikistani somoni | | *TOP* | Tongan pa'anga | | *TRY* | Turkish lira | | *TTD* | Trinidad and Tobago dollar | | *TWD* | New Taiwan dollar | | *TZS* | Tanzanian shilling | | *UAH* | Ukrainian hryvnia | | *UGX* | Ugandan shilling | | *UYU* | Uruguayan peso | | *UZS* | Uzbekistan som | | *VND* | Vietnamese đồng | | *VUV* | Vanuatu vatu | | *WST* | Samoan tala | | *XAF* | CFA franc BEAC | | *XCD* | East Caribbean dollar | | *XOF* | CFA franc BCEAO | | *XPF* | CFP franc (franc Pacifique) | # Tipos de documento de Customer por país Source: https://docs.malga.io/documentations/type-tables/customer-document-by-country Tabela de tipos de documento aceitos no cadastro de Customer na Malga por país, com código do país, tipo de documento, grupo (tax, vat, bank) e significado. | Country Code | Document Type | Group | Country | Meaning | | - | - | - | - | - | | *AL* | *NIPT* | Vat | Albania | Vat Identifier (Numri i Identifikimit për Personin e Tatueshëm) | | *AD* | *NRT* | Tax | Andorra | Tax Identifier (Número de Registre Tributari) | | *AR* | *CBU* | Bank | Argentina | Bank Account (Clave Bancaria Uniforme) | | *AR* | *CUIT* | Tax | Argentina | Tax Identity (Código Único de Identificación Tributaria) | | *AR* | *DNI* | Person | Argentina | National Identity (Documento Nacional de Identidad) | | *AT* | *Businessid* | Company | Austria | Austrian Company Register Numbers | | *AT* | *TIN* | Tax | Austria | Austrian tax identification number (Abgabenkontonummer) | | *AT* | *UID* | VAT | Austria | Austrian VAT number (Umsatzsteuer-Identifikationsnummer) | | *AT* | *VNR* | Person | Austria | Austrian social security number(Versicherungsnummer) | | *AU* | *ABN* | Company | Australia | Australian Business Number | | *AU* | *ACN* | Company | Australia | Australian Company Number | | *AU* | *TFN* | Tax/Person/Company | Australia | Australian Tax File Number | | *BA* | *JMBG* | Person | Bosnia and Herzegovina | Unique Master Citizen Number | | *BZ* | *TIN* | Person/Company | Belize | Brazilian Tax ID () | | *BE* | *VAT* | Company | Belgium | Belgian Enterprise Number | | *BG* | *EGN* | Person | Bulgaria | ЕГН, Единен граждански номер, Bulgarian personal identity codes | | *BG* | *PNF* | Person | Bulgaria | PNF (ЛНЧ, Личен номер на чужденец, Bulgarian number of a foreigner). | | *BG* | *VAT* | Company | Bulgaria | Идентификационен номер по ДДС, Bulgarian VAT number | | *BR* | *CPF* | Person | Brazil | Brazilian identity number (Cadastro de Pessoas Físicas) | | *BR* | *CNPJ* | Company | Brazil | Brazilian company number (Cadastro Nacional da Pessoa Jurídica) | | *BY* | *UNP* | Person/Company | Belarus | Учетный номер плательщика, the Belarus VAT number | | *CA* | *BN* | Company | Canada | Company Identifier (Canadian Business Number) | | *CA* | *SIN* | Person | Canada | Person Identifier (Social Insurance Number) | | *CU* | *NI* | Person | Cuba | Número de identidad, Cuban identity card numbers | | *CY* | *VAT* | Company | Cyprus | Αριθμός Εγγραφής Φ.Π.Α. (Cypriot VAT number) | | *CZ* | *DIC* | Company | Czech Republic | Daňové identifikační číslo, Czech VAT number | | *CZ* | *RC* | Person | Czech Republic | Rodné číslo, the Czech birth number | | *CH* | *SSN* | Person | Switzerland | Swiss social security number ("Sozialversicherungsnummer") | | *CH* | *UID* | Company | Switzerland | Unternehmens-Identifikationsnummer, Swiss business identifier | | *CH* | *VAT* | Company | Switzerland | Mehrwertsteuernummer, the Swiss VAT number | | *CL* | *RUT* | Tax | Chile | Tax Identifier (Rol Unico Tributario) \[RUN] | | *CN* | *RIC* | Person | China | Person Identifier (Chinese Resident Identity Card Number) | | *CN* | *USCC* | Company | China | Company Identifier (Unified Social Credit Code, 统一社会信用代码, China tax number) | | *CO* | *NIT* | Tax | Colombia | Tax Identifier (Número de Identificación Tributaria) | | *CR* | *CPF* | Person | Costa Rica | Person Identifier (Cédula de Persona Física) | | *CR* | *CPJ* | Company | Costa Rica | Company Identifier (Cédula de Persona Jurídica) | | *CR* | *CR* | Person | Costa Rica | Person Identifier (Cédula de Residencia) | | *DE* | *IDNR* | Person | Germany | Steuerliche Identifikationsnummer, German personal tax number | | *DE* | *STNR* | Company | Germany | Steuernummer, German tax number | | *DE* | *VAT* | Company | Germany | Vat identifier | | *DK* | *VAT* | Company | Denmark | Momsregistreringsnummer, Danish VAT number | | *DO* | *CEDULA* | Person | Dominican Republic | Person Identifier (Cédula de Residencia) | | *DO* | *NCF* | Vat | Dominican Republic | Tax Receipt Number (Números de Comprobante Fiscal) | | *DO* | *RNC* | Tax | Dominican Republic | Person Identifier (Registro Nacional del Contribuyente) | | *EC* | *CI* | Person | Ecuador | Ecuadorian person identifier (Cédula de identidad) | | *EE* | *IK* | Person | Estonia | Isikukood (Estonian Personal ID number). | | *EE* | *KMKR* | Company | Estonia | KMKR (Käibemaksukohuslase, Estonian VAT number) | | *EE* | *Registrikood* | Company | Estonia | Registrikood (Estonian organisation registration code) | | *EC* | *RUC* | Tax/Vat | Ecuador | Ecuadorian company tax number (Registro Único de Contribuyentes) | | *SV* | *NIT* | Tax | El Salvador | Tax Identifier (Número de Identificación Tributaria) | | *GT* | *CUI* | Person | Guatemala | Guatemala person (Código Único de Identificación) | | *GT* | *NIT* | Company | Guatemala | Guatemala company tax number (Número de Identificación Tributaria) | | *FI* | *ALV* | Company | Finland | ALV nro (Arvonlisäveronumero, Finnish VAT number) | | *FI* | *HETU* | Person | Finland | HETU (Henkilötunnus, Finnish personal identity code) | | *FI* | *YTUNNUS* | Company | Finland | Y-tunnus (Finnish business identifier) | | *FR* | *NIF* | Person | France | NIF (Numéro d'Immatriculation Fiscale, French tax identification number) | | *GB* | *UTR* | Person | Great Britain | UTR (United Kingdom Unique Taxpayer Reference) | | *GB* | *VAT* | Company | Great Britain | VAT (United Kingdom (and Isle of Man) VAT registration number) | | *GR* | *AMKA* | Company | Greece | AMKA (Αριθμός Μητρώου Κοινωνικής Ασφάλισης, Greek social security number) | | *GR* | *VAT* | Company | Greece | FPA, ΦΠΑ, ΑΦΜ (Αριθμός Φορολογικού Μητρώου, the Greek VAT number) | | *FR* | *NIR* | Person | France | NIR (French personal identification number) | | *FR* | *SIREN* | Company | France | SIREN (a French company identification number) | | *FR* | *SIRET* | Company | France | SIRET (a French company establishment identification number) | | *FR* | *TVA* | Vat | France | VAT Identifier | | *HR* | *OIB* | Person | Croatia | Osobni identifikacijski broj, Croatian identification number | | *HK* | *HKID* | Person | Hong Kong | Hong Kong Identity Card | | *HU* | *ANUM* | Vat | Hungaria | ANUM (Közösségi adószám, Hungarian VAT number) | | *IS* | *KENNITALA* | Person/Company | Iceland | Icelandic personal and organisation identity code | | *IS* | *VSK* | Vat | Iceland | Virðisaukaskattsnúmer, Icelandic VAT number | | *ID* | *NPWP* | Person/Company | Indonesia | NPWP (Nomor Pokok Wajib Pajak, Indonesian VAT Number). | | *IE* | *PPS* | Person | Ireland | Personal Public Service Number, Irish personal number | | *IE* | *VAT* | Tax/Vat | Ireland | Ireland Value Added Tax ID | | *IN* | *AADHAAR* | Company | India | Indian digital resident personal identity number | | *IN* | *PAN* | Person | India | Permanent Account Number, Indian income tax identifier | | *IL* | *IDNR* | Person | Israel | Identity Number (Mispar Zehut, מספר זהות, Israeli identity number) | | *IL* | *HR* | Company | Israel | Company Number (מספר חברה, or short ח.פ. Israeli company number) | | *IT* | *AIC* | Drug | Italy | Italian code for identification of drugs | | *IT* | *CODICEFISCALE* | Person | Italy | Codice Fiscale (Italian tax code for individuals) | | *IT* | *IVA* | Vat | Italy | Partita IVA (Italian VAT number) | | *LI* | *PEID* | Person/Company | Liechtenstein | Personenidentifikationsnummer | | *LT* | *ASMENS* | Person | Lithuanian | Asmens kodas (Person Number) | | *LT* | *PVM* | Vat | Lithuanian | Pridėtinės vertės mokestis mokėtojo kodas | | *LU* | *TVA* | Vat | Luxembourgian | taxe sur la valeur ajoutée | | *LV* | *PVN* | Person/Vat | Latvian | Pievienotās vērtības nodokļa | | *MK* | *JMBG* | Person | Macedonia | Unique Master Citizen Number (Единствен матичен број на граѓанинот) | | *MC* | *TVA* | Vat | Monaco | taxe sur la valeur ajoutée, Monacan VAT number | | *MD* | *IDNO* | Vat | Moldavia | Moldavian VAT number | | *MT* | *VAT* | Vat | Malta | Maltese VAT number | | *MU* | *NID* | Person | Mauritius | ID number (Mauritian national identifier) | | *JP* | *CN* | Company | Japan | 法人番号, hōjin bangō, Japanese Corporate Number | | *KR* | *BRN* | Company | South Korea | 사업자 등록 번호, South Korea Business Registration Number) | | *KR* | *RRN* | Person | South Korea | South Korean resident registration number | | *MX* | *RFC* | Tax/Vat | Mexico | Tax Identifier (Registro Federal de Contribuyentes) | | *MX* | *CURP* | Person | Mexico | Individual Identifier (Clave Única de Registro de Población) | | *MX* | *CLABE* | Bank | Mexico | Bank Account (Clave Bancaria Estandarizada) | | *ME* | *JMBG* | Person | Montenegro | Unique Master Citizen Number | | *MY* | *NRIC* | Person | Malaysia | Malaysian National Registration Identity Card Number | | *NL* | *BSN* | Person | Netherlands | Burgerservicenummer, the Dutch citizen identification number | | *NL* | *BTW* | Vat | Netherlands | Btw-identificatienummer (Omzetbelastingnummer, the Dutch VAT number) | | *NL* | *Onderwijsnummer* | Person | Netherlands | Onderwijsnummer (the Dutch student identification number) | | *NZ* | *IRD* | Person/Company | New Zealand | New Zealand Inland Revenue Department (Te Tari Tāke) number | | *NZ* | *BANK* | Bank | New Zealand | New Zealand Bank Account numbers - checkdigit | | *NO* | *Fodsels* | Person | Norway | Fødselsnummer (Norwegian birth number, the national identity number) | | *NO* | *Konto* | Bank | Norway | Konto nr. (Norwegian bank account number) | | *NO* | *MVA* | Vat | Norway | Merverdiavgift, Norwegian VAT number | | *NO* | *Orgnr* | Company | Norway | Organisasjonsnummer, Norwegian organisation number | | *PY* | *RUC* | Tax/Vat | Paraguay | Tax Identifier (Registro Único de Contribuyentes) | | *PE* | *CUI* | Person | Peru | Person Identifier (Cédula Única de Identidad) | | *PE* | *RUC* | Tax/Vat | Peru | Tax Identifier (Registro Único de Contribuyentes) | | *PE* | *CE* | Person | Peru | Person Identifier (Carné de Extranjería) | | *PK* | *CNIC* | Person | Pakistan | National Identity Card | | *PK* | *NTN* | Company | Pakistan | Tax Identification Number | | *PL* | *NIP* | Vat | Poland | Numer Identyfikacji Podatkowej, Polish VAT number | | *PL* | *PESEL* | Person | Poland | Polish national identification number | | *PL* | *REGON* | Company | Poland | Rejestr Gospodarki Narodowej, Polish register of economic units | | *PT* | *NIF* | Vat | Portugal | Número de identificação fiscal, Portuguese VAT number | | *RU* | *INN* | Tax/Vat | Russia | Tax Identifier (Идентификационный номер налогоплательщика) | | *RO* | *CF* | Vat | Romania | Cod de înregistrare în scopuri de TVA, Romanian VAT number | | *RO* | *CNP* | Person | Romania | Cod Numeric Personal, Romanian Numerical Personal Code) | | *RO* | *CUI* | Tax | Romania | Codul Unic de Înregistrare, Romanian company identifier | | *RO* | *ONRC* | Company | Romania | Ordine din Registrul Comerţului, Romanian Trade Register identifier | | *SM* | *COE* | Company | San Marcos | Codice operatore economico, San Marino national tax number | | *RS* | *PIB* | Vat | Serbia | Poreski identifikacioni broj Tax identification number | | *RS* | *JMBG* | Person | Serbia | Unique Master Citizen Number (Jedinstveni matični broj građana) | | *SE* | *ORGNR* | Company | Sweden | Organisationsnummer, Swedish company number | | *SE* | *PERSONNUMMER* | Person | Sweden | Personnummer (Swedish personal identity number) | | *SE* | *VAT* | Vat | Sweden | VAT (Moms, Mervärdesskatt, Swedish VAT number) | | *SG* | *UEN* | Company | Singapore | Singapore's Unique Entity Number | | *TH* | *IDNR* | Person | Thailand | Thai National ID (บัตรประจำตัวประชาชนไทย) | | *TW* | *UBN* | Company | Taiwan | Unified Business Number, 統一編號, Taiwanese tax number | | *TR* | *TCKIMLIK* | Person | Turkey | Türkiye Cumhuriyeti Kimlik Numarası (Personal ID) | | *TR* | *VKN* | Tax | Turkey | Vergi Kimlik Numarası, Turkish tax identification number | | *SI* | *DDV* | Vat | Slovenia | ID za DDV (Davčna številka, Slovenian VAT number) | | *SI* | *JMBG* | Person | Slovenia | Unique Master Citizen Number (Enotna matična številka občana) | | *SK* | *DPH* | Vat | Slovakia | IČ DPH (IČ pre daň z pridanej hodnoty, Slovak VAT number) | | *SK* | *RC* | Person | Slovakia | RČ (Rodné číslo, the Slovak birth number) | | *ES* | *CIF* | Tax/Vat | Spain | Tax Identifier (Código de Identificación Fiscal) | | *ES* | *DNI* | Person | Spain | Identity code (Documento Nacional de Identidad) | | *ES* | *NIE* | Person | Spain | Identity code foreigner (Número de Identificación de Extranjero) | | *ES* | *NIF* | Tax | Spain | Tax Identifier (Número de Identificación Fiscal) | | *UY* | *RUT* | Tax/Vat | Uruguay | Tax Identifier (Registro Único Tributario) | | *UY* | *CEDULA* | Person | Uruguay | Person Identifier (Cédula de Residencia) | | *UY* | *NIE* | Person | Uruguay | Foreigners identification Number | | *UA* | *RNTRC* | Person | Ukraine | КПП, RNTRC (Individual taxpayer registration number in Ukraine) | | *UA* | *EDRPOU* | Company | Ukraine | ЄДРПОУ, EDRPOU (Identifier for enterprises and organizations in Ukraine) | | *US* | *EIN* | Tax/Company | United States | Tax Identifier (Employer Identification Number) | | *US* | *SSN* | Tax/Individual | United States | Tax Identifier (Social Security Number) | | *VE* | *RIF* | Vat | Venezuelan | Vat Identifier (Registro de Identificación Fiscal) | | *VN* | *MST* | Company | Vietnam | Mã số thuế, Vietnam tax number | | *ZA* | *IDNR* | Person | South Africa | ID number (South African Identity Document number). | | *ZA* | *TIN* | Person/Company | South Africa | TIN (South African Tax Identification Number). | | | *noDocument* | Document number | | The document number is not provided | # Tabela de DeclinedCode da Malga Source: https://docs.malga.io/documentations/type-tables/declined-code Tabela com os códigos de recusa (declinedCode) retornados pela Malga, suas mensagens, retentabilidade e orientação ABECS para cada caso. | DeclinedCode | ResponseMessage | Retentável | O que fazer (ABECS) | | - | - | - | - | | *authentication\_attempts\_unavailable\_by\_issuer* | Authentication attempts unavailable by issuer | Não | - | | *authentication\_error* | Authentication Error | Não | - | | *authentication\_error\_without\_challenge* | Authentication error without challenge | Não | - | | *authentication\_unavailable* | Authentication Unavailable | Não | - | | *bad\_request* | Request failed with status code 400 | Sim | VERIFIQUE OS DADOS | | *blocked\_card* | Blocked Card | Sim | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | *canceled\_card* | Canceled Card | Sim | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | *card\_not\_supported* | The card does not support this type of purchase | Não | UTILIZE FUNÇÃO DÉBITO | | *cardholder\_not\_complete\_authentication* | Cardholder did not complete authentication | Não | - | | *denied\_reason\_not\_available* | The charge has been declined because the provider behaved unexpectedly and didn't sent a denied reason. | Sim | REFAZER A TRANSAÇÃO | | *expired\_card* | The card expiration date is invalid | Sim | VERIFIQUE OS DADOS DO CARTÃO | | *failed\_authentication* | Failed authentication eciRaw 07/00 | Não | - | | *fraud\_confirmed* | The charge has been declined for confirmed fraud | Não | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO - NÃO TENTE NOVAMENTE | | *fraud\_suspect* | The charge has been declined for suspect it is fraudulent | Sim | CONTATE A CENTRAL DO SEU CARTÃO | | *generic* | The card has been declined for a unknown reason | Sim | CONTATE A CENTRAL DO SEU CARTÃO | | *insufficient\_funds* | The card has insufficient funds | Sim | NÃO AUTORIZADA | | *internal\_error* | The charge has been declined for a unknown reason | Sim | REFAZER A TRANSAÇÃO | | *invalid\_amount* | The charge amount is not valid or exceeded maximum allowed | Depende do provedor | VALOR DA TRANSAÇÃO NÃO PERMITIDO | | *invalid\_credentials* | Invalid credentials | Sim | REFAZER A TRANSAÇÃO | | *invalid\_cvv* | The security code is invalid | Sim | SENHA INVÁLIDA | | *invalid\_data* | The card has been declined for invalid data | Não | VERIFIQUE OS DADOS DO CARTÃO | | *invalid\_installment* | The charge has been declined because invalid number of installments | Sim | PARCELAMENTO INVÁLIDO | | *invalid\_merchant* | The charge has been declined because merchant is not valid | Depende do provedor | CONTA ORIGEM INVÁLIDA | | *invalid\_number* | The card number is invalid | Não | VERIFIQUE OS DADOS DO CARTÃO | | *invalid\_pares* | Invalid PARes | Não | - | | *invalid\_pin* | The card has been declined because pin is invalid | Não | SENHA INVÁLIDA | | *issuer\_not\_available* | The card issuer could not be reached, charge not authorized | Sim | DADOS DO CARTÃO INVÁLIDO | | *lost\_card* | The card has been declined because the card is reported lost | Não | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | *maximum\_pin\_tries* | The card has been declined because pin validation has been exceeded | Depende do provedor | ERRO NO CARTÃO | | *not\_permitted* | The charge is not permitted to the card | Sim | TRANSAÇÃO NÃO PERMITIDA PARA O CARTÃO | | *pickup\_card* | The card cannot be used to make this charges | Sim | CONTATE A CENTRAL DO SEU CARTÃO | | *pin\_try\_exceeded* | The card has been declined because exceeded maximum pin tries | Não | EXCEDIDAS TENTATIVAS DE SENHA. CONTATE A CENTRAL DO SEU CARTÃO | | *processing\_error* | The charge has been declined for a unknown reason | Sim | REFAZER A TRANSAÇÃO | | *request\_not\_sent* | The charge has been declined for a unknown reason | Sim | REFAZER A TRANSAÇÃO | | *restricted\_card* | The card cannot be used to make this charge | Sim | DESBLOQUEIE O CARTÃO | | *security\_violation* | The card has been declined for a unknown reason | Sim | VERIFIQUE OS DADOS DO CARTÃO | | *service\_not\_allowed* | The card has been declined because do not support international charge | Não | CARTÃO NÃO PERMITE TRANSAÇÃO INTERNACIONAL | | *stolen\_card* | The card has been declined because the card is reported stolen | Não | TRANSAÇÃO NÃO PERMITIDA - NÃO TENTE NOVAMENTE | | *transaction\_not\_allowed* | The card has been declined for a unknown reason | Não | ERRO NO CARTÃO | | *try\_again* | The card has been declined for a unknown reason | Sim | REFAZER A TRANSAÇÃO | | *unable\_to\_perform\_authentication* | Issuer unable to perform authentication | Não | - | # Tabela de códigos COMPE dos principais bancos Source: https://docs.malga.io/documentations/type-tables/main-banks Códigos COMPE (3 dígitos) usados em `bankAccount.bank` na criação e atualização de recebedores. Esta tabela lista os códigos **COMPE** (3 dígitos) das principais instituições financeiras brasileiras, usados em `bankAccount.bank` ao criar ou atualizar um [recebedor](/documentations/split/seller). > [!NOTE] > > Como alternativa ao `bank` (COMPE), a `bankAccount` aceita o campo `ispb` — identificador da instituição financeira no Sistema de Pagamentos Brasileiro, com 8 dígitos numéricos. > > Pelo menos um entre `bank` e `ispb` deve ser informado; quando ambos são enviados, **`ispb` tem precedência**. A relação canônica de ISPBs é publicada e atualizada pelo Banco Central — para evitar listas desatualizadas, consulte a fonte oficial em [bcb.gov.br/estabilidadefinanceira/spbparticipantes](https://www.bcb.gov.br/estabilidadefinanceira/spbparticipantes). | Código | Banco | | - | - | | **001** | Banco do Brasil S.A. | | *033* | Banco Santander (Brasil) S.A. | | *104* | Caixa Econômica Federal | | *237* | Banco Bradesco S.A. | | *260* | Nubank | | *341* | Banco Itaú S.A. | | *356* | Banco Real S.A. (antigo) | | *389* | Banco Mercantil do Brasil S.A. | | *399* | HSBC Bank Brasil S.A. – Banco Múltiplo | | *422* | Banco Safra S.A. | | *453* | Banco Rural S.A. | | *633* | Banco Rendimento S.A. | | *652* | Itaú Unibanco Holding S.A. | | *745* | Banco Citibank S.A. | # Tabela de códigos MCC Source: https://docs.malga.io/documentations/type-tables/mcc-code Lista completa dos códigos MCC (Merchant Category Code) suportados pela Malga, com a descrição da categoria de negócio para cada código. O MCC (Merchant Category Code) é o código de quatro dígitos que identifica a atividade comercial de um estabelecimento. Você informa esse código no campo `mcc` ao cadastrar subcontas (merchants) e recebedores (sellers), e ele aparece nos detalhes da subconta no Dashboard (veja [Subcontas](/documentations/dashboard/merchants)). > [!NOTE] > > Esta tabela relaciona apenas o código MCC à descrição da categoria de negócio. A Malga não fornece uma tabela de equivalência entre CNAE e MCC. ## O que o MCC não define * **Canal de venda:** o MCC não indica se o negócio opera online (e-commerce) ou presencialmente. O canal de captura depende do seu setup comercial e do provedor contratado. * **Taxas:** as taxas comerciais (MDR, antecipação e demais) são acordadas no seu contrato com a Malga e não variam por código nesta tabela. Para confirmar a taxa aplicada à sua conta, fale com o time comercial da Malga. ## Como escolher e alterar o MCC 1. Identifique a atividade principal do negócio. 2. Procure nesta tabela a descrição que melhor corresponde a essa atividade. Use a busca do navegador (`Ctrl+F` ou `Cmd+F`) com palavras-chave da atividade. 3. Se não houver uma descrição exata, use a categoria mais próxima. Informe o código no campo `mcc` de [`POST /v1/merchants`](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) ao criar a subconta. Para alterar o MCC de uma subconta existente, use [`PATCH /v1/merchants/{id}`](/api-reference/merchants/atualizar-configuracoes-de-merchant). ## Tabela de códigos | MCC | Descrição | | - | - | | *742* | VETERINARIA | | *744* | Carefree Resorts | | *763* | COOPERATIVA AGRÍCOLA | | *780* | SERVIÇOS DE PAISAGISMO E HORTICULTURA | | *1520* | EMPREITEIROS EM GERAL - COMERCIAL E RESIDENCIAL | | *1711* | PREST. DE SERV. PARA AR COND., ENCANAMENTO E AQUEC. | | *1731* | ELETRICISTAS E SERVIÇOS ELÉTRICOS | | *1740* | PEDREIROS E SERVIÇOS DE INSTALAÇÃO | | *1750* | MARCENEIROS E SERVIÇOS DE CARPINTARIA | | *1761* | METALURGICOS | | *1771* | EMPREITEIRO PARA SERVIÇOS ESPECIALIZADOS | | *1799* | DEMAIS SVS DE REFORMA E CONSTRUÇÃO NÃO-CLASSIFICADOS | | *2741* | EDITORAS - PUBLICAÇÕES E IMPRESSÕES | | *2791* | TYPESETTING, PLATE MAKING AND RELATED SERVICES | | *2842* | SERVIÇOS DE LIMPEZA E POLIMENTO | | *4011* | TRANSPORTE FERROVIÁRIO DE CARGA | | *4111* | TRANSPORTE LOCAL DE PASSAGEIROS, INCLUINDO BALSAS | | *4112* | TRANSPORTE DE PASSAGEIROS EM TREM (LONGA DISTÂNCIA) | | *4119* | AMBULANCIAS | | *4121* | LIMUSINES E TÁXIS (TAXICABS AND LIMOUSINES) | | *4131* | COMPANHIAS DE ONIBUS | | *4214* | TRANSPORTE DE CARGA RODOVIÁRIO E ARMAZENAMENTO | | *4215* | CORREIOS - AÉREO, TERRESTRE E TRANSITÓRIOS | | *4225* | ARMAZENAM. PROD AGRÍCOLAS,MERCAD REFRIGERADAS,BENS DOMÉSTICO | | *4411* | LINHAS DE CRUZEIROS (CRUISE LINES) | | *4457* | ALUGUEL E ARRENDAMENTO DE BARCOS, ESQUIS E IATES | | *4468* | MARINAS, SERVIÇOS E FORNECEDORES | | *4511* | OUTRAS CIAS AÉREAS | | *4582* | AEROPORTOS E SERVIÇOS LIGADOS A AERONAVES | | *4722* | AGÊNCIAS DE VIAGENS (TRAVEL AGENCIES) | | *4723* | AGÊNCIAS DE VIAGEM TUI (TUI TRAVEL AGENCY) | | *4784* | PEDÁGIOS | | *4789* | SERVIÇOS DE TRANSPORTE | | *4812* | TELEFONES E EQUIPAMENTOS DE TELECOMUN. | | *4813* | SERVIÇOS DE TELEC.- CHAM. LOCAIS E LONGA DISTÂNCIA | | *4814* | SERVIÇOS DE TELECOMUNICAÇÃO | | *4816* | REDES DE COMPUTADORES / SERVIÇOS DE INFORMAÇÃO | | *4821* | TELEGRAFO | | *4829* | ORDENS DE PAGAMENTO POR TRANSFERÊNCIA BANCÁRIA | | *4899* | SERVIÇOS DE TV A CABO/PAGA (CABLE/PAY TV SERVICES) | | *4900* | UTILID./ELEC/GAS/ÁGUA/SANI (UT../ELEC/GAS/H2O/SANI) | | *5013* | ATACADISTAS E DISTRIBUIDORES DE ACESSÓRIOS DE VEÍCULOS | | *5021* | MÓVEIS PARA ESCRITÓRIOS (COMMERCIAL FURNITURE) | | *5039* | MATERIAL PARA CONSTRUÇÃO E AFINS (CONST. MAT. - DEF) | | *5044* | A/D DE EQUIPAMENTOS DE FOTOGRAFIA, CÓPIA E MICROFILME | | *5045* | COMPUTADORES, EQUIPAMENTOS E SOFTWARES | | *5046* | A/D DE MÁQUINAS E EQUIPAMENTOS PARA EC | | *5047* | A/D DE EQUIPAMENTO HOSPITALARES, MÉDICOS E OFTÁLMICOS | | *5051* | CENTROS DE SERVIÇOS DE METAIS (METAL SERVICE CENTERS) | | *5065* | LOJA ARTIGOS ELETRÔNICOS | | *5072* | EQUIP./DISTRIB. DE HARDWARE (HARDWARE EQUIP.SUPPLIES) | | *5074* | EQUIP. DE AQUECIMENTO/ENCANAMENTO (PLUMB./HEAT. E.) | | *5085* | A/D DE SUPRIMENTOS INDUSTRIAIS (NÃO CLASSIFICADO EM OUTRO) | | *5094* | JOALHERIA, PEDRAS PRECIOSAS, METAIS | | *5099* | ATACADISTAS E DISTRIBUIDORES DE MERCADORIAS DURÁVEIS | | *5111* | A/D DE ARTIGOS DE PAPELARIA E SUPRIMENTOS PARA ESCRITÓRIO | | *5122* | FARMACEUTICOS/DROGAS (DRUGS/DRUGGISTS SUNDRIES) | | *5131* | A/D DE TECIDOS E PRODUTOS DE ARMARINHO | | *5137* | ATACADISTAS E DISTRIBUIDORES DE ROUPAS | | *5139* | ATACADISTAS E DISTRIBUIDORES DE CALÇADOS | | *5169* | A/D DE PRODUTOS QUIMICOS E SEMELHANTES (N CLASSIF. EM OUTRO) | | *5172* | PRODUTOS DE PETRÓLEO (PETROLEUM/PETROLEUM PRODUCTS) | | *5192* | ATAC. E DISTRIB. DE LIVROS, PERIÓDICOS E JORNAIS | | *5193* | ATACADISTAS E DISTRIBUIDORES DE FLORES, PLANTAS E SEMENTES | | *5198* | PINTURA, POLIMENTO E SUPRIM. (PAN.,VARN. & SUPPLIES) | | *5199* | A/D DE MERCADORIAS NÃO DURÁVEIS (NÃO CLASSIF. EM OUTRO) | | *5200* | LOJAS DE MATERIAL DE CONSTRUÇÃO (PEQUENO/MÉDIO PORTE) | | *5211* | LOJAS DE MATERIAL DE CONSTRUÇÃO-PRODUTOS BRUTOS (EX: TIJOLO) | | *5231* | LOJAS DE VIDROS, TINTAS E PAPÉIS DE PAREDE | | *5251* | VENDA DE EQUIPAMENTOS, INCLUINDO DE FERRAGEM | | *5261* | JARDINAGEM | | *5271* | CORRETORES DE RESIDÊNCIAS MÓVEIS | | *5300* | VENDA POR ATACADO (WHOLESALE CLUBS) | | *5309* | DUTY FREE STORES | | *5310* | LOJAS DE DESCONTO | | *5311* | LOJAS DE DEPARTAMENTOS (DEPARTMENT STORES) | | *5331* | LOJAS DE VARIEDADES | | *5399* | LOJA MERCADORIAS GERAIS | | *5411* | MERCEARIAS/SUPERMERCADOS (GROCERY STORES/SUPERM.) | | *5422* | AÇOGUEIRO (FREEZER/MEAT LOCKERS) | | *5441* | LOJA DE DOCES | | *5451* | LOJA DE PRODUTOS DE LATICÍNIOS (DAIRY PROD. STORES) | | *5462* | CONFEITARIAS (BAKERIES) | | *5499* | LOJA DE ALIMENTOS VARIADOS (MISC FOOD S. - DEFAULT) | | *5511* | VENDA DE CARROS E CAMINHÕES (NOVOS E USADOS) | | *5521* | VENDA DE CARROS USADOS | | *5531* | Lojas de Automóveis, Lojas de Acessórios Domésticos | | *5532* | LOJA DE PNEUS | | *5533* | LOJA DE PEÇAS E ACESSÓRIOS DE CARROS | | *5541* | ESTAÇÕES DE SERVIÇOS (SERVICE STATIONS) | | *5551* | VENDA DE BARCOS MOTORIZADOS | | *5561* | ARTIGOS PARA ACAMPAMENTO | | *5571* | LOJAS DE MOTOCICLETAS E ACESSÓRIOS | | *5592* | VENDA DE TRAILERS | | *5598* | CONCESSIONÁRIA DE SNOWMOBILE | | *5599* | SERVIÇOS GERAIS PARA CARROS | | *5611* | ARTIGOS MASCULINOS | | *5621* | LOJA DE ROUPAS FEMININAS "PRONTA PARA USAR" | | *5631* | ACESSORIOS FEMININOS E LINGERIES | | *5641* | ARTIGOS PARA CRIANÇAS E BEBÊS | | *5651* | ROUPAS MASCULINAS, FEMININAS E INFANTIS | | *5655* | ROUPA ESPORTIVA | | *5661* | LOJAS DE SAPATOS | | *5681* | LOJA DE PELES | | *5691* | LOJA ROUPA UNISSEX | | *5697* | COSTUREIRAS E ALFAIATES | | *5698* | LOJAS DE PERUCA | | *5699* | SERVIÇOS GERAIS PARA VESTIMENTA | | *5712* | LOJA DE MÓVEIS | | *5713* | Loja de Pisos | | *5714* | LOJA DE ESTOFADOS (DRAPERY & UPHOLSTERY STORES) | | *5718* | LAREIRAS E ACESSÓRIOS (FIREPLACES & ACCESSORIES) | | *5719* | LOJA DE MÓVEIS ESPECIALIZADA (HOME FURNISHING SPEC.) | | *5722* | LOJAS DE ELETRODOMÉSTICOS | | *5732* | LOJA DE ELETRÔNICOS | | *5733* | LOJA INSTRUMENTO MUSICAIS | | *5734* | LOJA DE SOFTWARE | | *5735* | LOJAS DE DISCOS | | *5811* | DISTRIBUIÇÃO E PRODUÇÃO DE ALIMENTOS | | *5812* | RESTAURANTES | | *5813* | BARES, PUBS E CASA NOTURNAS | | *5814* | LANCHONETES DE COMIDAS RÁPIDAS (FAST FOOD) | | *5815* | Produtos Digitais - De comunicação social audiovisual, incluindo Livros, Filmes e Música | | *5816* | Produtos Digitais - Jogos | | *5817* | Produtos Digitais - Aplicativos de Software (Exceto Jogos) | | *5818* | Produtos Digitais - Diversas Categorias | | *5912* | FARMÁCIAS (DRUG STORES & PHARMACIES) | | *5921* | CERVEJAS, VINHOS E LICORES (STORE/BEER/WINE/LIQUOR) | | *5931* | LOJAS DE ARTIGOS DE SEGUNDA MÃO / BRECHÓS | | *5932* | LOJA DE ANTIGUIDADES (ANTIQUE SHOPS) | | *5933* | LOJAS DE PENHORES | | *5935* | DEMOLIÇÕES, SUCATAS, DESMANCHES DE AUTOMÓVEIS | | *5937* | L. DE REPRODUÇÃO DE ANTIGUIDADES (ANT.REPROD. STORES) | | *5940* | LOJA DE BICICLETAS - VENDAS E SERVIÇOS | | *5941* | SERVIÇOS GERAIS PARA ESPORTES | | *5942* | LIVRARIAS | | *5943* | PAPELARIAS | | *5944* | JOALHERIA (JEWELRY STORE) | | *5945* | LOJA DE BRINQUEDOS | | *5946* | LOJA DE FOTOGRAFIA | | *5947* | LOJA DE PRESENTES | | *5948* | ARTIGOS DE COURO | | *5949* | ARMARINHOS E LOJAS DE TECIDO | | *5950* | LOJA DE COPOS/CRISTAIS (GLASSWARE/CRYSTAL STORES) | | *5960* | MARK.DIRETO DE SEGUROS (DIR. MARKET. INSURANCE SVC) | | *5962* | SERV. DIRETOS DE VIAGENS (D. MKTG-TRAV. RELATED ARR) | | *5963* | VENDA DIRETA (DIRECT SELL/DOOR-TO-DOOR) | | *5964* | CATALOGO DE COMERCIOS (CATALOG MERCHANT) | | *5965* | CATÁLOGO DE VAREJO (COMB.CATALOG & RETAIL) | | *5966* | MARKETING DIRETO-SAÍDA (OUTB. TELEMARKETING M.) | | *5967* | MARKETING DIRETO - ENTRADA (INB. TELEMARKETING M.) | | *5968* | ASSINATURA COMERCIAL (CONTINUITY/SUBSCRIP. MERCHANT) | | *5969* | OUTROS VENDEDORES DE MARKETING DIRETO | | *5970* | PRODUTOS ARTESANAIS | | *5971* | GALERIA DE ARTE (ART DEALERS & GALLERIES) | | *5972* | LOJA DE MOEDAS E SELOS | | *5973* | LOJA DE BENS RELIGIOSOS | | *5975* | APARELHOS AUDITIVOS - VENDAS E SERVIÇOS | | *5976* | BENS ORTOPÉDICOS - PRÓTESES | | *5977* | LOJA DE COSMÉTICOS | | *5978* | MÁQUINAS DE ESCREVER - VENDA, ALUGUEL E SERVIÇOS | | *5983* | REVENDEDORES DE COMBUSTÍVEIS (FUEL DEALERS) | | *5992* | FLORICULTURA | | *5993* | TABACARIA | | *5994* | BANCA DE JORNAL E PROVEDOR DE NOTÍCIAS | | *5995* | PET SHOP | | *5996* | PISCINAS E BANHEIRAS - SERVIÇOS, SUPRIMENTOS E VENDAS | | *5997* | NAVALHA ELÉTRICA - VENDA E SERVIÇOS | | *5998* | LOJAS DE BARRACAS E TOLDOS | | *5999* | LOJAS ESPECIALIZADAS NÃO LISTADAS ANTERIORMENTE | | *6010* | BANCOS / LOJAS DE POUPANÇA E INST. FINANCEIRA | | *6011* | INSTITUIÇÃO FINANCEIRA - CAIXA ELETRÔNICO | | *6012* | INSTITUIÇÃO FINANCEIRA - AGÊNCIAS E SERVIÇOS | | *6050* | Similar a Dinheiro (Quase Cash) - Instituição Financeira Cliente | | *6051* | CASAS DE CÂMBIO | | *6211* | CORRETORES DE IMÓVEIS (SECURITIES BROKERS/DEALERS) | | *6300* | VENDA DE SEGUROS(INSURANCE SALES/UNDERWRITE) | | *6513* | CORRETOR DE IMÓVEIS (ALUGUEL) | | *6532* | PAGTOS DE TRANSAÇÕES DE INST.FINANCEIRAS | | *6533* | PAGTOS DE TRANSAÇÕES COMERCIAIS | | *7011* | HOTEIS (HOTELS/MOTELS/RESORTS) | | *7012* | TEMPO COMPARTILHADO (TIMESHARE) | | *7032* | ACAMPAMENTOS RECREATIVOS E ESPORTIVOS | | *7033* | SERVIÇOS DE ACAMPAMENTOS | | *7210* | LAVANDARIA, LIMPEZA E SERVIÇOS DE VESTUÁRIO | | *7211* | LAVANDERIA - FAMILIAR E COMERCIAL | | *7216* | LAVANDERIA TINTURARIA | | *7217* | LIMPEZA DE TAPETES E ESTOFADOS | | *7221* | ESTÚDIOS DE FOTOGRAFIA | | *7230* | SALAO DE BELEZA / BARBEARIA / DEPILAÇÃO / MANICURE | | *7251* | LOJA/REPARO DE SAPATOS | | *7261* | SERVIÇO FUNERÁRIO | | *7273* | SERVIÇO DE ENCONTROS E ACOMPANHANTE | | *7276* | SERVIÇOS DE PREP. IMPOST. DE RENDA (TAX PREP. SVCS) | | *7277* | S. DE ACONSELHAMENTO DE DÍVIDAS, CASAMENTO E PESSOAL | | *7278* | CLUBES DE COMPRAS | | *7296* | ALUGUEL DE ROUPAS - FANTASIAS, UNIFORMES E ROUPAS SOCIAIS | | *7297* | CENTRO DE SAUNAS E MASSAGENS | | *7298* | CLÍNICAS DE ESTÉTICA FACIAL / CORPORAL | | *7299* | OUTROS SERVIÇOS PESSOAIS | | *7311* | PUBLICIDADES | | *7321* | AGÊNCIAS DE ANÁLISE DE CRÉDITO DE CONSUMIDORES | | *7333* | SERVIÇOS DE IMPRESSÃO E ARTE GRÁFICA | | *7338* | COPIADORAS E FOTOCOPIADORAS | | *7339* | SERVIÇO DE SECRETARIADO E ESTENOGRAFIA | | *7342* | DEDETIZAÇÃO E DESINFECÇÃO | | *7343* | SERVIÇO DE EXTERMINIO E DESINFETAÇÃO | | *7349* | SERVIÇO LIMPEZA E MANUTENÇÃO | | *7361* | AGÊNCIAS DE EMPREGO | | *7372* | SERVIÇOS DE PROGRAMAÇÃO DE COMPUTADORES E PROCESS. DE DADOS | | *7375* | SERVIÇO DE RECUPERAÇÃO DE INFORMAÇÃO | | *7379* | COMPUTADORES: CONSERTOS E REPAROS | | *7392* | CONSULTORIA EMPRESARIAL E SERVIÇOS DE RELAÇÕES PÚBLICAS | | *7393* | AGÊNCIAS DE DETETIVES, PROTEÇÃO E DE SEGURANÇA | | *7394* | ALUGUEL DE EQUIPAMENTO E MOBÍLIA DE ESCRITÓRIOS | | *7395* | LABORATÓRIOS FOTOGRÁFICOS | | *7399* | SERVIÇOS DE NEGÓCIOS | | *7511* | PARADA DE CAMINHÕES (TRUCK STOP) | | *7512* | ALUGUEL DE AUTOMÓVEIS (AUTOMOBILE RENTAL AGENCY) | | *7513* | ALUGUEL DE CAMINHÕES (TRUCK/UTILITY TRAILER RENTALS) | | *7519* | ALUGUEL DE MOTOR HOME (MOTOR HOME/RV RENTALS) | | *7523* | ESTACIONAMENTOS E GARAGENS DE CARRO | | *7531* | FUNILARIAS E PINTURA AUTOMOTIVA | | *7534* | BORRACHARIAS | | *7535* | LOJAS DE PINTURA DE AUTOMÓVEIS | | *7538* | SERVIÇOS PARA CARROS (NÃO CONCESSIONÁRIA) | | *7542* | LAVA JATO | | *7549* | GUINCHO | | *7622* | CONSERTO DE EQUIP. AUDIO E TV | | *7623* | CONSERTO DE AR CONDICIONADO | | *7629* | CONSERTO DE ELETRONICOS | | *7631* | CONSERTO DE RELÓGIOS E JÓIAS | | *7641* | RESTAURAÇÃO DE MÓVEIS (FURNITURE REPAIR) | | *7692* | SERRALHEIROS E SOLDADORES | | *7699* | LOJA DE CONSERTOS GERAIS E SERVIÇOS RELACIONADOS | | *7829* | PRODUTORES E DISTRIBUIDORES DE FILMES | | *7832* | CINEMAS, PRODUÇÕES CINEMATOGRÁFICAS | | *7841* | LOJAS DE VIDEOS | | *7911* | DANÇA (ESTUDIOS, ESCOLAS E SALÕES) | | *7922* | TEATROS, PRODUC. TEATR. E ESPECTAC. | | *7929* | BANDAS,ORQUESTRAS,ARTISTAS DIVERSOS(N CLASSIFICADO EM OUTRO) | | *7932* | BARES DE SINUCA | | *7933* | BOLICHE | | *7941* | QUADRAS DE ESPORTE / PROPAGANDA ESPORTIVA | | *7991* | ATRAÇÕES TURÍSTICAS E EXPOSIÇÕES | | *7992* | AULAS DE GOLF PUBLICA | | *7993* | FORNECEDORES DE MÁQUINAS DE VIDEOGAME OU JOGOS | | *7994* | LOJAS DE DIVERSÃO / VIDEO GAME / LAN HOUSE / CIBER CAFÉ | | *7995* | CASSINOS, LOTERIAS E JOGOS DE AZAR | | *7996* | PARQUE DE DIVERSAO, CIRCO E AFINS | | *7997* | ACADEMIAS / CLUBES | | *7998* | AQUÁRIOS E ZOOLÓGICOS | | *7999* | SERVIÇOS DE RECREAÇÃO E FESTAS | | *8011* | MÉDICOS (CLÍNICAS E CONSULTÓRIOS) | | *8021* | DENTISTAS E ORTODONTISTAS (CLÍNICAS E CONSULTÓRIOS) | | *8031* | OSTEOPATAS | | *8041* | QUIROPRAXIA | | *8042* | OFTALMOLOGISTA E OPTOMETRISTAS | | *8043* | OPTICIANS, OPTICAL GOODS, AND EYEGLASSES | | *8049* | TRATAMENTOS PODIÁTRICOS | | *8050* | CASAS DE REPOUSO, CLÍN. DE RECUPERAÇÃO E ENFERMAGEM | | *8062* | HOSPITAIS | | *8071* | ANALISES CLÍNICAS MÉDICAS E DENTAIS | | *8099* | MEDICINA EM GERAL E PRATICANTES DE SERVIÇOS DE SAÚDE | | *8111* | SERVIÇOS JURÍDICOS - ADVOGADOS | | *8211* | EDUCAÇÃO PRIMÁRIA E SECUNDÁRIA (ELEM./SEC.S.) | | *8220* | UNIVERSIDADES E FACULDADES (COLLEGES/UNIV/JC/PROF.) | | *8241* | EDUCAÇÃO A DISTÂNCIA (CORRESPONDENCE SCHOOLS) | | *8244* | ESCOLA DE COMÉRCIOS E SECRETARIADO (BUS./SEC. SCHOOL) | | *8249* | ESCOLA DE NEGÓCIOS/VOCAÇÕES (TRADE/VOCATIONS S.) | | *8299* | COLEGIOS (SCHOOLS) | | *8351* | SERVIÇOS DE CUIDADOS DE CRIANÇAS (CHILD CARE SVCS) | | *8398* | ORGANIZAÇÕES DE SERVIÇOS BENEFICENTES E SOCIAIS | | *8641* | ASSOCIAÇÕES CÍVICAS E SOCIAIS | | *8651* | ORGANIZAÇÕES POLITICAS | | *8661* | ORGANIZAÇÕES RELIGIOSAS | | *8675* | ASSOCIAÇÃO DE CARROS | | *8699* | ORG. SIND., ASSOC. CULT. E OTRS ASSOC. NÃO CLASSIF. | | *8734* | LABORATÓRIOS DE TESTE (PARA TESTES NÃO MÉDICOS) | | *8911* | ARQUITETURA, ENGENHARIA E AGRIMENSURA | | *8931* | CONTABILIDADE, AUDITORIA E SERVIÇOS DE CONTABILIDADE | | *8999* | OUTROS SERVIÇOS PROFISSIONAIS DE ESPECIALIZADOS | | *9211* | PENSÃO ALIMENTÍCIA (COURT COSTS/ALIMONY/SUPPORT) | | *9222* | MULTAS (FINES) | | *9223* | PAGAMENTOS DE TÍTULOS E FINANÇAS (BAIL AND BOND P.) | | *9311* | PAGAMENTOS DE IMPOSTOS (TAX PAYMENTS) | | *9399* | SERVIÇOS GOVERNAMENTAIS (GOVT SERV - DEFAULT) | | *9402* | POSTAGENS (POSTAGE STAMPS) | | *9405* | COMPRAS GOVERNAMENTAIS (INTRA-GOVERNMENT PURCHASES) | | *9406* | Loteria de Propriedade do Governo (Países Específicos) | | *9950* | DEPART. DE COMPRAS (INTRA- COMPANY PURCHASES) | # Métodos de pagamento suportados por provedor Source: https://docs.malga.io/documentations/type-tables/payment-methods-by-providers Tabela completa dos provedores integrados à Malga com os métodos de pagamento suportados por cada um, como crédito, Pix, boleto e Apple Pay. Aqui você encontra uma visão completa dos provedores e métodos de pagamento suportados por cada um. | Provedor | Crédito | Pix | Boleto | Voucher | Apple Pay | Serviços | | - | :-: | :-: | :-: | :-: | :-: | :- | | ![](%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A\%0A>) Sandbox [Open](/documentations/providers/sandbox) | | | | | | 3DS nativo3DS2 Malga | | ![](%0A\%0A\%0A>) Adyen [Open](/documentations/providers/adyen) | | | | | | 3DS nativo3DS2 Malga | | ![](%0A\%0A\%0A\%0A\%0A\%0A\%0A>) Banrisul [Open](/documentations/providers/banrisul) | | | | | | | | ![](%0A\%0A\%0A>) Barte [Open](/documentations/providers/barte) | | | | | | 3DS2 Malga | | ![](%0A\%0A\%0A\%0A>) Banco do Brasil [Open](/documentations/providers/banco-do-brasil) | | | | | | | | ![](%0A\ bool ``` [Clique aqui e saiba mais sobre EdDSA e Ed25519](https://cryptobook.nakov.com/digital-signatures/eddsa-and-ed25519#eddsa-verify-signature) ### Exemplos de validação da signature Os exemplos estão disponíveis nesse repositório github: [https://github.com/plughacker/plug-sample-signature-verify/](https://github.com/plughacker/plug-sample-signature-verify/) Veja um trecho de cada linguagem: > [tab] Node.js > > ```javascript theme={null} > const crypto = require("crypto"); > > module.exports = { > /** > * Example of a function that validates the payload signature > * @param {string} publicKey Key returned on webhook creation > * @param {string} payload Event sent by the plug. This information goes in the body http > * @param {number} signatureTime Time in unix timestamp that the event was subscribed to > * @param {string} signature Hash sha512 > * @returns {bool} > */ > verify: function (publicKey, payload, signatureTime, signature) { > const payloadUtf8 = Buffer.from(payload, "utf-8").toString(); > const signatureBuffer = Buffer.from(signature, "hex"); > const data = Buffer.from(`${signatureTime}\n${payloadUtf8}`); > return crypto.verify(null, data, publicKey, signatureBuffer); > }, > }; > ``` > [tab] Golang > > ```go theme={null} > func Verify(publicKeyRaw string, payload string, signatureTime int64, sigHex string) (bool, error) { > > sig, err := hex.DecodeString(sigHex) > > if err != nil { > return false, err > } > > publicKey, err := getEd25519PublicKey(publicKeyRaw) > > if err != nil { > return false, err > } > > body := fmt.Sprintf("%d\n%s", signatureTime, payload) > message := []byte(body) > > isValid := ed25519.Verify(publicKey, message, sig) > > return isValid, nil > } > ``` > [tab] Python > > ```py theme={null} > signaturePayload = str.encode(httpSample['headers']['X-Plug-Date'] + "\n" + httpSample['body']) > signature = bytes.fromhex(httpSample['headers']['X-Plug-Signature']) > > try: > public_key.verify(signature, signaturePayload) > print('Congrats ... signature is valid!!!') > except: > print('Ops ... Signature is not valid!') > > ``` > [tab] C# > > ```csharp theme={null} > namespace PlugPagamentos; > > using System.Text; > using NSec.Cryptography; > > public class PlugSignature > { > private static Ed25519 algorithm = SignatureAlgorithm.Ed25519; > > public static Boolean verify(String payload, long signatureDate, String signatureHex, string publicKeyRaw) > { > var signature = Convert.FromHexString(signatureHex); > var payloadToVerify = Encoding.UTF8.GetBytes($"{signatureDate}\n{payload}"); > var publicKeyBytes = Encoding.UTF8.GetBytes(publicKeyRaw); > > var publicKey = PublicKey.Import(algorithm, publicKeyBytes, KeyBlobFormat.PkixPublicKeyText); > return algorithm.Verify(publicKey, payloadToVerify, signature); > } > > } > ``` > [tab] Java > > ```java theme={null} > package com.plugpagamentos; > > import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters; > import org.bouncycastle.crypto.signers.Ed25519Signer; > import org.bouncycastle.util.encoders.Hex; > > public class PlugSignature { > > public static boolean verify(String publicKeyHex, String payload, String signatureTime, String signatureHex) { > var publicKeyBytes = Hex.decode(publicKeyHex); > > var signatureBytes = Hex.decode(signatureHex); > var signingDataBytes = (signatureTime+"\n"+payload).getBytes(); > > var params = new Ed25519PublicKeyParameters(publicKeyBytes, 0); > var verifier = new Ed25519Signer(); > > verifier.init(false, params); > verifier.update(signingDataBytes, 0, signingDataBytes.length); > > return verifier.verifySignature(signatureBytes); > } > > } > ``` > [tab] PHP > > ```php theme={null} > $data = "{$sampleHttp['headers']['X-Plug-Date']}\n{$sampleHttp['body']}"; > > // convert signature hex to bin > $signature = hex2bin($sampleHttp['headers']['X-Plug-Signature']); > > if ($key->verify($data, $signature)) { > echo 'Congrats ... signature is valid!!!'; > } else { > echo 'Ops ... Signature is not valid!'; > } > ``` > [tab] Ruby > > ```ruby theme={null} > sig_bytes = hex_to_bin(http_sample['headers']['X-Plug-Signature']) > > message = http_sample['headers']['X-Plug-Date'] + "\n" + http_sample['body'] > > begin > verify_key.verify(sig_bytes, message) > puts 'Congrats ... signature is valid!!!' > rescue StandardError > puts 'Ops ... Signature is not valid!' > end > ``` ## Eventos suportados para notificação via webhooks ### Eventos Transaction | Evento | Descrição | | - | - | | **transaction.pending** | Evento enviado quando a cobrança é registrada e os dados para pagamento estão disponíveis | | **transaction.pre\_authorized** | Evento enviado quando é reconhecida a confirmação da pré-captura do pagamento da cobrança | | **transaction.authorized** | Evento enviado quando é reconhecida a confirmação da captura do pagamento da cobrança | | **transaction.failed** | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada | | **transaction.canceled** | Evento enviado quando a cobrança é cancelada após ter sido autorizada porém não capturada, sem estorno financeiro | | **transaction.voided** | Evento enviado quando a cobrança é cancelada após ter sido autorizada e capturada, produzindo um estorno financeiro | | **transaction.charged\_back** | Evento enviado quando a cobrança é cancelada após ter sido contestada e/ou não reconhecida pelo portador do cartão | | **transaction.dispute** | Evento enviado quando uma disputa relacionada à transação é aberta | | **transaction.dispute\_closed** | Evento enviado quando uma disputa é encerrada. Caso você receba charged\_back ao invés de dispute\_closed, significa que o cliente ganhou a disputa. | | **transaction.refund\_pending** | Evento enviado quando um estorno está pendente. Isso pode ocorrer em fluxos assíncronos como o Pix. | | **transaction.revert\_void** | Evento enviado quando precisamos fazer a reversão de um estorno bem-sucedido. [Veja mais](/documentations/payment-methods/credit-card#reversão-automática-de-um-estorno-revert_void) | | **transaction.probe\_void** | Evento enviado quando a sonda faz o cancelamento de uma cobrança que foi duplicada. | ### Eventos Seller | Evento | Descrição | | - | - | | **seller.active** | Evento enviado quando um seller é aprovado no provedor. Isso indica que podemos gerar uma transação com split usando esse seller. | | **seller.inactive** | Evento enviado quando o seller é inativado manualmente ou não aprovado na análise do provedor. | ### Eventos de revisão cadastral Estes eventos acompanham os processos de revisão cadastral que o provedor abre para os seus recebedores. Entenda o fluxo em [Revisão cadastral](/documentations/split/revisao-cadastral). | Evento | Descrição | | - | - | | **seller.registration\_review\.required** | Evento enviado quando o provedor abre um processo. É o aviso de que há dados a coletar dentro de um prazo. | | **seller.registration\_review\.reminder** | Lembrete periódico enquanto o processo continua sem envio. A frequência aumenta conforme o prazo se aproxima. | | **seller.registration\_review\.overdue** | Evento enviado quando o processo entra em cobrança ativa, na virada da fase inicial da revisão periódica. | | **seller.registration\_review\.expired** | Evento enviado quando o prazo vence sem envio. O provedor ainda aceita a submissão. | | **seller.registration\_review\.failed** | Evento enviado quando o provedor recusa a submissão. Havendo prazo, ela pode ser corrigida e reenviada. | | **seller.registration\_review\.finished** | Evento enviado quando o provedor confirma o recebimento e encerra o processo. | O objeto `data` traz o estado do processo, o que há para coletar e a origem no provedor: ```json theme={null} { "id": "92865677-6413-458d-b132-84600fa7878b", "apiVersion": "1.1", "object": "seller", "event": "registration_review.required", "data": { "processId": "710d84ca-950d-49fd-9747-c3d33301c6cb", "reviewType": "acp", "status": "pending", "deadlineAt": "2026-09-15T23:59:59.000Z", "daysRemaining": 18, "requestedFieldsPending": false, "requestedFields": { "raw": ["revenue"], "fields": [ { "path": "revenue", "type": "enum", "required": true, "providerField": "revenue", "label": { "pt-br": "Faixa de faturamento", "en": "Revenue range" }, "allowedValues": ["10000_to_50000", "50000_to_100000", "100000_to_500000"] } ] }, "seller": { "id": "9d160f4f-717b-4e93-8520-044bd228ec37", "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8" }, "origin": { "provider": "ZOOP", "providerId": "663f7f0c-9cad-4d7a-959c-c64ce904016e" } } } ``` > [!NOTE] > > Quando o provedor abre o processo sem informar ainda o que pedir, `requestedFields` vem ausente e `requestedFieldsPending` vem `true`. O aviso é enviado mesmo assim, porque o prazo já está correndo. ### Eventos Subscription | Evento | Descrição | | - | - | | **subscription.created** | Evento enviado quando uma nova assinatura é criada (exceto quando trial ativo) | | **subscription.trial\_started** | Evento enviado quando uma assinatura é criada com período de trial ativo | | **subscription.activated** | Evento enviado quando uma assinatura tem seu primeiro pagamento aprovado | | **subscription.updated** | Evento enviado quando uma assinatura é atualizada (mudança de valor, produtos, etc.) | | **subscription.paused** | Evento enviado quando uma assinatura é pausada | | **subscription.resumed** | Evento enviado quando uma assinatura pausada é retomada | | **subscription.unpaid** | Evento enviado quando uma assinatura fica em situação de não paga | | **subscription.expired** | Evento enviado quando uma assinatura expira | | **subscription.canceled** | Evento enviado quando uma assinatura é cancelada manualmente | | **subscription.cycle\_failed** | Evento enviado quando um ciclo de pagamento falhar devido a inconsistência de dados | ### Eventos Purchase Os eventos de Venda existem somente na versão 1.1 do webhook. Veja o formato de cada um em [purchase](#purchase). | Evento | Descrição | | - | - | | **purchase.created** | Evento enviado quando a venda é criada e aceita e a autorização é enfileirada | | **purchase.charge\_authorized** | Evento enviado quando uma cobrança da venda conclui a autorização com sucesso | | **purchase.pre\_authorized** | Evento enviado quando todas as cobranças da venda estão pré-autorizadas e a venda permanece pendente | | **purchase.paid** | Evento enviado quando a venda é paga | | **purchase.failed** | Evento enviado quando a venda falha por recusa ou abandono de uma cobrança órfã | | **purchase.cancelled** | Evento enviado quando a venda é cancelada | | **purchase.void\_failed** | Evento enviado quando o estorno das cobranças da venda esgota as tentativas, ou quando esse estorno é encerrado com uma cobrança ainda retida | # Sobre o produto Source: https://docs.malga.io/documentations/welcome/about-the-product Conheça a infraestrutura de pagamentos online da Malga, com múltiplos provedores, motor de autorização inteligente, antifraude e conformidade PCI. Somos uma infraestrutura completa de pagamentos online que permite que você construa a combinação ideal de provedores, com melhores custos e maior taxa de aprovação. Na Malga você vai ter: * **Acesso a diversos provedores de pagamento:** Conecte-se a múltiplos provedores de pagamento com uma única integração, expandindo suas possibilidades e flexibilidade. * **Motor de autorização inteligente:** Aumente suas conversões com o fluxo inteligente de transações, maximizando suas chances de sucesso a cada venda. * **Segurança e resiliência:** Proteja seus dados e transações com nosso sistema robusto e em conformidade com a regulamentação PCI. * **Proteção contra fraudes:** Utilize nosso antifraude avançado para detectar e prevenir transações fraudulentas, protegendo seu negócio e seus clientes. * **Tokenização de cartões:** Simplifique compras futuras para seus clientes e reduza o risco de fraudes com nosso serviço seguro de tokenização. * **Foco no seu negócio:** Deixe a Malga ajudar você com os dados e a gestão financeira para que você possa se concentrar no que realmente importa: o seu negócio e os seus clientes. * **Painel de dados:** Visualize seus dados financeiros de forma intuitiva e imediata. * **Analytics API:** Obtenha insights valiosos sobre o seu negócio através da nossa API de análise. * **Exportação de dados:** Exporte seus dados configurando os campos do arquivo gerado de acordo com a sua necessidade. ## Métodos de integração > [card] Aplicação própria > > Faça a integração via back-end direto com a nossa [API](/api-reference) ou use algum dos nossos [SDKs](/sdks). > [card] E-Commerce > > Use nosso plugin [VTEX](/sdks/plugins/vtex-connector) > [card] Opções No-code > > Utilize um [Link de Pagamento](/documentations/payment-link/intro) para receber pagamentos sem a necessidade de um site ou plataforma. Compare e escolha o método de integração ideal para o seu negócio: | Provedor | API Charges | API Session | Checkout SDK | Checkout Full SDK | SDK Node JS | Link de Pagamento | | :- | :-: | :-: | :-: | :-: | :-: | :-: | | Fluxo Inteligente | | | | | | | | Antifraude | | | | | | | | Campo Personalizado na Transação | | | | | | | | Envio de customer sem documento\* | | | | | | | | Split | | | | | | | | Tokenização | | | | | | | | Migração da base de cartões | | | | | | | | WebHooks | | | | | | | | Cartão, Pix e Boleto | | | | | | | | Nupay, Drip e Voucher | | | | | | | Também é possível integrar facilmente através do nosso plugin Vtex: | Provedor | VTEX | | - | :-: | | Fluxo Inteligente | | | Antifraude | | | Campo Personalizado na Transação | | | Envio de customer sem documento\* | | | Split | | | Tokenização | | | Migração da base de cartões | | | WebHooks | | | Cartão, Pix e Boleto | | | Nupay, Drip e Voucher | | Independente do método, conte com um serviço excelente de **autonomia** e **flexibilidade** em nosso [Dashboard](https://dashboard.malga.io) através do [Fluxo Inteligente](/documentations/flow-guide/flow-dash) e realize **modificações** quanto aos provedores e às regras de orquestração de pagamento. ## Recursos Aprimore sua experiência aproveitando nossos recursos dedicados a orientá-lo para uma integração rápida e eficaz: * **Documentação Específica:** Cada funcionalidade possui documentação detalhada, incluindo exemplos e casos de uso específicos. * **Melhores práticas:** Dicas e sugestões para otimizar o uso da Malga e garantir o máximo de segurança e eficiência em seus pagamentos. * **Suporte completo:** Conte com nossa equipe de especialistas para auxiliar em qualquer etapa do processo, desde a integração até o suporte técnico. # Ativando sua conta Source: https://docs.malga.io/documentations/welcome/activating-account Nesta documentação, apresentamos **o que você precisa configurar para ativar a conta em produção na Malga e começar a processar pagamentos reais da sua loja.** Através do cadastro no [Dashboard Malga](https://dashboard.malga.io/), é possível testar e integrar a solução da Malga utilizando as **credenciais de teste** disponíveis na entrada do ambiente: `client-id`, `api-key` e `merchant-ID`. Com elas, você pode simular a criação de uma cobrança e validar os cenários para a sua loja processar pagamentos com a Malga. Antes de ativar sua conta em produção, é importante **testar sua integração.** Acesse a página de [Testes](/documentations/welcome/testing) e verifique as funcionalidades disponíveis para explorar diferentes cenários e garantir a cobertura completa. Para realizar a **ativação da sua conta em produção** e processar transações reais, siga o passo a passo descrito a seguir: ### 1. **Acesse sua conta no Dashboard** A conta criada no Dashboard possuirá papel de administrador e terá acesso às credenciais de teste da sua empresa, que estarão sempre disponíveis para validação dos serviços na sua integração; ![Painel Inicial no Dashboard](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/activating-account/access-your-account-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=269d02f091f2cdb80d4bad89051539ae) ### 2. **Obtenha as chaves de produção** Com a sua conta criada no Dashboard e os testes finalizados, é hora de entrar em contato com a equipe da Malga para iniciar o processo de ativação da sua conta em produção: * Envie um e-mail para [**suporte@malga.io**](mailto:suporte@malga.io) informando que já concluiu a etapa de testes e solicitando a geração das chaves necessárias para ativação da conta. * Indique os **provedores e métodos de pagamento** que deseja utilizar na sua loja; ![Provedores Ilustrados](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/activating-account/providers.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=361b62d4e4589795ad8de12148ba2fd3) > [!NOTE] > > **NEGOCIAÇÃO COM PROVEDORES** > > Caso necessite de **cotação de taxas de provedores ou abertura de novas contas**, nosso time de atendimento poderá realizar a negociação e intermediação de propostas para o seu negócio, através do nosso pacote de serviços. Confira os provedores disponíveis [aqui](/documentations/type-tables/payment-methods-by-providers); ### 3. **Criação da subconta para processar pagamentos (merchant)** Nosso time de atendimento é responsável pela **criação da sua primeira subconta** e pelo envio das chaves de produção. Este processo pode ser realizado antes ou depois dos testes e do processo de integração; * **Funcionamento do Merchant na Malga:** O **merchant (subconta)** na Malga é a entidade que representa sua loja ou negócio na plataforma. Ele é utilizado para processar cobranças e para separar operações, recebíveis e dados de cada loja ou cliente (para modelos de subadquirência); * Cada merchant possui um `client-id` associado, que é usado para identificar e autenticar suas requisições na API da Malga; * O merchant contém as informações de **provedores habilitados na conta, status (ativo/inativo) e código MCC (Merchant Category Code)**, que é um padrão global para classificar negócios de acordo com o tipo de atividades comerciais; * O merchant pode ser configurado com **diferentes provedores de pagamento**, cada um com suas próprias credenciais e configurações específicas. Isso permite que você customize o processamento de pagamentos conforme as necessidades do seu negócio; * A configuração dos provedores dentro do merchant permite definir a **prioridade** de cada um, o que pode influenciar a ordem de tentativa de processamento das transações; * Saiba mais sobre subcontas nesta documentação, e você pode conferir suas subcontas ativas no Dashboard, em **Gerenciar subcontas** (clique no nome da empresa, no topo do menu lateral): ![Painel de Merchants](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/activating-account/create-merchant-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=47ad4da2baed299d85c38b0e52413708) ### 4. **Valide sua integração** Certifique-se de que todos os testes foram concluídos com sucesso e que sua integração está funcionando corretamente em todos os cenários desejados. Como proceder: * **Atualização das Credenciais na Integração:** Atualize sua integração com as novas credenciais de produção. Isso inclui substituir o `client-id` e a `api-key` de testes pelas credenciais de produção em todas as chamadas à API da Malga. * **Teste Final com Credenciais de Produção** Realize um teste final utilizando as credenciais de produção para garantir que tudo está funcionando conforme esperado no ambiente de produção. Este passo é crucial para verificar se a mudança de credenciais ocorreu sem problemas. * **Configuração de Webhooks** A Malga disponibiliza o serviço de webhooks para informar o seu sistema sobre eventos ocorridos em nossa plataforma. Por meio dos webhooks, você pode manter seu sistema atualizado sempre que um evento significativo ocorre, como a atualização do status de uma cobrança para confirmar ou cancelar um pagamento específico. * **Início das Operações em Produção** Com a integração testada e as credenciais de produção configuradas, você está pronto para iniciar as operações em produção. Isso significa que sua loja agora está preparada para processar pagamentos reais através da Malga. ### 5. **Configuração do fluxo inteligente de pagamentos da sua loja** Após a **ativação da sua conta em produção**, você poderá realizar a configuração do fluxo inteligente de pagamentos no Dashboard (selecione a subconta no seletor do menu lateral e acesse **Fluxos Inteligentes**), com a inserção de condicionais e regras flexíveis para garantir a máxima aprovação e otimização de custos para a sua loja. Você poderá fazer alterações a qualquer momento e publicar ajustes nos provedores e regras diretamente pelo Dashboard. [Saiba mais aqui.](/documentations/flow-guide/flow-dash) ![Painel do Flow](https://mintcdn.com/malga/-IrbFw4MHs9nOTYj/assets/images/flow-guide/flow-dash/smart-flow-light.png?fit=max\&auto=format\&n=-IrbFw4MHs9nOTYj\&q=85\&s=393f1d870f0630b322632264956fe0b7) ### 6. **Conte com o nosso time de Suporte e Monitoramento** Após a ativação, continue monitorando as transações e o desempenho da integração. A equipe da Malga está disponível para oferecer suporte e assistência caso você encontre qualquer dificuldade ou tenha dúvidas durante a operação em produção. > [card] Aplicação própria > > Faça a integração via back-end direto com a nossa [API](/api-reference) ou use algum dos nossos [SDKs](/sdks). > [card] E-Commerce > > Use nosso plugin [VTEX](/sdks/plugins/vtex-connector) > [card] Opções No-code > > Utilize um [Link de Pagamento](/documentations/payment-link/intro) para receber pagamentos sem a necessidade de um site ou plataforma. **Seguindo estes passos, sua loja estará pronta para processar pagamentos em produção com a Malga, oferecendo aos seus clientes uma experiência de pagamento segura e eficiente.** > [!NOTE] > > Você pode acionar o nosso time a qualquer momento pelo email [**suporte@malga.io**](mailto:suporte@malga.io) ou clicando no botão **Falar com o Time** disponível no *banner das chaves no ambiente de testes do Dashboard*; # Autentique-se com a Malga Source: https://docs.malga.io/documentations/welcome/authentication Autentique suas requisições à API da Malga com os headers X-Client-Id e X-Api-Key, gerando chaves de acesso no Dashboard com armazenamento seguro. Os serviços da Malga são protegidos através de chaves de acesso. Você pode gerenciar suas chaves de acesso através do seu [Dashboard](https://dashboard.malga.io/). É importante armazenar suas chaves de maneira privada e segura, uma vez que elas possuem privilégios de alteração na sua conta. Não compartilhe suas chaves, não deixe elas fixadas no seu código e nem armazene elas no seu servidor de controle de versão. Recomendamos utilizar variáveis de ambiente secretas para deixar a chave disponível para sua aplicação. > [!NOTE] > > A Autenticação para todas as chamadas da API é feita através de headers HTTP, > sendo necessário informar seu identificador de cliente na Malga e a chave > secreta de acesso. ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' ``` ## Ambientes A Malga disponibiliza dois ambientes, cada um com URL base e credenciais próprias: | Ambiente | URL base | Uso | | - | - | - | | Sandbox | `https://sandbox-api.malga.io` | Testes de integração, sem valores reais | | Produção | `https://api.malga.io` | Processamento de pagamentos reais | Os exemplos desta documentação usam a URL de produção. Para testar, substitua `https://api.malga.io` por `https://sandbox-api.malga.io` e use o `X-Client-Id` e a `X-Api-Key` de sandbox. > [!NOTE] > > Cobranças criadas em `sandbox-api.malga.io` aparecem apenas no ambiente de > testes (sandbox) do Dashboard, e não no ambiente de produção. As credenciais > de um ambiente não funcionam no outro. Veja os cenários disponíveis para simulação no [Guia de teste](/documentations/welcome/testing). ## Gestão de chaves Sua conta tem dois tipos de chave: | Tipo | Onde obter | Acesso | Validade | | - | - | - | - | | Chave secreta (chave principal) | No Dashboard | Toda a API | Até ser revogada | | Sub-key | Pela API (`POST /v1/auth`), usando a chave secreta | Só os escopos escolhidos na criação | Definida por você no campo `expires` | ## Sub-keys Sub-keys são chaves derivadas da chave secreta da sua conta, com escopo e tempo de validade limitados. Você gerencia as sub-keys integralmente pela API, sem abrir chamado com a Malga: * **Criação:** com escopos (`scope`) e tempo de validade em segundos (`expires`). Veja [Criar sub-key](/api-reference/client-token/criar-nova-chave-publica-para-uso-no-client-side). * **Remoção:** antes do fim da validade, para fazer uma rotação manual. Veja [Remover sub-key](/api-reference/client-token/remover-sub-key). Uma sub-key é usada como a chave secreta, no header `X-Api-Key`, mas só acessa os escopos dela e deixa de funcionar quando expira ou é removida. ### Onde usar sub-keys * **Aplicações back-end:** dê a cada serviço ou time uma sub-key só com os escopos de que ele precisa, em vez de compartilhar a chave secreta. Por exemplo, uma ferramenta interna que só estorna cobranças recebe uma sub-key com o escopo `charges/*/void`. * **Aplicações client-side:** no navegador ou em aplicativos, a sub-key fica exposta. Use sub-keys de curta duração (por exemplo, `900` segundos) e, de preferência, só com o escopo `tokens`, para tokenizar cartões. Crie uma sub-key nova a cada sessão de compra. | Uso | Escopo | Validade sugerida | | - | - | - | | Tokenização de cartões no checkout do navegador | `tokens` | `900` (15 minutos) | | Aplicativo que tokeniza e lista cartões salvos | `tokens`, `cards` | `3600` (1 hora) | | Ferramenta interna de atendimento que só estorna cobranças | `charges/*/void` | `86400` (24 horas) | | Ferramenta de BI que consulta a [Analytics API](/analytics/authentication/authentication) | `graphql` | Conforme a política de rotação da sua empresa | ### Criar uma sub-key Faça a chamada no seu servidor, com a chave secreta: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/auth' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "scope": ["tokens"], "expires": 900 }' ``` Resposta `201`: ```json theme={null} { "clientId": "YOUR_CLIENT_ID", "publicKey": "YOUR_PUBLIC_KEY", "scope": ["tokens"], "expires": 900, "createdAt": "2026-09-30T14:00:00.000Z" } ``` Use o `publicKey` no header `X-Api-Key`: ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/tokens' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_PUBLIC_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4019598346009339", "cardCvv": "123", "cardExpirationDate": "12/2026" }' ``` ### Remover uma sub-key A sub-key expira sozinha quando termina o tempo definido em `expires`. Se você quiser fazer uma rotação manual ou bloquear uma sub-key exposta, remova a sub-key antes do prazo, informando o `publicKey` dela na rota: ```bash theme={null} curl --location --request DELETE 'https://api.malga.io/v1/auth/YOUR_PUBLIC_KEY' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` A resposta de sucesso é `200`, sem corpo. Depois disso, as chamadas com a sub-key removida são recusadas com `403`. ## Chave secreta A Malga oferece suporte a duas chaves secretas ativas ao mesmo tempo. Para trocar a chave secreta, gere uma nova chave e mantenha a anterior ativa durante a transição. Assim, você migra a integração sem interromper as chamadas à API. Depois da migração, revogue a chave anterior. Hoje, a revogação da chave secreta é feita pelo suporte da Malga: abra um chamado pedindo a revogação. Não envie a chave secreta no chamado. Chamados urgentes, como o vazamento de uma chave, têm SLA contratual de resolução em até 2 horas, 24/7. # Tratamento de erros na integração Source: https://docs.malga.io/documentations/welcome/errors Entenda onde os erros da Malga aparecem (resposta da API, recurso recusado e webhook), como identificar cada um e onde consultar os códigos de Charges, Purchases e webhooks. A Malga padroniza os códigos de erro de todas as APIs e provedores. Assim, você trata uma recusa do mesmo jeito, qualquer que seja o adquirente que processou o pagamento. Esta página mostra onde cada erro aparece e leva você ao catálogo completo de cada API. > [card] [Charges](/documentations/welcome/errors-charges) > > Cobranças em `/v1/charges`: recusas do emissor, validações, antifraude, captura e estorno. > [card] [Purchases](/documentations/welcome/errors-purchases) > > Purchases com múltiplos cartões em `/v1/purchases`: `businessCode`, recusa por cartão e revisão. > [card] [Webhooks](/documentations/welcome/errors-webhooks) > > Onde está o motivo da recusa em cada evento e como mapear os códigos no seu sistema. > [card] [Tabela de declinedCode](/documentations/type-tables/declined-code) > > Códigos de recusa padronizados, se permitem retentativa e o que orientar ao comprador. ## Como identificar o erro Um mesmo problema pode chegar por caminhos diferentes. Siga o fluxo para saber onde ler o código: ```mermaid theme={null} flowchart TD A[Você enviou a requisição] --> B{Status HTTP} B -->|4xx ou 5xx| C[Leia o objeto error da resposta] B -->|2xx| D{Status do recurso} D -->|failed| E[Cobrança: error, providerError e fraudAnalysis.status
Purchase: payments.declineReason] D -->|canceled, pre_authorized ou authorized
com antifraude| F[Leia fraudAnalysis.status] D -->|pending| H{Purchase com pendingReview?} H -->|sim| I[Pare o polling e
acione o suporte] H -->|não| G[Aguarde o webhook
ou consulte o recurso] G --> D ``` | Onde | Quando acontece | Onde ler o código | | - | - | - | | Resposta da requisição (4xx/5xx) | A Malga recusa a requisição, como em um dado inválido, ou o processamento falha | Objeto `error` no corpo da resposta | | Cobrança ou Purchase recusada | O pagamento foi processado e recusado pelo emissor, pelo provedor ou pela Malga | Cobrança: `error` e `transactionRequests[].providerError`. Purchase: `payments[].declineReason`. Os dois campos podem vir ausentes | | Reprovação do antifraude | O antifraude reprovou a cobrança, antes ou depois da autorização | `transactionRequests[].fraudAnalysis.status`. Conforme a configuração, a cobrança fica `failed`, `canceled`, `pre_authorized` ou `authorized` | | Webhook | O status da cobrança ou da Purchase mudou, por exemplo para `failed` | Depende do recurso e da versão do webhook. Veja [Webhooks](/documentations/welcome/errors-webhooks) | > [!NOTE] > > Os erros de validação dos dados enviados, como cartão inválido ou campo obrigatório ausente, recusam a requisição antes de criar a cobrança ou a Purchase. Já um erro de servidor (5xx) ou um tempo limite excedido pode acontecer depois que o recurso foi criado. Nesses casos, verifique o estado antes de tentar de novo: consulte a cobrança pelo `orderId` ou reenvie a criação da Purchase com a mesma chave de idempotência. ## Boas práticas > [accordion] Use o código, não a mensagem > > Monte suas regras com `declinedCode`, `declined_code` ou `businessCode`. O texto de `message` pode mudar ou ser traduzido. > [accordion] Trate códigos desconhecidos como recusa genérica > > A Malga pode adicionar códigos novos. Um código que você não conhece, ou uma recusa sem código, deve ser tratado como `generic`. > [accordion] Confie no status, não na ausência de erro > > `error` e `declineReason` podem vir ausentes mesmo numa recusa. Use o `status` da cobrança ou da Purchase para saber o desfecho. > [accordion] Guarde os identificadores para o suporte > > Registre o `id` da cobrança ou da Purchase e os campos `networkDeniedReason` e `networkDeniedMessage`. Eles agilizam a análise de um caso com o suporte da Malga. ## Tipos de erro da API de Charges Resumo dos principais valores de `error.type` da API de Charges. A lista completa, com exemplos, está em [Charges](/documentations/welcome/errors-charges). A API de Purchases usa outro conjunto de tipos, descrito em [Purchases](/documentations/welcome/errors-purchases). | Type | HTTP code | Descrição | O que fazer | | - | - | - | - | | *api\_error* | *500* | Erro inesperado | Entre em contato com o suporte da Malga | | *bad\_request* | *400* | Erro na validação dos dados enviados no request | Verifique o detalhe do erro | | *invalid\_request\_error* | *400* | Erro no processamento com base nos dados enviados no request | Verifique o detalhe do erro | | *card\_declined* | Depende da operação | Transação não aprovada pelo provedor (cobrança `failed`, com `201` na criação e `200` na consulta) ou dado de cartão inválido na requisição (`400` ou `401`) | Verifique o motivo de rejeição no declinedCode | | *too\_many\_requests* | *429* | Estorno recusado por falhas seguidas no provedor | Aguarde até o horário de `retry_after_at` e tente de novo | | *unprocessable\_entity* | *422* | Erro de regra de negócio, como o estorno bloqueado pelo limite de falhas no provedor | Verifique a mensagem do erro. No caso do estorno bloqueado, entre em contato com o suporte da Malga | Veja como funciona o [limite de falhas no estorno](/documentations/more/limite-falhas-estorno). Consulte a [tabela de declinedCode](/documentations/type-tables/declined-code) para ver todos os códigos de recusa de `error.declinedCode`, se cada um permite nova tentativa e o que orientar ao comprador. # Erros da API de Charges Source: https://docs.malga.io/documentations/welcome/errors-charges Consulte os erros da API de Charges da Malga: formato do objeto error, recusas do emissor e do provedor, códigos de validação de cartão, split, 3DS, captura e estorno, com exemplos de resposta. A API de Charges devolve erros de três formas: * **Erro na requisição**: a resposta tem status 4xx ou 5xx e o objeto `error`. Os erros de validação dos dados enviados recusam a requisição antes de criar a cobrança. Um erro de servidor (5xx) ou um tempo limite excedido pode acontecer depois que a cobrança foi criada: antes de tentar de novo, [liste as cobranças](/api-reference/charges/listar-cobrancas) filtrando pelo `orderId` do pedido. * **Cobrança recusada**: o pagamento foi processado e recusado. A cobrança existe e tem `status: failed`. Esse é o caso que também chega por [webhook](/documentations/welcome/errors-webhooks). * **Reprovação do antifraude**: o antifraude reprovou a cobrança, antes ou depois da autorização. O status final depende de quando o antifraude roda e das opções do provedor antifraude. Veja [Reprovação do antifraude](#reprovação-do-antifraude). ## Cobrança recusada Quando o emissor ou o provedor recusa o pagamento, a cobrança fica com `status: failed`. A resposta de [`POST /v1/charges`](/api-reference/charges/realizar-nova-cobranca), a consulta em [`GET /v1/charges/{id}`](/api-reference/charges/recuperar-detalhes-de-cobranca) e o evento `transaction.failed` trazem os mesmos campos: ```json theme={null} { "id": "64254aef-82f2-48ba-a185-d65343462833", "status": "failed", "error": { "type": "card_declined", "declinedCode": "expired_card" }, "transactionRequests": [ { "providerType": "SANDBOX", "requestStatus": "failed", "requestType": "authorization", "providerError": { "retryable": false, "declinedCode": "expired_card", "message": null, "networkDeniedReason": "sandbox expired card", "networkDeniedMessage": "expired_card" } } ] } ``` * `error.declinedCode` é o código padronizado pela Malga. Os valores estão na [tabela de declinedCode](/documentations/type-tables/declined-code). * `providerError.networkDeniedReason` e `providerError.networkDeniedMessage` trazem o código e a mensagem originais do provedor. Use para investigar um caso, não para regras. O significado de cada campo está em [Erros recebidos por webhook](/documentations/welcome/errors-webhooks). Uma cobrança `failed` pode vir sem o objeto `error`: ele só aparece quando existe um `declinedCode`. Isso acontece, por exemplo, quando a cobrança falha antes de chegar a um provedor. Use o `status` para saber se a cobrança foi recusada e trate a ausência de código como recusa genérica. ## Reprovação do antifraude Quando o [antifraude](/documentations/anti-fraud/intro) reprova uma cobrança, o resultado não aparece em `error`. A análise fica em uma tentativa com `requestType: anti_fraud`, no campo `transactionRequests[].fraudAnalysis.status`, que vale `reproved`. Essa tentativa tem `requestStatus: success`, porque a análise foi concluída, e não traz `providerError`. O status final da cobrança depende de quando o antifraude roda e das opções do provedor antifraude: | Quando o antifraude roda | Status da cobrança após a reprovação | | - | - | | Antes do adquirente (`runBeforeCharge: true`) | `failed`: a cobrança não chega ao adquirente e gera `transaction.failed`, em geral sem o objeto `error`. Com `captureOnReproved: true`, a cobrança segue para o adquirente apesar da reprovação | | Depois da pré-autorização | `canceled`, quando a Malga anula a pré-autorização (`refundOnReproved`, ligado por padrão). Se a anulação falhar, `pre_authorized` | | Depois da pré-autorização, com captura de reprovadas | Com `captureOnReproved: true` e `refundOnReproved: false`: `authorized`, se a captura funcionar, ou `pre_authorized`, se falhar. Com as duas opções ligadas, a Malga captura e depois anula, e o status final segue o resultado da anulação | Os arranjos de `capture` e `runBeforeCharge` estão em [Antifraude síncrono](/documentations/anti-fraud/sync-anti-fraud). ```json theme={null} { "id": "64254aef-82f2-48ba-a185-d65343462833", "status": "canceled", "transactionRequests": [ { "requestStatus": "success", "requestType": "anti_fraud", "fraudAnalysis": { "status": "reproved" } } ] } ``` Para detectar a reprovação, leia `fraudAnalysis.status`, qualquer que seja o status da cobrança. Não dependa do evento `transaction.failed` nem de `error.declinedCode`. ## Formato do erro na requisição ```json theme={null} { "error": { "type": "card_declined", "code": 400, "declined_code": "invalid_cvv", "message": "Invalid card cvv. Check the data and try again" } } ``` | Campo | Descrição | | - | - | | `type` | Categoria do erro | | `code` | Status HTTP da resposta | | `declined_code` | Código estável do erro, quando existe. Use para tratar o erro no seu sistema | | `message` | Texto do erro. Pode mudar ou ser traduzido: não use em regras | | `details` | Lista de textos com detalhes, como os campos inválidos | | `context` | Valores do erro em campos, quando existem (por exemplo, `sellerId`) | | `retry_after_minutes` | Minutos até a próxima tentativa permitida. Só no `429` do estorno | | `retry_after_at` | Data e hora (UTC) da próxima tentativa permitida. Só no `429` do estorno | > [!WARNING] > > No erro da requisição o código vem em `declined_code` (com sublinhado). Na cobrança recusada e no webhook, o código vem em `declinedCode`. A exceção é o `401` de token expirado, que também usa `declinedCode`. `type` e `declined_code` são texto aberto: trate um valor que você não conhece como erro genérico. ## Erros na requisição Os erros estão agrupados por assunto. Escolha uma aba: > [tab] Cartão > > | HTTP | `type` | `declined_code` | `message` | Quando acontece | > | - | - | - | - | - | > | 400 | `card_declined` | `invalid_number` | Invalid card number. Check the data and try again | Número do cartão inválido | > | 400 | `card_declined` | `invalid_card_holder_name` | Invalid holder name. Check the data and try again | Nome do portador inválido | > | 400 | `card_declined` | `invalid_expiration_date` | Invalid expiration date. Check the data and try again | Data de validade inválida | > | 400 | `card_declined` | `invalid_cvv` | Invalid card cvv. Check the data and try again | CVV inválido | > | 400 | `card_declined` | `required_cvv` | The security code (CVV) is required to proceed. Check card details and try again | CVV obrigatório não enviado | > | 400 | `card_failed` | - | This card has a failed status and cannot be used to make a payment | Cartão salvo com status `failed` | > | 401 | `card_declined` | `expired_token` (em `declinedCode`) | Expired Token | Token de cartão expirado ou inválido | > | 404 | `card_pending_token_expired` | - | The card is in pending status: it has not been validated with a CVV yet (...) | Cartão pendente de validação usado sem CVV | > [tab] Não encontrado > > | HTTP | `type` | `message` | Quando acontece | > | - | - | - | - | > | 404 | `invalid_request_error` | Card not found | `cardId` inexistente ou de outro cliente | > | 404 | `invalid_request_error` | Customer not found | `customerId` inexistente | > | 404 | `invalid_request_error` | Token CVV Id Not Found | Token de CVV inexistente | > | 404 | `invalid_request_error` | Seller not found | Seller do split inexistente | > | 404 | `invalid_request_error` | Session not found | Session inexistente | > | 404 | `invalid_request_error` | Transaction not found | Cobrança inexistente na captura, no estorno ou na consulta | > | 400 | `not_found` | Merchant not found | `merchantId` inexistente | > | 400 | `not_found` | Provider not found | Nenhum provedor configurado para o merchant e o meio de pagamento | > [tab] Split e taxa > > | HTTP | `type` | `declined_code` | Quando acontece | > | - | - | - | - | > | 400 | `bad_request` | - | Split misto (`percentage` e `amount` juntos) ou soma do split maior que o valor da cobrança | > | 400 | `bad_request` | `split_percentage_sum_cannot_be_greater_than_100` | Soma de `percentage` acima de 100, no `splitRules` ou em um `provider[].splitRules` | > | 400 | `bad_request` | - | Seller bloqueado, inválido ou sem cadastro no provedor | > | 422 | `unprocessable_entity` | `split_multiple_transaction_owners` | Mais de uma regra com `transactionOwner: true` | > | 422 | `unprocessable_entity` | `split_multiple_liable_not_supported` | Mais regras com `liable: true` do que o provedor aceita | > | 422 | `unprocessable_entity` | `platform_fee_*` e `split_amount_mismatch` | Recusa pela taxa da plataforma. Os códigos estão em [Taxa da plataforma](/documentations/split/platform-fee) | > | 503 | `service_unavailable` | `platform_fee_config_unavailable` | Configuração da taxa da plataforma indisponível. Tente de novo | > [tab] 3DS > > | HTTP | `type` | `declined_code` | Quando acontece | > | - | - | - | - | > | 400 | `invalid_request_error` | `provider_not_configured_for_3ds2` | Cobrança com 3DS Malga ou autenticação externa sem provedor configurado para `3ds2_malga` | > | 400 | `invalid_request_error` | `provider_not_configured_for_required_capabilities` | Nenhum provedor atende ao mesmo tempo `3ds2_malga` e split | > > Os erros da autenticação 3DS estão em [Principais erros do 3DS Malga](/documentations/3ds2-malga/3ds-malga/principais-erros). > [tab] Captura e estorno > > | HTTP | `type` | `message` | Quando acontece | > | - | - | - | - | > | 400 | `invalid_request_error` | Amount cannot be greater than the transaction amount | Valor da captura maior que o da cobrança | > | 409 | `invalid_request_error` | Transaction has not pre-authorized | Captura de cobrança que não está pré-autorizada | > | 409 | `invalid_request_error` | Transaction is not pending | Autorização 3DS de uma cobrança que não está pendente | > | 409 | `invalid_request_error` | Charge already voided/canceled | Cobrança já cancelada ou estornada | > | 409 | `invalid_request_error` | It is not possible to make a refund greater than the payment amount | Estorno acima do valor pago | > | 409 | `conflict` | Transaction is processing | Outra operação na mesma cobrança, ou a mesma chave de idempotência, ainda está em processamento | > | 422 | `unprocessable_entity` | Transaction failed | Cancelamento ou estorno de cobrança fora de `authorized`, `pre_authorized` ou `pending` | > | 429 | `too_many_requests` | Too many consecutive refund failures for this charge. Please wait before trying again. | Estorno recusado por falhas seguidas no provedor. Aguarde até `retry_after_at` | > | 422 | `unprocessable_entity` | This charge has too many refund failures at the provider. (...) | Estorno bloqueado. Acione o suporte da Malga | > > Veja como funciona o [limite de falhas no estorno](/documentations/more/limite-falhas-estorno). > [tab] Validação e infra > > | HTTP | `type` | Quando acontece | > | - | - | - | > | 400 | `bad_request` | Campo obrigatório ausente ou em formato inválido. `details` lista os problemas | > | 403 | `forbidden` | Cliente sem permissão para usar o 3D Secure | > | 500 | `api_error` | Erro inesperado (`message: "Unexpected error"`). Entre em contato com o suporte | > | 504 | `gateway_timeout` | Tempo limite excedido. Consulte a cobrança antes de tentar de novo | ## Exemplos de resposta > [accordion] 400 · CVV inválido > > ```json theme={null} > { > "error": { > "type": "card_declined", > "code": 400, > "declined_code": "invalid_cvv", > "message": "Invalid card cvv. Check the data and try again" > } > } > ``` > [accordion] 400 · CVV obrigatório > > ```json theme={null} > { > "error": { > "type": "card_declined", > "code": 400, > "declined_code": "required_cvv", > "message": "The security code (CVV) is required to proceed. Check card details and try again" > } > } > ``` > [accordion] 401 · Token expirado > > ```json theme={null} > { > "error": { > "type": "card_declined", > "code": 401, > "message": "Expired Token", > "declinedCode": "expired_token" > } > } > ``` > [accordion] 404 · Cartão não encontrado > > ```json theme={null} > { > "error": { > "type": "invalid_request_error", > "code": 404, > "message": "Card not found" > } > } > ``` > [accordion] 400 · Soma de percentuais do split acima de 100 > > ```json theme={null} > { > "error": { > "type": "bad_request", > "code": 400, > "declined_code": "split_percentage_sum_cannot_be_greater_than_100", > "message": "Split percentage sum cannot be greater than 100" > } > } > ``` > [accordion] 422 · Mais de um dono da venda no split > > ```json theme={null} > { > "error": { > "type": "unprocessable_entity", > "code": 422, > "declined_code": "split_multiple_transaction_owners", > "message": "Only one split rule can have transactionOwner true." > } > } > ``` > [accordion] 400 · Provedor sem 3DS Malga > > ```json theme={null} > { > "error": { > "type": "invalid_request_error", > "code": 400, > "declined_code": "provider_not_configured_for_3ds2", > "message": "No provider configured for Malga 3DS2 or external authentication charge", > "details": ["no provider configured with paymentTypes=3ds2_malga for this charge"] > } > } > ``` > [accordion] 409 · Operação em processamento > > ```json theme={null} > { > "error": { > "type": "conflict", > "code": 409, > "message": "Transaction is processing" > } > } > ``` > [accordion] 409 · Captura de cobrança não pré-autorizada > > ```json theme={null} > { > "error": { > "type": "invalid_request_error", > "code": 409, > "message": "Transaction has not pre-authorized" > } > } > ``` > [accordion] 429 · Estorno com falhas seguidas > > ```json theme={null} > { > "error": { > "type": "too_many_requests", > "code": 429, > "message": "Too many consecutive refund failures for this charge. Please wait before trying again.", > "retry_after_minutes": 30, > "retry_after_at": "2026-11-03T14:30:00.000Z" > } > } > ``` > [accordion] 500 · Erro inesperado > > ```json theme={null} > { > "error": { > "type": "api_error", > "code": 500, > "message": "Unexpected error" > } > } > ``` # Erros da API de Purchases Source: https://docs.malga.io/documentations/welcome/errors-purchases Consulte os erros da API de Purchases da Malga: businessCode de cada endpoint, erros do pagamento de Session com múltiplos cartões, motivo de recusa por cartão (declineReason) e pendingReview, com exemplos. A API de [Purchases com múltiplos cartões](/documentations/payment-methods/multiple-cards) devolve erros de três formas: * **Erro na requisição**: a resposta tem status 4xx ou 5xx e o objeto `error`. Os erros de validação dos dados enviados recusam a chamada antes de criar a Purchase. Depois de um `408` ou `503`, a Purchase pode já existir: reenvie a criação com a mesma `X-Idempotency-Key` e o mesmo corpo para receber o estado atual. * **Purchase recusada**: a criação respondeu `202`, mas um cartão foi recusado no processamento. A Purchase termina `failed` e o motivo, quando existe, fica em `payments[].declineReason`. * **Purchase em revisão**: a Purchase continua `pending` com o campo `pendingReview`, que indica uma anomalia no processamento. ## Formato do erro na requisição ```json theme={null} { "error": { "type": "conflict", "code": 409, "message": "Conflict", "businessCode": "purchase_invalid_state", "details": ["purchase_invalid_state"] } } ``` | Campo | Descrição | | - | - | | `type` | Categoria: `api_error`, `bad_request`, `validation_error`, `not_found`, `conflict`, `unauthorized` ou `unavailable` | | `code` | Status HTTP da resposta | | `message` | Texto resumido do erro. Não use em regras | | `businessCode` | Código do erro. Use para tratar o erro no seu sistema. Vem nos erros `400`, `404`, `409` e `422` | | `details` | Nos erros `404`, `409` e `422`, repete o `businessCode` | ## Erros na requisição | `businessCode` | HTTP | `type` | Endpoints | Quando acontece | | - | - | - | - | - | | `invalid_request` | 400 | `bad_request` | Todos com corpo ou filtros | JSON ilegível, campo não previsto no corpo (como `amount` no cancelamento) ou filtro inválido na listagem (`limit` acima de 100, UUID malformado, `status` fora do enum) | | `invalid_request` | 422 | `validation_error` | Criação, captura, cancelamento e listagem | Header `X-Idempotency-Key` ausente. Na criação, também `paymentType` diferente de `credit`, `installments` menor que 1 ou split inválido. No cancelamento, `intent` fora de `cancel` e `refund`. Na listagem, data fora do formato RFC 3339 | | `pan_not_allowed` | 422 | `validation_error` | Criação | Dados de cartão em claro em `paymentSource`, `metadata` ou `fraudAnalysis`. Use `cardId` ou `tokenId` | | `invalid_payments_count` | 422 | `validation_error` | Criação | Quantidade de cartões fora do intervalo de 2 a 3 | | `payments_amount_mismatch` | 422 | `validation_error` | Criação | Soma dos valores dos cartões diferente de `amount` | | `payment_amount_below_minimum` | 422 | `validation_error` | Criação | Valor de um cartão abaixo de 100 centavos | | `currency_not_brl` | 422 | `validation_error` | Criação | Moeda diferente de `BRL` | | `payment_source_required` | 422 | `validation_error` | Criação | `paymentSource` sem exatamente uma referência de cartão (`cardId` ou `tokenId`) | | `purchase_not_found` | 404 | `not_found` | Consulta, histórico, captura e cancelamento | Purchase inexistente, com `id` malformado ou de outro cliente | | `idempotency_key_payload_mismatch` | 409 | `conflict` | Criação, captura e cancelamento | Mesma chave de idempotência com outro corpo, ou chave já usada em outra operação | | `purchase_operation_in_progress` | 409 | `conflict` | Captura e cancelamento | Já existe uma operação em andamento na Purchase e a chamada veio com uma chave nova | | `purchase_invalid_state` | 409 | `conflict` | Captura e cancelamento | Captura: Purchase criada com `capture: true`, fora de `pending` ou sem cartões `pre_authorized`. Cancelamento: estado misto, Purchase `failed` ou `cancelled`, ou sem saldo estornável | | `purchase_intent_mismatch` | 409 | `conflict` | Cancelamento | `intent: cancel` em Purchase `paid`, ou `intent: refund` em Purchase com cartões apenas pré-autorizados. Nenhum valor é movimentado | Quando `idempotency_key_payload_mismatch` e `purchase_operation_in_progress` se aplicam ao mesmo tempo, a resposta traz `idempotency_key_payload_mismatch`. ### Erros sem `businessCode` | HTTP | `type` | `message` | Quando acontece | | - | - | - | - | | 401 | `unauthorized` | Unauthorized | Header `X-Client-Id` ausente, vazio ou inválido | | 408 | `api_error` | Request timeout | A requisição passou do tempo limite de processamento. A Purchase pode já existir: reenvie com a mesma chave de idempotência e o mesmo corpo | | 503 | `unavailable` | Service unavailable | Dependência temporariamente indisponível na criação. Tente de novo com a mesma chave de idempotência e o mesmo corpo | ## Erros do pagamento de Session [`POST /v1/sessions/{id}/purchase`](/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes) paga uma Session com múltiplos cartões. Essa rota devolve dois grupos de erros: * **Erros da própria rota**: validações da Session, listadas na tabela abaixo. Os erros `422` vêm com `type: bad_request` e, em geral, `details` vazio. A exceção é um seller do split da Session que não existe mais: a resposta é um `422` com `type: bad_request`, `details` preenchido e sem `businessCode`. * **Erros repassados da API de Purchases**: depois das validações da Session, a rota cria a Purchase e repassa sem alteração o status e o corpo de um erro da API de Purchases. Esses erros seguem a tabela de [Erros na requisição](#erros-na-requisição), por exemplo um `422` com `type: validation_error` e `details` preenchido. Trate os dois grupos pelo `businessCode`, sem depender de `type` ou de `details`. Quando o erro não tiver `businessCode`, trate-o como recusa genérica pelo status HTTP, sem montar regras com o texto de `message`. | `businessCode` | HTTP | `message` | Quando acontece | | - | - | - | - | | - | 400 | Missing required header: X-Client-Id | Header `X-Client-Id` ausente | | - | 400 | Invalid JSON payload | Corpo JSON inválido | | - | 404 | Session not found | Session inexistente ou de outro cliente | | `idempotency_key_payload_mismatch` | 409 | Conflict | Chave de idempotência já usada com outro corpo | | `multiple_payments_required` | 422 | session is not configured for multiple payments | Session sem `paymentType: multiple` em `paymentMethods` | | `session_cannot_be_paid` | 422 | session cannot be paid in current status | Session já paga ou cancelada | | `session_disabled` | 422 | session disabled | Session desativada | | `purchase_in_progress` | 422 | purchase is already in progress | Já existe uma Purchase em andamento para a Session. Depois de uma Purchase `failed`, tente de novo em alguns segundos, com uma chave nova | | `multiple_payments_limit_reached` | 422 | multiple payments limit reached | Limite de pagamentos do link atingido | | `invalid_payments_count` | 422 | number of payments is outside the session card limit | Quantidade de cartões fora do intervalo de 2 até o `quantity` da Session | | `payments_amount_mismatch` | 422 | sum of payment amounts must equal session amount | Soma dos cartões diferente do valor da Session | | `payment_amount_below_minimum` | 422 | each payment amount must be at least 100 | Valor de um cartão abaixo de 100 centavos | | `payment_source_required` | 422 | payment source must contain exactly one vault reference | Cartão sem exatamente uma referência (`cardId` ou `tokenId`) | | `pan_not_allowed` | 422 | card data must use a vault reference | Dados de cartão em claro | | `currency_not_brl` | 422 | session currency must be BRL | Session com moeda diferente de `BRL` | | `invalid_request` | 422 | payment type must be credit and installments must be within the session configuration | `paymentType` diferente de `credit`, ou parcelas menores que 1 ou acima do `installments` da Session | | `split_seller_not_active` | 422 | This payment could not be completed. Please contact the seller. | Recebedor do split da Session inativo | | `platform_fee_seller_not_active` | 422 | This payment could not be completed. Please contact the seller. | Recebedor da Session sem as condições exigidas pela taxa da plataforma | > [!WARNING] > > Um `422` com `multiple_payments_limit_reached` também pode chegar depois que a API de Purchases aceitou a Purchase, quando a Session não consegue reservar o pagamento ao mesmo tempo que outra cobrança. Nesse caso a Purchase pode existir e seguir em processamento. Antes de oferecer uma nova tentativa ao comprador, [liste as Purchases](/api-reference/purchases/listar-vendas) com o filtro `sessionId` da Session. ## Motivo da recusa por cartão Quando um cartão é recusado, a Purchase termina `failed` e o cartão traz `status: failed`. O campo `declineReason` traz só o código, sem mensagem, e vem de uma destas origens: | Origem | Valor de `declineReason` | | - | - | | Recusa do emissor ou do provedor | O `declinedCode` da cobrança do cartão, como `insufficient_funds` ou `invalid_cvv`. Os valores estão na [tabela de declinedCode](/documentations/type-tables/declined-code) | | Recusa da API de Charges antes do provedor | O `declined_code` do erro, como `required_cvv` ou `split_multiple_transaction_owners`. Sem código, vem o `type` do erro, como `card_failed`. Veja [Erros da API de Charges](/documentations/welcome/errors-charges) | | Validação da Malga | `merchant_not_owned`, quando o `merchantId` informado não pertence ao seu cliente | `declineReason` é opcional: quando a Malga não recebe um código, o campo é omitido. Trate um cartão `failed` sem `declineReason`, ou com um código que você não conhece, como recusa genérica. Use o `status` da Purchase e do cartão para saber o desfecho, nunca a ausência de `declineReason`. Quando o cartão tem `chargeId`, você pode consultar a cobrança em [`GET /v1/charges/{id}`](/api-reference/charges/recuperar-detalhes-de-cobranca) para ver a mensagem e o código original do provedor. Nas recusas da API de Charges antes do provedor e no `merchant_not_owned`, a cobrança não chega a ser criada e o cartão não tem `chargeId`: o motivo disponível é o próprio `declineReason`. ```json theme={null} { "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "status": "failed", "payments": [ { "slotIndex": 1, "amount": 5000, "status": "failed", "chargeId": "7b1e3f0a-2c4d-4e5f-8a9b-0c1d2e3f4a5b", "declineReason": "insufficient_funds", "refundedAmount": 0 } ] } ``` ## Purchase em revisão Uma Purchase `pending` com o campo `pendingReview` teve uma anomalia no processamento e não avança sozinha. Interrompa o polling automático e acione o suporte da Malga com o `id` da Purchase. | `pendingReview.reason` | Descrição | | - | - | | `reconciliation_failed` | O prazo de reconciliação terminou sem confirmar o desfecho de uma cobrança | | `amount_mismatch` | O valor observado na cobrança é diferente do valor esperado para o cartão | | `claims_exhausted` | O processamento esgotou as tentativas automáticas e o desfecho do valor é desconhecido | ```json theme={null} { "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "status": "pending", "pendingReview": { "reason": "reconciliation_failed", "since": "2026-07-27T18:05:00Z" } } ``` ## Erros por webhook Os eventos `purchase.failed` e `purchase.void_failed` não trazem o motivo. Ao receber um deles, consulte a Purchase em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda). O passo a passo está em [Erros recebidos por webhook](/documentations/welcome/errors-webhooks). ## Exemplos de resposta > [accordion] 400 · invalid\_request > > ```json theme={null} > { > "error": { > "type": "bad_request", > "code": 400, > "message": "Validation error", > "businessCode": "invalid_request", > "details": [] > } > } > ``` > [accordion] 401 · X-Client-Id ausente > > ```json theme={null} > { > "error": { > "type": "unauthorized", > "code": 401, > "message": "Unauthorized", > "details": ["unauthorized"] > } > } > ``` > [accordion] 404 · purchase\_not\_found > > ```json theme={null} > { > "error": { > "type": "not_found", > "code": 404, > "message": "Resource not found", > "businessCode": "purchase_not_found", > "details": ["purchase_not_found"] > } > } > ``` > [accordion] 408 · Tempo limite excedido > > ```json theme={null} > { > "error": { > "type": "api_error", > "code": 408, > "message": "Request timeout", > "details": [] > } > } > ``` > [accordion] 409 · idempotency\_key\_payload\_mismatch > > ```json theme={null} > { > "error": { > "type": "conflict", > "code": 409, > "message": "Conflict", > "businessCode": "idempotency_key_payload_mismatch", > "details": ["idempotency_key_payload_mismatch"] > } > } > ``` > [accordion] 409 · purchase\_operation\_in\_progress > > ```json theme={null} > { > "error": { > "type": "conflict", > "code": 409, > "message": "Conflict", > "businessCode": "purchase_operation_in_progress", > "details": ["purchase_operation_in_progress"] > } > } > ``` > [accordion] 409 · purchase\_invalid\_state > > ```json theme={null} > { > "error": { > "type": "conflict", > "code": 409, > "message": "Conflict", > "businessCode": "purchase_invalid_state", > "details": ["purchase_invalid_state"] > } > } > ``` > [accordion] 409 · purchase\_intent\_mismatch > > ```json theme={null} > { > "error": { > "type": "conflict", > "code": 409, > "message": "Conflict", > "businessCode": "purchase_intent_mismatch", > "details": ["purchase_intent_mismatch"] > } > } > ``` > [accordion] 422 · pan\_not\_allowed > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "pan_not_allowed", > "details": ["pan_not_allowed"] > } > } > ``` > [accordion] 422 · invalid\_request (X-Idempotency-Key ausente) > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "invalid_request", > "details": ["invalid_request"] > } > } > ``` > [accordion] 422 · invalid\_payments\_count > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "invalid_payments_count", > "details": ["invalid_payments_count"] > } > } > ``` > [accordion] 422 · payments\_amount\_mismatch > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "payments_amount_mismatch", > "details": ["payments_amount_mismatch"] > } > } > ``` > [accordion] 422 · payment\_amount\_below\_minimum > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "payment_amount_below_minimum", > "details": ["payment_amount_below_minimum"] > } > } > ``` > [accordion] 422 · currency\_not\_brl > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "currency_not_brl", > "details": ["currency_not_brl"] > } > } > ``` > [accordion] 422 · payment\_source\_required > > ```json theme={null} > { > "error": { > "type": "validation_error", > "code": 422, > "message": "Validation error", > "businessCode": "payment_source_required", > "details": ["payment_source_required"] > } > } > ``` > [accordion] 503 · Serviço indisponível > > ```json theme={null} > { > "error": { > "type": "unavailable", > "code": 503, > "message": "Service unavailable", > "details": [] > } > } > ``` > [accordion] Session · 422 purchase\_in\_progress > > ```json theme={null} > { > "error": { > "type": "bad_request", > "code": 422, > "message": "purchase is already in progress", > "businessCode": "purchase_in_progress", > "details": [] > } > } > ``` > [accordion] Session · 422 session\_cannot\_be\_paid > > ```json theme={null} > { > "error": { > "type": "bad_request", > "code": 422, > "message": "session cannot be paid in current status", > "businessCode": "session_cannot_be_paid", > "details": [] > } > } > ``` > [accordion] Session · 404 Session não encontrada > > ```json theme={null} > { > "error": { > "type": "not_found", > "code": 404, > "message": "Session not found", > "details": [] > } > } > ``` # Erros recebidos por webhook Source: https://docs.malga.io/documentations/welcome/errors-webhooks Saiba onde está o código de erro em cada evento de webhook da Malga (transaction, purchase e subscription), o que significa cada campo e como mapear as recusas no seu sistema. Os eventos de webhook não têm um campo de erro próprio. O conteúdo de `data` depende do recurso e da versão do webhook: * Nos eventos `transaction.*` da versão 1.1, `data` tem o mesmo formato da consulta da cobrança, com o estado do momento do evento. O motivo da recusa fica dentro desse objeto. * Nos eventos `purchase.*`, `data` traz só o resumo da Purchase, sem os cartões e sem o motivo. Consulte a Purchase para ver o motivo. Esta página mostra onde ler o código em cada evento e como usá-lo no seu sistema. > [!NOTE] > > Um erro de validação dos dados enviados recusa a requisição antes de criar a cobrança ou a Purchase, por isso não gera webhook. Esses erros estão em [Erros da API de Charges](/documentations/welcome/errors-charges) e [Erros da API de Purchases](/documentations/welcome/errors-purchases). ## Onde está o motivo em cada evento | Evento | Onde está o motivo da recusa | | - | - | | `transaction.failed` (webhook v1.1) | `data.error.declinedCode` e, para cada tentativa no provedor, `data.transactionRequests[].providerError` | | `transaction.*` (webhook v1.0, obsoleto) | `data.transactionError.declinedCode` e `data.transactionRequests[].providerError` | | `purchase.failed` | Não vem no evento. Consulte `payments[].declineReason` em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda) | | `purchase.void_failed` | Não traz código. É um alerta de valor retido: consulte a Purchase e acione o suporte da Malga com o `id` da Purchase | | `subscription.unpaid` | `data.cycle.paymentHistory[].error`, com `providerError` nas recusas do provedor. Veja [Webhooks de assinaturas](/documentations/more/recurrence/engine/webhooks) | ## Campos de erro da cobrança No evento `transaction.failed` da versão 1.1, o objeto `data` tem o mesmo formato da resposta de [`GET /v1/charges/{id}`](/api-reference/charges/recuperar-detalhes-de-cobranca), com o estado da cobrança no momento do evento. Os campos de erro são: | Campo | O que é | Como usar | | - | - | - | | `error` | Objeto do erro. Só aparece quando existe um `declinedCode`: uma cobrança `failed` pode vir sem ele | Use o `status` para saber se a cobrança foi recusada | | `error.type` | Categoria do erro. No webhook, vem `card_declined` sempre que há um `declinedCode` | Identifique que a cobrança foi recusada | | `error.declinedCode` | Código de recusa padronizado pela Malga, igual para todos os provedores | Use para regras no seu sistema. Consulte a [tabela de declinedCode](/documentations/type-tables/declined-code) | | `error.message` | Texto da recusa. Pode vir ausente | Use só para exibição ou log, nunca em regras | | `transactionRequests[].providerError.declinedCode` | Código padronizado da recusa naquela tentativa | Na recusa do provedor, a última tentativa traz o mesmo código de `error.declinedCode` | | `transactionRequests[].providerError.retryable` | Indica se a recusa permite nova tentativa | Decida se oferece uma nova tentativa ao comprador | | `transactionRequests[].providerError.networkDeniedReason` | Código original devolvido pelo provedor ou pela bandeira | Guarde para suporte e conciliação. O valor muda de provedor para provedor | | `transactionRequests[].providerError.networkDeniedMessage` | Mensagem original devolvida pelo provedor ou pela bandeira | Guarde para suporte e conciliação | | `transactionRequests[].providerError.message` | Mensagem associada ao erro do provedor. Pode vir `null` | Use só para log | > [!TIP] > > Para mapear os erros no seu sistema, use `error.declinedCode`. Os campos `networkDeniedReason` e `networkDeniedMessage` trazem o código original de cada provedor e não têm uma lista fechada: eles servem para investigar um caso com o suporte, não para regras de negócio. `transactionRequests` lista as tentativas da cobrança em cada provedor, da mais recente para a mais antiga. Quando um [Fluxo Inteligente](/documentations/flow-guide/introduction) tenta mais de um provedor, cada tentativa recusada traz o próprio `providerError`. > [!WARNING] > > A reprovação do antifraude não preenche `error.declinedCode`. O evento depende de quando o antifraude roda e das opções do provedor antifraude. Antes do adquirente, com `captureOnReproved` desligado, a cobrança fica `failed` e gera `transaction.failed`. Com `captureOnReproved` ligado, a cobrança segue para o adquirente apesar da reprovação, e o evento depende do status final. Depois da pré-autorização, a cobrança fica `canceled`, `pre_authorized` ou `authorized`, conforme as opções do provedor antifraude. Em todos os casos, o resultado fica em `transactionRequests[].fraudAnalysis.status`. Veja [Reprovação do antifraude](/documentations/welcome/errors-charges#reprovação-do-antifraude). ### Exemplo de `transaction.failed` Evento gerado no Sandbox por uma cobrança com cartão de final 3 (cartão expirado), conforme [Teste sua integração](/documentations/welcome/testing). O exemplo mostra apenas os campos relevantes para o erro: ```json theme={null} { "id": "0b0a3c4e-6a8b-4d0c-9d47-4f3b2a1f8e21", "apiVersion": "1.1", "object": "transaction", "event": "failed", "createdAt": "2026-11-03T13:20:11.482Z", "data": { "id": "64254aef-82f2-48ba-a185-d65343462833", "merchantId": "a8baa4b4-3cc9-4083-95f5-44c1c8b0f9da", "amount": 1500, "currency": "BRL", "status": "failed", "error": { "type": "card_declined", "declinedCode": "expired_card" }, "transactionRequests": [ { "id": "8c1a08e7-89aa-47e4-9edd-44e7630e8996", "providerType": "SANDBOX", "amount": 1500, "requestStatus": "failed", "requestType": "authorization", "providerError": { "retryable": false, "declinedCode": "expired_card", "message": null, "networkDeniedReason": "sandbox expired card", "networkDeniedMessage": "expired_card" } } ] } } ``` Em produção, `networkDeniedReason` e `networkDeniedMessage` trazem o código e a mensagem do provedor que processou a cobrança. ## Recusa de uma Purchase com múltiplos cartões O evento `purchase.failed` traz só o resumo da Purchase, sem a lista de cartões e sem o motivo. Ao receber o evento, consulte a Purchase e leia `payments[].declineReason` do cartão recusado. **1. Receba o evento** ```json theme={null} { "id": "f5792979-d4a5-4224-97a2-79f5f3f32878", "apiVersion": "1.1", "object": "purchase", "event": "failed", "data": { "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "merchantId": "6d5b0464-090b-480b-a4e9-e1a0fb60a495", "status": "failed", "amount": 15000, "currency": "BRL", "capture": true }, "createdAt": "2026-07-27T18:00:19.774Z" } ``` **2. Consulte a Purchase** ```bash theme={null} curl --request GET 'https://api.malga.io/v1/purchases/1c6381d1-9fcd-4e9a-a012-93cf0457dcb9' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` **3. Leia o declineReason do cartão recusado** Trecho da resposta com o cartão recusado: ```json theme={null} { "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9", "status": "failed", "payments": [ { "slotIndex": 1, "amount": 5000, "status": "failed", "chargeId": "7b1e3f0a-2c4d-4e5f-8a9b-0c1d2e3f4a5b", "declineReason": "insufficient_funds", "refundedAmount": 0 } ] } ``` `declineReason` traz só o código, sem mensagem, e pode vir ausente. Os valores possíveis estão em [Erros da API de Purchases](/documentations/welcome/errors-purchases). Quando o cartão tem `chargeId`, consulte a cobrança em `GET /v1/charges/{id}` para ver os detalhes da recusa no provedor. Sem `chargeId`, a cobrança não chegou a ser criada e o motivo disponível é o próprio `declineReason`. ## Como mapear os erros no seu sistema 1. Identifique o evento de falha: `transaction.failed` para cobranças e `purchase.failed` para Purchases. 2. Leia o código padronizado: `data.error.declinedCode` na cobrança ou `payments[].declineReason` na Purchase. 3. Decida a ação pela [tabela de declinedCode](/documentations/type-tables/declined-code), que indica se o código é retentável e o que orientar ao comprador. 4. Trate um código que você não conhece, ou a ausência de código, como recusa genérica (`generic`). A Malga pode adicionar códigos novos. Nunca conclua que o pagamento foi aprovado só porque não há `error` ou `declineReason`: use o `status`. 5. Para cobranças com antifraude, leia também `transactionRequests[].fraudAnalysis.status`. 6. Guarde `networkDeniedReason`, `networkDeniedMessage` e o `id` da cobrança ou da Purchase para abrir um chamado com o suporte, se precisar. # Sobre a Malga Source: https://docs.malga.io/documentations/welcome/introduction Otimize vendas e simplifique pagamentos online com a Malga, integrando múltiplos provedores ao seu e-commerce em uma única infraestrutura. Otimize suas vendas e simplifique pagamentos online com a Malga! Somos uma infraestrutura completa de pagamentos online que se integra facilmente ao seu e-commerce dando acesso a diversos provedores de pagamento e maximizando suas chances de sucesso a cada venda. ![Malga Dark](https://mintcdn.com/malga/T_s8SpOXGhWYo7Vj/assets/images/intro/about-malga---light.webp?fit=max\&auto=format\&n=T_s8SpOXGhWYo7Vj\&q=85\&s=3828be0e028e6974d90508a9a2c30000) ### Começando Desenvolvedor, este é o seu guia para testar e realizar as configurações necessárias para integrar com a Malga. > [card] [Sobre o produto](/documentations/welcome/about-the-product) > > Entenda como uma única integração pode evoluir a experiência de pagamentos do seu negócio > [card] [Getting Started](/documentations/welcome/primeiros-passos) > > Prepare-se para uma integração simples e segura neste guia para testar e integrar com a Malga ### Integrando com um agente de código? Instale a skill da Malga para o assistente usar esta documentação com mais contexto. Instale a skill da Malga no seu agente. npx skills add [https://docs.malga.io](https://docs.malga.io) ## Consulte também > [card] [SDKs](/sdks/tokenization/v2/intro) > > Sua última integração de pagamentos agora mais simples e fácil de integrar > [card] [API](/api-reference) > > Explore nossa documentação detalhada da API para integrar facilmente e aproveitar ao máximo nossos serviços > [card] [Analytics](/analytics/intro) > > Tenha todos os seus dados de pagamentos para análises e insights em um só lugar > [card] [Release Notes](/release-notes) > > Fique por dentro das últimas atualizações e melhorias em nosso produto # Primeiros passos Source: https://docs.malga.io/documentations/welcome/primeiros-passos Siga os primeiros passos na Malga: crie sua conta no Dashboard e obtenha credenciais como client-id e api-key para iniciar suas integrações. **1. Crie sua conta** Vá até nosso [Dashboard](https://dashboard.malga.io) para iniciar o processo de criação da sua conta. Complete o processo de criação da conta para obter suas **credenciais**, como `client-id` e `api-key` ![Tela de login da Dashboard](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/getting-started/create-your-account-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=b79c93ba0bf308649eb90bba505b76fe) **2. Suas chaves** As chaves que deverão ser enviadas nas requisições para a Malga estão disponíveis na Dashboard da Malga. A `api-key` deve ser enviada como `X-Api-Key`, já o `client-id` deve ser enviado como `X-Client-Id`. Além disso, um merchant também será disponibilizado para que você possa começar a realizar cobranças dentro da Malga. ![Interface de chaves na Dashboard](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/getting-started/your-keys-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=109a1b851a275e2a2b0653ca125f6489) **3. Integração com a Malga** A Malga conta com diversos tipos de integração, escolha a ideal para o seu negócio. > [card] [API Charges](/api-reference/charges/realizar-nova-cobranca) > > Integre direto com a nossa API de Cobranças para criar transações para o seu negócio > [card] [API Sessions](/documentations/more/sessions) > > Crie Links de Pagamento utilizando a nossa API de Sessions > [card] [API SDK](/sdks/api-sdks/introduction) > > Utilize nosso SDK para acelerar a sua integração > [card] [Checkout SDK](/sdks/intro-sdk) > > Conheça as nossas soluções para integração rápida no front-end > [card] [Plugin](/sdks/plugins) > > Vtex > [card] [Link de Pagamento](/documentations/payment-link/intro) > > Crie Links de Pagamento sem nenhuma integração **4. Testando sua integração** * Acesse a página [Testando](/documentations/welcome/testing) para conferir nossas funcionalidades de testes * Comece com testes simples e vá aumentando a complexidade gradativamente * Explore diferentes cenários e casos de uso para garantir a cobertura completa * Registre todos os resultados e anomalias para análise posterior * Utilize a documentação e o suporte para solucionar dúvidas e otimizar seus testes * Suporte dedicado: Nossa equipe de especialistas está pronta para te ajudar a qualquer momento. Entre em contato se tiver dúvidas ou precisar de assistência **5. Ative sua conta e dê vida ao seu projeto!** Parabéns! Você concluiu a etapa de testes e integração e está pronto para dar o próximo passo: ativar sua conta e criar seu ambiente de produção. **É simples assim:** * **Acesse o Dashboard:** Faça login no [Dashboard](https://dashboard.malga.io) e localize o botão "Entrar em contato". * **Clique em "Entrar em contato":** Nossa equipe de especialistas estará pronta para te atender e te guiar na criação do seu ambiente de produção. ![Interface de ativação de conta na Dashboard](https://mintcdn.com/malga/oDWEND-6kl-CwXp6/assets/images/welcome/getting-started/contact-dialog-light.png?fit=max\&auto=format\&n=oDWEND-6kl-CwXp6\&q=85\&s=22f1332e8ed79a22df8d9be16a6794a5) **O que esperar:** **Atendimento personalizado:** Nossa equipe irá entender suas necessidades e te auxiliar em todo o processo. **Configuração personalizada:** Ajustaremos a plataforma de acordo com suas especificidades. **Treinamento e suporte:** Te forneceremos todo o suporte necessário para você aproveitar ao máximo a plataforma. ### Integrando com um agente de código? Instale a skill da Malga para o assistente usar esta documentação com mais contexto. Instale a skill da Malga no seu agente. npx skills add [https://docs.malga.io](https://docs.malga.io) # Guia de teste Source: https://docs.malga.io/documentations/welcome/testing Guia de teste da integração com a Malga: use cartões fictícios e regras por final do número para simular aprovação, recusa e antifraude no Sandbox. Os números de cartões a serem utilizados no teste podem ser gerados a partir de qualquer site gerador de cartões, devendo o comportamento seguir a seguinte regra: | Cartão | Autorizado? | Status | | - | - | - | | Final 0, 1 ou 4 | SIM | Aprovado | | Final 2 | NÃO | Não autorizado | | Final 3 | NÃO | Cartão expirado | | Final 5 | NÃO | Cartão bloqueado | | Final 6 | NÃO | Timeout | | Final 7 | NÃO | Cartão cancelado | | Final 8 | Aleatório SIM/NÃO | Aprovado / Timeout | > [!NOTE] > > Transações no ambiente de sandbox envolvendo tokenização funcionam normalmente > com base em cartões de teste. Cada cartão salvo na tokenização é tratado como > um cartão normal, podendo ser usado no processo de simulação. A informação de > Cód. Segurança (CVV) segue a seguinte regra de validação em sandbox, CVV final > zero "0" o cartão é validado, para qualquer outro valor o status retorna como > não validado. > [!NOTE] > > Os cenários da tabela acima são os únicos disponíveis para simulação de cartão em sandbox. Não é possível simular códigos de recusa específicos, como `insufficient_funds`. Esses códigos aparecem apenas em respostas reais dos emissores e estão listados na [tabela de declined codes](/documentations/type-tables/declined-code). Para gerar cartões de teste com um status específico via SDK, consulte [Gerar cartão](/sdks/api-sdks/docs/sandbox/generate-card). **Se você conseguiu inserir os dados de cartão na sua aplicação cliente, criar um token, enviar os dados para o seu servidor e criar uma cobrança, então sua integração está finalizada.** ## 3DS Malga Em cobranças com 3DS Malga, o Sandbox aprova pelo resultado da autenticação da Cybersource (`transStatus` `Y` ou `A` e ECI fora de `00` e `07`), sem aplicar a regra do último dígito. Nessas cobranças, o antifraude não é executado. Para os cartões de teste, o portador `FAILED` e a regra do CVV, consulte [Testando 3DS Malga no Sandbox](/documentations/3ds2-malga/3ds-malga/testes-sandbox). ## Captura e estorno Caso queira testar o cenário de falha na captura ou estorno, o valor **991** deverá ser utilizado como valor para essas duas requisições. ## Antifraude Caso queira testar cenários antifraude, o valor analisado em sandbox será o final do documento enviado no nó de antifraude (`fraudAnalysis`) na criação da transação. O status retornado para antifraude seguirá as regras dispostas na tabela abaixo: | Documento | Autorizado? | Status | Declined Code | | - | - | - | - | | Final 0 | NÃO | Pendente; **Aprovado** após 2 minutos | Nulo | | Final 1 | SIM | Aprovado | Nulo | | Final 2 | NÃO | Falha | Aleatório `timeout` ou `processing_error` | | Final 3 | NÃO | Erro no antifraude (análise falha) | Nulo | | Final 9 | NÃO | Pendente; **Reprovado** após 2 minutos | Nulo | | Qualquer outro final | NÃO | Reprovado | Nulo | Os finais 0 e 9 simulam o antifraude assíncrono. Os detalhes estão em [Testando antifraude em sandbox](/documentations/anti-fraud/testing). ## Recebedores No ambiente de sandbox, o status inicial de um recebedor é derivado de forma determinística a partir do **último dígito do documento**. O documento considerado é o `owner.document.number` e, na sua ausência, o `business.document.number` (nessa ordem de prioridade). | Documento | Status inicial do recebedor | | - | - | | Final 7 | `pending` | | Final 8 | `inactive` | | Final 9 | `failed` | | Qualquer outro final | `active` | A cada mudança de status (na criação e na troca manual) o webhook correspondente `seller.` é enviado ao cliente. ### Alterar o status de um recebedor no sandbox Também é possível alterar manualmente o status de um recebedor em sandbox por meio de um endpoint dedicado, recebendo o webhook correspondente à mudança. > [!NOTE] > > Este endpoint está disponível apenas no ambiente de sandbox. `POST /v1/sellers/{id}/status` Cabeçalho: `X-Client-Id` Corpo: ```json theme={null} { "status": "inactive" } ``` Valores aceitos para `status`: `pending`, `active`, `inactive`, `failed`. Após a alteração, o recebedor tem seu status recalculado e o webhook `seller.` é disparado. # Relatório de Parcelas (agenda de recebíveis por parcela) Source: https://docs.malga.io/relatorio-de-parcelas-agenda-de-recebiveis-por-parcela Exporte o relatório de Parcelas do Dashboard com a agenda de recebíveis das cobranças processadas pelo provedor Malga, parcela a parcela e por recebedor. > [!NOTE] > > Estes relatórios cobrem apenas as transações processadas pelo **provedor Malga**. Cobranças feitas por outros provedores conectados à plataforma (como Cielo, Rede, Adyen, entre outros) não aparecem aqui. O relatório de **Parcelas** contempla a agenda de recebíveis, parcela a parcela. É o relatório usado para projetar o que ainda está por receber e conferir como cada parcela de uma cobrança foi dividida entre os recebedores. Na estrutura deste relatório, **cada linha é uma parcela de uma cobrança, por recebedor**. Uma cobrança em 6 vezes dividida entre dois recebedores gera 12 linhas. Com isso é possível analisar: * Agenda de recebíveis por data estimada de repasse * Divisão de cada parcela entre os recebedores * Taxa aplicada parcela a parcela, em valor e em percentual * Recebíveis por bandeira Caso precise do que já foi efetivamente repassado, utilize o [**relatório de Repasses**](/relatorio-de-repasses-detalhe-por-transacao-do-lote) ou o [**Resumo de repasses**](/resumo-de-repasses-consolidado-por-lote). > [!NOTE] > > O relatório de Parcelas traz a **projeção** dos recebíveis, e **não inclui parcelas bloqueadas**. Os valores a receber e as previsões de recebimento são estimativas e podem mudar em função de novas vendas, negociações ou estornos. Uma parcela só vira repasse quando entra em um lote. A partir daí ela passa a aparecer nos relatórios de Repasses e Resumo de repasses. ## Como os valores se relacionam Em cada linha, a taxa carrega o próprio sinal e a conta é uma soma simples: ```text theme={null} Valor bruto da parcela + Valor de taxa = Valor líquido da parcela ``` O `Valor bruto da parcela` é a fatia do recebedor naquela parcela, e não o valor cheio da parcela. Para chegar ao valor da parcela inteira, some as linhas de todos os recebedores daquela parcela. O `Valor total da cobrança` traz o valor cheio da cobrança, antes de qualquer divisão. O `Taxa %` é o percentual que o `Valor de taxa` representa sobre o `Valor bruto da parcela` daquela linha. ## Estornos Um estorno aparece como uma linha com `Operação` igual a **Estorno**, com o `Valor bruto da parcela` negativo e a taxa devolvida com sinal positivo. O `Status final da cobrança` dessa cobrança passa a ser **Estornada**. Nas linhas de estorno, o `Número da parcela` vem preenchido com um traço. **Confira abaixo os campos disponíveis no relatório de Parcelas:** | **Dados** | **Campo (pt-br)** | **Descrição** | | - | - | - | | **Cobrança** | Data da criação | Data e hora em que a cobrança foi criada | | | ID da cobrança | Identificador da cobrança na Malga | | | Operação | Autorização ou Estorno | | | Status final da cobrança | Autorizada ou Estornada | | **Split** | ID da subconta | Identificador da subconta | | | Nome da subconta | Nome da subconta | | | ID do recebedor | Identificador do recebedor | | | Recebedor | Nome do recebedor | | **Cliente** | Nome do cliente | Nome do cliente final | | **Pagamento** | Método de pagamento | Método usado na cobrança | | | Bandeira | Bandeira do cartão | | | Número da parcela | Parcela a que a linha se refere, no formato 1/6 | | **Valores** | Valor total da cobrança | Valor cheio da cobrança, antes da divisão entre recebedores | | | Valor bruto da parcela | Fatia do recebedor nesta parcela, antes da taxa | | | Valor de taxa | Taxa descontada desta linha | | | Taxa % | Percentual que a taxa representa sobre o valor bruto da linha | | | Valor líquido da parcela | Valor bruto da parcela mais o valor de taxa | | **Datas** | Data estimada do repasse | Data prevista para o repasse da parcela | > [!NOTE] > > Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)). # Relatório de Repasses (detalhe por transação do lote) Source: https://docs.malga.io/relatorio-de-repasses-detalhe-por-transacao-do-lote Exporte o relatório de Repasses do Dashboard com o detalhe transação a transação de cada lote processado pelo provedor Malga, incluindo valor bruto, MDR, taxa de antecipação e valor líquido por recebedor. > [!NOTE] > > Estes relatórios cobrem apenas as transações processadas pelo **provedor Malga**. Cobranças feitas por outros provedores conectados à plataforma (como Cielo, Rede, Adyen, entre outros) não aparecem aqui. O relatório de **Repasses** contempla o detalhe das transações que compõem cada lote de repasse. É o relatório usado para auditar a composição de um repasse e conferir, linha a linha, quanto cada recebedor recebeu de cada venda. Na estrutura deste relatório, **cada linha é uma transação de um recebedor dentro de um lote**. Uma mesma cobrança dividida entre três recebedores gera três linhas, e uma cobrança parcelada gera uma linha por parcela. Com isso é possível analisar: * Composição completa de um lote de repasse * Valor bruto, taxas e valor líquido por recebedor * Estornos e chargebacks e o impacto deles no repasse * Regra de split aplicada em cada transação * Datas estimada e realizada de liquidação Caso precise da visão consolidada por lote, com o saldo final repassado a cada recebedor, utilize o [**Resumo de repasses**](/resumo-de-repasses-consolidado-por-lote). > [!NOTE] > > O período de exportação é **pela data estimada de liquidação do lote**, e não pela data de criação da cobrança. Uma venda feita em setembro que liquida em outubro aparece no relatório de outubro. ## Como o lote é formado Um lote agrupa as transações de um mesmo **recebedor**, de um mesmo **arranjo de pagamento** (bandeira), com a mesma **data estimada de liquidação**. Por isso um recebedor pode ter vários lotes no mesmo dia, um por bandeira. ## Como os valores se relacionam Em cada linha, as taxas carregam o próprio sinal e a conta é uma soma simples: ```text theme={null} Valor bruto + Total de taxas descontadas = Valor líquido ``` O `Total de taxas descontadas` é a soma do `MDR` com a `Taxa de antecipação sob demanda`. Em um estorno, o `Valor bruto` vem negativo e as taxas são devolvidas, aparecendo com sinal positivo. Em um chargeback, o valor é debitado integralmente e as taxas não são devolvidas. Somando o `Valor líquido` de todas as linhas de um mesmo lote, você chega ao valor que o [Resumo de repasses](/resumo-de-repasses-consolidado-por-lote) traz como `Saldo total` menos `Saldo devedor` daquele lote. > [!WARNING] > > As tarifas de 3DS e antifraude **não aparecem neste relatório**. Elas são consolidadas e debitadas uma vez ao final do mês. O valor consolidado aparece na coluna `Tarifas` do Resumo de repasses, e o detalhe por cobrança aparece no relatório de Cobranças. **Confira abaixo os campos disponíveis no relatório de Repasses:** | **Dados** | **Campo (pt-br)** | **Descrição** | | - | - | - | | **Operação** | Data da cobrança | Data em que a cobrança original foi criada | | | Data da operação | Data em que a operação desta linha aconteceu | | | Tipo de operação | Venda, Estorno parcial, Estorno total, Chargeback | | | ID do lote | Identificador do lote de repasse ao qual a linha pertence | | | ID da transação | Identificador da transação na Malga | | | ID do pedido | Identificador do pedido enviado na cobrança | | **Split** | Subconta | Identificador da subconta | | | ID da regra do split | Identificador do registro de split que originou a linha | | | ID do recebedor | Identificador do recebedor, igual ao do Resumo de repasses | | | Recebedor | Nome do recebedor | | | Responsável pelo chargeback | Indica se este recebedor responde pelo chargeback da transação | | | Regra de split | Percentual aplicado a este recebedor na transação | | **Valores** | Valor da cobrança | Valor total da cobrança, antes da divisão entre recebedores | | | Valor bruto | Parcela do valor da cobrança que cabe a este recebedor | | | MDR | Taxa de intermediação descontada da transação | | | Taxa de antecipação sob demanda | Taxa cobrada quando há antecipação do recebível | | | Total de taxas descontadas | Soma de MDR e taxa de antecipação | | | Valor líquido | Valor bruto mais o total de taxas descontadas | | | Moeda | Moeda da transação | | **Pagamento** | Número da parcela | Parcela da cobrança a que a linha se refere, no formato 1/6 | | | Método de pagamento | Método usado na cobrança | | **Liquidação** | Conta de liquidação | Conta de onde o valor é liquidado | | | Conta destinatária | Conta que recebe o valor | | | Data estimada de liquidação | Data prevista para a liquidação do lote | | | Data de liquidação | Data em que a liquidação ocorreu | | | Status do repasse | Pago, Em andamento, Falha ou Compensado | ## Status do repasse
Status O que significa
**Pago** O lote foi liquidado e o valor foi creditado na conta destinatária
**Em andamento** O lote ainda não chegou à data de liquidação
**Falha** A liquidação foi tentada e não se concluiu
**Compensado** O lote fechou com saldo zero ou negativo e não gerou crédito. O valor foi usado para abater um saldo devedor anterior. O detalhe aparece no Resumo de repasses, nas colunas `Saldo devedor` e `Saldo total`
> [!NOTE] > > Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)). # Feb 21 - Parcelas pela Drip Source: https://docs.malga.io/release-notes/2024-02-21-Release-Notes Adição do campo de quantidade de parcelas máximas (opcional) para determinada transação realizada pela DRIP ![Letícia Plácido](https://github.com/letypbarbosa.png) [Letícia Plácido](https://github.com/letypbarbosa) Software EngineerÉ possível informar a quantidade máxima de parcelas de forma opcional para as transações realizadas através da **DRIP**, por meio do novo campo: "maxInstallments", [conforme descrito na documentação](https://docs.dev.malga.io/api-reference/charges/realizar-nova-cobranca) Siga acompanhando as novidades da Malga 🤓🎉 # Feb 28 - Safrapay Source: https://docs.malga.io/release-notes/2024-02-28-Release-Notes Adição de Safrapay ![Lais Petra](https://github.com/laispetra-malga.png) [Lais Petra](https://github.com/laispetra-malga) Software Engineer A partir de agora, é possível transacionar com **cartão de crédito** e **pix** junto ao provedor **Safrapay**. Siga acompanhando as novidades Malga 🤓🎉 # Mar 05 - Reversão de estorno Source: https://docs.malga.io/release-notes/2024-03-05-Release-Notes Reversão de uma operação de estorno bem-sucedido ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer **Tratar eventos de reversão de um estorno que foi bem-sucedido** Adicionamos um novo tipo de evento que pode ocorrer em transações que tiveram uma solicitação de estorno bem-sucedido: a reversão do estorno. Embora seja pouco comum, alguns provedores têm a capacidade de reverter uma transação de estorno bem-sucedida, como é o caso do provedor ADYEN. Conforme indicado pela ADYEN, tais ocorrências não são frequentes, porém são possíveis. Portanto, é necessário que lidemos com essa eventualidade de forma adequada. Na plataforma Malga, esse evento é tratado como **revert\_void**. Se ocorrer uma operação desse tipo, você receberá um webhook com o evento **transaction.revert\_void**. Além disso, essa informação estará disponível nas transactionRequests com um novo requestType do tipo **revert\_void**. Para maiores informações sobre essa funcionalidade [acesse aqui](/documentations/payment-methods/credit-card#reversão-automática-de-um-estorno-revert_void) Siga acompanhando as novidades da Malga 🤓🎉 # Mar 06 - Cobrança por status Source: https://docs.malga.io/release-notes/2024-03-06-Release-Notes Novas visões no Painel de Dados 🔢 ![Filippe Rodrigues](https://github.com/filipperodrigues.png) [Filippe Rodrigues](https://github.com/filipperodrigues) Tech Lead Estamos felizes em apresentar as novas visões no [Painel de Dados](https://dashboard.malga.io/app/insights) no Dashboard Malga, confira! Adicionamos a visão de **Cobranças por status**, com a participação % de cada status de cobrança, pelo maior volume de transações, no período selecionado para exibição no Painel. Passando o mouse em cada status, são exibidas as informações detalhadas de **volume**, **quantidade de cobranças** e **total financeiro** daquele status; ![Imagem do Painel de Dados](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-06/1.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=77b8296ddb1ccfdd573f3212ac970c6f) > [!NOTE] > > Status das Cobranças Os status exibidos no gráfico de **Cobranças por Status** > correspondem à soma das cobranças realizadas nos métodos de pagamento da loja. > No gráfico seguinte de **Principais métodos de pagamento**, é exibido o > detalhamento de cobranças autorizadas por método de pagamento. Saiba mais > sobre os [status das > cobranças](/api-reference/charges/recuperar-detalhes-de-cobranca) > na Malga em nossa documentação; ### Novidades nas Cobranças do Dashboard 🤘 Realizamos ajustes nas **nomenclaturas da listagem e detalhes de Cobranças** em nosso Dashboard: > [!TIP] > > Data de criação (refere-se ao `created_at` da cobrança); > [!TIP] > > ID da cobrança (charge ID); > [!TIP] > > Valor original; > [!TIP] > > Valor atual. ![Imagem da Listagem de Cobranças](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-06/2.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=0773f35ec94c630d4c0144c2fac6eb84) ![Imagem da Detalhe de Cobrança](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-06/3.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=fe102e11179e2d288c64ba7f7bd73760) > [!TIP] > > MELHORIAS > > > [!TIP] > > > > > > > > **Adição das parcelas Nupay** no relatório .csv de exportação de cobranças, > > agora retornando o número de parcelas (installments) das cobranças do método > > Nupay; > > > [!TIP] > > > > > > > > Correção na exibição das **informações da Transaction Request** no Histórico > > de Operações dentro do detalhe da cobrança; > > > [!TIP] > > > > > > > > Correção em **traduções** para eng-us, carregamento de ilustrações e > > melhoria de performance. Siga acompanhando as melhorias e novidades da Malga! Até mais 🤓 # Mar 11 - Pesquisa por NSU Source: https://docs.malga.io/release-notes/2024-03-11-Release-Notes Grandes novidades no Dashboard 🤩 ![Filippe Rodrigues](https://github.com/filipperodrigues.png) [Filippe Rodrigues](https://github.com/filipperodrigues) Tech Lead Adicionamos novos recursos ao [Dashboard Malga](https://dashboard.malga.io/app), evoluindo a experiência de gestão financeira através da nossa plataforma. Confira as mudanças: > [!TIP] > > Pesquisa de cobranças por NSU; > [!TIP] > > Informações de cobranças recusadas no Painel de Dados; > [!TIP] > > > > Exibição de reversão de estorno no Histórico de Operações da cobrança. ### Pesquisa de cobranças por NSU Agora é possível **buscar Cobranças pelo NSU** (número sequencial único), ID do pedido e ID da cobrança, em uma nova experiência no menu lateral. Cada cobrança possui um NSU referente à autorização no provedor **(authorizationNsu)** retornado para a Malga. Para utilizar a pesquisa, basta selecionar o **ícone de pesquisa na Listagem de Cobranças,** selecionando "NSU" em Buscar por e inserindo NSU no campo de busca. A cobrança, se encontrada, será exibida na listagem com a busca aplicada, refletindo o NSU pesquisado, conforme as imagens: ![Imagem da Busca por cobranças](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/1.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=36824bcede8651cbe9b6e73e8d7e737f) *** ![Imagem da Busca pelo NSU aplicada](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/2.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=d771c96ca8a710911cd49f492fae84ab) *** ![Imagem da Listagem de Cobranças com opções de Busca, Filtros e Exportação](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/3.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=5d5a227d03bc09c75b55d776c5066ee0) > [!NOTE] > > Presença do NSU nas cobranças Cada cobrança possui um NSU para identificação > da transação realizada no provedor. O NSU não está presente em > cobranças dos métodos Drip, Nupay e Pix, podendo ser buscadas pelo ID do > pedido (se enviado) ou ID da cobrança na Malga. ### Cobranças recusadas no Painel de dados Ajustamos a visão geral de Cobranças no [Painel](https://dashboard.malga.io/app/insights), passando a exibir as **Cobranças Recusadas**, correspondentes ao status falha (failed), com o volume de cobranças e total financeiro de acordo com o período e moeda selecionados. No gráfico de **Principais motivos de recusa**, é possível conferir os principais motivos de recusa das cobranças falhadas (`declinedCode`), conforme as imagens: ![Imagem das Cobranças recusadas no Painel de Dados](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/4.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=5e252b23b00133d5800661cd0a014ed3) ### Exibição da requisição de Reversão de Estorno Adicionamos o evento de **Reversão do estorno** (`revert_void`) no Histórico de Operações, no detalhe das cobranças, com os detalhes de uma requisição de estorno revertida pelo provedor. No detalhe do Histórico, é possível conferir o provedor responsável pela atualização e os valores da cobrança alterada: > [!TIP] > > **Valor atual da cobrança** (no momento da requisição); > [!TIP] > > **Valor revertido;** > [!TIP] > > **Valor da cobrança após a reversão do estorno pelo provedor.** > [!NOTE] > > REVERSÃO DO ESTORNO Quando este cenário acontece, é necessário realizar um > **novo estorno parcial ou total na cobrança**, utilizando o botão de > **Estornar**, habilitado no detalhe da cobrança que sofreu reversão do estorno > anterior; ![Imagem do Detalhe de uma Cobrança com reversão de estorno](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/5.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=59b2b33310a1f691cde70d2770acdacc) *** ![Imagem do Histórico de Operações com reversão de estorno](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-03-11/6.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=9e6e950a3b5bfdbf408f75123945d5ba) Para mais informações sobre a **requisição de reversão de estorno**, confira o [release](https://docs.malga.io/blog/release-2024-03-05) e a [documentação](/documentations/payment-methods/credit-card#reversão-automática-de-um-estorno-revert_void); > [!TIP] > > MELHORIAS NO DASHBOARD > \[!TIP] Implementação de **nova tela de erro** por motivo inesperado; > \[!TIP] Reorganização dos menus para **busca e filtro de cobranças**; Em breve, mais novidades em nossa plataforma! 🙌 # Apr 02 - Filtro por provedor Source: https://docs.malga.io/release-notes/2024-04-02-Release-Notes Nova forma de encontrar cobranças pelo Dashboard Malga 🙌 ![Thiago Correa](https://github.com/thiagocorreadev.png) [Thiago Correa](https://github.com/thiagocorreadev) Software Engineer ### Filtro por provedor Implementamos o **filtro por provedor** no menu de Cobranças do Dashboard, facilitando a experiência de encontrar os pagamentos realizados na sua loja. O filtro está disponível no menu lateral e pode ser combinado com outros filtros por período, status e método de pagamento, refletindo as cobranças processadas pelo provedor no período selecionado. O filtro corresponde ao provedor responsável pelo processamento final da transação (equivalente ao último status da cobrança), também exibido na listagem: ![Imagem do Filtro de cobranças na Dashboard](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-04-02/1.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=a67110a1c3737776cf8747d4c69ce017) ![Imagem da Listagem de Cobranças na Dashboard](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-04-02/2.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=47ce8d2259fa8488c4434b573ec68ccd) O filtro exibe a listagem dos **provedores cadastrados na conta do cliente Malga**, em ordem alfabética, conforme a imagem: ![Imagem da Filtro de cobranças na Dashboard com Provedor Selecionado](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-04-02/3.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=0ea9f962227f768fdba89d6909174919) > [!TIP] > > MELHORIAS NO DASHBOARD > > > [!TIP] > > > > Retiramos a validação de formato na criação de conta do Dashboard, agora > > permitindo o uso de caracteres especiais e números; Em breve, mais novidades em nossa plataforma! Siga acompanhando por aqui e através dos canais da Malga 😍 # Apr 18 - Export relatórios Source: https://docs.malga.io/release-notes/2024-04-18-Release-Notes Export V2 🚀 ![Thiago Correa](https://github.com/thiagocorreadev.png) [Thiago Correa](https://github.com/thiagocorreadev) Software Engineer **Novo!** Relatório completo no Dashboard, nova opção para exportação de cobranças em formato .csv! Liberamos o **novo relatório completo de cobranças**, disponível através do [Dashboard](https://dashboard.malga.io/). Agora, os clientes Malga possuem duas opções de relatório, de acordo com as suas necessidades de análise: > [!TIP] > > **Relatório simples** Recomendado para análises e consolidação das informações > pelo **último status da cobrança**. Confira os dados desse relatório através > do link 🔗 > [!TIP] > > **Relatório completo** Recomendado para analisar cobranças pelo histórico > completo de operações da cobrança e os detalhes de cada etapa do > processamento. Confira os dados desse relatório através do link 🔗 **Confira a documentação detalhada [Link para o guia de uso novo](/documentations/dashboard/export-data) e o passo a passo para exportação dos relatórios no Dashboard:** ![Export v2](https://malga-docs-prod.s3.amazonaws.com/images/release-notes/export-v2.gif) > [!NOTE] > > Informações dos tipos de relatórios disponíveis > > O período de exportação corresponde à data de **criação das cobranças**; > > As informações exportadas correspondem às **cobranças realizadas até o dia anterior (D-1)**, de acordo com o período selecionado; > > É possível exportar cobranças realizadas no ambiente de produção e em sandbox, com um período de até **31 dias anteriores à data selecionada**. Caso seja necessário um período de análise maior, entre em contato com o suporte da Malga. > > Os relatórios são **enviados por e-mail** para a conta cadastrada no Dashboard Malga, garantindo a segurança das informações. Em casos de relatórios grandes, o envio pode levar mais tempo. > > Para mais informações, consulte a documentação: [Exportando dados](/documentations/dashboard/export-data) > [!TIP] > > Melhorias no Dashboard > > > [!TIP] > > > > Adição da informação de NSU no detalhe da cobrança, junto às informações > > básicas da transação; > > > [!TIP] > > > > Novos ícones indicando se a transação possui split e recorrência no detalhe da > > cobrança; Caso enfrente alguma dificuldade ou ainda não possua acesso ao Dashboard para as informações da sua empresa, avise o nosso time através do e-mail [suporte@malga.io](mailto:suporte@malga.io). Até mais! 🤓 # May 09 - Filtro de disputa Source: https://docs.malga.io/release-notes/2024-05-09-Release-Notes ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ### Mais informações nas cobranças do Dashboard 🔢 Implementamos melhorias na **visualização de cobranças** no [Dashboard](https://dashboard.malga.io/app/insights), incluindo o **novo filtro de cobranças em disputa**, informações na listagem, detalhe dos pagamentos e opções de bandeira nos [Fluxos Inteligentes](https://dashboard.malga.io/app/smart-flows). > [!TIP] > > **CONFIRA AS NOVIDADES** > > * **Cobranças em disputa**: Novo **filtro de cobranças em disputa** (flag > is\_dispute: true), refletindo os pagamentos que sofreram abertura de disputa; > * **Transações recorrentes**: Novo campo **"Recorrência"** nos **detalhes da > cobrança** contendo a informação de que a transação correspondente a qual > momento da recorrência: **initial**, **subsequent** ou **unscheduled**, > traduzidas respectivamente para: - Primeira transação recorrente - Transação > recorrente consecutiva - Cobrança avulsa; > * **Split e Recorrência**: Novas etiquetas no detalhe da cobrança indicando a > presença de split ou recorrência, junto ao Histórico de Operações da Cobrança; > * **Eventos de Disputa e Reversão de estorno em destaque** - Marcação nos > eventos do Histórico de Operações da cobrança indicando a presença de uma > notificação de **disputa aberta** e **estorno revertido** (ocorrência para o > provedor Adyen); > * **Novas bandeiras nos condicionais dos Fluxos Inteligentes**: Agora é > possível utilizar as bandeiras **Hipercard** e **Hiper** como condicionais no > fluxo, adicionando mais possibilidades de customização no processamento das > cobranças; > [!WARNING] > > **TRANSAÇÕES RECORRENTES PARA CARTÕES DE CRÉDITO** > > A flag de “Recorrência” nas transações é enviada nas cobranças do **método de pagamento de crédito**. Assim, se uma cobrança tiver o [paymentType](https://docs.malga.io/api#tag/Charges) igual a **card** e **existir recorrência**, a informação do tipo de recorrência será exibida nos detalhes dessa cobrança. Confira a [documentação](/documentations/dashboard/charge-details) detalhada da API Charges e abaixo apresentamos as melhorias implementadas: #### Filtro de Cobranças em Disputa no menu lateral da listagem de Cobranças ![Filtro de disputa](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-05-09/1.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=11b54b137faf22a9cb2c256db4dbb7e3) > [!NOTE] > > **NOTIFICAÇÃO DE ABERTURA DE DISPUTA** > > A informação se uma cobrança sofreu **abertura de processo de disputa** é recebida através da notificação do provedor para a Malga, indicada pela flag "em disputa" (is\_dispute true). > > **Confira os provedores que enviam esta informação em nossa [documentação](/documentations/dashboard/charge-details)** #### Informações de **Recorrência** e **Split** nos detalhes da cobrança ![Recorrência e split](https://mintcdn.com/malga/_aM0jdYPBvMaBBdu/assets/images/release/2024-05-09/2.png?fit=max\&auto=format\&n=_aM0jdYPBvMaBBdu\&q=85\&s=4f2abc9eae37b52cb63532bdb59fa84f) #### Eventos de **disputa** e **reversão de estorno** sinalizados nos detalhes de uma cobrança ![Disputa e reversão de estorno](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-05-09/3.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=f329d91eb09e2a2e02b6f5218d3eef97) > [!NOTE] > > **EVENTOS DE DISPUTA E REVERSÃO DE ESTORNO** > > Adicionamos o marcador em destaque para indicar transações com **disputa aberta** e transações com **reversão de estorno** (quando este for o último evento do histórico). Em ambos cenários, o cliente deve tratar as cobranças a partir de cada cenário, realizando um estorno ou tratativa da disputa no provedor responsável; #### Parâmetros de bandeira Hiper e HiperCard como condicionais nos Fluxos Inteligentes ![Hiper e HiperCard](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-05-09/4.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=daf0ac20a2b4567103c5e6f63662c943) > [!NOTE] > > **CONDICIONAIS DO FLUXO INTELIGENTE** > > Saiba mais sobre as regras e opções de parâmetros condicionais para o processamento das transações em nossa [documentação](/documentations/flow-guide/conditional). Caso enfrente alguma dificuldade ou ainda não possua acesso às informações da sua empresa no Dashboard, avise o nosso time através do e-mail [suporte@malga.io](mailto:suporte@malga.io). Até mais! 🤓 # May 23 - Correções Dash Source: https://docs.malga.io/release-notes/2024-05-23-Release-Notes ![Thiago Correa](https://github.com/thiagocorreadev.png) [Thiago Correa](https://github.com/thiagocorreadev) Software Engineer ### **Ajustes e Correções no Dashboard 💻** Implementamos ajustes na experiência do Dashboard Malga, confira as mudanças: **Gráfico de taxa de aprovação diária no Painel de Dados** Alteramos a exibição das informações do gráfico de taxa de aprovação diária no Painel de Dados, agora exibindo o detalhe das cobranças ao passar o mouse nos pontos do gráfico. Em cada ponto, é possível conferir a taxa de aprovação e a quantidade total de transações autorizadas e recusadas do dia. ![Gráfico de taxa de aprovação diária no Painel de Dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-05-23/1.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=a602b54aa4bf406951cd99e08af2c759) > [!TIP] > > CORREÇÕES NO DASHBOARD > > * Ajuste nos ícones das bandeiras Diners e Maestro no menu de Cartões; > > * Correção nos campos do [relatório completo](https://docs.malga.io/documentations/dashboard/full-report) da Exportação de cobranças, para correta exibição dos dados de `metadata` e `payment_flow_id`; Siga acompanhando as novidades! Até mais 🚀 # May 28 - Tokens de Bandeira Source: https://docs.malga.io/release-notes/2024-05-28-Release-Notes ![Fábio Cereto](https://github.com/cereto.png) [Fábio Cereto](https://github.com/cereto) Product Manager ### **Tokens de Bandeira (Network tokens)** Adicionamos a possibilidade de tokenizar cartões diretamente nas bandeiras diretamente através da integração com a Malga. A **Tokenização de Bandeira** é um sistema de segurança que substitui os dados sensíveis de um cartão de crédito por um **token criptografado** registrado diretamente na bandeira do cartão. Cada transação feita após a tokenização do cartão passará a utilizar o token, dispensando o uso dos dados do cartão como nome do portador do cartão, data de validade, CVV, entre outros. Além de trazer uma maior conversão das transações, também ajuda a prevenir perdas pois é um processo mais seguro para captura. ![Token de Bandeira](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-05-24/networktoken.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=a109f7060d82c4c2b5f133109741d360) > [!TIP] > > **CONFIRA AS NOVIDADES** > > * Quando uma cobrança em cartão de crédito é feita, tokenizamos o cartão na bandeira e armazenamos o token no sistema da Malga para ser utilizado em transações futuras. > > * A cada nova transação, é criado e utilizado um novo criptograma, garantindo a segurança de cada transação. > > * Caso exista atualização do cartão na bandeira, fazemos automaticamente a atualização do token na Malga (LCM). > [!WARNING] > > **SUPORTE A PROVEDORES** > > Nem todos os Provedores suportam transacionar utilizando Tokens de Bandeira, consulte [nossa documentação](/documentations/tokenization/network-tokens) para mais informações! Siga acompanhando as novidades! Até a próxima 🚀 # May 28 - Barte Source: https://docs.malga.io/release-notes/2024-05-28-Release-Notes-2 Adição da Barte como novo provedor de crédito ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer **Novo Provedor de Crédito na Malga!💳🎉** Estamos animados em anunciar a integração com um novo provedor de pagamento, a **Barte**! Esta novidade traz alguns benefícios para nossos usuários: * **Parcelamento em até 21 vezes**: Ofereça maior flexibilidade de pagamento, permitindo parcelamentos em até 21 vezes. > [!TIP] > > SAIBA MAIS > > 1. Barte agora disponível como provedor de pagamento na Malga. > 2. Facilite as transações com condições de parcelamento vantajosas. Continue acompanhando as novidades da Malga 🤓🎉 # Jun 24 - Exportação de Cobranças Source: https://docs.malga.io/release-notes/2024-06-24-Release-Notes Novos campos de Tokenização de Bandeira ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer ### **Exportação de Cobranças** **Novos dados na exportação de cobranças em .csv do Dashboard 🚀** Adicionamos novos campos para que seja possível identificar transações criadas com **Tokenização de Bandeira**. Confira: | **Campo no relatório pt-br** | **Campo no relatório eng-us** | | - | - | | Transação utilizando token de bandeira | Transaction using network token | | Cartão tokenizado na bandeira em | Tokenized card in network on | #### Relatórios atualizados > [!TIP] > > Simples > [!TIP] > > Completo Siga acompanhando as novidades! Até a próxima 🚀 # June 28 - Estorno Parcial de Split Source: https://docs.malga.io/release-notes/2024-06-28-Release-Notes Adição do parâmetro splitRules no estorno para possibilitar o estorno parcial de split ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer **Nova Capacidade de Estorno Parcial de Split na Malga!🔄✨** Adicionamos uma nova capacidade ao Split da Malga! Agora é possível escolher como estornos são divididos entre os recebedores da transação utilizando o parâmetro **splitRules** no corpo da request de estorno. Esta novidade traz alguns benefícios para nossos usuários: * **Flexibilidade de Gestão**: Permite maior controle sobre como os estornos de transações split. * **Compatibilidade**: Funciona com os provedores **Pagarme**, **Zoop**, e **Braspag**. > [!TIP] > > IMPORTANTE > Ainda não é possível fazer estornos parciais com splitRules através do Dashboard, mas em breve estará disponível. Continue acompanhando as novidades da Malga 🤓🎉 # July 03 - Facilitadores de pagamentos Source: https://docs.malga.io/release-notes/2024-07-03-Release-Notes ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **Novo serviço de Vendors!✨** \ Estamos felizes em anunciar que adicionamos um novo serviço para clientes Malga que atuam como facilitadores de pagamento! Este serviço permite identificar os beneficiários finais de suas transações, e deve ser utilizado por marketplaces, franquias, aplicativos de delivery, entre outros tipos de negócios que possuem exigência regulatória prevista na Circular do BACEN N° 3978. Para mais informações [**clique aqui**](/documentations/vendors/intro) #### Provedores suportados > [!TIP] > > Adyen > [!TIP] > > Cielo > [!TIP] > > Getnet > [!TIP] > > Rede > [!TIP] > > SANDBOX Siga acompanhando as novidades! Até a próxima 🚀 # July 05 - Busca de cobranças Source: https://docs.malga.io/release-notes/2024-07-05-Release-Notes ![Camila Leal](https://media.licdn.com/dms/image/v2/C4D03AQH3zPy7mpg0aw/profile-displayphoto-shrink_800_800/profile-displayphoto-shrink_800_800/0/1594648616933?e=1730332800\&v=beta\&t=sOAezAY_ZqD3FMBJxmXdkyHHyhEdqytrgz3INn_gquc) [Camila Leal](https://www.linkedin.com/in/camiladleal/) Product Manager ### **Novidades na busca de cobranças do Dashboard 🔎** É com muita alegria que anunciamos a **nova experiência de busca de cobranças**, agora diretamente pela listagem do [Dashboard](https://dashboard.malga.io/app), confira: ![Gif de Buscas](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-07-05/search.gif?s=b56e7774f17b2207635023e4ffd99604) > [!TIP] > > NOVAS BUSCAS > > * Documento do cliente > * E-mail do cliente > * Número de cartão (4 últimos dígitos) #### Passo a passo para buscar cobranças 1. Selecione a chave que deseja utilizar para encontrar a cobrança, entre as opções disponíveis; 2. Insira a informação pela qual deseja buscar no campo de "Buscar cobranças" e pressione Enter ou clique no botão de pesquisar (ícone da lupa); 3. A listagem de cobranças retornará os resultados para a chave pesquisada; 4. Clique na cobrança desejada para acessar os detalhes da transação e mais informações sobre o processamento nos provedores, dados do cliente, cartão, entre outros; #### Chaves disponíveis para busca de cobranças: | **Chave de pesquisa** | **Onde encontrar** | **Forma de busca** | **Disponibilidade** | **Resultado** | | - | - | - | - | - | | Email do cliente (customer email) | Malga, provedor e sistema próprio | [exemplo@exemplo.com](mailto:exemplo@exemplo.com) | Todas as cobranças / [Customers API](https://docs.malga.io/api-reference/customers/cria%C3%A7%C3%A3o-de-novo-customer-para-cobran%C3%A7a) | 1h após a ocorrência da transação | | Documento do cliente (customer document) | Malga, provedor e sistema próprio | Pode variar entre texto e números | Todas as cobranças / [Customers API](https://docs.malga.io/api-reference/customers/cria%C3%A7%C3%A3o-de-novo-customer-para-cobran%C3%A7a) | 1h após a ocorrência da transação | | Número de cartão | Malga e provedor | 4 últimos dígitos | Todas as cobranças crédito/voucher | 1h após a ocorrência da transação | | NSU (authorization NSU) | Malga, provedor e sistema próprio | Pode variar entre texto e números | Cartão, voucher e boleto (gerada pelo provedor) | Tempo real | | ID do pedido (order ID) | Malga e sistema próprio | Pode variar entre número, texto ou caracteres | Chave opcional enviada pelo cliente para a Malga para identificação do pedido | Tempo real | | ID da cobrança (charge ID) | Malga e sistema próprio | Combinação de texto, número e caracteres | Chave gerada pela Malga para identificação da cobrança, que pode ser salva no sistema do cliente | Tempo real | > [!NOTE] > > ESCOLHA DA CHAVE DE BUSCA\ > A chave selecionada ficará registrada para futuras > consultas, e pode ser alterada sempre que necessário, realizando uma nova > seleção dentre as opções disponíveis; Em breve, mais novidades na gestão de cobranças pelo Dashboard, e contamos com seus feedbacks para seguir evoluindo a sua experiência Malga. Até mais! 🤝 # Aug 19 - PicPay Source: https://docs.malga.io/release-notes/2024-08-19-Release-Notes Novo método PicPay ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **Agora contamos com a PicPay como provedor e método de pagamento na Malga!🎉** Estamos animados em anunciar a nova integração com o **PicPay**! Agora os clientes Malga podem utilizar o PicPay como provedor de crédito 💳, ou [utilizar a wallet do PicPay como método de pagamento](/documentations/payment-methods/picpay). Continue acompanhando as novidades da Malga 🤓🎉 # Aug 29 - Dashboard Source: https://docs.malga.io/release-notes/2024-08-29-Release-Notes Melhorias de UX no Dashboard e novas documentações ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer Liberamos novidades para tornar a sua experiência com a Malga ainda mais fácil! 🤝 ## Novo filtro de período Implementamos um novo calendário para filtrar períodos no Painel de Dados e nos menus de Cobranças, Links e Exportação de Relatórios, com uma interface intuitiva e simples de utilizar: ![Filtro na exportação de dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-08-29/1.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=1cb681cf1c53792f445ae69683ebcaa9) ## Busca nas listagens de Clientes, Subcontas, Recebedores e Links de pagamento Agora é possível pesquisar informações diretamente pela listagem, inserindo os IDs para localizar clientes, subcontas, recebedores ou links de pagamentos, nos respectivos menus. Confira no [Dashboard](https://dashboard.malga.io/) 🔗; ## Novas documentações Atualizamos documentações e adicionamos o menu de [Conexões](https://docs.malga.io/documentations/type-tables/payment-methods-by-providers), com detalhes sobre os recursos de cada provedor disponível na Malga: ![Filtro na exportação de dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-08-29/2.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=334d73a25303c527d059ddc88f613437) > [!TIP] > > Melhorias > > * Atualização da documentação Sobre as APIs, com a especificação da > OpenAPI; > * Mudanças na interface com reorganização dos menus e novos ícones e > cores; > * Páginas específicas por provedor de pagamento, detalhando os serviços > suportados em cada um deles e na Malga; # Sep 04 - PicPay Pix Source: https://docs.malga.io/release-notes/2024-09-04-Release-Notes Novo método de pagamento na PicPay ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **PicPay agora possui suporte a Pix na Malga!🎉** Estamos felizes em anunciar que adicionamos o [método de pagamento Pix](/documentations/payment-methods/pix) à integração com o **PicPay**! Continue acompanhando as novidades da Malga 🤓🎉 # Sep 10 - Usuários e permissões Source: https://docs.malga.io/release-notes/2024-09-10-Release-Notes Gestão de contas do Dashboard ![Dani](https://github.com/danielaschutt.png) [Dani](https://github.com/danielaschutt) Software Engineer ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer ### Permissões de Usuários no Dashboard Disponibilizamos **novos papéis com permissões** específicas para os usuários da sua empresa, aprimorando a segurança e controle da sua operação no Dashboard. Através dos papéis disponíveis de **Visualizador** e **Visualizador (cobranças)**, é possível restringir o acesso de usuários somente para visualização das informações, sem a possibilidade de realização de operações. Os dois perfis não podem realizar ações como estorno, captura e exportação de relatórios, possuindo permissão para visualização de detalhe de cobranças ou visualização integral da área de Vendas (cobranças, clientes, cartões, links de pagamento e recebedores); Ambos perfis **não possuem acesso** aos menus de Fluxos Inteligentes, Painel de Dados, Subcontas e Usuários, que são restritos ao perfil de Administrador; Através do menu [Usuários](https://dashboard.malga.io/app/accounts), disponível para o Administrador da conta na Malga, é possível atribuir os novos papéis aos usuários do seu time, e também excluir usuários, caso necessário. ### Como editar o perfil de um usuário no Dashboard ![Filtro na exportação de dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-09-10/1.gif?s=713eb224cbb80f917115afeaee4e76dc) 🔗 Confira os detalhes nesta [documentação](/documentations/dashboard/users), onde descrevemos as permissões específicas de cada perfil. Em breve, mais novidades por aqui! 🤝🚀 # Sep 19 - Barte Source: https://docs.malga.io/release-notes/2024-09-19-Release-Notes Pré-autorização e captura ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **Barte agora possui suporte à pré-autorização na Malga!🎉** Estamos felizes em anunciar que o provedor [Barte](/documentations/providers/barte) agora suporta [pré-autorização e captura!](/api-reference/charges/capturar-cobranca-pre-autorizada) > [!NOTE] > > Disponível apenas para o método de pagamento crédito. Continue acompanhando as novidades da Malga 🤓🎉 # Oct 07 - Novos filtros Source: https://docs.malga.io/release-notes/2024-10-07-Release-Notes Novos filtros de provedor e método de pagamento ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer Lançamos novos filtros no [Painel de Dados](https://dashboard.malga.io/app/insights), facilitando as análises sobre a performance dos provedores e métodos de pagamento da loja. Agora você pode filtrar os dados por: * **Provedor de pagamento** * **Método de pagamento** * **Subconta (merchant)** * **Moeda** * **Período** **Confira a nova experiência:** ![Painel de Dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-10-07/painel-filtros.gif?s=a0132b001335020677da6432771d86aa) > [!NOTE] > > Os filtros e resultados do Painel de Dados estão ordenados por maior volume de cobranças ao longo do histórico de pagamentos na Malga, e estão disponíveis no padrão d-1, retornando as cobranças criadas até o dia anterior; > [!TIP] > > MELHORIAS IMPLEMENTADAS > > * Atualização da [documentação](/documentations/dashboard/insights) sobre os dados do Painel > * Melhorias de UX no Dashboard Em breve, disponibilizaremos novas métricas e recursos na plataforma. Até o próximo release! 🤓 # Oct 21 - Bandeira de cartão | Painel Source: https://docs.malga.io/release-notes/2024-10-21-Release-Notes ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer É com muita alegria que anunciamos novidades no Painel de Dados 🔢✨ * Novo dado de vendas autorizadas por **bandeira de cartão**; * Filtro de período ampliado para **seleção de até 3 meses**; * Visão **diária, semanal e mensal da taxa de aprovação** e cobranças por período. ![Painel de Dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-10-21/1.gif?s=22a34ee3b601b6561422823e2868f24e) ## Dados de cobranças autorizadas por bandeira de cartão * **Volume de vendas por bandeira** → participação % da bandeira sobre o total de cobranças do período selecionado (métodos crédito, wallet e voucher); * **Autorização** → % de cobranças pré-autorizadas e autorizadas sobre o total de cobranças; * **Quantidade** → volume de cobranças realizadas na bandeira; * **Valor** → total financeiro processado na bandeira. ![Painel de Dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-10-21/2.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=07b44e2d95702cae9b55e1963e7b0d54) ## Visão detalhada da taxa de aprovação diária, semanal e mensal Agora é possível visualizar o gráfico de **taxa de aprovação diária, semanal e mensal**, com o detalhamento das cobranças autorizadas, recusadas e o total, facilitando a comparação dos resultados entre os períodos selecionados. ![Painel de Dados](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-10-21/3.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=08281f91bf0cc1b1dfb34ef627f74c18) > [!TIP] > > MELHORIAS IMPLEMENTADAS > > API Sessions > > * Implementação de regra de unicidade da idempotency key. > > Checkout > > * Adição de novas propriedades no objeto de itens e carrinho do fraudAnalysis; > * Correção da versão mobile do pagamento do tipo crédito; > > Gerais > > * Ajustes nas nomenclaturas do Painel de Dados; Siga acompanhando as novidades e até a próxima! 🤝 # Nov 11 - Query Cards | Analytics Source: https://docs.malga.io/release-notes/2024-11-11-Release-Notes ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer Disponibilizamos a query de **Cards** na [Analytics API](/analytics/intro), onde é possível consultar e extrair a base de cartões e tokens salvos através da Malga, aplicando filtros por card id, data de criação, status, bandeira, customer ID e holder name. Através da query, é possível analisar a **base de cartões e tokens** gerados nas cobranças, e informações como o volume de bandeiras, clientes vinculados aos cartões, entre outras análises. Confira em nossa [documentação](/analytics/queries/cards) todas as informações retornadas na query, com os detalhes do cartão, token e do cliente associado ao cartão, caso exista. > [!NOTE] > > É possível testar a [query Cards](/analytics/queries/cards) e a Analytics API > através do playground disponível neste [link](https://graphql.malga.io/), > utilizando suas credenciais de acesso à Malga. Até a próxima! 🚀 # Nov 14 - API Settings Source: https://docs.malga.io/release-notes/2024-11-14-Release-Notes Personalização do Link de Pagamento ![Dani](https://github.com/danielaschutt.png) [Dani](https://github.com/danielaschutt) Software Engineer ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer Disponibilizamos o serviço de [settings](/api-reference/settings) para facilitar a personalização do link de pagamento com as cores e configurações da sua empresa. Hoje através da funcionalidade do link de pagamento Malga, é possível direcionar o seu cliente final diretamente para o pagamento de um pedido, optando pelo método e realizando a cobrança. Saiba mais aqui sobre os recursos do [Link de Pagamento](/documentations/payment-link/intro), que pode ser configurado pelo Dashboard ou pela API [Sessions](/documentations/more/sessions), e aqui como funciona a experiência do checkout [personalizado](https://checkout-full.vanilla.malga.io/). Através do serviço, é possível atribuir cores, logo da sua empresa e até configurar a URL do Link de Pagamento. > [!NOTE] > > COMO CONFIGURAR A URL DO LINK DE PAGAMENTO > > Do nosso lado, apenas estamos retornando nos endpoints de Sessions o domínio personalizado junto ao identificador da sessão criada. > Para que seja possível ter a personalização de URL funcionando, também será necessário ter algum redirecionamento configurado no seu servidor. > [!TIP] > > MELHORIAS > > Melhorias nas validações de CEP do Checkout e do Link de Pagamento \\ > > Correção de bug no botão avançar do Checkout \\ > > Melhoria na configuração de parcela do Checkout (agora é possível configurar o número de parcelas sem exibir a interface de seleção) \\ > > Correção de bug na exibição das subcontas no Painel de Dados Se precisar de ajuda nas configurações para personalizar o Link de Pagamento ou em algum dos nossos serviços, entre em contato com o time de atendimento Malga! Boas vendas 🤝 # Dez 10 - Performance | Painel de Dados Source: https://docs.malga.io/release-notes/2024-12-10-Release-Notes Estamos muito empolgados em compartilhar a nova aba de **Performance** no Painel de dados! Agora, é possível acompanhar de forma ainda mais detalhada o desempenho do seu **fluxo inteligente de crédito**, ajudando você a tomar decisões estratégicas e otimizar a operação do seu negócio. ![Nova aba de Performance](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-12-10/1.gif?s=30ad9694e25ddbef629970a9d5e5ac5e) Confira o que tem de novo: **- Taxa de aprovação na primeira tentativa e retentativas:** acompanhe o impacto das retentativas na sua taxa de aprovação e recuperação de vendas; **- Taxa de aprovação por tentativa e provedor:** analise o desempenho de cada provedor em todas as tentativas do fluxo inteligente, entendendo sua contribuição e identificando oportunidades para otimizar seus resultados; **- Histórico de fluxos inteligentes:** compare o desempenho do fluxo atual com fluxos anteriores para evoluir suas estratégias. > [!NOTE] > > Para mais detalhes e informações das métricas apresentadas, confira nossa > [documentação aqui](/documentations/dashboard/insights/performance). Qualquer dúvida, entre em contato com o time de atendimento Malga. Contamos com seu feedback para continuar evoluindo o Painel de dados. Até mais! 🚀 # Dez 13 - 3DSecure2 Agnóstico Source: https://docs.malga.io/release-notes/2024-12-13-Release-Notes ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Eny Martins](https://github.com/enymartins.png) [Eny Martins](https://github.com/enymartins) Software Engineer ![Tiago Aro](https://github.com/tgaro.png) [Tiago Aro](https://github.com/tgaro) Tech Lead ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer Agora você pode contar com o 3DS2 Agnóstico na Malga! Sendo uma evolução do 3DS2 tradicional, esta nova funcionalidade torna o processo de autenticação mais flexível, garantindo compatibilidade com diferentes provedores de pagamento e permitindo fluxos customizados, com retentativas sem a necessidade de uma nova autenticação. ![3DS2 Agnóstico na Malga](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2024-12-13/1-light.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=cef3a28a21ed432ae9e85cd96bc70dd0) O 3DS2 é um protocolo de autenticação que adiciona uma camada extra de segurança às transações online. Ele verifica a identidade do comprador durante o pagamento, transferindo a responsabilidade de chargebacks por fraude para o banco emissor. Com o 3DS2 Agnóstico da Malga, a sua empresa tem uma solução de combate à fraude sem ficar dependente de um único provedor. Para mais informações confira a nossa [documentação completa](/documentations/3ds2-malga/intro). Se tiver qualquer dúvida, entre em contato com o nosso time de suporte. Até mais! 🚀 # Dec 18 - Barte Source: https://docs.malga.io/release-notes/2024-12-18-Release-Notes Novo campo de antifraude ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **Barte novo campo de antifraude!** Agora clientes Malga que utilizam o provedor [Barte](/documentations/providers/barte) podem enviar o id da sessão nos dados de antifraude ao [realizar uma cobrança](/api-reference/charges/realizar-nova-cobranca) através do campo `fraudAnalysis.device.sessionId` > [!NOTE] > > Disponível apenas para o método de pagamento crédito. Continue acompanhando as novidades da Malga 🤓🎉 # Dez 23 - Painel de dados em tempo real Source: https://docs.malga.io/release-notes/2024-12-23-Release-Notes Painel de dados real time ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer Estamos animados em anunciar que o ** Painel de Dados agora opera próximo do tempo real!** Isso significa que você terá acesso quase imediato às informações mais recentes para tomar decisões mais rápidas. Benefícios: * **Decisões mais assertivas:** monitore e reaja ao desempenho da sua loja com o atraso de no máximo 20min. * **Mantenha o controle da sua operação:** agora é mais fácil identificar oportunidades e resolver problemas rapidamente. Aproveite a melhoria! Teremos mais novidades em breve, até logo 🚀 # Jan 02 - Apple Pay Source: https://docs.malga.io/release-notes/2025-01-02-Release-Notes Apple Pay ![Apple Pay na Malga](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/release/2025-01-02/1-light.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=499e8b0c1dbd36ef73436bf9f3b5ad9a) Apple Pay agora disponível na Malga! Facilitamos ainda mais os pagamentos para seus clientes! Apple Pay está disponível como um novo método de pagamento para ser integrado aos provedores **Cielo** e **Pagar.me V5**, permitindo que você utilize nosso fluxo inteligente para otimizar sua operação. Com suporte para cartões de crédito, o Apple Pay permite transações rápidas e seguras com apenas um toque ou um olhar. Isso significa maior conveniência para seus clientes e uma redução no abandono de carrinho. [🔗 Confira a documentação para mais detalhes.](/documentations/payment-methods/apple-pay/intro) Até mais! 🚀 # Jan 03 - Exportação de Cobranças Source: https://docs.malga.io/release-notes/2025-01-03-Release-Notes Novos campos de 3DSecure2 ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer ### **Exportação de Cobranças** **Novos dados disponíveis na exportação de cobranças em CSV do Dashboard 🚀** Agora é possível identificar transações criadas com [3DSecure2](/documentations/3ds2-malga/intro) diretamente nos relatórios. Adicionamos os seguintes campos: | **Campo no Relatório (PT-BR)** | **Campo no Relatório (ENG-US)** | | - | - | | Resultado de autenticação | Authentication result | | Análise de risco | Risk analysis | | Cobertura de risco | Risk coverage | | Autenticação | Authentication | | Tipo de análise | Analysis type | | Tipo de autenticação | Authentication type | #### Relatórios atualizados > [!TIP] > > Simples > [!TIP] > > Completo Siga acompanhando as novidades! Até a próxima 🚀 # Jan 03 - Barte Source: https://docs.malga.io/release-notes/2025-01-03-Release-Notes2 Estorno parcial ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer **Barte agora suporta estornos parciais!** Clientes Malga que utilizam o provedor [Barte](/documentations/providers/barte) agora podem realizar [estornos parciais de cobranças aprovadas](/api-reference/charges/estornar-cobranca-aprovada). > [!NOTE] > > Disponível apenas para o método de pagamento crédito. Continue acompanhando as novidades da Malga 🤓🎉 # Jan 30 - 3DS DataOnly Source: https://docs.malga.io/release-notes/2025-01-30-Release-Notes Nova funcionalidade 3DS DataOnly ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer **Novo recurso: 3DS DataOnly!** Agora nossos clientes podem realizar transações 3DS DataOnly! Esta funcionalidade permite coletar e enviar dados 3DS sem realizar a autenticação completa, oferecendo mais flexibilidade no processo de pagamento. Para utilizar, basta adicionar a propriedade `dataOnly: true` no objeto `threeDSecure2`: ```shell theme={null} curl --location --request POST 'https://api.malga.io/v1/charges' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "b9bb37a3-cb2b-4d8e-a72e-f296bcec2ba7", "amount": 100, "statementDescriptor": "Pedido #231 loja joão", "capture": true, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "card": { "cardHolderName": "JOSE DAS NEVES", "cardNumber": "4929564637987814", "cardCvv": "123", "cardExpirationDate": "12/2026" } }, "threeDSecure2": { "dataOnly": true, <-- novo campo "redirectURL": "http://your-company/receive", "requestorURL": "http://your-company", "browser": { "acceptHeader": "*/*", "colorDepth": 24, "javaEnabled": true, "javaScriptEnabled": true, "language": "pt-BR", "screenHeight": 1080, "screenWidth": 1920, "timeZoneOffset": "180", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36", "ip": "0.0.0.0" }, "cardHolder": { "email": "cardHolder@email.com", "mobilePhone": "11 99329899" }, "billingAddress": { "city": "Rio de Janeiro", "country": "Brasil", "streetNumber": "45", "zipCode": "2547896", "state": "RJ", "street": "Av. Brasil" }, "shippingAddress": { "city": "São Paulo", "country": "Brasil", "streetNumber": "45", "zipCode": "2957896", "state": "SP", "street": "Rua das Flores" } } } ``` > [!NOTE] > > Disponível para os provedores Zoop e Rede nos serviços: > > * API Transacional > * Session API > * Export Data Para mais detalhes, consulte nossa [API do Transacional](/documentations/3ds2-malga/3ds-data-only). Continue acompanhando as novidades da Malga 🚀 # Mar 25, 2025 - Tokenization V2 Source: https://docs.malga.io/release-notes/2025-03-25-Release-Notes Lançamento do SDK de Tokenização V2 da Malga com Hosted Fields, que hospedam os campos sensíveis do cartão na Malga para mais segurança e conformidade PCI DSS. ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer **SDK Tokenization: mais segurança com Hosted Fields!** ![](https://mintcdn.com/malga/vYWnjE_PEfqgCqeH/assets/images/tokenization/sdk-tokenization-light.png?fit=max\&auto=format\&n=vYWnjE_PEfqgCqeH\&q=85\&s=cb8ebef070684148132eae8da188a31c) Agora você pode reforçar a segurança ao tokenizar cartões utilizando o Hosted Fields! Com essa novidade, os campos sensíveis do cartão são hospedados diretamente na Malga, garantindo conformidade com PCI DSS e reduzindo a complexidade da sua implementação. **O que muda?** **Mais segurança:** os dados do cartão são processados em um ambiente seguro, sem transitar pelo seu servidor ou serem expostos diretamente ao navegador ou ao front-end da aplicação. **Experiência personalizável:** estilize os campos para que se encaixem perfeitamente no seu checkout. [🔗 Para saber mais, confira nossa documentação.](/sdks/tokenization/v2/intro) # May 2025 - Convite de Usuários Source: https://docs.malga.io/release-notes/2025-05-07-Release-Notes ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![Dani](https://github.com/danielaschutt.png) [Dani](https://github.com/danielaschutt) Software Engineer ![Convida usuário](https://mintcdn.com/malga/CNIt8g3uASeU-e_S/assets/images/dashboard/users/invite.gif?s=3f29cbcb44feadc22bc2a272a441d829) **Convite de usuários disponível no Dashboard!** Agora você pode criar convites e adicionar novos usuários à conta da sua empresa diretamente pelo dashboard. Com essa atualização, é possível: * Convidar membros da sua equipe com diferentes níveis de acesso * Acompanhar o status de cada convite enviado * Definir e personalizar quando quiser o tipo de acesso do seu convidado Acesse a aba de [Usuários](https://dashboard.malga.io/app/accounts) e comece a convidar [🔗 Confira nossa documentação de permissões!](/documentations/dashboard/users) # May 16 - Split Pagarme Source: https://docs.malga.io/release-notes/2025-05-16-Release-Notes ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer É com grande entusiasmo que anunciamos mais uma atualização nas nossas integrações de meios de pagamento! Agora, estamos orgulhosos em anunciar que adicionamos suporte a funcionalidade de **split** no provedor PAGARME V5. Isso significa que você terá ainda mais flexibilidade e controle na distribuição de pagamentos entre diferentes destinatários, tornando o processo de divisão de receitas mais fácil e eficiente. ### Como utilizar? 1. Primeiro crie um [`merchant`](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) com configurações para usar o provedor PAGARME V5; 2. Crie um [`seller`](https://docs.malga.io/api#operation/postSeller) usando o merchant criado anteriormente; 3. Quando você criar uma [`transação (charge)`](/api-reference/charges/realizar-nova-cobranca) basta informar as regras de split usando a propriedade splitRules. ### Mais sobre split? Temos um espaço dedicado em nossa [`documentação`](https://docs.malga.io/documentations/split/intro) com mais detalhes de como usar o split na malga. Gostaria de saber mais sobre o assunto de split? Temos um post bem legal em nosso [`blog`](https://malga.io/post/split-de-pagamento-o-que-e-como-funciona/) e um vídeo no [`youtube`](https://www.youtube.com/watch?v=P859PvvhtDY). # Jul 29, 2025 - GETNET SEP Source: https://docs.malga.io/release-notes/2025-07-29-Release-Notes ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer Lançamos a integração com o provedor GETNET SEP! Essa versão permite buscar transações pelo Id, o que facilita a vida dos nossos clientes e também diminui os problemas de transações inconsistentes, facilitando o trabalho da nossa Sonda! > [!TIP] > > Features: > > 1. Método de pagamento: crédito > 2. Zero Dollar # Sep 08, 2025 - MapInvest Source: https://docs.malga.io/release-notes/2025-09-08-Release-Notes Novo provedor ![João Filho](https://github.com/joaofilho-plug.png) [João Filho](https://github.com/drummerzzz) Software Engineer Chegou novidade! Agora a [MapInvest](/documentations/providers/mapinvest) faz parte da lista de [provedores suportados](/documentations/type-tables/payment-methods-by-providers) pela Malga. Agora clientes Malga podem realizar cobranças através do [método de pagamento](/documentations/payment-methods/intro) Pix com a [MapInvest](/documentations/providers/mapinvest). > [!TIP] > > Integração com a MapInvest disponível para pagamentos via Pix. Continue acompanhando as novidades da Malga 🤓🎉 # Set 12, 2025 - Bolt Source: https://docs.malga.io/release-notes/2025-09-12-Release-Notes Inclusão da Bolt na lista de provedores suportados pela Malga. ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer E como a gente não para, mais uma integração acabou de sair do forno, e dessa vez é a [Bolt](/documentations/providers/bolt) que passa a integrar a lista de [provedores suportados](/documentations/type-tables/payment-methods-by-providers) pela Malga. Clientes Malga já podem realizar cobranças através do [método de pagamento](/documentations/payment-methods/intro) Crédito com a [Bolt](/documentations/providers/bolt). Fique ligado nas próximas atualizações! 👨‍🍳 > [!TIP] > > Features: > > 1. Método de pagamento: crédito > 2. Zero Dollar # Sep 15, 2025 - Split PagSeguro Source: https://docs.malga.io/release-notes/2025-09-15-Release-Notes ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer É com grande entusiasmo que anunciamos mais uma atualização nas nossas integrações de meios de pagamento! Agora, estamos orgulhosos em anunciar que adicionamos suporte à funcionalidade de split no provedor PagSeguro. Isso significa que você terá ainda mais flexibilidade e controle na distribuição de pagamentos entre diferentes destinatários, tornando o processo de divisão de receitas mais fácil e eficiente. ### Como utilizar? O fluxo de utilização com o PagSeguro possui algumas etapas adicionais de segurança para o cadastro e autorização do vendedor (*seller*). 1. Primeiro, crie um [`merchant`](/api-reference/merchants/criacao-de-novo-merchant-para-cobranca) com as configurações para usar o provedor PagSeguro. 2. Crie um [`seller`](https://docs.malga.io/api#operation/postSeller) usando o merchant criado anteriormente. 3. Após a criação via API, o *seller* receberá um e-mail do PagSeguro com os próximos passos para finalizar o seu cadastro. Esta etapa incluirá o envio de documentos e a realização de biometria para validação da conta. 4. Com o cadastro finalizado, o passo seguinte é a autorização. O *seller* precisará autorizar que a sua aplicação (marketplace) possa criar transações em nome dele. Você deverá direcioná-lo para o fluxo de autorização do PagSeguro. 5. Uma vez que o *seller* esteja totalmente cadastrado e tenha autorizado a aplicação, você poderá criar uma [`transação (charge)`](/api-reference/charges/realizar-nova-cobranca) e informar as regras de divisão usando a propriedade `splitRules`. ### Mais sobre split? Temos um espaço dedicado em nossa [`documentação`](https://docs.malga.io/documentations/split/intro) com mais detalhes de como usar o split na Malga. Gostaria de saber mais sobre o assunto de split? Temos um post bem legal em nosso [`blog`](https://malga.io/post/split-de-pagamento-o-que-e-como-funciona/) e um vídeo no [`youtube`](https://www.youtube.com/watch?v=P859PvvhtDY). # Sep 16, 2025 - Assinaturas Source: https://docs.malga.io/release-notes/2025-09-16-Release-Notes Gestão de Assinaturas ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer Estamos muito felizes em anunciar que lançamos a versão beta do motor de assinaturas da Malga. > [!TIP] > > Confira a nossa [documentação](/api-reference/subscriptions) para conhecer mais! Clientes que utilizam o nosso motor podem **gerenciar suas assinaturas diretamente pelo [dashboard](https://dashboard.malga.io/)**, sendo possível buscar assinaturas específicas e aplicar filtros para facilitar a visualização e organização: ![Listagem de assinaturas](https://mintcdn.com/malga/8OvWxkYk9Utp83HO/assets/images/dashboard/subscriptions/subscriptions-list.gif?s=d4cd61331bf04697a874613f7d1d7ece) Além disso, ao clicar em uma assinatura, você pode pausá-la, cancelá-la e retomar quando quiser. Também disponibilizamos um histórico completo de logs, com todas as ações realizadas em cada assinatura. ![Detalhes de assinatura](https://mintcdn.com/malga/8OvWxkYk9Utp83HO/assets/images/dashboard/subscriptions/subscriptions-details.png?fit=max\&auto=format\&n=8OvWxkYk9Utp83HO\&q=85\&s=a215fcfc5a82f71112926e9fb6ce8ef9) Confira também a listagem de todas as faturas geradas de acordo com o que foi definido na criação de uma assinatura. ![Listagem de faturas](https://mintcdn.com/malga/8OvWxkYk9Utp83HO/assets/images/dashboard/subscriptions/cycles-list.png?fit=max\&auto=format\&n=8OvWxkYk9Utp83HO\&q=85\&s=a084371e26292ae743e50a5c991066d6) Continue nos acompanhando para mais novidades! 🤓🎉 # Oct 02, 2025 - Trial, retentativas personalizadas e mais Source: https://docs.malga.io/release-notes/2025-10-02-Release-Notes Melhorias no Motor de Assinaturas ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer Estamos trazendo uma série de melhorias para tornar a gestão de assinaturas mais **flexível** e **alinhada** ao seu modelo de negócio. Confira as novidades: ## 🔁 Retentativas personalizadas Agora você pode definir, via API, o número de tentativas e os intervalos entre elas para a recuperação de pagamentos que falharam. Essa novidade vem como uma estratégia de recuperação de receita alinhada ao seu modelo de negócio. Use réguas mais curtas para assinaturas semanais ou mais longas para planos mensais, aumentando a taxa de aprovação e reduzindo o churn involuntário. [Veja a documentação completa](/documentations/more/recurrence/engine/client-settings) ## 🛠️ Status final da assinatura após falhas Você agora tem o poder de escolher, via API, o que acontece com uma assinatura quando todas as tentativas de pagamento de uma fatura falham: * Manter a assinatura como inadimplente (continuando a gerar faturas), ou * Cancelar a assinatura (interrompendo o serviço). Essa flexibilidade permite que sua operação de cobrança reflita exatamente sua regra de negócio, sem precisar de adaptações manuais. [Veja a documentação completa](/documentations/more/recurrence/engine/managing#l%C3%B3gica-de-falha-ap%C3%B3s-retentativas) ## 🎁 Período de teste (trial) Adicionamos a opção de criar assinaturas com **período de teste**. Assim, a cobrança só acontece ao final do trial, permitindo que o cliente experimente o serviço antes de pagar. [Veja a documentação completa](/documentations/more/recurrence/engine/managing#sistema-de-trials) ## 📊 Detalhes da fatura no dashboard ![Gif do Dashboard](https://mintcdn.com/malga/Nnuey7dEDWXB68N6/assets/images/release/2025-10-02/1.gif?s=7c47849bef1be4eb297dcfef72b46b9a) Disponibilizamos no dashboard uma visão completa das faturas de cada assinatura. Você pode consultar informações gerais da fatura e acompanhar todas as cobranças associadas a ela. ## 💳 Descrição personalizada no extrato do cartão Agora você pode personalizar as **descrições de extrato** que aparecem nos comprovantes bancários dos seus clientes. Isso ajuda a dar mais clareza sobre a cobrança, reduzindo estornos e contestações. [Veja a documentação completa](/documentations/more/recurrence/engine/client-settings#param-statement-descriptor) *** Estas são as primeiras de muitas novidades que estamos preparando para o Motor de Assinaturas da Malga. Explore a documentação, e acione o nosso suporte em caso de dúvidas. Até breve! # Nov 11, 2025 - B2E Source: https://docs.malga.io/release-notes/2025-11-11-Release-Notes Atualização da Malga em novembro de 2025 com a integração da B2E como novo provedor antifraude, com análise assíncrona contra fraudes. ![Dennis Quintal](https://github.com/dennisqq.png) [Dennis Quintal](https://github.com/dennisqq) Software Engineer ![Leandro Araujo](https://github.com/leandroaraujo-malga.png) [Leandro Araujo](https://github.com/leandroaraujo-malga) Software Engineer Tem provedor antifraude novo na Malga! 🎉 A [B2E](https://www.b2egroup.com.br/) chegou para reforçar ainda mais a segurança da sua operação. Com análise assíncrona, a B2E oferece uma camada robusta de proteção contra fraudes, ajudando você a reduzir perdas e aumentar a confiança nas transações. [Veja a documentação completa](/documentations/providers-antifraud/b2e) # Nov 12, 2025 - ApplePay na Pagseguro Source: https://docs.malga.io/release-notes/2025-11-12-Release-Notes ApplePay na Pagseguro ![Lucas Saraiva](https://github.com/lucassaraiva5.png) [Lucas Saraiva](https://github.com/lucassaraiva5) Software Engineer Apple Pay via PagSeguro agora disponível na Malga A Malga agora oferece suporte a Apple Pay para pagamentos processados pela PagSeguro. Com essa atualização, você pode disponibilizar aos seus clientes uma experiência de pagamento mais rápida, segura e fluida em dispositivos Apple. O que muda com esse lançamento? Suporte a Apple Pay em transações roteadas pela PagSeguro. Seu checkout simplificado, sem a necessidade de digitar dados do cartão. Autenticação nativa do dispositivo, trazendo mais segurança e menos fricção. Maior potencial de conversão para usuários de iPhone, iPad e Mac. Para detalhes de configuração, testes e requisitos técnicos, é só consultar a documentação aqui ou acionar nosso time Malga. # Nov 19, 2025 - Novo Link de Pagamento Source: https://docs.malga.io/release-notes/2025-11-19-Release-Notes Design renovado e mais agilidade no Link de Pagamento ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer ![Novo Link de Pagamento](https://malga-docs-prod.s3.us-east-1.amazonaws.com/gifs/release-09-15-25/1.gif) O Link de Pagamento ganhou uma nova interface, mais moderna, intuitiva e focada na conversão. Além da experiência visual aprimorada, implementamos funcionalidades que garantem mais agilidade e transparência no seu checkout: * **Preenchimento automático de endereço via CEP:** Na hora de pagar, seu cliente não precisará mais digitar todo o endereço. Ao preencher o campo do CEP, o restante dos dados será preenchido automaticamente. Menos atrito, mais vendas! * **Feedback imediato para recusas:** Agora, o seu cliente receberá o **motivo de recusa** de forma clara e instantânea, caso a transação não seja aprovada. Isso permite que ele corrija rapidamente a informação e **tente o pagamento novamente**, elevando suas chances de conversão imediata. * **Confirmação automática de pagamento via Pix:** Assim que o Pix é concluído, o pagamento é identificado instantaneamente e o cliente é redirecionado automaticamente para a página de sucesso. Mais rapidez e uma experiência muito mais fluida. # Nov 24, 2025 - Pix e Boleto na GETNET SEP Source: https://docs.malga.io/release-notes/2025-11-24-Release-Notes Pix e Boleto na GETNET SEP ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer Pix e Boleto estão disponíveis na integração da Malga com a GETNET SEP Com essa atualização, você pode disponibilizar aos seus clientes os métodos de pagamento Boleto e Pix na sua integração com a GETNET SEP. # Nov 25, 2025 - 3DS2 Malga no Link Source: https://docs.malga.io/release-notes/2025-11-25-Release-Notes 🛡️ Suporte a 3DS2 agora disponível no Link de Pagamento ![Filippe Rodrigues](https://github.com/filipperodrigues.png) [Filippe Rodrigues](https://github.com/filipperodrigues) Tech Lead ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer Estamos felizes em anunciar que o 3D Secure (3DS2) já está disponível no Link de Pagamento da Malga. Com essa atualização, seus links de pagamento podem passar a contar com uma camada adicional de segurança, reduzindo risco de fraude e aumentando a taxa de aprovação. #### O que muda a partir de agora? * Você pode criar links de pagamento com 3DS habilitado direto na Dashboard e também via API; * Você escolhe se quer exigir **cobertura de risco** ou não. ![Link com 3DS2](https://mintcdn.com/malga/d-BdtqCbybwntJDg/assets/images/release/2025-11-25/1.png?fit=max\&auto=format\&n=d-BdtqCbybwntJDg\&q=85\&s=5c8c2321b0af628b361cb0f841df2716) Se tiver dúvidas ou quiser explorar como ativar o 3DS nos seus links, pode consultar as nossas documentações ou acionar nosso time Malga! > [card] [Link de Pagamento com 3DS2 Agnóstico](/documentations/payment-link/intro) > > Saiba como funciona o 3DS2 no Link de Pagamento. Continue vendendo com mais segurança e confiança! 🚀 # Dez 19, 2025 - Zero dollar Safra Pay Source: https://docs.malga.io/release-notes/2025-12-19-Release-Notes 🛡️ Zero dollar Safra Pay ![Lucas Saraiva](https://github.com/lucassaraiva5.png) [Lucas Saraiva](https://github.com/lucassaraiva5) Software Engineer Novidade: Malga agora suporta Zero Dollar da Safra Pay A Malga ampliou sua integração com a Safra Pay e passa a oferecer suporte ao fluxo de Zero Dollar Authorization. ### Zero Dollar (Safra Pay) Agora você pode validar cartões da Safra Pay sem realizar uma cobrança real. Esse fluxo é ideal para: * cadastro e verificação de cartões, * carteiras digitais (wallets), * modelos de pagamento recorrente. A validação acontece de forma segura, rápida e sem impacto para o portador do cartão. Consulte nossa [doc](https://docs.malga.io/documentations/providers/safrapay) para mais informações # Dez 22, 2025 - Click to Pay Source: https://docs.malga.io/release-notes/2025-12-22-Release-Notes Suporte a Click to Pay na Malga ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Dennis Quintal](https://github.com/dennisqq.png) [Dennis Quintal](https://github.com/dennisqq) Software Engineer Agora o Click to Pay (C2P) está disponível na Malga para cartões Visa e Mastercard. O C2P oferece uma experiência de pagamento tokenizada, mais rápida e extremamente segura, eliminando a necessidade de digitar dados do cartão a cada compra. **Reutilização Global de Cartões:** Com o Click to Pay, seus clientes podem reutilizar cartões que cadastraram previamente em qualquer outra loja que também utilize o C2P, agilizando o pagamento do checkout e aumentando a segurança da transação. ![Click to Pay](https://mintcdn.com/malga/WKvAjWB9gShm652n/assets/images/payment-methods/click-to-pay/c2p-payment-link.png?fit=max\&auto=format\&n=WKvAjWB9gShm652n\&q=85\&s=b6eda8451d3ed9fd2af534f65a778d9d) ## Link de Pagamento Já disponível no Link de Pagamento, homologamos a solução em conjunto com a Mastercard para oferecer a melhor experiência possível para o cliente. Além disso, associado ao C2P, introduzimos a opção de autenticação via Passkey, uma tecnologia de ponta que garante o Liability Shift em caso de fraude. ### **Liability Shift:** O que isso significa para o seu negócio? Com o Liability Shift garantido pela Passkey, a responsabilidade por transações fraudulentas passa do lojista (você) para o banco emissor do cartão, oferecendo uma camada extra de proteção e tranquilidade para o seu negócio. ## API de Cobranças/Sessions Também é possível criar transações com Click to Pay através da API de Cobranças/Sessions. A integração é feita da mesma forma que outros métodos, porém requer o uso do SDK da Mastercard para obter os dados necessários. Além disso, para ter o Passkey, a implementação precisa ser feita à parte. ## Sugestões * Precisa de **integração rápida** com **boa experiência**? Use o Link de Pagamento. * Precisa de **controle total** sobre a experiência? Use a API de Cobranças/Sessions. > [card] [Link de Pagamento com Click to Pay](/documentations/payment-methods/click-to-pay/link-de-pagamento) > > Crie sessões (links) de pagamento que oferecem Click to Pay automaticamente > [card] [Integração via API de Charges](/documentations/payment-methods/click-to-pay/integracao-api-charges) > > Use Click to Pay diretamente pela API de cobranças > [card] [Guia oficial Mastercard](https://developer.mastercard.com/product/click-to-pay/) > > Consulte os detalhes completos da experiência Click to Pay Ficou com alguma dúvida? Entre em contato com nossa equipe. # Jan 05, 2026 - Recorrência | Agendar cancelamento Source: https://docs.malga.io/release-notes/2026-01-05-Release-Notes Suporte a agendamento de cancelamento de assinaturas ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer Agora, quem utiliza o motor de recorrência pode, além de cancelar uma assinatura imediatamente, **agendar o cancelamento para o fim do ciclo.** Com o cancelamento agendado, o cliente indica que não deseja renovar a assinatura ao final do período vigente. A assinatura permanece ativa até o último ciclo pago e é cancelada automaticamente, sem a realização de novas cobranças. ## O que isso resolve * Permite que o assinante decida antecipadamente não renovar * Evita renovações e cobranças indesejadas * Elimina processos manuais de cancelamento no fim do ciclo * Dá mais clareza sobre churn futuro e fim de contratos Essa funcionalidade amplia o controle sobre o ciclo de vida da recorrência e melhora a experiência de cancelamento sem impactar o período já contratado. 👉 Em caso de dúvidas pode consultar nossa documentação ou acionar nosso time para suporte! > [card] [Cancelamento Agendado](/documentations/more/recurrence/engine/scheduled-cancellation) > > Veja como funciona o cancelamento agendado na documentação. > [card] [Referência da API](/api-reference/subscriptions/atualizar-assinatura) > > Consulte a referência completa da API de atualização de assinatura. # Jan 06, 2026 - Paypal Source: https://docs.malga.io/release-notes/2026-01-06-Release-Notes Suporte a Paypal na Malga ![Marcos Trevisan](https://github.com/marcostrevisan.png) [Marcos Trevisan](https://github.com/marcostrevisan) Software Engineer Agora você já pode usar a [PayPal](/documentations/providers/paypal) com a Malga! Nessa nova versão, ela passa a estar disponível na nossa lista de [provedores suportados](/documentations/type-tables/payment-methods-by-providers). Se você é cliente Malga, já pode realizar cobranças através do [método de pagamento](/documentations/payment-methods/intro) Crédito com a [PayPal](/documentations/providers/paypal). Siga acompanhando para ficar por dentro das novidades! > [!TIP] > > Features: > > 1. Método de pagamento: crédito # Jan 15, 2026 - Banrisul Source: https://docs.malga.io/release-notes/2026-01-15-Release-Notes Suporte a Banrisul na Malga ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer 2026 começou com tudo! 🚀 A integração com a [Banrisul](/documentations/providers/banrisul) já está disponível para os clientes da Malga e agora faz parte da nossa lista de [provedores suportados](/documentations/type-tables/payment-methods-by-providers). Se você é cliente Malga, já pode realizar cobranças com [Pix](/documentations/payment-methods/intro) usando a Banrisul. A Banrisul é um dos maiores bancos do Sul do Brasil, oferecendo processamento de pagamentos seguro e eficiente para suas transações. Com essa integração, você expande suas opções de provedores, alcançando mais clientes com a confiabilidade que só a Malga oferece. Continue acompanhando as novidades da Malga 🤓🎉 > [!TIP] > > Features: > > 1. Método de pagamento: pix > 2. Processamento via Banrisul # Mar 09, 2026 - Suporte a recorrência no adapter Barte Source: https://docs.malga.io/release-notes/2026-03-09-Release-Notes A partir de agora é possível realizar transações de recorrência com provedor Barte através da Malga Estamos felizes de anunciar que o adapter **Barte** agora suporta a flag de [recorrência](/documentations/more/recurrence/charges). Com essa flag, transações de recorrência avulsa são sinalizadas corretamente ao adquirente, o que tende a melhorar a taxa de aprovação em cobranças recorrentes. Para mais detalhes, consulte nossa documentação sobre [recorrência](/documentations/more/recurrence/intro) ou [cobranças com cartão](/api-reference/charges/realizar-nova-cobranca#body-payment-method). > [!TIP] > > Features: > > 1. Adapter Barte com suporte à flag de recorrência > 2. Melhor sinalização para transações de recorrência avulsa > 3. Potencial melhoria na taxa de aprovação para cobranças recorrentes # Abr 08, 2026 - Upload de documentos para Sellers Source: https://docs.malga.io/release-notes/2026-04-08-Release-Notes Novos endpoints para upload e gerenciamento de documentos de identidade (KYC) para sellers Agora é possível enviar documentos de identidade (KYC) para sellers diretamente pela API da Malga. O fluxo permite que o merchant faça upload dos arquivos antes ou depois de criar o seller, sem depender de painéis externos do provedor. ## Como funciona O merchant faz upload dos documentos via API, recebe os IDs e os inclui no campo `documentIds` do body do `POST /v1/sellers` ao criar o seller. Os documentos ficam armazenados temporariamente por 7 dias. Após esse prazo, expiram automaticamente. ## Novos endpoints * `POST /v1/sellers/documents` - Upload de documento (multipart) * `GET /v1/sellers/documents` - Listar documentos * `GET /v1/sellers/documents/{documentId}` - Consultar documento * `DELETE /v1/sellers/documents/{documentId}` - Deletar documento ## Tipos de documento aceitos * `SELFIE` - Selfie do titular * `CNH_FULL` - CNH completa (frente e verso) * `CNH_FRONT` / `CNH_BACK` - CNH frente / verso separados * `RG_FRONT` / `RG_BACK` - RG frente / verso Para mais detalhes, consulte a [referência da API](/api-reference/sellers/upload-de-documento). > [!TIP] > > Features: > > 1. Upload de documentos de identidade para sellers via API > 2. Associação de documentos na criação do seller > 3. Gerenciamento completo: upload, consulta, listagem e exclusão > 4. Suporte ao provedor Zoop # Apr 15, 2026 - Konduto Source: https://docs.malga.io/release-notes/2026-04-15-Release-Notes Atualização da Malga em abril de 2026 com a integração da Konduto como novo provedor antifraude, com análise em tempo real e machine learning. ![Tiago Aro](https://github.com/tgaro.png) [Tiago Aro](https://github.com/tgaro) Tech Lead ![Leandro Araujo](https://github.com/leandroaraujo-malga.png) [Leandro Araujo](https://github.com/leandroaraujo-malga) Software Engineer Tem provedor antifraude novo na Malga! 🎉 A [Konduto](https://www.konduto.com) é uma solução de prevenção a fraudes voltada à análise de risco em transações online. Além de suportar operações **em tempo real** e **análises assíncronas**, também conta com aprendizado de máquina para avaliar o comportamento do comprador. [Veja a documentação completa](/documentations/providers-antifraud/konduto) # Abr 23, 2026 - Nova experiência da Dashboard Source: https://docs.malga.io/release-notes/2026-04-23-Release-Notes Nova experiência da Dashboard ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer ![Lucas Saraiva](https://github.com/lucassaraiva5.png) [Lucas Saraiva](https://github.com/lucassaraiva5) Software Engineer ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ## Nova experiência da Dashboard Novidade fresquinha na [dashboard da Malga](https://dashboard.malga.io/) 🎨✨ ![Nova tela de login da Malga](https://mintcdn.com/malga/hqqq502H9FEbdNuR/assets/images/release/2026-04-23/Malgav2.gif?s=5eb3223cba70c389251e708d26e2fffc) A experiência de usar a Malga mudou. Pensamos com cuidado em cada detalhe que faz diferença no dia a dia. Revisamos toda a plataforma: a forma como a informação é apresentada, como você navega, como os dados aparecem. Menos esforço para encontrar o que precisa. Mais clareza em cada interação. Seus dados e configurações estão intactos. O que mudou é tudo ao redor deles. Aproveitamos a virada para otimizar o que acontece por trás da nova interface: os componentes passaram a ser mais leves e as listagens agora carregam sensivelmente mais rápido. Menos espera, mais fluidez para operar o seu negócio. 💡 Importante: para garantir que você enxergue a nova experiência corretamente, recomendamos limpar o cache e os cookies do navegador antes de acessar a dash. Isso evita que versões antigas de estilos e scripts fiquem salvas e causem comportamentos inesperados na interface. * Chrome: Ctrl + Shift + Del (Windows) ou Cmd + Shift + Del (Mac) → selecionar "Imagens e arquivos em cache" e "Cookies e outros dados do site" → Limpar dados * Safari: menu Safari → Configurações → Privacidade → Gerenciar dados de sites → remover dados de dashboard.malga.io * Firefox / Edge: Ctrl + Shift + Del → selecionar cache e cookies → Limpar agora Continue acompanhando as novidades da Malga e qualquer dúvida entre em contato com o nosso suporte 🤓🎉 # Abr 29, 2026 - Split no Link de Pagamento Source: https://docs.malga.io/release-notes/2026-04-29-Release-Notes Agora é possível configurar split de pagamentos direto no Link de Pagamento, com regras reutilizáveis no cadastro do recebedor ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer Agora você pode configurar **split de pagamentos direto no Link de Pagamento**. Crie cobranças onde o valor pago é automaticamente dividido entre múltiplos recebedores. ## Como utilizar? Ao criar um Link de Pagamento, você pode definir as regras de divisão informando os recebedores e seus respectivos valores (em `%` ou `R$`). Assim, toda cobrança gerada a partir desse link já seguirá automaticamente essa configuração. ## Mais agilidade com configurações reutilizáveis Para que o split funcione de forma completa, você pode definir previamente algumas regras no cadastro do recebedor. Isso permite reutilizar essas configurações sempre que ele participar de um split, sem precisar enviá-las a cada transação. Entre as configurações disponíveis, é possível definir: * Quem é responsável pelas taxas de processamento * Quem assume reembolsos e chargebacks * Tarifas adicionais (Braspag) * MDR por tipo de pagamento e parcelamento (Braspag) * Taxa fixa por transação (Braspag) Caso essas configurações não sejam definidas, o comportamento padrão é atribuir essas responsabilidades à própria empresa, isentando os recebedores. ## Mais sobre split? Temos um espaço dedicado na nossa [documentação](/documentations/split/intro) com mais detalhes de como usar o split na Malga, incluindo o novo guia de [Split em sessão e Link de Pagamento](/documentations/split/split-em-sessao-link). > [!TIP] > > Features: > > 1. Configuração de split direto no Link de Pagamento > 2. Regras de divisão por percentual ou valor fixo entre múltiplos recebedores > 3. Configurações reutilizáveis no cadastro do recebedor (taxas, chargeback, MDR) # Abr 30, 2026 - APIs de payouts e novo campo totalPaidAmount Source: https://docs.malga.io/release-notes/2026-04-30-Release-Notes Lançamento das APIs de payouts, salesPlanId em Sellers e novo campo totalPaidAmount na query allCharges da Analytics API da Malga. ![Leonardo Pinheiro](https://github.com/0xleozera.png) [Leonardo Pinheiro](https://github.com/0xleozera) Tech Lead ![João Victor](https://github.com/jvdrip.png) [João Victor](https://github.com/jvdrip) Data Engineer ## Novas APIs de saldo, repasses e ordens de pagamento, campo novo na criação de seller Adicionamos uma nova seção na **Referência da API**: a [Payouts](/api-reference/payouts/consultar-saldo-de-payouts), pensada para te dar visibilidade total sobre saldos, repasses e ordens de pagamento da nossa subadquirente, tudo em um só lugar. Além disso, agora na [criação de seller](/api-reference/sellers/criacao-de-um-novo-recebedor) adicionamos o campo opcional `salesPlanId`, que é um identificador do **Plano de Venda na Zoop**, usado para amarrar o seller a um plano comercial de vendas específico. ### Novos endpoints de Payouts * `GET /v1/payouts/balance`: saldo disponível e a receber. * `GET /v1/payouts/payment-batches`: listagem paginada de repasses. * `GET /v1/payouts/payment-batches/{id}`: detalhe de um repasse. * `GET /v1/payouts/payment-batches/{id}/orders`: ordens de pagamento que compõem um repasse. * `GET /v1/payouts/orders`: listagem paginada de ordens de pagamento. * `GET /v1/payouts/orders/{id}`: detalhe de uma ordem de pagamento. ### Como usar Consultar o saldo disponível e a receber: ```bash theme={null} curl --location 'https://api.malga.io/v1/payouts/balance' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Listar repasses: ```bash theme={null} curl --location 'https://api.malga.io/v1/payouts/payment-batches' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Filtrar ordens de pagamento por cobrança: ```bash theme={null} curl --location 'https://api.malga.io/v1/payouts/orders?chargeId=YOUR_CHARGE_ID' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Aproveite para dar uma olhada na [referência completa](/api-reference/payouts/consultar-saldo-de-payouts) e levar a conciliação financeira do seu negócio para o próximo nível 🚀 ## Novo campo totalPaidAmount na Analytics API Disponibilizamos o campo `totalPaidAmount` nas queries `allCharges` e `charge` da [Analytics API](/analytics/intro). Esse campo representa o valor total efetivamente pago na transação, incluindo eventuais taxas que possam ter sido repassadas ao pagador. Esse cenário acontece no **Mercado Pago**, onde as taxas podem ser assumidas pelo cliente final, e não pelo lojista. Nesses casos, o valor pago pelo cliente pode ser maior do que o valor original da cobrança (`amount`). Com o `totalPaidAmount`, você consegue: * Ter maior precisão na análise do valor pago pelo cliente final * Diferenciar o valor da cobrança do valor efetivamente desembolsado **Importante**: O campo `totalPaidAmount` não se aplica a todos os provedores ou transações e será preenchido apenas em cenários específicos do **Mercado Pago** nos quais exista diferença entre o valor da cobrança e o valor efetivamente pago, como nos casos em que o cliente assume as taxas. Em geral, esse campo é populado exclusivamente quando o provedor retorna o valor com juros aplicados; para demais provedores ou transações sem juros ao comprador, permanecerá vazio. Confira em nossa [documentação](/analytics/queries/charges) os detalhes do campo e as demais informações retornadas pela query. > [!TIP] > > Features: > > 1. Nova seção Payouts no API Reference com 6 endpoints > 2. Consulta de saldo, repasses e ordens de pagamento em um único lugar > 3. Filtros por seller, status e intervalo de datas > 4. Novo campo opcional `salesPlanId` na criação de seller (provedor Zoop) > 5. É possível testar a query [allCharges](/analytics/queries/charges) e a Analytics API através do playground disponível neste [link](https://graphql.malga.io/), utilizando suas credenciais de acesso à Malga. Até a próxima! 🚀 # Mai 08, 2026 - Link de Pagamento 1:N Source: https://docs.malga.io/release-notes/2026-05-08-Release-Notes Crie links de pagamento com múltiplos pagamentos e limite de pagamentos configurável. ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer Estamos lançando uma nova funcionalidade para Links de Pagamento: agora você pode configurar o mesmo link para aceitar múltiplos pagamentos, com limite definido ou sem limite de quantidade. ## Como utilizar Ao criar um Link de Pagamento via API, envie o campo `maxPayments` na criação da sessão. Use `-1` para permitir pagamentos sem limite de quantidade ou um número maior que `1` para definir um limite máximo de pagamentos. Veja a [documentação de criação via API](/documentations/payment-link/create-link-using-api) para saber mais. Você também pode criar links pelo Dashboard de forma rápida. Acesse a área de Links de Pagamento, habilite o limite de pagamentos quando o link precisar aceitar mais de um pagamento e informe a quantidade permitida. Caso mantenha o controle desabilitado, o link segue o comportamento padrão de pagamento único. ![Tela do Dashboard com o controle de limite de pagamentos habilitado na criação de link](https://mintcdn.com/malga/iRTVaScHeeJlF7_T/assets/images/dashboard/payment-link/payment-link-maxPayments-light.png?fit=max\&auto=format\&n=iRTVaScHeeJlF7_T\&q=85\&s=7affa19a90bc57dc6a68bd3b39152fc0) > [!NOTE] > > Ficou com alguma dúvida? Entre em contato pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). ## E mais Também melhoramos a configuração de validade dos links. Agora é possível criar Links de Pagamento sem data de expiração e desativá-los quando necessário pelo Dashboard ou pela API. > [!TIP] > > Principais novidades: > >
    >
  • Criação de Links de Pagamento 1:N com `maxPayments`.
    • >
  • Criação de Links de Pagamento sem data de expiração.
    • >
# Mai 29, 2026 - Beneficiário final NuPay e Antecipação avulsa Source: https://docs.malga.io/release-notes/2026-05-29-Release-Notes Informe os beneficiários finais de uma cobrança NuPay com o novo campo recipients e antecipe seus recebíveis sob demanda com simulação e aceite via API. ![Marcos Trevisan](https://github.com/marcostrevisan.png) [Marcos Trevisan](https://github.com/marcostrevisan) Software Engineer ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer ## Beneficiário final em cobranças NuPay Agora você pode informar o **beneficiário final** de uma cobrança **NuPay** por meio do novo campo `recipients`. O beneficiário final é o destinatário efetivo dos valores de uma transação e seu envio atende às exigências da Circular BACEN 3.978/2020 sobre prevenção à lavagem de dinheiro e financiamento do terrorismo (PLDFT). ### Como utilizar O campo `recipients` é **opcional** e deve ser enviado dentro de `paymentMethod` na criação da cobrança. Ele aceita um array em que cada item representa um beneficiário final, com os campos `referenceId`, `name`, `document` (`country`, `type` e `number`) e `amount` (em centavos). Confira os detalhes completos no [guia de pagamento NuPay](/documentations/payment-methods/nupay#beneficiário-final) e na [referência da API de criação de cobrança](/api-reference/charges/realizar-nova-cobranca). > [!TIP] > > Principais novidades: > >
    >
  • Novo campo `recipients` no `paymentMethod` das cobranças NuPay.
    • >
  • Suporte a múltiplos beneficiários finais por transação.
    • >
  • Identificação do beneficiário final por documento (`country`, `type` e `number`).
    • >
## Antecipação avulsa de recebíveis Estamos lançando em **Beta** a **antecipação avulsa de recebíveis**: agora você pode receber antes da data prevista o dinheiro das suas vendas processadas pelo provedor de pagamento Malga, pagando uma taxa proporcional ao tempo antecipado. É uma antecipação **sob demanda** — você escolhe quando e quais recebíveis quer antecipar. > [!NOTE] > > A funcionalidade está disponível para clientes habilitados, mas a documentação e as APIs podem evoluir nas próximas versões. ### Como utilizar A antecipação é solicitada **por data de recebimento**. Você informa uma ou mais datas e a Malga **agrupa todos os recebíveis previstos para cada data** numa única simulação, calculando o valor líquido que você vai receber. O fluxo é simples e tem 3 passos: 1. [Consulte os recebíveis disponíveis](/api-reference/prepayment/consultar-recebiveis-disponiveis-para-antecipacao) para ver o valor total e as datas elegíveis. 2. [Simule a antecipação](/api-reference/prepayment/simular-antecipacao) informando as datas que quer antecipar — a resposta traz o valor líquido a receber e a validade da simulação. 3. [Confirme a antecipação](/api-reference/prepayment/confirmar-antecipacao) enviando o aceite. Para receber **amanhã (D+1)**, simule e confirme até as **15h (horário de Brasília)**. Após esse horário, o pagamento passa para D+2. Detalhes completos no [guia conceitual de Antecipação avulsa](/documentations/more/prepayment). > [!NOTE] > > A antecipação avulsa está disponível apenas para clientes que **transacionam pelo provedor de pagamento Malga** e tiveram a habilitação aprovada. Para solicitar a habilitação, entre em contato pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). > [!TIP] > > Principais novidades: > >
    >
  • Consulta dos recebíveis disponíveis para antecipação, com valor total e quantidade.
    • >
  • Simulação por uma ou mais datas — a Malga agrupa os recebíveis daquela data.
    • >
  • Aceite com registro de IP e timestamp como comprovante da operação.
    • >
  • Suporte a antecipação por recebedor para quem usa split de pagamentos.
    • >
# Jun 12, 2026 - Fim do split agnóstico e payout eligible Source: https://docs.malga.io/release-notes/2026-06-12-Release-Notes Encerramento do split agnóstico e do indicador payout eligible na Malga, com orientações para integrações que listavam sellers sem merchantId. ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer Descontinuamos o **split agnóstico** e o indicador **payout eligible** (`isPayoutEligible` / `payout_eligible`). Essas funcionalidades não estão mais disponíveis na plataforma Malga nem no Dashboard. ## O que foi descontinuado ### Split agnóstico * Listagem de recebedores (sellers) **sem** `merchantId` associado * Filtro `agnosticSplitEligible` em consultas de sellers * Dual fetch que combinava sellers do merchant com sellers “agnósticos” ### Payout eligible * Campo `isPayoutEligible` em respostas de cobrança (camada de integração interna) * Feature flag `payout_eligible` no Dashboard * Fluxos de estorno com split condicionados exclusivamente a esse indicador (fora do contexto de subadquirente) ## Breaking changes > [!WARNING] > > **Mudança incompatível:** integrações que listavam sellers sem `merchantId` ou que liam `isPayoutEligible` / `agnosticSplitEligible` precisam ser atualizadas. > > **O que fazer:** > > 1. **Sellers:** informe sempre `merchantId` ao consultar ou referenciar recebedores. Veja [Recebedor (seller)](/documentations/split/seller) e a [API de sellers](/api-reference/sellers/criacao-de-um-novo-recebedor). > 2. **Cobranças com split:** use o fluxo documentado em [Cobrança com Split](/documentations/split/split) e [Split em sessão ou link](/documentations/split/split-em-sessao-link), com `splitRules` e sellers válidos para o merchant da transação. > 3. **Estorno:** para estorno parcial com divisão entre recebedores, continue usando `splitRules` na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) conforme a documentação de split — não dependa mais de `isPayoutEligible`. ## O que não muda * **Split de pagamentos** via `splitRules` em cobranças diretas, sessões e links permanece suportado conforme a [documentação de split](/documentations/split/intro). * **APIs de Payouts** (`GET /v1/payouts/*`) para saldo, repasses e ordens de pagamento da subadquirente — funcionalidade distinta, sem relação com `payout_eligible`. Veja [Payouts](/api-reference/payouts/consultar-saldo-de-payouts). > [!TIP] > > Resumo: > >
    >
  • Split agnóstico e payout eligible descontinuados
    • >
  • `merchantId` obrigatório ao trabalhar com sellers em novas integrações
    • >
  • Split via `splitRules` e APIs de Payouts seguem documentados e ativos
    • >
# June 18, 2026 - Platform Fee Source: https://docs.malga.io/release-notes/2026-06-18-Release-Notes Taxas de plataforma por método de pagamento nos merchants ![Filippe Rodrigues](https://github.com/filipperodrigues.png) [Filippe Rodrigues](https://github.com/filipperodrigues) Tech Lead ![Dennis Quintal](https://github.com/dennisqq.png) [Dennis Quintal](https://github.com/dennisqq) Software Engineer Novidade na Malga! Agora você pode configurar **taxas de plataforma (platform fee)** diretamente nos seus merchants via API. Se você opera um marketplace ou plataforma, essa funcionalidade permite definir regras de cobrança por método de pagamento de forma simples e flexível com suporte a percentual, valor fixo ou ambos combinados. ## Como funciona O platform fee é simples de configurar e opera em dois níveis: 1. **Ativação**: Uma flag no merchant habilita ou desabilita a aplicação das taxas. Enquanto desativada, nenhuma regra é aplicada nas transações, dando total controle sobre quando começar a cobrar. 2. **Regras por método de pagamento**: Cada regra define a taxa para um método específico (`credit`, `pix`, `boleto`). Para cartão de crédito, as regras são configuradas por **faixa de parcelamento**. As regras suportam cobrança por **percentual** (0-100%), **valor fixo** em centavos, ou **ambos combinados** adaptando-se ao modelo de negócio que fizer mais sentido para você. ## Faixas de parcelamento para crédito Para o método de pagamento `credit`, o campo `installment` é **obrigatório** e o valor informado (1 a 24) é automaticamente associado a uma das quatro faixas: | Faixa | Parcelas | | - | - | | À vista | 1 | | 2x a 6x | 2 a 6 | | 7x a 12x | 7 a 12 | | 13x a 24x | 13 a 24 | Cada merchant pode ter **no máximo uma regra por faixa**. O valor original informado é preservado na resposta da API. ### Exemplo Se você criar uma regra com `installment: 5`, ela cobrirá a faixa **2x a 6x**. Ao tentar criar outra regra com `installment: 3` (mesma faixa), a API retornará `409 Conflict` com a mensagem indicando que já existe uma regra para a faixa 2x a 6x. ### Outros detalhes * O método de pagamento `default` **não aceita** o campo `installment`. Ele funciona exclusivamente como regra de fallback para métodos sem regra específica. * Para `pix` e `boleto`, uma regra por método, sem parcelamento. ## Novos endpoints * `PATCH /v1/merchants/{merchantId}/platform-fee/enabled`: Ativar ou desativar platform fee * `POST /v1/merchants/{merchantId}/platform-fee`: Criar regras de taxa * `GET /v1/merchants/{merchantId}/platform-fee`: Listar regras ativas * `PUT /v1/merchants/{merchantId}/platform-fee`: Atualizar regras existentes * `DELETE /v1/merchants/{merchantId}/platform-fee/{platformFeeId}`: Remover regras Para mais detalhes, consulte a [referência da API](/api-reference/merchants/criar-regras-de-platform-fee). > [!TIP] > > Features: > > 1. Configuração de taxas de plataforma por método de pagamento (credit, pix, boleto) > 2. Suporte a percentual, valor fixo ou ambos combinados > 3. Regras por faixa de parcelamento para cartão de crédito (à vista, 2x-6x, 7x-12x, 13x-24x) > 4. Ativação/desativação independente via flag no merchant > 5. CRUD completo de regras via API # June 30, 2026 - Instruções de boleto em sessões Source: https://docs.malga.io/release-notes/2026-06-30-Release-Notes Envie instruções de boleto (vencimento, juros, multa) ao criar uma sessão de link de pagamento por meio do campo instructions no paymentMethod do boleto. ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer Novidade na Malga! Agora você pode enviar **instruções de boleto** diretamente na criação de uma sessão de link de pagamento por meio do campo `instructions` no `paymentMethod` do boleto. Esse campo atende fluxos de ERP e cobrança que precisam repassar instruções como vencimento, juros e multa ao provedor de boleto, com o mesmo comportamento já existente nas cobranças via API. ## Como funciona O campo `instructions` é **opcional e anulável** e aceita uma string de até **255 caracteres**. Quando omitido ou enviado como `null`, a sessão é criada normalmente. Utilize `\n` para incluir quebras de linha na instrução exibida no boleto. ### Exemplo ```bash Request theme={null} curl --location 'https://api.malga.io/v1/sessions' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "merchantId": "", "paymentMethods": [ { "paymentType": "boleto", "expiresDate": "2026-01-01", "instructions": "Não receber após o vencimento. Multa de 2% e juros de 1% ao mês." } ] }' ``` Na consulta da sessão, o campo `instructions` é retornado no objeto `paymentMethod` do boleto, espelhando o valor informado na criação. Para mais detalhes, consulte a [referência de criação de sessão](/api-reference/sessions/criar-nova-sessao). > [!TIP] > > Features: > > 1. Campo `instructions` no `paymentMethod` do boleto na criação de sessões > 2. Campo opcional e anulável, com limite de 255 caracteres > 3. Paridade de comportamento com as cobranças via API > 4. Suporte a quebras de linha com `\n` # July 13, 2026 - Antifraude no link de pagamento Source: https://docs.malga.io/release-notes/2026-07-13-Release-Notes Ative monitoramento antifraude no link de pagamento da Malga via SDK, com identificação de dispositivos e integração ao fluxo inteligente de crédito. ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer Mais segurança para seus clientes! Agora você pode monitorar dispositivos no link de pagamento para evitar fraudes e garantir uma melhor experiência para seus clientes. Após criar um fluxo inteligente com um provedor de antifraude, seus [links de pagamento](/documentations/payment-link/intro) estarão sendo monitorados por SDKs disponibilizados pelos antifraudes, que agem na verificação e identificação dos dispositivos dos clientes, que estão usando o link de pagamento. ## Como funciona Você não precisa fazer nada para começar a ter essa funcionalidade. Basta observar se já possui a seguinte configuração: * [Fluxo inteligente](/documentations/flow-guide/introduction) de crédito ativo para o merchant que você deseja criar o link de pagamento. * Um provedor de antifraude configurado nesse fluxo E então, ao criar o link de pagamento, [provedores como ClearSale, Konduto e B2E](/documentations/type-tables/antifraude-providers) estarão realizando coletas e análise de informações públicas da máquina do usuário, incluindo se já é conhecida no provedor e o histórico de ações. Isso garante maior agilidade na identificação de fraudes e melhoria na aprovação de transações. Ficou com alguma dúvida? Entre em contato com a nossa equipe de suporte: [support@malga.com.br](mailto:support@malga.com.br) # July 16, 2026 - Subacquirer e updatedAt na Analytics API Source: https://docs.malga.io/release-notes/2026-07-16-Release-Notes Novo grupo de queries Subacquirer na Analytics API com a query balance, e novos filtros por updated_at e o campo updatedAt no grupo Charges. ![Paulo Chaves](https://github.com/paulosdchaves.png) [Paulo Chaves](https://github.com/paulosdchaves) Data Engineer Novidade na Analytics API! Agora você pode consultar o **saldo do subadquirente** pelo novo grupo de queries **Subacquirer**, além de filtrar as cobranças do grupo **Charges** pela data de última atualização. ## Subacquirer — consulta de saldo Disponibilizamos a query `balance` no grupo [Subacquirer](/analytics/queries/subacquirer), com paridade com a API oficial `/v1/payouts/balance`. Ela retorna o saldo disponível e o saldo a receber do subadquirente, podendo ser filtrada por `feature` e `sellerId`. * `feature`: define o contexto do saldo (`NUPAY`, `SUBACQUIRER`, `GENERAL`, `SUBACQUIRER_PREPAYMENT`), com padrão `SUBACQUIRER`. * `sellerId`: filtra o saldo de um recebedor específico. Quando omitido, retorna o saldo do client master. O objeto de retorno é o [SubacquirerBalance](/analytics/objects/subacquirer-balance), com os campos `available`, `receivable`, `feature` e `currency`. ## Charges — filtro por atualização No grupo [Charges](/analytics/queries/charges), adicionamos os argumentos `updatedStartDate` e `updatedEndDate` em todas as queries, permitindo filtrar cobranças pelo campo `updated_at`. Esses filtros são independentes e combináveis com `startDate`/`endDate` (que filtram por `created_at`). Além disso, o objeto [Charge](/analytics/objects/charge) passa a retornar o campo `updatedAt`, com a data da última atualização da cobrança. > [!TIP] > > Features: > > 1. Novo grupo de queries Subacquirer com a query `balance` > 2. Objeto de retorno `SubacquirerBalance` (`available`, `receivable`, `feature`, `currency`) > 3. Filtros `updatedStartDate`/`updatedEndDate` em todas as queries do grupo Charges > 4. Campo `updatedAt` no objeto `Charge` # July 20, 2026 - Simulação de status de recebedor no Sandbox Source: https://docs.malga.io/release-notes/2026-07-20-Release-Notes Simule o ciclo de vida do recebedor no Sandbox: status inicial derivado do documento, endpoint para troca manual e webhook seller.. ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer Agora é possível simular o ciclo de vida de um **recebedor** no ambiente de **Sandbox**, assim como já acontecia com as cobranças: o recebedor nasce com um status determinístico, você pode alterar o status manualmente e recebe o webhook `seller.` a cada mudança. ## Status inicial derivado do documento Ao criar um recebedor no Sandbox, o status inicial é derivado do **último dígito do documento**, considerando o `owner.document.number` e, na sua ausência, o `business.document.number` (nessa ordem de prioridade). | Documento | Status inicial | | - | - | | Final 7 | `pending` | | Final 8 | `inactive` | | Final 9 | `failed` | | Qualquer outro final | `active` | ## Troca manual de status Um novo endpoint permite alterar manualmente o status de um recebedor no Sandbox, disparando o webhook correspondente: `POST /v1/sellers/{id}/status` Consulte os detalhes em [Alterar o status de um recebedor no ambiente de sandbox](/api-reference/sellers/alterar-o-status-de-um-recebedor-no-ambiente-de-sandbox) e o mapeamento completo no [Guia de teste](/documentations/welcome/testing). > [!TIP] > > Features: > > 1. Status inicial do recebedor derivado do documento no Sandbox > 2. Novo endpoint `POST /v1/sellers/{id}/status` para troca manual de status > 3. Webhook `seller.` disparado a cada mudança (criação e troca manual) # Ago 04, 2026 - Apple Pay WorldPay e disputa SafraPay (Beta) Source: https://docs.malga.io/release-notes/2026-08-04-Release-Notes O Apple Pay chega às cobranças roteadas pela WorldPay e a SafraPay passa a enviar notificação de abertura de disputa, ambos em Beta na Malga. ![Stefano](https://github.com/stefanosandes.png) [Stefano](https://github.com/stefanosandes) Software Engineer ![Manu](https://github.com/manucirne.png) [Manu](https://github.com/manucirne) Software Engineer ## Apple Pay na WorldPay (Beta) O **Apple Pay** passa a ser suportado pela API da Malga em cobranças roteadas pela **WorldPay**. > [!NOTE] > > Esta integração está em **Beta**. A funcionalidade já pode ser utilizada, mas o fluxo e a documentação podem evoluir nas próximas versões. Confira a matriz de capacidades da [WorldPay](/documentations/providers/worldpay) e o guia de [Apple Pay](/documentations/payment-methods/apple-pay/intro). ## Notificação de disputa na SafraPay (Beta) A Malga passa a receber e repassar a **notificação de abertura de disputa** (webhook de início da operação de disputa) para cobranças processadas pela **SafraPay**, via o evento `transaction.dispute`. > [!NOTE] > > Este suporte está em **Beta** e cobre **somente o recebimento do webhook de início de operação de disputa**. **Não há integração com a API completa de chargeback** do provedor (defesa, consulta ou tratamento completo de chargeback via API). Consulte a página da [SafraPay](/documentations/providers/safrapay), a tabela de provedores em [detalhes da cobrança](/documentations/dashboard/charge-details#provedores-com-suporte-à-notificação-de-abertura-de-disputa) e a documentação de [webhooks](/documentations/webhooks/webhook1-1). # Ago 10, 2026 - Koin Source: https://docs.malga.io/release-notes/2026-08-10-Release-Notes A Malga integra o antifraude Koin à plataforma, com suporte a análise síncrona e assíncrona de transações para prevenção a fraudes online. ![Leandro Araujo](https://github.com/leandroaraujo-malga.png) [Leandro Araujo](https://github.com/leandroaraujo-malga) Software Engineer Tem provedor antifraude novo na Malga! 🎉 A Malga agora conta com o [Koin](https://www.koin.com.br) Antifraude integrado à plataforma, com suporte a análise síncrona e assíncrona de transações. [Veja a documentação completa](/documentations/providers-antifraud/koin) # Ago 26, 2026 - Melhoria em Cards no Analytics API Source: https://docs.malga.io/release-notes/2026-08-26-Release-Notes A Analytics API ganha as queries cards e card no novo índice card, com tokens e transaction requests aninhados; a query allCards foi depreciada. ![Paulo Chaves](https://github.com/paulosdchaves.png) [Paulo Chaves](https://github.com/paulosdchaves) Data Engineer Novidade na Analytics API! O grupo **Cards** agora conta com as consultas `cards` e `card`, que utilizam o novo índice `card` com os objetos aninhados `tokens` e `transactionRequests`. ## Cards — novas consultas No grupo [Cards](/analytics/queries/cards) disponibilizamos duas novas consultas: * `cards`: retorna os cartões a partir do novo índice `card`. Mantém paridade de argumentos com `allCards` (o filtro de identificador passa a se chamar `id`) e adiciona novos filtros: * Objetos aninhados: `tokenStatus`, `tokenFingerprint`, `tokenProviderType` e `providerType` (consultas em `tokens` e `transactionRequests`). * Raiz do cartão: `sellerId`, `merchantId`, `fingerprint`, `expirationMonth` e `expirationYear`. * Data de atualização: `updatedStartDate` e `updatedEndDate`. * `card`: retorna um único cartão pelo `id`, também a partir do índice `card`. O objeto de retorno traz os campos de raiz do cartão (como `id`, `clientId`, `customerId`, `status`, `brand`, `holderName`, `createdAt`, `updatedAt`, `merchants`, `sellers`, `fingerprint`) e os objetos aninhados `tokens` e `transactionRequests`. ## Depreciação — allCards A consulta `allCards` está **depreciada** e será **descontinuada em 2027**. Ela continua funcionando normalmente até lá, mas recomendamos a migração para a nova consulta `cards`. O principal ajuste é o filtro de identificador, que deixa de ser `cardId` e passa a se chamar `id`. > [!WARNING] > > A query `allCards` será descontinuada em **2027**. Planeje a migração para `cards` (índice `card`), lembrando que o argumento `cardId` foi renomeado para `id`. > [!TIP] > > Features: > > 1. Nova query `cards` no grupo Cards (índice `card`, com `tokens` e `transactionRequests` aninhados) > 2. Nova query `card` para consulta de um único cartão pelo `id` > 3. Novos filtros: `sellerId`, `merchantId`, `fingerprint`, `tokenFingerprint`, `tokenProviderType`, `providerType`, `expirationMonth`, `expirationYear`, `updatedStartDate`/`updatedEndDate` > 4. Depreciação da query `allCards` (descontinuação em 2027) # Ago 31, 2026 - Listagem de antecipações e notificação de repasse no recebedor Source: https://docs.malga.io/release-notes/2026-08-31-Release-Notes Novo endpoint de listagem paginada das antecipações avulsas e novo campo notifyOnPayout na criação e na atualização de recebedores. ![Leonardo Pinheiro](https://github.com/0xleozera.png) [Leonardo Pinheiro](https://github.com/0xleozera) Tech Lead Duas novidades nesta release: a **antecipação avulsa** ganhou um endpoint de listagem, e os **recebedores** passam a controlar se devem ser notificados quando ocorre um repasse. ## Antecipação avulsa — listagem de antecipações Até agora, consultar uma antecipação exigia guardar o `id` devolvido na simulação. Com o novo endpoint [Listar antecipações](/api-reference/prepayment/listar-antecipacoes), você consulta o histórico completo da sua conta em uma única chamada: ```bash theme={null} curl --location 'https://api.malga.io/v1/subacquirer/prepayment?page=1&limit=10' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` Pontos importantes do contrato: * A listagem é escopada pelo `X-Client-Id`, ou seja, devolve apenas as antecipações da sua conta. * Os resultados vêm da mais recente para a mais antiga. * A paginação usa `page` (padrão `1`) e `limit` (padrão `10`, máximo `100`). Valores acima do máximo são limitados a `100`. * Cada item traz exatamente os mesmos campos da consulta por identificador, incluindo a lista de recebíveis em `items`. Não é preciso consultar cada antecipação individualmente para ver os detalhes. * Simulações com status `pending` que já passaram do `expiresAt` são retornadas como `expired`, seguindo a mesma regra da consulta por identificador. A resposta segue o envelope de listagem já usado na plataforma, com `items` e `meta`: ```json theme={null} { "items": [ { "id": "687d7c26-d270-4b59-81c4-eb3af4eda2a8", "status": "pending", "grossAmount": 20000, "netAmount": 19323 } ], "meta": { "totalItems": 32, "itemCount": 10, "itemsPerPage": 10, "totalPages": 4, "currentPage": 1 } } ``` > [!NOTE] > > A **antecipação avulsa** segue em **Beta**. A funcionalidade está disponível para clientes habilitados, e detalhes da API podem evoluir nas próximas versões. Para habilitar sua conta, fale com o suporte pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). ## Recebedores — campo notifyOnPayout Os endpoints de [criação](/api-reference/sellers/criacao-de-um-novo-recebedor) e de [atualização](/api-reference/sellers/atualizacao-de-recebedor-pelo-id) de recebedor aceitam o novo campo booleano opcional `notifyOnPayout`, na raiz do corpo da requisição. Ele define se o recebedor deve ser notificado quando ocorre um repasse. ```json theme={null} { "merchantId": "4101ad7b-caf7-4065-9fbc-74461715bff8", "notifyOnPayout": false } ``` O comportamento padrão é notificar. Quem não quiser isso precisa desligar a notificação explicitamente: * **Na criação:** quando o campo é omitido, o recebedor é criado com `notifyOnPayout` igual a `true`. * **Na atualização:** quando o campo é omitido, o valor atual do recebedor é mantido. Uma atualização parcial que não cita a flag não religa a notificação de um recebedor configurado com `false`. * **Nos recebedores existentes:** todos passam a responder `notifyOnPayout` igual a `true`. O campo também é devolvido nas respostas de criação, atualização, consulta por identificador e listagem de recebedores. > [!TIP] > > Features: > > 1. Novo endpoint `GET /v1/subacquirer/prepayment` para listar as antecipações da conta, com paginação por `page` e `limit` > 2. Novo campo opcional `notifyOnPayout` em `POST /v1/sellers` e `PATCH /v1/sellers/{id}` > 3. Campo `notifyOnPayout` incluído nas respostas dos endpoints de recebedor > [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Set 01, 2026 - Composição financeira no detalhe da cobrança Source: https://docs.malga.io/release-notes/2026-09-01-Release-Notes O detalhe da cobrança agora mostra o bloco Composição financeira, com valor bruto, taxas e valor líquido das cobranças processadas pelo provedor Malga. ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer Agora, ao abrir o detalhe de uma cobrança **processada pelo provedor Malga**, você encontra o bloco **Composição financeira**, com o passo a passo de como chegamos ao valor que você recebe. ## Composição financeira no detalhe da cobrança Nele você vê, para cada cobrança: * **Valor bruto:** o valor total cobrado do seu cliente. * **Taxa:** o percentual e o valor descontado, incluindo a taxa de antecipação quando você antecipa o recebível. * **Valor líquido:** o valor final que cai para você. Em casos de estorno, o desconto da taxa correspondente também aparece na composição, assim que o estorno é confirmado. ![Bloco Composição financeira no detalhe da cobrança, com valor bruto, taxa e valor líquido](https://mintcdn.com/malga/IXQMXdPsWom6nHhO/assets/images/dashboard/charge-details/financial-composition-light.png?fit=max\&auto=format\&n=IXQMXdPsWom6nHhO\&q=85\&s=59d858b9a6fbac7a5f0085b39850a38f) Com isso, fica mais fácil conferir e reconciliar cada cobrança sem precisar cruzar informações em outros relatórios. Para saber mais sobre o detalhe da cobrança no Dashboard, consulte o [guia de Gestão de Cobranças](/documentations/dashboard/charge-details). > [!TIP] > > Principais novidades: > >
    >
  • Novo bloco **Composição financeira** no detalhe das cobranças processadas pelo provedor Malga.
    • >
  • Detalhamento de **valor bruto**, **taxa** (percentual e valor, incluindo a taxa de antecipação) e **valor líquido**.
    • >
  • Desconto da taxa correspondente exibido na composição quando o estorno é confirmado.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Set 08, 2026 - Revisão cadastral de recebedores Source: https://docs.malga.io/release-notes/2026-09-08-Release-Notes Novos endpoints para consultar e responder os processos de revisão cadastral abertos pelo provedor, com seis eventos de webhook acompanhando cada etapa. ![Alberto Martins](https://github.com/albertomalga.png) [Alberto Martins](https://github.com/albertomalga) Software Engineer O provedor pode pedir a atualização do cadastro dos seus recebedores, e agora esse pedido chega até você pela API. Disponibilizamos três endpoints para acompanhar e responder os processos de **revisão cadastral**, além de seis eventos de webhook que avisam a cada mudança. ## Por que isso existe A **Resolução BCB 4.658** obriga a instituição a manter o cadastro dos recebedores atualizado. O provedor cumpre isso abrindo processos de revisão em duas modalidades: a **atualização cadastral periódica (ACP)**, do ciclo regular, e a **atualização por inconsistência (ACI)**, aberta quando um dado divergente é detectado e que já entra em cobrança ativa. Quem coleta o dado com o recebedor é você. A Malga transporta o pedido, valida o que você envia contra a lista de campos que o provedor solicitou, e devolve a resposta dele. ## Consultar os processos Duas rotas de leitura, com filtros por status, tipo e prazo: * [`GET /v1/sellers/registration-reviews`](/api-reference/sellers/listar-processos-de-revisao-cadastral) — todos os processos abertos para os seus recebedores. * [`GET /v1/sellers/{sellerId}/registration-reviews`](/api-reference/sellers/listar-processos-de-revisao-cadastral-de-um-recebedor) — os processos de um recebedor. Cada processo traz a lista de campos pedidos já traduzida para o vocabulário da Malga, com o tipo de cada um, se é obrigatório e os valores aceitos quando houver. ## Enviar os dados coletados [`POST /v1/sellers/{sellerId}/registration-reviews/{processId}/submit`](/api-reference/sellers/enviar-dados-de-revisao-cadastral) recebe os dados junto com a **evidência da coleta** — quando foi coletado, por qual canal e em qual jornada. > [!WARNING] > > Os dados precisam vir de uma **coleta ativa** com o recebedor. Reaproveitar dado do onboarding, de bureau de crédito, de base interna ou de um envio anterior é vedado pelo provedor e sujeita o recebedor a penalidade. ## Eventos de webhook Seis eventos acompanham o ciclo de vida do processo: | Evento | Quando chega | | - | - | | `seller.registration_review.required` | O provedor abriu o processo | | `seller.registration_review.reminder` | Lembrete enquanto o processo segue sem envio | | `seller.registration_review.overdue` | O processo entrou em cobrança ativa | | `seller.registration_review.expired` | O prazo venceu sem envio | | `seller.registration_review.failed` | O provedor recusou a submissão | | `seller.registration_review.finished` | O provedor confirmou o recebimento | Os detalhes de cada payload estão no [guia de webhooks](/documentations/webhooks/webhook1-1#eventos-de-revisão-cadastral). > [!TIP] > > Features: > > 1. Consulta dos processos de revisão cadastral, de todos os recebedores ou de um > 2. Envio dos dados coletados com evidência da coleta > 3. Seis eventos de webhook cobrindo abertura, lembrete, vencimento, expiração, recusa e encerramento > 4. Guia completo do fluxo em [Revisão cadastral](/documentations/split/revisao-cadastral) # Set 09, 2026 - Relatório de parcelas Source: https://docs.malga.io/release-notes/2026-09-09-Release-Notes Novo relatório de parcelas no Dashboard, com a data estimada de recebimento e o valor líquido de cada parcela das cobranças processadas pelo provedor Malga. ![Leonardo Pinheiro](https://github.com/0xleozera.png) [Leonardo Pinheiro](https://github.com/0xleozera) Tech Lead ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer Saber quando cada parcela de uma venda cai na conta era uma informação que você só conseguia pedindo para o nosso time. Agora ela está no Dashboard: em **Relatórios**, você encontra o **Relatório de parcelas**, com a data prevista de recebimento e o valor líquido de cada parcela. ## Relatório de parcelas O relatório abre parcela a parcela cada cobrança do período e traz, para cada uma: * **Data estimada do repasse:** quando aquela parcela deve cair na sua conta. * **Valor bruto e valor líquido da parcela:** o que foi cobrado e o que sobra depois da taxa. * **Valor e percentual de taxa:** quanto foi descontado naquela parcela. * **Identificação da venda:** data de criação, ID da cobrança, subconta, recebedor, cliente, método de pagamento, bandeira e status final. ![Tela de Relatórios no Dashboard, com o Relatório de parcelas na listagem e o botão Exportar](https://mintcdn.com/malga/8qwEMHNiJVEV-efd/assets/images/dashboard/reports/installment-report-light.gif?s=37a53a25d35b85d6d8b6c254c34df40f) ## Como exportar O fluxo é o mesmo dos outros relatórios de cobrança: você escolhe o período, aplica os filtros e recebe o arquivo por e-mail. * **Período:** de D-1 até 31 dias, aplicado sobre a **data de criação da cobrança**. Você seleciona vendas já realizadas, e o relatório traz as parcelas delas com as datas de recebimento, que podem estar no passado ou no futuro. * **Filtros:** subconta, recebedor e método de pagamento. > [!NOTE] > > O relatório está disponível para clientes Malga Sub, contempla apenas cobranças do provedor Malga e não inclui parcelas bloqueadas. Os valores e as datas são estimativas, sujeitas a alteração por mudanças nas vendas, negociações ou cobranças realizadas. > [!TIP] > > Principais novidades: > >
    >
  • Novo **Relatório de parcelas** na tela de Relatórios do Dashboard.
    • >
  • **Data estimada do repasse**, valor bruto, valor líquido e taxa de cada parcela.
    • >
  • Filtros de período (data de criação da cobrança), subconta, recebedor e método de pagamento.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Set 15, 2026 - Documentos comprobatórios de estorno Source: https://docs.malga.io/release-notes/2026-09-15-Release-Notes Carta de cancelamento e comprovante de estorno em PDF para cobranças estornadas, disponíveis no detalhe da cobrança no Dashboard e pela API. ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer ![Leonardo Pinheiro](https://github.com/0xleozera.png) [Leonardo Pinheiro](https://github.com/0xleozera) Tech Lead A Malga agora emite os documentos que comprovam o estorno de uma cobrança. No detalhe da cobrança estornada você baixa a **carta de cancelamento** e o **comprovante de estorno** em PDF, prontos para enviar ao comprador ou ao banco emissor. ## Documentos disponíveis * **Carta de cancelamento:** endereçada ao banco emissor, traz NSU, código de autorização, cartão, o valor da venda e o valor do cancelamento. Serve para o portador pedir a liberação do limite sem esperar o ciclo do estorno. Emitida por evento: cada estorno parcial gera a sua própria carta. Disponível apenas para cartão de crédito. * **Comprovante de estorno:** endereçado ao comprador, consolida em um único arquivo todos os estornos confirmados da cobrança, com o total estornado, o valor final e a lista de eventos. Em cobranças Pix, o comprovante traz o identificador de cada devolução, com o qual o comprador localiza o crédito no banco dele. ![Detalhe de uma cobrança com estornos confirmados no Dashboard, com o download da carta de cancelamento e do comprovante de estorno](https://mintcdn.com/malga/6gcXtNzgxD90TuA0/assets/images/dashboard/charge-details/refund-documents-light.gif?s=5cbf1065e6e7ecd4181c046bbca29680) ## Como baixar Os botões ficam no detalhe da cobrança, na área de ações, e aparecem depois que o primeiro estorno é confirmado pelo provedor. Enquanto o estorno está em processamento, você acompanha pelo status e pelo histórico da cobrança. * **Carta de cancelamento:** com um único estorno, o clique baixa a carta. Com mais de um, baixa um arquivo `.zip` com uma carta por evento. * **Comprovante de estorno:** sempre um arquivo único, gerado no momento do clique com todos os estornos já confirmados. A cada novo estorno, um novo download traz o comprovante atualizado. ## Pela API Os mesmos documentos são gerados por `POST /v1/subacquirer/{transactionId}/receipts`, informando `cancellation_letter` ou `refund_receipt` no campo `type`. A resposta traz a URL de download do arquivo, o que permite exibir o documento dentro do seu próprio produto. Detalhes em [Gerar documento comprobatório de estorno](/api-reference/receipts/gerar-documento-comprobatorio). > [!NOTE] > > Os documentos estão disponíveis apenas para cobranças do provedor Malga. O documento só é emitido depois que o provedor confirma o estorno, e a carta de cancelamento não existe para cobranças Pix. > [!TIP] > > Principais novidades: > >
    >
  • **Carta de cancelamento** em PDF, por evento de estorno, para cobranças de cartão de crédito.
    • >
  • **Comprovante de estorno** consolidado por cobrança, com a lista de estornos confirmados.
    • >
  • Download no detalhe da cobrança no Dashboard e geração pela API.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Set 22, 2026 - Planos de venda no provedor Malga Source: https://docs.malga.io/release-notes/2026-09-22-Release-Notes Planos de venda no provedor Malga permitem prazos de recebimento diferentes por recebedor e por transação, com políticas como Fluxo, D+2, D+15 e D+30. ![Jean Castro](https://github.com/jeanvcastro.png) [Jean Castro](https://github.com/jeanvcastro) Software Engineer Quem usa o provedor Malga, a subadquirência da Malga, agora pode ter mais de uma política comercial no mesmo `client_id`. O prazo de recebimento deixa de ser único para todos os recebedores. As políticas contratadas com a Malga (Fluxo, D+2, D+15, D+30) são organizadas em planos de venda, que podem ser aplicados por recebedor e por transação. ## Como o plano é aplicado na transação Cada recebedor é liquidado pelo plano vinculado a ele. Quem não tem plano próprio segue o plano padrão da sua conta. No split, o campo `transactionOwner` define qual plano vale para a transação inteira. Ao marcar um participante com `transactionOwner: true`, o plano dele passa a valer para todas as participações. Sem `transactionOwner`, cada participante é liquidado pelo próprio plano. ## Listar os planos de venda [`GET /v1/subacquirer/plans`](/api-reference/subacquirer/listar-planos-de-venda) retorna os planos cadastrados para a sua conta, com nome, status, políticas comerciais e taxas de cada um. É por aqui que você descobre o `id` do plano que vai vincular a um recebedor. ## Vincular um plano ao recebedor O campo `planId` faz o vínculo, tanto na [criação](/api-reference/sellers/criacao-de-um-novo-recebedor) quanto na [atualização](/api-reference/sellers/atualizacao-de-recebedor-pelo-id) do recebedor. Se você não informar o `planId`, o recebedor segue o plano padrão da sua conta. ## Desvincular um plano do recebedor [`DELETE /v1/sellers/{id}/plan`](/api-reference/sellers/desvincular-plano-de-venda-de-um-recebedor) remove o vínculo do recebedor com o plano atual, que volta a seguir o plano padrão da sua conta. > [!TIP] > > Features: > > 1. Novo endpoint `GET /v1/subacquirer/plans`, com paginação e filtro por status > 2. Novo endpoint `DELETE /v1/sellers/{id}/plan` para desvincular o plano de um recebedor > 3. Campo `planId` na criação e na atualização de recebedores para vincular um plano > [!NOTE] > > Ficou com dúvida? [suporte@malga.io](mailto:suporte@malga.io) # Set 23, 2026 - Descrição na fatura em cobranças Rede Source: https://docs.malga.io/release-notes/2026-09-23-Release-Notes Como a Rede monta a descrição exibida na fatura do comprador e o que muda no tratamento do statementDescriptor enviado pela Malga. ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer O texto que aparece na fatura do comprador em cobranças processadas pela [Rede](/documentations/providers/rede) agora é tratado antes do envio ao provedor. A mudança evita descrições cortadas no lugar errado e ajuda a manter a taxa de aprovação. ## Como a Rede monta a descrição na fatura A Rede envia para a bandeira uma linha de até **22 caracteres**, composta por duas partes separadas por `*`: * **Hard descriptor:** o nome do estabelecimento, cadastrado no portal da Rede. O `*` já faz parte dele e conta como 1 caractere. * **Soft descriptor:** o valor que você envia no campo `statementDescriptor` da cobrança. Aceita até 18 caracteres. Quando a soma passa de 22, a Rede corta o **hard descriptor** para caber o soft descriptor inteiro, até sobrarem só 3 caracteres do nome do estabelecimento. Por exemplo, com o hard descriptor `SUALOJA*` (8 caracteres) e o `statementDescriptor` `PLANOPREMIUMANUAL` (17 caracteres): | Envio | Fatura do comprador | | - | - | | `PLANOPREMIUMANUAL` (17) | `SUAL*PLANOPREMIUMANUAL` — o nome da loja é cortado | | `PLANOPREMIUM` (12) | `SUALOJA*PLANOPREMIUM` — o nome da loja aparece completo | ## O que muda * **Asterisco e caracteres especiais removidos:** a Malga remove do `statementDescriptor` o asterisco e os caracteres especiais, e troca letras acentuadas pela versão sem acento. O `*` enviado por você seria lido como um segundo separador e deixaria a fatura inconsistente. * **Espaços mantidos:** o espaço simples entre palavras é preservado. Espaços repetidos viram um só, e o espaço que sobrar no fim depois do corte é removido. * **Limite de 18 caracteres:** o `statementDescriptor` é cortado em 18 caracteres, contados já depois da limpeza. * **Malga Sub:** nas cobranças da subadquirência Malga, o hard descriptor é `MALGA*` (6 caracteres). Nesse caso, o `statementDescriptor` é limitado a 16 caracteres e **sem espaços**, para que o nome `MALGA` continue completo na fatura, como exige a regulação. | Envio | Valor enviado para a Rede | Valor enviado no Malga Sub | | - | - | - | | `LOJA*PEDIDO` | `LOJAPEDIDO` | `LOJAPEDIDO` | | `LOJA * DO JOSE` | `LOJA DO JOSE` | `LOJADOJOSE` | | `Padaria São João Ltda.` | `Padaria Sao Joao L` | `PadariaSaoJoaoLt` | ## Site do Vendor Em cobranças com [Vendor](/documentations/vendors/intro), o campo `website` do Vendor é enviado à Rede só com o domínio (sem `https://`, `www.` e caminho) e limitado a **25 caracteres**. Por exemplo, `https://backoffice.aviva.barte.com/seller/3202` é enviado como `backoffice.aviva.barte.co`. ## O que recomendamos Calcule o tamanho do `statementDescriptor` a partir do seu hard descriptor: **22 − tamanho do hard descriptor (com o `*`)**. Com `SUALOJA*`, por exemplo, sobram 14 caracteres. Os espaços contam como caracteres, então prefira descrições curtas. > [!TIP] > > Principais novidades: > >
    >
  • Asterisco e caracteres especiais removidos do `statementDescriptor` em cobranças Rede, mantendo o espaço simples entre palavras.
    • >
  • Limite de 16 caracteres, sem espaços, no Malga Sub, para manter o `MALGA*` completo na fatura.
    • >
  • Site do Vendor enviado à Rede com até 25 caracteres.
    • >
  • Recomendação de tamanho do `statementDescriptor` a partir do seu hard descriptor.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Set 24, 2026 - Dashboard: seletor de empresa e subcontas no menu lateral Source: https://docs.malga.io/release-notes/2026-09-24-Release-Notes Seletor de contexto no menu lateral para alternar entre visão Empresa e subconta. ![Lari](https://github.com/lariane-guerra.png) [Lari](https://github.com/lariane-guerra) Software Engineer ![Lucas Saraiva](https://github.com/lucassaraiva5.png) [Lucas Saraiva](https://github.com/lucassaraiva5) Software Engineer ## Dashboard: seletor de empresa e subcontas no menu lateral Agora você escolhe o contexto uma única vez, no topo do menu lateral, e ele vale para toda a navegação do Dashboard. * **Seletor de contexto**: alterne entre a visão consolidada da empresa e a visão de uma subconta específica, com busca por nome. * **Conta principal**: marque com a estrela a conta que deve abrir por padrão. * **Menus por contexto**: Financeiro aparece na visão Empresa; Links de pagamento e Fluxos inteligentes, na visão de uma subconta. * **Filtros**: o filtro de subconta fica disponível na visão Empresa, e o novo filtro de recebedor aparece nas duas visões. * **Formulários mais curtos**: criar link de pagamento e criar fluxo inteligente não pedem mais a subconta — usam a que está ativa no seletor. * **Gerenciar subcontas** passa para o rodapé do seletor, e o menu **Usuários** agora se chama **Equipe e permissões** (disponível na visão Empresa). Saiba mais em [Navegação por empresa e subcontas](/documentations/dashboard/context-selector). ## Taxa da plataforma por parcela A [taxa da plataforma](/documentations/split/platform-fee) no cartão de crédito agora pode ter um valor diferente para cada número de parcelas, de 1x a 24x. Você ajusta a taxa de cada parcela ao seu custo e confere o resultado antes de vender. * **Parcela exata no lugar de faixas**: a regra de crédito com `installment: 3` vale só para vendas em 3x. Antes, as regras eram agrupadas por faixa (1x, 2x-6x, 7x-12x, 13x-24x). * **Tabela por parcela**: cadastre a taxa de crédito parcela a parcela com `installmentRates` (só percentual) ou `installments` (percentual e valor fixo). Veja [Taxa de crédito por parcela](/documentations/split/platform-fee#taxa-de-crédito-por-parcela). * **Tabela por fórmula**: envie `maxInstallments`, `base` e, se quiser, `growth`, `surcharges`, `overrides` e `cap`. A Malga gera e grava uma regra para cada parcela. Veja [Cadastrando a tabela por fórmula](/documentations/split/platform-fee#cadastrando-a-tabela-por-fórmula). * **Simulação da taxa**: informe `simulationAmount` em [`GET /v1/merchants/{merchantId}/platform-fee`](/api-reference/merchants/listar-regras-de-platform-fee) para ver a taxa e o valor líquido dos recebedores em cada método e parcela. * **Substituição da tabela no `PUT`**: com tabela ou fórmula, [`PUT /v1/merchants/{merchantId}/platform-fee`](/api-reference/merchants/atualizar-regras-de-platform-fee) substitui a tabela de crédito inteira e remove as parcelas que ficaram de fora. Envie sempre a tabela completa. * **`PUT` aplicado por inteiro**: se qualquer regra avulsa do corpo não existir, a resposta é `404` e a Malga não altera nenhuma regra. * **Corpo em array ou objeto**: o [`POST`](/api-reference/merchants/criar-regras-de-platform-fee) e o `PUT` aceitam um array de regras ou um objeto com a lista em `rules`. * **Chaves desconhecidas recusadas**: um campo com grafia errada, como `fixedamount` ou `capp`, agora recusa a requisição com `400` em vez de ser ignorado. > [!NOTE] > > A regra genérica `default` foi encerrada em 8 de outubro. Veja como fica a venda sem regra para a parcela em [Taxa de plataforma por recebedor](/release-notes/2026-10-08-Release-Notes). # Set 30, 2026 - Múltiplos cartões no Link de Pagamento e limite de falhas no estorno Source: https://docs.malga.io/release-notes/2026-09-30-Release-Notes O Link de Pagamento da Malga agora aceita múltiplos cartões: o pagador divide o valor da venda entre 2 ou 3 cartões de crédito em uma única compra. Estornos com falhas repetidas no provedor passam a ser recusados com 429 ou 422. ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer O Link de Pagamento agora aceita o método **múltiplos cartões**. O pagador pode dividir o valor da venda entre 2 ou 3 cartões de crédito em uma única compra. ## Como gerar Crie o link pela Dashboard ou via API. Você define a quantidade máxima de cartões (2 ou 3) e o limite de parcelas por cartão. * **Dashboard:** veja [Criando Links via Dashboard](/documentations/payment-link/create-link-using-dashboard). * **API:** inclua em `paymentMethods` um item com `paymentType: "multiple"`. Veja [Criando Links via API](/documentations/payment-link/create-link-using-api). O método fica disponível para subcontas com crédito habilitado. Você pode oferecê-lo junto com Pix, Boleto e cartão de crédito único. Em [links com múltiplos pagamentos (1:N)](/documentations/payment-link/intro), o método também está disponível. ## Como o cliente paga Em integrações via sessão, envie o ID da sessão no header e um `paymentMethod` com `type: "multiple"`, com os dados de cada cartão em `paymentSource`. Saiba mais em [Pagar uma sessão](/api-reference/sessions/pagar-uma-sessao). No link de pagamento, o pagador escolhe **Combinar cartões de crédito**: ![Checkout com a opção Combinar cartões de crédito](https://mintcdn.com/malga/P7v8TiBDPTpB8LMJ/assets/images/release/2026-09-30/multiple-light.png?fit=max\&auto=format\&n=P7v8TiBDPTpB8LMJ\&q=85\&s=7e4e0498126ed20189f289d72eeff794) 1. Se o link permitir até 3 cartões, ele escolhe pagar com 2 ou 3. 2. Ajusta quanto cobra em cada cartão. O valor mínimo por cartão é R\$ 1,00, e a soma precisa fechar o total do pedido. 3. Preenche os dados e o parcelamento de cada cartão. 4. Confirma o pagamento e acompanha a autorização de cada cartão na tela de processamento. ![Checkout com o preenchimento de cada cartão](https://mintcdn.com/malga/P7v8TiBDPTpB8LMJ/assets/images/release/2026-09-30/multiple-tabs-light.png?fit=max\&auto=format\&n=P7v8TiBDPTpB8LMJ\&q=85\&s=80200dc336f693d33687c47a9ff44969) Se algum cartão for recusado, o checkout mostra o resultado por cartão e o pagador pode tentar novamente. ## Eventos de webhook Sete novos eventos `purchase.*` acompanham a venda com múltiplos cartões. Eles são enviados somente na versão 1.1 dos webhooks. | Evento | Quando chega | | - | - | | `purchase.created` | A venda foi criada e a autorização foi enfileirada | | `purchase.charge_authorized` | Uma cobrança da venda foi autorizada | | `purchase.pre_authorized` | Todas as cobranças estão pré-autorizadas e a venda segue pendente | | `purchase.paid` | A venda foi paga | | `purchase.failed` | A venda falhou por recusa ou abandono de uma cobrança | | `purchase.cancelled` | A venda foi cancelada | | `purchase.void_failed` | O estorno das cobranças da venda esgotou as tentativas ou terminou com uma cobrança ainda retida | > [!WARNING] > > O evento de cancelamento é `purchase.cancelled`, com dois "L". Ao cadastrar o webhook, use exatamente essa grafia. Veja todos os eventos no [guia de webhooks](/documentations/webhooks/webhook1-1#eventos-purchase). ## Atualização: limite de falhas no estorno Quando o provedor recusa várias vezes o estorno de uma mesma cobrança, a Malga para de enviar novos pedidos de estorno ao provedor. O limite vale para a [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) em qualquer meio de pagamento. | HTTP code | `error.type` | Quando acontece | O que fazer | | - | - | - | - | | `429` | `too_many_requests` | O estorno falhou várias vezes seguidas. O tempo de espera aumenta conforme as falhas se acumulam. | Aguarde até o horário de `retry_after_at` e tente de novo. | | `422` | `unprocessable_entity` | A cobrança atingiu o limite total de falhas de estorno. O bloqueio é definitivo. | Não repita a requisição. Se necessário, fale com o suporte da Malga. | Nesses casos, a Malga não cria um novo `transactionRequest` e não altera o status da cobrança. Um estorno concluído com sucesso zera a contagem. Veja como tratar esses erros em [Limite de falhas no estorno](/documentations/more/limite-falhas-estorno) e na [tabela de erros da API](/documentations/welcome/errors). > [!TIP] > > Principais novidades: > >
    >
  • Novo método **Múltiplos cartões** no Link de Pagamento, com 2 ou 3 cartões.
    • >
  • Configuração na Dashboard ou via API: quantidade máxima de cartões e de parcelas.
    • >
  • Link com divisão do valor e autorização de cada cartão.
    • >
  • Sete novos eventos de webhook `purchase.*` para acompanhar a venda com múltiplos cartões.
    • >
  • Estornos com falhas repetidas no provedor recusados com `429` (aguarde `retry_after_at`) ou `422` (bloqueio definitivo).
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 08, 2026 - Taxa de plataforma por recebedor Source: https://docs.malga.io/release-notes/2026-10-08-Release-Notes Defina uma taxa diferente para cada recebedor da subconta, com cálculo individual e detalhamento na resposta da cobrança. ![Lucas Saraiva](https://github.com/lucassaraiva5.png) [Lucas Saraiva](https://github.com/lucassaraiva5) Software Engineer A [taxa da plataforma](/documentations/split/platform-fee) agora pode ser definida por seller. Um seller da subconta pode ter taxa própria em um ou mais métodos, e onde ele não tem regra própria continua valendo a taxa da subconta. Esta release também encerra a regra genérica (`default`) e, com a taxa ligada, passa a recusar algumas vendas com split, como descrito abaixo. ## Regras por seller As regras do seller são cadastradas em `/v1/merchants/{merchantId}/sellers/{sellerId}/platform-fee`, com `POST`, `GET` e `PUT`, nas mesmas formas de corpo das regras da subconta. A regra do seller substitui a da subconta para ele, método a método e só nas parcelas que ela cobre. * No Pix e no boleto, o seller aceita percentual, valor fixo ou os dois. * No crédito, a regra do seller é só percentual por parcela. * Para isentar um seller num método, cadastre `percentage: 0` e `fixedAmount: 0`. Para ele voltar à taxa da subconta, apague a regra dele. * O seller precisa estar cadastrado na subconta da regra. ## Conta seller a seller Quando algum seller da cobrança tem regra própria, a taxa de cada seller incide sobre a parte bruta dele. O valor fixo da regra da subconta é cobrado uma vez e rateado só entre os sellers que usam a regra da subconta. Cada seller precisa receber ao menos R\$ 0,01. Numa cobrança Pix de R\$ 100,00 dividida em 50%, 30% e 20%, com a subconta cobrando 1,09% mais R\$ 0,30 e o primeiro seller com R\$ 0,39 fixos no Pix, os sellers recebem R\$ 49,61, R\$ 29,50 e R\$ 19,67, e a plataforma fica com R\$ 1,22. O objeto `platformFee` da cobrança ganha `lines`, com a regra, a parte bruta, a taxa e o valor recebido de cada seller. ## Mudanças para quem usa a taxa da plataforma > [!WARNING] > > **Validações com a taxa ligada:** em toda subconta com a taxa ligada, mesmo sem regra de seller, a cobrança com split passa a ser recusada com `422` quando tem seller repetido, seller de outra subconta ou sem subconta, ou provedores com split diferente. No split por percentual, a cobrança em que algum seller ficaria com menos de R\$ 0,01 depois da taxa também é recusada, com `platform_fee_exceeds_amount`. Com a taxa desligada, nada muda. > > **Split por percentual:** com regra de seller na cobrança, o split precisa ser por percentual. Split por valor é recusado com `platform_fee_requires_percentage_split`. > > **Venda sem split:** com a taxa ligada, a cobrança sem `splitRules` paga a taxa pelo único seller ativo da subconta, que recebe o valor já líquido da taxa. Sem exatamente um seller ativo, a cobrança é recusada com `422` e `platform_fee_seller_not_active`, e `error.context.reason` diz o motivo. A venda Apple Pay continua sem taxa. > > **O que fazer:** confira os códigos em [Erros](/documentations/split/platform-fee#erros). ## Fim da regra genérica A regra `paymentMethod: default` deixa de existir. Antes de ela sair, a Malga converteu cada regra `default` em regras por método, com o mesmo valor, nos métodos que a subconta oferece. No crédito, a conversão gravou uma regra sem `installment`, que vale para toda parcela sem regra própria. A taxa dessas vendas não mudou. > [!WARNING] > > **Cadastro:** `POST` e `PUT` com `paymentMethod: default`, na subconta ou no seller, respondem `400` com `PLATFORM_FEE_DEFAULT_RULE_DISCONTINUED`, e nada é gravado. > > **Venda sem regra:** com a taxa ligada, a venda, com ou sem split, num método ou numa parcela que não tem regra na subconta nem no seller é recusada com `422` e `platform_fee_rule_not_configured`. Antes, ela usava a regra `default` ou passava sem taxa. > > **O que fazer:** troque `default` por uma regra para cada método que você vende e cadastre a tabela de crédito de 1x a 24x, ou ao menos até o maior número de parcelas que você vende. O `GET /v1/merchants/{merchantId}/platform-fee` mostra em `coverage` o que ainda está sem regra. > [!TIP] > > Principais novidades: > >
    >
  • Rotas de regra de platform fee por seller, com isenção por método.
    • >
  • `sellerRules` e `coverage` com o estado de cada método e parcela no `GET /v1/merchants/{merchantId}/platform-fee`.
    • >
  • `platformFee.lines` na cobrança, com a taxa de cada seller.
    • >
  • `error.context` nas recusas da taxa, com os valores em campos.
    • >
  • Fim da regra genérica `default`, com recusa da venda com split sem regra para o método ou a parcela.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 13, 2026 - Relatórios de repasses no Dashboard Source: https://docs.malga.io/release-notes/2026-10-13-Release-Notes Novos relatórios de Repasses e Resumo de repasses no Dashboard, com o detalhe e o consolidado de cada lote processado pelo provedor Malga, e estornos no relatório de Parcelas. ![Leonardo Pinheiro](https://github.com/0xleozera.png) [Leonardo Pinheiro](https://github.com/0xleozera) Tech Lead ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer Agora você confere no Dashboard o que já foi repassado a cada recebedor. Dois novos relatórios mostram os lotes de repasse do provedor Malga, do detalhe por transação ao saldo final de cada lote. ## Novidades ### Relatório de Repasses Cada linha é uma transação de um recebedor dentro de um lote. Use o relatório para auditar a composição de um repasse. * Valor bruto, MDR, taxa de antecipação sob demanda e valor líquido por recebedor. * Estornos, chargebacks e a regra de split aplicada em cada transação. * Datas estimada e realizada de liquidação e status do repasse: **Pago**, **Em andamento**, **Falha** ou **Compensado**. Veja os campos em [Relatório de Repasses](/relatorio-de-repasses-detalhe-por-transacao-do-lote). ### Resumo de repasses Cada linha é um lote de um recebedor, com vendas, ajustes e descontos somados em colunas próprias. * Crédito total, chargebacks, estornos, ajustes manuais, taxas, tarifas de 3DS e antifraude e taxa de saque. * **Saldo devedor** e **Saldo total** para acompanhar dívidas abatidas de um lote para o outro. * Lotes **Compensados**, que fecharam sem gerar crédito, aparecem com todas as colunas preenchidas. Veja os campos em [Resumo de repasses](/resumo-de-repasses-consolidado-por-lote). > [!NOTE] > > Nos dois relatórios, o período de exportação usa a **data estimada de liquidação do lote**, e não a data de criação da cobrança. Os relatórios cobrem apenas transações do provedor Malga. ## Melhorias ### Estornos no relatório de Parcelas O [relatório de Parcelas](/relatorio-de-parcelas-agenda-de-recebiveis-por-parcela) agora traz os estornos como linhas próprias, com `Operação` igual a **Estorno** e o `Status final da cobrança` como **Estornada**. Cada linha é uma parcela por recebedor, com o novo campo `Taxa %`. > [!TIP] > > Principais novidades: > >
    >
  • Novo **relatório de Repasses**, com o detalhe por transação de cada lote.
    • >
  • Novo **Resumo de repasses**, com o consolidado e o saldo de cada lote por recebedor.
    • >
  • Estornos e `Taxa %` no **relatório de Parcelas**.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 15, 2026 - Captura automática após o antifraude Source: https://docs.malga.io/release-notes/2026-10-15-Release-Notes A Malga passa a pré-autorizar e capturar cobranças de cartão de crédito com capture true e antifraude quando o antifraude aprova. ![André Campos](https://github.com/ATCamposs.png) [André Campos](https://github.com/ATCamposs) Software Engineer Cobranças de cartão de crédito com `capture: true` e antifraude configurado agora são pré-autorizadas e capturadas pela Malga quando o antifraude aprova. Você não precisa chamar o serviço de captura. ## Quando vale * Cartão de crédito, inclusive Click to Pay, com `capture: true`. * Merchant com provedor antifraude configurado e sem fluxo de pagamentos. * Não vale para 3DS com `setupId` nem para MPI externo. ## O que acontece * A Malga pré-autoriza a cobrança e captura sozinha quando o antifraude aprova, no veredito síncrono e no assíncrono. * A captura acontece mesmo com `captureOnApproved: false`. * Reprovação e erro seguem as opções do provedor antifraude (`captureOnReproved`, `refundOnReproved`, `captureOnError` e `refundOnError`), como antes. * Durante a análise, a cobrança aparece como `pre_authorized` com `capture: false`. Depois da captura, ela passa a `authorized` com `capture: true`, e os webhooks seguem o status. ## Prazo de 72 horas Uma aprovação que chega depois de 72 horas da criação não captura. Uma pré-autorização que continua sem veredito após esse prazo é cancelada automaticamente. ## Sessão e link de pagamento 1:1 Enquanto a cobrança de uma sessão 1:1 está em análise, um novo pagamento nessa sessão recebe `409` com a mensagem "There is already a charge for this session under anti-fraud analysis". Repetir a requisição com a mesma `X-Idempotency-Key` devolve a cobrança original. ## Liberação gradual O recurso está em liberação gradual por cliente. Enquanto a sua conta não for liberada, `capture: true` com antifraude continua recebendo `400` com a mensagem "The capture cannot be true in this operation". Fale com o suporte para habilitar. ## Sandbox A simulação do veredito segue a mesma regra de produção. O cancelamento automático em 72 horas não existe no sandbox. Para simular o antifraude assíncrono, use documentos com final 0 ou 9. A análise começa pendente e o veredito chega sozinho cerca de 2 minutos depois: aprovado no final 0 e reprovado no final 9. Veja [Testando em Sandbox](/documentations/anti-fraud/testing). Para os detalhes, veja [Antifraudes síncronos](/documentations/anti-fraud/sync-anti-fraud), [Antifraudes assíncronos](/documentations/anti-fraud/async-anti-fraud) e [Cartão de crédito](/documentations/payment-methods/credit-card). # Out 16, 2026 - Modalidades de 3DS e roteamento da PagBank Source: https://docs.malga.io/release-notes/2026-10-16-Release-Notes Erros de elegibilidade para 3DS2 Malga e MPI externo, badge de 3DS nativo na tabela de provedores, escolha da API da PagBank pelos dados do comprador e testes de 3DS Malga no Sandbox. Esta semana traz regras mais claras para cada modalidade de 3DS, a escolha automática da API da PagBank e novos recursos de teste no Sandbox. ## Novidades ### Erros de elegibilidade para 3DS2 Malga e MPI externo A Malga agora verifica, antes de criar a cobrança, se algum provedor do merchant atende à modalidade de 3DS pedida. Quando nenhum atende, a API responde `400` com um destes códigos: * `provider_not_configured_for_3ds2`: cobrança com `setupId` ou MPI externo sem provedor com `paymentTypes=3ds2_malga`. * `provider_not_configured_for_required_capabilities`: cobrança com `setupId` ou MPI externo e `splitRules` sem um mesmo provedor com `3ds2_malga` e `split`. Esses erros não consomem o `setupId` nem a chave de idempotência. Depois de ajustar o provedor, repita a mesma requisição. O 3DS nativo continua respondendo `404` quando falta provedor com `operation=3ds2`. Veja [Principais erros](/documentations/3ds2-malga/3ds-malga/principais-erros) e [Modalidades de 3DS na Malga](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). ### Badge de 3DS nativo na tabela de provedores A [tabela de provedores e meios de pagamento](/documentations/type-tables/payment-methods-by-providers) agora mostra **3DS nativo** e **3DS2 Malga** como capacidades separadas. Um provedor com `3ds2_malga` não atende ao [3DS nativo](/documentations/3dsecure2-adyen/intro), e `operation=3ds2` não atende ao 3DS2 Malga nem ao MPI externo. ## Atualizações ### Escolha da API da PagBank pelos dados do comprador No cartão de crédito com PagSeguro, a Malga envia a cobrança para a API de Orders da PagBank quando ela traz nome, e-mail e CPF ou CNPJ do comprador. Sem algum desses dados, a cobrança vai para a API de Charges. Os dados vêm do `customerId` ou de `fraudAnalysis.customer`. Para usar a API recomendada pela PagBank, envie os três dados em toda cobrança. Veja [PagSeguro](/documentations/providers/pagseguro). ### Testes de 3DS Malga no Sandbox No Sandbox, a cobrança com 3DS Malga é aprovada ou recusada pelo resultado da autenticação, com os cartões de teste da Cybersource. A regra do último dígito do cartão não vale quando a autenticação é bem-sucedida, e o antifraude não é executado. Veja [Testando 3DS Malga no Sandbox](/documentations/3ds2-malga/3ds-malga/testes-sandbox). > [!TIP] > > Principais novidades: > >
    >
  • Novos erros `400` de elegibilidade para 3DS2 Malga e MPI externo, sem consumir o `setupId`.
    • >
  • Badges separados de 3DS nativo e 3DS2 Malga na tabela de provedores.
    • >
  • API da PagBank escolhida pelos dados do comprador.
    • >
  • Cartões de teste da Cybersource para 3DS Malga no Sandbox.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 19, 2026 - Repasses e recebíveis no Dashboard Source: https://docs.malga.io/release-notes/2026-10-19-Release-Notes Nova página de Repasses em Financeiro, com o detalhe de cada repasse até a parcela, e a aba Repasses no detalhe da cobrança e do recebedor, ligando cobrança, recebível e repasse. ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer Quanto você vai receber, quando o dinheiro cai na conta e de quais vendas ele vem: até aqui, responder isso exigia planilha ou chamado no suporte. Agora o Dashboard mostra o caminho completo do dinheiro nas cobranças **processadas pelo provedor Malga**, da cobrança à parcela e da parcela ao repasse que chegou na sua conta bancária. ## Repasses em Financeiro O menu **Financeiro** ganhou a página **Repasses**. No topo, três cards resumem o seu saldo: * **Saldo a receber:** tudo o que ainda não foi repassado, já com as taxas descontadas, incluindo o que ainda vai liquidar. * **Saldo reserva:** o valor retido como garantia para cobrir tarifas, estornos e chargebacks. * **Próximo repasse:** o valor previsto para o próximo repasse e a data em que ele deve cair na sua conta. O botão **Política de repasse** mostra a conta bancária ou a chave Pix de destino. Logo abaixo, a listagem traz todos os repasses do período, com data, método, bandeira, destino, valor líquido e status. ![Página Repasses em Financeiro, com os cards de saldo a receber, saldo reserva e próximo repasse e a listagem de repasses](https://mintcdn.com/malga/ZIWewmI5oz773_hd/assets/images/release/2026-10-19/financeiro-repasses.gif?s=0537f72012eddc3eabe27e75ea950dfa) ## Detalhe do repasse Cada repasse da listagem agora abre. O detalhe mostra o valor, o status, o destino e a data prevista. Quando o repasse já foi pago, o detalhe mostra a data do pagamento. O detalhe se divide em duas partes: * **Composição:** como a Malga chega ao valor depositado, linha a linha. Parte do **valor bruto** dos recebíveis e desconta **taxas**, **tarifas**, **estornos e chargebacks**, **ajustes**, **saldo negativo anterior** e **taxa de saque**, até o valor **depositado na conta**. Linhas sem valor não aparecem. * **Recebíveis:** as parcelas que compõem o repasse, com parcela, ID da cobrança, valor bruto, taxa e valor líquido. Um clique leva direto à cobrança de origem. ## Aba Repasses no detalhe da cobrança O detalhe da cobrança passa a ter as abas **Geral** e **Repasses**. A aba Repasses mostra para onde foi o dinheiro daquela venda: * **Regras da divisão:** uma linha por recebedor, com a regra aplicada, valor bruto, taxas e valor líquido. A sua empresa aparece na primeira linha quando recebe parte da venda. A taxa da plataforma aparece em reais, descontada de quem paga e somada a quem recebe. * **Recebíveis:** as parcelas da cobrança, agrupadas por recebedor, com a previsão de cada uma e o repasse em que ela entrou. Pelo link **Ver repasse** você abre o detalhe do repasse. ![Detalhe da cobrança com as abas Geral e Repasses, mostrando as regras da divisão e os recebíveis](https://mintcdn.com/malga/ZIWewmI5oz773_hd/assets/images/release/2026-10-19/cobranca-aba-repasses.gif?s=85dc63b1d459653f4beaf65addad9df8) ## Aba Repasses no recebedor Em **Recebedores**, o detalhe de cada recebedor ganhou a aba **Repasses**, com os mesmos cards e a mesma listagem da página de Financeiro, filtrados para aquele recebedor. Ao abrir um repasse a partir dali, o botão de voltar retorna para o recebedor. > [!NOTE] > > A página de Repasses, a aba Repasses no recebedor e o bloco Recebíveis estão disponíveis para cobranças do provedor Malga. O bloco Regras da divisão aparece em qualquer cobrança com split. Nos outros provedores, ele mostra recebedor, regra e valor bruto, já que as taxas são definidas pelo provedor. Para saber mais sobre o detalhe da cobrança no Dashboard, consulte o [guia de Gestão de Cobranças](/documentations/dashboard/charge-details). > [!TIP] > > Principais novidades: > >
    >
  • Nova página **Financeiro → Repasses**, com saldo a receber, saldo reserva, próximo repasse e a listagem completa de repasses.
    • >
  • **Detalhe do repasse** com a composição até o valor depositado e os recebíveis que o compõem.
    • >
  • Aba **Repasses** no detalhe da cobrança, com as regras da divisão e as parcelas de cada recebedor.
    • >
  • Aba **Repasses** no detalhe do recebedor.
    • >
  • Navegação nos dois sentidos entre cobrança, recebível e repasse.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 20, 2026 - Webhooks aceitam 204 como entrega concluída Source: https://docs.malga.io/release-notes/2026-10-20-Release-Notes A Malga passa a considerar a resposta 204 (No Content) do seu endpoint como entrega concluída do webhook, sem retentativas. ![Diego Saouda](https://github.com/diego-malga.png) [Diego Saouda](https://github.com/diego-malga) Staff Software Engineer O seu endpoint de webhook agora pode responder `204 No Content` para confirmar o recebimento de uma notificação. ## Melhorias ### Resposta 204 nos webhooks * A Malga considera a entrega concluída quando o seu endpoint responde `200 OK`, `201 Created` ou `204 No Content` dentro do tempo de espera. * Com qualquer uma dessas respostas, o evento não entra em retentativa. * Vale para as versões [1.0](/documentations/webhooks/webhook1-0) e [1.1](/documentations/webhooks/webhook1-1) dos webhooks. * Você não precisa mudar nada. Se o seu endpoint já responde `204`, as reentregas desnecessárias deixam de acontecer. > [!TIP] > > Principais novidades: > >
    >
  • `204 No Content` aceito como confirmação de entrega do webhook.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 21, 2026 - Mais de um cartão no Tokenization SDK Source: https://docs.malga.io/release-notes/2026-10-21-Release-Notes O Tokenization SDK passa a tokenizar dois ou mais cartões na mesma página, com uma instância de MalgaTokenization para cada cartão. ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer O [Tokenization SDK](/sdks/tokenization/v2/multiple-cards) agora permite tokenizar vários cartões na mesma página, o que viabiliza fluxos como o pagamento dividido entre múltiplos cartões no checkout. ## Melhorias ### Múltiplos cartões na mesma página * Crie uma instância de `MalgaTokenization` para cada cartão. Cada instância tem os próprios campos, eventos e token. * O `container` de cada campo aceita qualquer `id`, desde que seja único na página. Antes, só eram aceitos `card-number`, `card-holder-name`, `card-cvv` e `card-expiration-date`. * Os eventos registrados com `on` em uma instância recebem apenas os eventos dos campos daquele cartão. ```html theme={null}
``` ```typescript theme={null} const firstCard = new MalgaTokenization({ apiKey: 'YOUR_API_KEY', clientId: 'YOUR_CLIENT_ID', options: { sandbox: true, config: { fields: { cardNumber: { container: 'card-number-1' }, cardHolderName: { container: 'card-holder-name-1' }, cardCvv: { container: 'card-cvv-1' }, cardExpirationDate: { container: 'card-expiration-date-1' }, }, }, }, }) const secondCard = new MalgaTokenization({ apiKey: 'YOUR_API_KEY', clientId: 'YOUR_CLIENT_ID', options: { sandbox: true, config: { fields: { cardNumber: { container: 'card-number-2' }, cardHolderName: { container: 'card-holder-name-2' }, cardCvv: { container: 'card-cvv-2' }, cardExpirationDate: { container: 'card-expiration-date-2' }, }, }, }, }) const [first, second] = await Promise.all([ firstCard.tokenize(), secondCard.tokenize(), ]) ``` > [!WARNING] > > Não repita o mesmo `container` em duas instâncias. Um `id` repetido faz os dados de um cartão se misturarem com os do outro. Veja o passo a passo em [Múltiplos cartões](/sdks/tokenization/v2/multiple-cards). > [!TIP] > > Principais novidades: > >
    >
  • Tokenização de dois ou mais cartões na mesma página, com uma instância de `MalgaTokenization` por cartão.
    • >
  • `container` aceita qualquer `id` único na página.
    • >
  • Novo evento `loading`, disparado no início e no fim da tokenização. Veja [Eventos](/sdks/tokenization/v2/events).
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 26, 2026 - Extrato no Dashboard Source: https://docs.malga.io/release-notes/2026-10-26-Release-Notes Nova página de Extrato em Financeiro, com as movimentações do saldo, o detalhe de cada uma e a aba Extrato no recebedor. ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer O Dashboard agora mostra tudo o que entrou e saiu do seu saldo: liquidações, repasses, estornos, chargebacks, tarifas e ajustes. Vale para cobranças do provedor Malga. ## Extrato em Financeiro O menu **Financeiro** ganhou a página **Extrato**. Os cards no topo mostram as **Entradas**, as **Saídas** e o **Líquido** do período. O período padrão é de 7 dias. Você escolhe entre duas visualizações: * **Por movimentação:** um lançamento por linha, com data, tipo, descrição, valor bruto, taxas e valor líquido. Em tarifas e ajustes, passe o mouse na descrição para ver o motivo completo. * **Por recebível:** uma parcela por linha, com previsão, método, bandeira, valores e status. Aqui você também filtra por status. ![Página Extrato em Financeiro, com os cards de entradas, saídas e líquido do período e a listagem por movimentação](https://mintcdn.com/malga/enRnPaEVaWvS6Db9/assets/images/release/2026-10-26/financeiro-extrato-light.png?fit=max\&auto=format\&n=enRnPaEVaWvS6Db9\&q=85\&s=0b8dcb9697f3841f6b95fcc69217d037) ## Detalhe da movimentação Clique em uma liquidação, um estorno ou um chargeback para ver o detalhe: o resumo dos valores e a lista de recebíveis que compõem a movimentação. As outras linhas levam à origem do valor: * **Repasse** e **Devolução de repasse** abrem o detalhe do repasse. * Em **Por recebível**, o recebível liquidado abre o repasse em que entrou. Os demais abrem a cobrança. ## Aba Extrato no recebedor O detalhe do recebedor, em **Recebedores**, ganhou a aba **Extrato**. Ela mostra o mesmo conteúdo da página de Financeiro, filtrado para aquele recebedor. Veja os tipos de movimentação e como ler os valores no [guia do Extrato](/documentations/dashboard/financeiro/statement). > [!TIP] > > Principais novidades: > >
    >
  • Página **Financeiro → Extrato**, com entradas, saídas e líquido do período.
    • >
  • Visualizações **Por movimentação** e **Por recebível**.
    • >
  • **Detalhe da movimentação**, com os recebíveis que a compõem.
    • >
  • Aba **Extrato** no detalhe do recebedor.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 28, 2026 - Tokenization SDK 5.0.0 Source: https://docs.malga.io/release-notes/2026-10-28-Release-Notes O Tokenization SDK 5.0.0 ganha o método destroy() para desmontar uma instância, recusa containers já usados por outra instância e valida os campos antes de tokenizar. ![Mila](https://avatars.githubusercontent.com/u/64020657?v=4) [Mila](https://github.com/milenacrios) Software Engineer A versão 5.0.0 do [Tokenization SDK](/sdks/tokenization/v2/events) permite desmontar uma instância de `MalgaTokenization`. Em aplicações de página única, o checkout deixa de acumular iframes e listeners cada vez que a tela é montada de novo. Esta é uma versão major: quem monta o checkout mais de uma vez sem desmontar a instância anterior precisa ajustar a integração antes de atualizar. Veja a seção Mudanças para quem usa o Tokenization SDK, abaixo. ## Melhorias ### Método destroy() * `destroy()` remove os iframes dos containers, o listener de mensagens e os callbacks registrados com `on`, apaga os dados do cartão coletados e libera os containers para uma nova instância. * Chame o método sempre que o checkout sair da tela: na função de limpeza do `useEffect` no React, em `onUnmounted` no Vue ou em `ngOnDestroy` no Angular. * Depois de `destroy()`, `tokenize()` lança um erro. Chamar `destroy()` mais de uma vez não tem efeito. Em React, por exemplo, o componente do checkout cria a instância ao montar e a desmonta na função de limpeza do `useEffect`: ```tsx theme={null} useEffect(() => { const instance = new MalgaTokenization(configurations) malgaTokenization.current = instance return () => instance.destroy() }, []) ``` Veja o componente completo em React, Vue e Angular em [destroy()](/sdks/tokenization/v2/events#destroy). ### Validação dos campos antes de tokenizar * `tokenize()` confere se todos os campos configurados em `config.fields` foram preenchidos antes de enviar os dados. * Se faltar algum, o método retorna na hora, sem chamar a API, com `tokenId` vazio e um `error` com `type: 'invalid_request_error'`. O `details` lista os campos que faltam, por exemplo `['cardCvv']`. Veja [tokenize()](/sdks/tokenization/v2/events#tokenize). ## Correções * Apagar o CVV ou o nome do titular sem sair do campo agora limpa também o valor coletado. Antes, o último valor digitado continuava sendo enviado na tokenização. ## Mudanças para quem usa o Tokenization SDK > [!WARNING] > > **Containers em uso:** o construtor passa a lançar um erro, antes de renderizar qualquer campo, quando o `container` já é usado por outra instância ativa (`ContainerInUseError`) ou aparece em dois campos da mesma configuração (`DuplicatedContainerError`). Até a versão 4.x, essas configurações eram aceitas: os iframes se empilhavam nos mesmos containers e os dados dos cartões se misturavam. > > **O que fazer:** se a tela do checkout pode ser montada mais de uma vez (um `useEffect` sem função de limpeza, o `StrictMode` do React ou a volta para a rota), chame `destroy()` na desmontagem. Use também um `container` diferente para cada campo e para cada cartão. Veja [Containers em uso](/sdks/tokenization/v2/events#containers-em-uso). > [!TIP] > > Principais novidades: > >
    >
  • Método `destroy()` para desmontar uma instância de `MalgaTokenization`.
    • >
  • `ContainerInUseError` e `DuplicatedContainerError` para containers repetidos.
    • >
  • `tokenize()` retorna `invalid_request_error` quando falta um campo configurado.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Out 29, 2026 - Agenda de recebíveis no Dashboard Source: https://docs.malga.io/release-notes/2026-10-29-Release-Notes Veja no Dashboard quanto você tem a receber em cada dia dos próximos 90 dias, com a nova Agenda de recebíveis em Financeiro e no detalhe do recebedor. ![Bruno Lucena](https://avatars.githubusercontent.com/u/50156485?v=4) [Bruno Lucena](https://github.com/BrunoLucena99) Front Engineer ![Viviane Tolomeotti](https://github.com/vivianemalga.png) [Viviane Tolomeotti](https://github.com/vivianemalga) Software Engineer Agora você vê no Dashboard quanto vai receber e quando. A nova **Agenda de recebíveis**, em **Financeiro**, ajuda você a planejar o caixa sem depender de planilhas. > [!NOTE] > > A Agenda de recebíveis está disponível para clientes Malga Sub e contempla apenas cobranças do provedor Malga. ## Agenda de recebíveis * **Previsão por dia:** o valor que você tem a receber em cada dia dos próximos 90 dias. * **Total de um período:** selecione uma semana ou um mês para ver quanto entra no intervalo. * **De onde vem o valor:** vendas por método de pagamento e bandeira, taxas, estornos e chargebacks. ![Agenda de recebíveis em Financeiro, com o calendário do mês, o valor bruto, as taxas e o valor líquido do dia selecionado e os lançamentos](https://mintcdn.com/malga/Dm49UW4wM6AeXWen/assets/images/release/2026-10-29/agenda-recebiveis-light.png?fit=max\&auto=format\&n=Dm49UW4wM6AeXWen\&q=85\&s=bf947c83d58f937dab6ccbcfcf9190fa) ## Agenda de cada recebedor Em **Recebedores**, cada recebedor ganhou a mesma visão, com a agenda só dele. > [!TIP] > > Principais novidades: > >
    >
  • Nova página **Financeiro → Agenda de recebíveis**, com o que você tem a receber em cada dia dos próximos 90 dias.
    • >
  • Total previsto de um dia ou de um período, com as vendas, as taxas e os estornos e chargebacks que o compõem.
    • >
  • Agenda de recebíveis no detalhe de cada recebedor.
    • >
> [!NOTE] > > Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Mais releases Source: https://docs.malga.io/release-notes/releases Arquivo histórico das release notes da Malga, com atualizações da API, SDKs, Dashboard, provedores e novos recursos organizadas por ano. > [tab] Release Notes - 2026 > >
    >
  1. [Agenda de recebíveis no Dashboard](/release-notes/2026-10-29-Release-Notes)
    2. >
  2. [Tokenization SDK 5.0.0](/release-notes/2026-10-28-Release-Notes)
    3. >
  3. [Extrato no Dashboard](/release-notes/2026-10-26-Release-Notes)
    4. >
  4. [Mais de um cartão no Tokenization SDK](/release-notes/2026-10-21-Release-Notes)
    5. >
  5. [Webhooks aceitam 204 como entrega concluída](/release-notes/2026-10-20-Release-Notes)
    6. >
  6. [Repasses e recebíveis no Dashboard](/release-notes/2026-10-19-Release-Notes)
    7. >
  7. [Modalidades de 3DS e roteamento da PagBank](/release-notes/2026-10-16-Release-Notes)
    8. >
  8. [Captura automática após o antifraude](/release-notes/2026-10-15-Release-Notes)
    9. >
  9. [Relatórios de repasses no Dashboard](/release-notes/2026-10-13-Release-Notes)
    10. >
  10. [Taxa de plataforma por recebedor](/release-notes/2026-10-08-Release-Notes)
    11. >
  11. [Múltiplos cartões no Link de Pagamento e limite de falhas no estorno](/release-notes/2026-09-30-Release-Notes)
    12. >
  12. [Dashboard: seletor de empresa e subcontas no menu lateral](/release-notes/2026-09-24-Release-Notes)
    13. >
  13. [Descrição na fatura em cobranças Rede](/release-notes/2026-09-23-Release-Notes)
    14. >
  14. [Planos de venda no provedor Malga](/release-notes/2026-09-22-Release-Notes)
    15. >
  15. [Relatório de parcelas](/release-notes/2026-09-09-Release-Notes)
    16. >
  16. [Revisão cadastral de recebedores](/release-notes/2026-09-08-Release-Notes)
    17. >
  17. [Composição financeira no detalhe da cobrança](/release-notes/2026-09-01-Release-Notes)
    18. >
  18. [Listagem de antecipações e notifyOnPayout em recebedores](/release-notes/2026-08-31-Release-Notes)
    19. >
  19. [Melhoria em Cards no Analytics API](/release-notes/2026-08-26-Release-Notes)
    20. >
  20. [Koin](/release-notes/2026-08-10-Release-Notes)
    21. >
  21. [Apple Pay WorldPay e disputa SafraPay (Beta)](/release-notes/2026-08-04-Release-Notes)
    22. >
  22. [Simulação de status de recebedor no Sandbox](/release-notes/2026-07-20-Release-Notes)
    23. >
  23. [Antifraude no link de pagamento](/release-notes/2026-07-13-Release-Notes)
    24. >
  24. [Instruções de boleto em sessões](/release-notes/2026-06-30-Release-Notes)
    25. >
  25. [Platform Fee](/release-notes/2026-06-18-Release-Notes)
    26. >
  26. [Descontinuação de split agnóstico e payout eligible](/release-notes/2026-06-12-Release-Notes)
    27. >
  27. [Beneficiário final NuPay e Antecipação avulsa](/release-notes/2026-05-29-Release-Notes)
    28. >
  28. [Link de Pagamento 1:N](/release-notes/2026-05-08-Release-Notes)
    29. >
  29. [Payouts API, salesPlanId em Sellers e Query Charges](/release-notes/2026-04-30-Release-Notes)
    30. >
  30. [Split no Link de Pagamento](/release-notes/2026-04-29-Release-Notes)
    31. >
  31. [Nova experiência da Dashboard](/release-notes/2026-04-23-Release-Notes)
    32. >
  32. [Konduto](/release-notes/2026-04-15-Release-Notes)
    33. >
  33. [Upload de documentos para Sellers](/release-notes/2026-04-08-Release-Notes)
    34. >
  34. [Recorrência Barte](/release-notes/2026-03-09-Release-Notes)
    35. >
  35. [Banrisul](/release-notes/2026-01-15-Release-Notes)
    36. >
  36. [PayPal](/release-notes/2026-01-06-Release-Notes)
    37. >
> [tab] Release Notes - 2025 > >
    >
  1. [Zero dollar Safra Pay](/release-notes/2025-12-19-Release-Notes)
    2. >
  2. [3DS2 Malga no Link](/release-notes/2025-11-25-Release-Notes)
    3. >
  3. [Getnet Sep Pix Boleto](/release-notes/2025-11-24-Release-Notes)
    4. >
  4. [Novo Link de Pagamento](/release-notes/2025-11-19-Release-Notes)
    5. >
  5. [ApplePay Pagseguro](/release-notes/2025-11-12-Release-Notes)
    6. >
  6. [B2E](/release-notes/2025-11-11-Release-Notes)
    7. >
  7. [Assinaturas](/release-notes/2025-09-16-Release-Notes)
    8. >
  8. [Split PagSeguro](/release-notes/2025-09-15-Release-Notes)
    9. >
  9. [Bolt](/release-notes/2025-09-12-Release-Notes)
    10. >
  10. [MapInvest](/release-notes/2025-09-08-Release-Notes)
    11. >
  11. [GETNET SEP](/release-notes/2025-07-29-Release-Notes)
    12. >
  12. [Split Pagarme](/release-notes/2025-05-16-Release-Notes)
    13. >
  13. [Convite de Usuários](/release-notes/2025-05-07-Release-Notes)
    14. >
  14. [Tokenization V2](/release-notes/2025-03-25-Release-Notes)
    15. > >
  15. > [Nova funcionalidade 3DS > DataOnly](/release-notes/2025-01-30-Release-Notes) >
    16. > >
  16. > [Novos campos de 3DSecure2](/release-notes/2025-01-03-Release-Notes) >
    17. > >
  17. [Estorno parcial](/release-notes/2025-01-03-Release-Notes2)
    18. >
  18. [Apple Pay](/release-notes/2025-01-02-Release-Notes)
    19. >
> [tab] Release Notes - 2024 > >
    >
  1. [3DS Malga](/release-notes/2024-10-22-Release-Notes)
    2. > >
  2. > [Novos filtros no painel de > dados](/release-notes/2024-10-07-Release-Notes) >
    3. > >
  3. [Nova busca de cobranças](/release-notes/2024-07-05-Release-Notes)
    4. > >
  4. > [Facilitadores de pagamentos](/release-notes/2024-07-03-Release-Notes) >
    5. > >
  5. [Estorno Parcial de Split](/release-notes/2024-06-28-Release-Notes)
    6. >
  6. [Exportação de cobranças](/release-notes/2024-06-24-Release-Notes)
    7. >
  7. [Barte](/release-notes/2024-05-28-Release-Notes-2)
    8. >
  8. [Tokens de Bandeira](/release-notes/2024-05-28-Release-Notes)
    9. >
  9. [Correções Dash](/release-notes/2024-05-23-Release-Notes)
    10. >
  10. [Export V2](/release-notes/2024-04-18-Release-Notes)
    11. >
  11. [Filtro por provedor](/release-notes/2024-04-02-Release-Notes)
    12. >
  12. [Pesquisa por NSU](/release-notes/2024-03-11-Release-Notes)
    13. >
  13. [Cobrança por status](/release-notes/2024-03-06-Release-Notes)
    14. >
  14. [Reversão de estorno](/release-notes/2024-03-05-Release-Notes)
    15. >
  15. [Safrapay](/release-notes/2024-02-28-Release-Notes)
    16. >
  16. [Parcelas pela Drip](/release-notes/2024-02-21-Release-Notes)
    17. >
  17. [Detalhes de estorno](/release-notes/2024-02-09-Release-Notes)
    18. >
  18. [Novos campos no export](/release-notes/2024-01-31-Release-Notes)
    19. >
  19. [Novos SDKs](/release-notes/2024-01-26-Release-Notes)
    20. >
  20. [Filtro por subconta](/release-notes/2024-01-19-Release-Notes)
    21. > >
  21. > [Novos campos de antifraude](/release-notes/2024-01-17-Release-Notes) >
    22. > >
  22. [Novidades Pagarme V5](/release-notes/2024-01-16-Release-Notes)
    23. >
  23. [Listagem de cartões](/release-notes/2024-01-05-Release-Notes)
    24. >
> [tab] Release Notes - 2023 > >
    >
  1. [Pix com a Adyen](/release-notes/2023-01-09-Release-Notes)
    2. > >
  2. > [Melhorias no filtro e cadastro no > Dashboard](/release-notes/2023-01-10-Release-Notes) >
    3. > >
  3. [Plug agora é Malga!](/release-notes/2023-01-11-Release-Notes)
    4. >
  4. [Abertura de Disputa](/release-notes/2023-01-17-Release-Notes)
    5. >
  5. [Pix na PagSeguro](/release-notes/2023-01-24-Release-Notes)
    6. > >
  6. > [Melhorias nos filtros e mais](/release-notes/2023-01-25-Release-Notes) >
    7. > >
  7. [Melhorias com a Zoop](/release-notes/2023-01-27-Release-Notes)
    8. > >
  8. > [Suporte a antifraude e customers no Malga > Checkout](/release-notes/2023-02-03-Release-Notes) >
    9. > >
  9. > [Notificação de Disputas na > Adyen](/release-notes/2023-02-07-Release-Notes) >
    10. > >
  10. [Novo Provedor Klap](/release-notes/2023-02-10-Release-Notes)
    11. > >
  11. > [Mais flexibilidade no Checkout > Malga](/release-notes/2023-03-01-Release-Notes) >
    12. > >
  12. > [Novo campo de transactionConfig no > checkout](/release-notes/2023-03-16-Release-Notes) >
    13. > >
  13. > [Melhorias Checkout Full e link de > pagamento](/release-notes/2023-03-31-Release-Notes) >
    14. > >
  14. [Exportação de cobranças](/release-notes/2023-04-04-Release-Notes)
    15. > >
  15. > [Split no Pix e Boleto da > Pagarme](/release-notes/2023-04-14-Release-Notes) >
    16. > >
  16. > [Listagem e detalhes de > subcontas](/release-notes/2023-04-17-Release-Notes) >
    17. > >
  17. > [Nomes personalizáveis às > subcontas](/release-notes/2023-05-15-Release-Notes) >
    18. > >
  18. > [Gestão de Split através do > Dashboard](/release-notes/2023-05-30-Release-Notes) >
    19. > >
  19. [Validação de cartões](/release-notes/2023-06-01-Release-Notes)
    20. > >
  20. > [Novo nome do ambiente de testes da > Malga](/release-notes/2023-06-06-Release-Notes) >
    21. > >
  21. > [Propriedades opcionais de cvvCheck e > cvvCheckMerchantId](/release-notes/2023-06-16-Release-Notes) >
    22. > >
  22. > [Mudanças no contrato de customer no Malga > Checkout](/release-notes/2023-06-20-Release-Notes) >
    23. > >
  23. > [Fluxos Inteligentes no > Dashboard](/release-notes/2023-06-27-Release-Notes) >
    24. > >
  24. [Clearsale Tickets](/release-notes/2023-07-10-Release-Notes)
    25. > >
  25. > [Área de Recebedores no > Dashboard](/release-notes/2023-07-11-Release-Notes) >
    26. > >
  26. [Pix Nupay](/release-notes/2023-07-13-Release-Notes)
    27. >
  27. [Voucher](/release-notes/2023-07-28-Release-Notes)
    28. >
  28. [Drip e Worldpay](/release-notes/2023-08-03-Release-Notes)
    29. > >
  29. > [Suporte a Zero Dollar na Rede](/release-notes/2023-08-06-Release-Notes) >
    30. > >
  30. [Idempotency Key](/release-notes/2023-08-07-2-Release-Notes)
    31. > >
  31. > [Nupay e Drip no Malga Checkout](/release-notes/2023-08-07-Release-Notes) >
    32. > >
  32. > [Tokenização do CVV nas > transações](/release-notes/2023-08-08-Release-Notes) >
    33. > >
  33. [Analytics API](/release-notes/2023-08-09-Release-Notes)
    34. > >
  34. > [Tokenização do cartão voucher nas > transações](/release-notes/2023-08-10-Release-Notes) >
    35. > >
  35. > [Voucher com provedor Pagarme](/release-notes/2023-08-25-Release-Notes) >
    36. > >
  36. > [Novos filtros na Analytics API](/release-notes/2023-08-30-Release-Notes) >
    37. > >
  37. > [Novo menu de usuários & > Melhorias](/release-notes/2023-08-31-Release-Notes) >
    38. > >
  38. > [Novo step notificação no > webhooks](/release-notes/2023-09-18-Release-Notes) >
    39. > >
  39. > [Informação de rastreabilidade de > cobranças](/release-notes/2023-09-19-Release-Notes) >
    40. > >
  40. > [Novos dados no relatório de > cobranças](/release-notes/2023-09-20-Release-Notes) >
    41. > >
  41. > [Melhorias validação de cartão](/release-notes/2023-09-26-Release-Notes) >
    42. > >
  42. > [Novas queries na Analytics API](/release-notes/2023-10-06-Release-Notes) >
    43. > >
  43. > [Painel de Dados no Dashboard > Malga](/release-notes/2023-10-16-Release-Notes) >
    44. > >
  44. > [Suporte a Zero Dollar na > Pagseguro](/release-notes/2023-10-23-Release-Notes) >
    45. > >
  45. [Malga e VTEX](/release-notes/2023-10-27-Release-Notes)
    46. > >
  46. > [Teste de Performance (Black Friday > 2023\)](/release-notes/2023-11-01-Release-Notes) >
    47. > >
  47. > [Preparativos para Black Friday > 2023](/release-notes/2023-11-07-Release-Notes) >
    48. > >
  48. > [Pix v2 no Banco do Brasil](/release-notes/2023-11-09-Release-Notes) >
    49. > >
  49. [Módulo para Magento 2](/release-notes/2023-11-22-Release-Notes)
    50. > >
  50. > [Adição de Campos à Charges API e Sessions > API](/release-notes/2023-12-11-Release-Notes) >
    51. > >
  51. [Crédito na Pagarme V5](/release-notes/2023-12-19-Release-Notes)
    52. > >
  52. > [Novo tipo de documento em > Customers](/release-notes/2023-12-20-Release-Notes) >
    53. >
> [tab] Release Notes - 2022 > >
    >
  1. > [Suporte ao provedor Mercado > Pago](/release-notes/2022-01-17-Release-Notes) >
    2. > >
  2. > [Boleto no retorno de transactionRequest e > mais](/release-notes/2022-02-10-Release-Notes) >
    3. > >
  3. [Major release](/release-notes/2022-03-25-Release-Notes)
    4. >
  4. [Suporte a boleto por BS2](/release-notes/2022-05-30-Release-Notes)
    5. >
  5. [New Dashboard](/release-notes/2022-06-07-Release-Notes)
    6. > >
  6. > [Novos meios de pagamento com Mercado Pago e > mais](/release-notes/2022-06-22-Release-Notes) >
    7. > >
  7. > [Chaves de sandbox no Dashboard](/release-notes/2022-08-01-Release-Notes) >
    8. > >
  8. > [Listagem de Customers no Dash e > mais](/release-notes/2022-08-17-Release-Notes) >
    9. > >
  9. > [Análise de risco utilizando provedores > antifraude](/release-notes/2022-09-05-Release-Notes) >
    10. > >
  10. [Nupay e Braintree](/release-notes/2022-10-10-Release-Notes)
    11. > >
  11. > [Busca por id e suporte a estorno no > Dashboard](/release-notes/2022-11-11-Release-Notes) >
    12. > >
  12. [Link de Pagamento](/release-notes/2022-11-16-Release-Notes)
    13. > >
  13. > [Eventos assíncronos com webhook](/release-notes/2022-11-24-Release-Notes) >
    14. > >
  14. [Fluxo Inteligente](/release-notes/2022-11-29-Release-Notes)
    15. >
  15. [Split de Pagamentos](/release-notes/2022-12-20-Release-Notes)
    16. > >
  16. > [runBeforeCharge option no > Antifraude](/release-notes/2022-12-22-Release-Notes) >
    17. >
> [tab] Release Notes - 2021 > >
    >
  1. [Pix atrelado a customer](/release-notes/2021-07-28-Release-Notes)
    2. >
  2. [Features pagarme, fingerprint, fluxo de estorno e mais](/release-notes/2021-10-20-Release-Notes)
    3. >
  3. [Novidades no Checkout](/release-notes/2021-11-08-Release-Notes)
    4. >
  4. [Crédito pela REDE](/release-notes/2021-11-29-Release-Notes)
    5. >
  5. [Novidades em tokenização de cartões](/release-notes/2021-12-23-Release-Notes)
    6. >
# Resumo de repasses (consolidado por lote) Source: https://docs.malga.io/resumo-de-repasses-consolidado-por-lote Exporte o Resumo de repasses do Dashboard com o consolidado de cada lote por recebedor processado pelo provedor Malga, incluindo crédito total, ajustes, taxas, tarifas, saldo devedor e saldo total. > [!NOTE] > > Estes relatórios cobrem apenas as transações processadas pelo **provedor Malga**. Cobranças feitas por outros provedores conectados à plataforma (como Cielo, Rede, Adyen, entre outros) não aparecem aqui. O **Resumo de repasses** contempla a visão consolidada dos lotes de repasse. É o relatório usado para conferir quanto cada recebedor recebeu em cada lote e de que forma esse valor foi composto. Na estrutura deste relatório, **cada linha é um lote de um recebedor**. Todas as vendas, estornos, chargebacks, ajustes e taxas daquele lote vêm somados em colunas próprias. Com isso é possível analisar: * Saldo repassado a cada recebedor, lote a lote * Composição do repasse, da venda bruta até o valor creditado * Impacto de estornos, chargebacks e ajustes manuais * Taxas, tarifas e taxa de saque descontadas * Saldo devedor trazido de lotes anteriores Caso precise do detalhe transação a transação que compõe cada lote, utilize o [**relatório de Repasses**](/relatorio-de-repasses-detalhe-por-transacao-do-lote). > [!NOTE] > > O período de exportação é **pela data estimada de liquidação do lote**, e não pela data de criação da cobrança. Uma venda feita em setembro que liquida em outubro aparece no relatório de outubro. ## Como o lote é formado Um lote agrupa as transações de um mesmo **recebedor**, de um mesmo **arranjo de pagamento** (bandeira), com a mesma **data estimada de liquidação**. Por isso um recebedor pode ter vários lotes no mesmo dia, um por bandeira. ## Como o saldo é composto Cada coluna carrega o próprio sinal, e o saldo é uma soma simples: ```text theme={null} Saldo total = Crédito total + Ajuste total + Taxas + Tarifas + Taxa de saque + Saldo devedor ``` Onde: * **Crédito total** é a soma das vendas do lote pelo valor bruto, antes de qualquer desconto * **Ajuste total** é a soma de `Chargebacks`, `Estornos` e `Ajustes manuais` * **Taxas** agrega o MDR e a taxa de antecipação sob demanda das transações do lote * **Tarifas** é o débito consolidado das tarifas de 3DS e antifraude * **Taxa de saque** é cobrada no lote em que o saque acontece * **Saldo devedor** é a dívida com que o lote começa Para conferir o consolidado contra o detalhe, o `Saldo total` menos o `Saldo devedor` de um lote é igual à soma do `Valor líquido` das linhas daquele lote no [relatório de Repasses](/relatorio-de-repasses-detalhe-por-transacao-do-lote). ## Saldo devedor e lotes compensados Quando as operações de um lote não cobrem o que o recebedor já devia, o lote fecha com saldo negativo e nada é creditado. A dívida restante passa para o lote seguinte. * **`Saldo devedor`** é a dívida com que o lote **começa**, ou seja, o `Saldo total` do lote anterior * **`Saldo total`** é o que **sobra** depois do lote, e vira o `Saldo devedor` do próximo * O quanto foi abatido no lote é a diferença entre os dois Exemplo de um lote que abate parte de uma dívida anterior: | Coluna | Valor | | - | - | | Crédito total | 294,50 | | Estornos | -51,09 | | Taxas | -207,19 | | Saldo devedor (veio do lote anterior) | -726,56 | | **Saldo total** (passa para o próximo) | **-690,34** | Neste lote houve 294,50 de venda, foram abatidos 36,22 da dívida, e restaram 690,34 a abater. O lote aparece com o status **Compensado**, e segue no relatório com todas as colunas preenchidas. > [!NOTE] > > Lotes com status Compensado aparecem normalmente no relatório. É assim que você acompanha vendas que ocorreram mas não geraram crédito, e enxerga a dívida sendo abatida ao longo da cadeia de lotes. **Confira abaixo os campos disponíveis no Resumo de repasses:** | **Dados** | **Campo (pt-br)** | **Descrição** | | - | - | - | | **Lote** | ID do lote | Identificador do lote, igual ao do relatório de Repasses | | | Subconta | Identificador da subconta | | | ID do recebedor | Identificador do recebedor, igual ao do relatório de Repasses | | | Recebedor | Nome do recebedor | | **Crédito** | Crédito total | Soma das vendas do lote pelo valor bruto, antes de qualquer desconto | | **Ajustes** | Chargebacks | Soma dos chargebacks do lote | | | Estornos | Soma dos estornos do lote | | | Ajustes manuais | Soma dos ajustes lançados manualmente | | | Motivo do ajuste | Motivo do ajuste manual, quando houver | | | Ajuste total | Soma de chargebacks, estornos e ajustes manuais | | **Descontos** | Taxas | MDR mais taxa de antecipação sob demanda das transações do lote | | | Tarifas | Débito consolidado das tarifas de 3DS e antifraude do mês | | | Taxa de saque | Tarifa cobrada no lote em que o saque acontece | | **Saldo** | Saldo devedor | Dívida com que o lote começa, igual ao saldo total do lote anterior | | | Saldo total | Resultado do lote. Positivo é o valor creditado, negativo é a dívida que passa ao próximo lote | | **Liquidação** | Conta de liquidação | Conta de onde o valor é liquidado | | | Conta destinatária | Conta que recebe o valor | | | Data estimada de liquidação | Data prevista para a liquidação do lote | | | Data de liquidação | Data em que a liquidação ocorreu | | | Status do lote | Pago, Em andamento, Falha ou Compensado | ## Status do lote
Status O que significa
**Pago** O lote foi liquidado e o valor foi creditado na conta destinatária
**Em andamento** O lote ainda não chegou à data de liquidação
**Falha** A liquidação foi tentada e não se concluiu
**Compensado** O lote fechou com saldo zero ou negativo e não gerou crédito. O valor foi usado para abater o saldo devedor, e o que restou passa ao lote seguinte
> [!NOTE] > > Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)). # Criar chave pública Source: https://docs.malga.io/sdks/api-sdks/docs/auth/create-public-key Gere uma chave pública temporária (client-token) para uso no client-side da Malga via API SDK em Node.js ou PHP, garantindo segurança PCI. Crie chaves de acesso com escopos específicos para que possam ser usadas no client-side. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.auth.createPublicKey({ > scope: ["tokens"], > expires: 60, > }); > ``` > [tab] Response > > ```typescript theme={null} > { > publicKey: 'ff4664a8-a4e2-43dc-b6f3-27f44291b31c', > createdAt: '2023-12-31T14:12:37.735Z', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > expires: 60, > scope: ['tokens'], > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **scope** `array` *required* Escopos suportados da chave. Os valores suportados são: * `customers` * `cards` * `tokens` * `charges` * `webhooks` * `sessions` * `auth` * `reports` * `flows` * `sellers` * `providers` * `subscriptions` * `graphql` (Analytics API) **expires** `number` *required* Tempo de expiração da chave em segundos # Criar cartão Source: https://docs.malga.io/sdks/api-sdks/docs/cards/create-card Crie e armazene cartões de crédito com segurança PCI usando o método de criação de cartões da API SDK da Malga em Node.js, PHP e mais. Crie e armazene cartões com segurança. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.cards.create({ > tokenId: '2c9ba735-3600-45f3-a4b8-7ecdec230051', > zeroDollar: { > cvvCheck: true, > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > }, > }) > ``` > [tab] response > > ```typescript theme={null} > { > id: 'a7e38bca-80d7-47a4-8553-7bda4a308424', > status: 'active', > createdAt: '2023-12-31T03:00:00.000Z', > clientId: 'c13a47b7-f232-46bd-bac7-7effe39af877', > customerId: null, > brand: 'Mastercard', > cardHolderName: 'João da Silva', > cvvChecked: true, > fingerprint: '/cddsad2sgTXxfNhdsadasdas2QSLsJ/dsadsadcxc=', > first6digits: '545388', > last4digits: '7600', > expirationMonth: '10', > expirationYear: '2030', > statusReason: 'fingerprint', > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **tokenId** `uuid` *required* ID do cartão tokenizado **zeroDollar** `object` Dados da validação de cartão com Zero Dollar **Parâmetros do zeroDollar** **merchantId** `uuid` ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar **cvvCheck** `boolean` Valide o CVV do cartão no momento da criação # Buscar cartão Source: https://docs.malga.io/sdks/api-sdks/docs/cards/find-card Recupere os detalhes de um cartão armazenado a partir do seu identificador usando o método de busca de cartão da API SDK da Malga. Busca um cartão pelo seu ID. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.cards.find('a7e38bca-80d7-47a4-8553-7bda4a308424') > ``` > [tab] response > > ```typescript theme={null} > { > id: 'a7e38bca-80d7-47a4-8553-7bda4a308424', > status: 'active', > createdAt: '2023-12-31T03:00:00.000Z', > clientId: 'c13a47b7-f232-46bd-bac7-7effe39af877', > customerId: null, > brand: 'Mastercard', > cardHolderName: 'João da Silva', > cvvChecked: true, > fingerprint: '/cddsad2sgTXxfNhdsadasdas2QSLsJ/dsadsadcxc=', > first6digits: '545388', > last4digits: '7600', > expirationMonth: '10', > expirationYear: '2030', > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID do cartão # Listar os cartões Source: https://docs.malga.io/sdks/api-sdks/docs/cards/list-cards Liste de forma paginada os cartões armazenados na sua conta Malga usando o método de listagem de cartões da API SDK em Node.js ou PHP. Liste todos os seus cartões armazenados. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.cards.list() > ``` > [tab] response > > ```typescript theme={null} > { > items: [ > { > id: 'a7e38bca-80d7-47a4-8553-7bda4a308424', > status: 'active', > createdAt: '2023-12-31T03:00:00.000Z', > clientId: 'c13a47b7-f232-46bd-bac7-7effe39af877', > customerId: null, > brand: 'Mastercard', > cardHolderName: 'João da Silva', > cvvChecked: true, > fingerprint: '/cddsad2sgTXxfNhdsadasdas2QSLsJ/dsadsadcxc=', > first6digits: '545388', > last4digits: '7600', > expirationMonth: '10', > expirationYear: '2030', > } > ], > meta: { > totalItems: 1 > itemCount: 1 > itemsPerPage: 15 > totalPages: 1 > currentPage: 1 > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **page** `number` Número da página que deverá ser listada **limit** `number` Limite de itens por página # Tokenização de cartão Source: https://docs.malga.io/sdks/api-sdks/docs/cards/tokenization-card Tokenize dados de cartão de crédito de forma segura para uso em cobranças posteriores usando o método de tokenização da API SDK da Malga. Crie tokens para referenciar seus cartões e não ter que trafegar dados sensíveis no seu servidor. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.cards.tokenization({ > holderName: 'João da Silva', > number: '5453881028277600', > cvv: '170', > expirationDate: '10/2030', > }) > ``` > [tab] response > > ```typescript theme={null} > { > tokenId: '2c9ba735-3600-45f3-a4b8-7ecdec230051' > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **holderName** `string` *required* Nome do portador do cartão **number** `string` *required* Número do cartão **cvv** `string` *required* Código de segurança do cartão **expirationDate** `string` *required* Data de validade do cartão # Tokenização de CVV Source: https://docs.malga.io/sdks/api-sdks/docs/cards/tokenization-cvv Tokenize o código CVV de um cartão para reutilizá-lo em novas cobranças com segurança usando a API SDK da Malga em Node.js ou PHP. Crie tokens de CVV para transacionar com cartões já existentes e não ter que trafegar dados sensíveis no seu servidor. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.cards.tokenization({ > cvv: '170', > }) > ``` > [tab] response > > ```typescript theme={null} > { > tokenId: '2c9ba735-3600-45f3-a4b8-7ecdec230051' > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **cvv** `string` *required* Código de segurança do cartão # Capturar cobrança Source: https://docs.malga.io/sdks/api-sdks/docs/charges/capture-charge Capture cobranças pré-autorizadas em cartão de crédito de forma total ou parcial via API SDK da Malga em Node.js ou PHP, com payload completo. Capture cobranças pré-autorizadas. ### Método > [tab] Node > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.capture( > '2f97378a-f174-4865-9d14-6ffc10fb34f0', > { amount: 100 } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: true, > isDispute: false, > status: 'authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: 'ff59d15e-5837-42c5-bc3c-d3988b0486c7', > createdAt: '2023-12-31T19:19:45.013Z', > updatedAt: '2023-12-31T19:19:45.044Z', > idempotencyKey: 'bd99414d-9fdc-4801-818e-7482085ab77e', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'capture', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > }, > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da cobrança **payload** `object` *required* Segundo parâmetro **Parâmetros de payload** **amount** `number` *required* Valor da cobrança a ser capturado # Criar cobrança com boleto Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-boleto Crie cobranças com boleto bancário através da API SDK da Malga em Node.js ou PHP, com geração automática do boleto e linha digitável. Crie cobranças com boleto e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > amount: 100, > paymentMethod: { > type: 'boleto' > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pending', > paymentMethod: { > paymentType: 'boleto', > barcodeData: '1111 2222 3333 4444', > barcodeImageUrl: 'https://malga.io', > }, > paymentSource: { > sourceType: 'customer', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: null, > authorizationNsu: null, > requestStatus: 'success', > requestType: 'pending', > responseTs: '11ms', > boleto: { > expiresDate: null, > barcodeData: '1111 2222 3333 4444', > barcodeImageUrl: 'https://malga.io', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com boleto **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com boleto sempre será `boleto` **expiresDate** `string` Data de vencimento do boleto **instructions** `string` Instruções do boleto **interest** `object` Dados opcionais da condição de juros para pagamento em atraso **Parâmetros do interest** **days** `number` *required* Dias após a expiração do boleto em que ocorrerá a cobrança dos juros **amount** `number` Valor em centavos da taxa de juros que será cobrado ao dia **percentage** `number` Valor em porcentagem da taxa de juros que será cobrado ao mês **fine** `object` Dados opcionais da condição de multa para pagamento em atraso **Parâmetros do fine** **days** `number` *required* Dias após a expiração do boleto em que ocorrerá a cobrança da multa **amount** `number` Valor em centavos da multa **percentage** `number` Valor em porcentagem da multa **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` *required* ID do Customer que será usado na cobrança **customer** `object` *required* Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com cartão de crédito Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-credit Crie cobranças com cartão de crédito usando a API SDK da Malga em Node.js ou PHP, com suporte a parcelamento, antifraude e captura. Crie cobranças com cartão de crédito e comece a transacionar com Malga. > [!WARNING] > > Lembre-se que para gerenciar e armazenar cartões diretamente no seu servidor é necessário o certificado PCI-DSS. > > Caso sua empresa não tenha o certificado, utilize a tokenização de cartão para a criação de cobranças com cartão de crédito. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > amount: 100, > paymentMethod: { > type: 'credit', > installments: 1, > card: { > holderName: 'João da Silva', > number: '5453881028277600', > cvv: '170', > expirationDate: '10/2030', > }, > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pre_authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **paymentMethod** `object` *required* Dados do pagamento com cartão **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com cartão de crédito sempre será `credit` **card** `object` *required* Dados do cartão de crédito **Parâmetros do card** **holderName** `string` *required* Nome do portador do cartão **number** `string` *required* Número do cartão **cvv** `string` *required* Código de segurança do cartão **expirationDate** `string` *required* Data de validade do cartão **zeroDollar** `object` Dados da validação de cartão com Zero Dollar **Parâmetros do zeroDollar** **merchantId** `uuid` ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar **cvvCheck** `boolean` Valide o CVV do cartão no momento da criação **installments** `number` *required* Número de parcelas **linkCardToCustomer** `boolean` Vincula o cartão automaticamente com o customer **capture** `boolean` Define se a cobrança deve ser capturada automaticamente **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **statementDescriptor** `string` Descrição da cobrança que irá aparecer na fatura do cartão **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **fraudAnalysis** `object` Dados para utilização das funcionalidades de antifraude **Parâmetros do fraudAnalysis** **sla** `number` Valor em minutos de SLA máximo de análise do pedido **customer** `object` Dados do cliente **Parâmetros do customer** **name** `string` Nome do cliente **email** `string` E-mail do cliente **phone** `string` Telefone do cliente **identity** `string` Número do documento do cliente **identityType** `string` Tipo do documento do cliente **registrationDate** `string` Data de registro do cliente **deliveryAddress** `object` Dados do endereço de entrega do cliente **Parâmetros do deliveryAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **billingAddress** `object` Dados do endereço de cobrança do cliente **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **browser** `object` Dados do navegador do cliente **Parâmetros do browser** **browserFingerprint** `string` *required* Fingerprint gerado dos dados do navegador **cookiesAccepted** `boolean` *required* Indica se os cookies foram aceitados **email** `string` *required* E-mail logado no navegador **hostName** `string` *required* Nome do host do usuário **ipAddress** `string` *required* Endereço de IP do usuário **type** `string` *required* User-Agent do navegador **cart** `object` Dados dos itens do carrinho **Parâmetros do cart** **items** `array` *required* **Parâmetros do items** **name** `string` *required* Nome do produto **quantity** `number` *required* Quantidade do produto **sku** `string` *required* Identificador único do item na loja **unitPrice** `number` *required* Preço de cada produto **risk** `string` *required* Definição do índice de risco do produto Os tipos suportados são: `Low` ou `High` **description** `string` Descrição do produto **categoryId** `string` Categoria do produto **locality** `string` Localidade onde ocorrerá o evento **date** `string` Data do evento **type** `number` Tipo do evento **genre** `string` Definição do gênero do evento **tickets** `object` Dados do ingresso **Parâmetros do tickets** **quantityTicketSale** `number` Quantidade total de ingressos à venda **quantityEventHouse** `number` Quantidade de vezes que o evento será realizado na casa **convenienceFeeValue** `number` Taxa de conveniência **quantityFull** `number` Quantidade de ingressos com valor integral **quantityHalf** `number` Quantidade de ingresso com desconto (meia entrada) **batch** `number` Lote do ingresso **location** `object` Dados do endereço do evento **Parâmetros do location** **city** `string` Cidade **country** `string` País **district** `string` Bairro **state** `string` Estado **street** `string` Nome da rua, avenida ou travessa **number** `string` Número da rua **zipCode** `string` Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **device** `object` Dados do aparelho do cliente **Parâmetros do device** **model** `string` Nome do modelo do aparelho **ramCapacity** `string` Capacidade da memória RAM do aparelho **diskCapacity** `string` Capacidade de armazenamento do aparelho **freeDiskSpace** `number` Quantidade de armazenamento livre do aparelho **resolution** `number` Resolução do aparelho **os** `object` Dados do sistema operacional do aparelho **Parâmetros do os** **type** `string` Tipo do sistema operacional **version** `string` Versão do sistema operacional **vendorAttributes** `object` Dados dos atributos do aparelho **Parâmetros do vendorAttributes** **flash** `boolean` Aparelho possui flash na câmera **phoneCalls** `boolean` Aparelho pode realizar chamadas **sendSms** `boolean` Aparelho pode enviar SMS **videoCamera** `boolean` Aparelho possui câmera de vídeo **cpuCount** `number` Quantidade de CPUs do aparelho **simulator** `boolean` Aparelho possui simulador **language** `string` Linguagem do aparelho **idiom** `string` Idioma do aparelho **platform** `string` Plataforma do sistema operacional **name** `string` Nome do aparelho **family** `string` Família do aparelho **retinaDisplay** `boolean` Aparelho possui display de retina **camera** `boolean` Aparelho possui câmera **model** `string` Modelo do aparelho **frontCamera** `boolean` Aparelho possui câmera frontal **vendors** `array` Dados adicionais do aparelho **Parâmetros do vendors** **name** `string` Nome do atributo do fornecedor **value** `string` Valor do atributo do fornecedor **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **threeDSecure** `object` Dados para utilização da funcionalidade de 3DS **Parâmetros do threeDSecure** **redirectURL** `string` *required* URL para redirecionamento da autenticação **requestorURL** `string` *required* URL de origem da requisição **browser** `object` *required* Dados do navegador do cliente **Parâmetros do browser** **acceptHeader** `string` *required* O Accept do cabeçalho de requisição HTTP **colorDepth** `number` *required* A profundidade de cores da tela **javaEnabled** `boolean` *required* Indica se o Java está habilitado **javaScriptEnabled** `boolean` *required* Indica se o JavaScript está habilitado **language** `string` *required* A linguagem utilizada pelo sistema do usuário **screenHeight** `number` *required* Altura da tela **screenWidth** `number` *required* Largura da tela **timeZoneOffset** `string` *required* Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual **userAgent** `string` *required* O User-Agent do cabeçalho de requisição HTTP **ip** `string` *required* Endereço de IP do usuário **billingAddress** `object` Dados do endereço de cobrança **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **shippingAddress** `object` Dados do endereço de envio **Parâmetros do shippingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **cardHolder** `object` Dados do titular do cartão **Parâmetros do cardHolder** **email** `string` *required* E-mail do titular do cartão **mobilePhone** `string` Telefone do titular do cartão **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com Drip Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-drip Crie cobranças com o método de pagamento Drip pela API SDK da Malga em Node.js ou PHP, com toda a estrutura de payload necessária. Crie cobranças com Drip e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > amount: 100, > paymentMethod: { > type: 'drip', > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pending', > paymentMethod: { > paymentType: 'drip', > paymentUrl: 'https://sdb-drip-checkout-url.com.br/2f97378a-f174-4865-9d14-6ffc10fb34f0', > successRedirectUrl: null, > cancelRedirectUrl: null, > }, > paymentSource: { > sourceType: 'customer', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: null, > authorizationNsu: null, > requestStatus: 'success', > requestType: 'pending', > responseTs: '11ms', > drip: { > paymentUrl: 'https://sdb-drip-checkout-url.com.br/2f97378a-f174-4865-9d14-6ffc10fb34f0', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com Drip **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com Drip sempre será `drip` **successRedirectUrl** `string` Link de redirecionamento em caso de aprovação do pagamento no ambiente de checkout da Drip **cancelRedirectUrl** `string` Link de redirecionamento em caso de cancelamento do pagamento no ambiente de checkout da Drip **browser** `object` Dados do navegador do cliente **Parâmetros do browser** **ipAddress** `string` Endereço IP do cliente **browserFingerprint** `string` Fingerprint do navegador utilizado pelo cliente **items** `array` Dados dos produtos do pedido **Parâmetros do items** **id** `string` *required* Identificador único do produto **title** `string` *required* Nome do produto **unitPrice** `number` *required* Preço do produto **quantity** `number` *required* Quantidade do produto **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com NuPay Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-nupay Crie cobranças com o método de pagamento NuPay usando a API SDK da Malga em Node.js ou PHP, com exemplo completo de payload e fluxo. Crie cobranças com NuPay e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > orderId: '3630e825-efa3-42a8-b4b1-4528cefaaf5b', > amount: 100, > paymentMethod: { > type: 'nupay', > items: [ > { > sku: '123', > name: 'Produto 1', > quantity: 1, > unitPrice: 100, > risk: 'Low', > } > ] > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: '3630e825-efa3-42a8-b4b1-4528cefaaf5b', > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pending', > paymentMethod: { > paymentType: 'nupay', > }, > paymentSource: { > sourceType: 'customer', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > }, > fraudAnalysisMetadata: { > sla: null, > customer: { > name: null, > email: null, > identity: null, > identityType: null, > birthdate: null, > phone: null, > billingAddress: null, > deliveryAddress: null > }, > cart: { > items: [ > { > name: 'Produto 1', > quantity: 1, > sku: '123', > unitPrice: 1, > risk: 'Low', > locality: null, > date: null, > type: null, > genre: null, > tickets: null, > location: null > } > ] > } > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: null, > authorizationNsu: null, > requestStatus: 'success', > requestType: 'pending', > responseTs: '11ms', > nupay: { > paymentUrl: 'https://nubank.com.br' > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com NuPay **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com NuPay sempre será `nupay` **items** `array` *required* Dados dos produtos do pedido **Parâmetros do items** **name** `string` *required* Nome do produto **quantity** `number` *required* Quantidade do produto **sku** `string` *required* Identificador único do item na loja **unitPrice** `number` *required* Preço de cada produto **risk** `string` *required* Definição do índice de risco do produto Os tipos suportados são: `Low` ou `High` **orderUrl** `string` URL de origem da cobrança **returnUrl** `string` URL para a qual o cliente será redirecionado após finalizar o pagamento **cancelUrl** `string` URL para onde o cliente será direcionado caso escolha não finalizar o pagamento e cancele o pedido **taxValue** `number` Total de taxas aplicadas em centavos **delayToAutoCancel** `number` Tempo em minutos para a expiração de uma cobrança criada que não tenha sido paga **orderId** `string` *required* Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com Pix Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-pix Crie cobranças com Pix usando a API SDK da Malga em Node.js ou PHP, com geração de QR Code e copia-e-cola para pagamento instantâneo. Crie cobranças com Pix e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > amount: 100, > paymentMethod: { > type: 'pix', > expiresIn: 3600 > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pending', > paymentMethod: { > paymentType: 'pix', > qrCodeData: '00020101021126430014BR.GOV.BCB.PIX010002173fcae964ec08d0ad9196d59e1e66304477C', > qrCodeImageUrl: 'https://malga.io', > expiresIn: 3600, > }, > paymentSource: { > sourceType: 'customer', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: null, > authorizationNsu: null, > requestStatus: 'success', > requestType: 'pending', > responseTs: '11ms', > pix: { > qrCodeData: '00020101021126430014BR.GOV.BCB.PIX010002173fcae964ec08d0ad9196d59e1e66304477C', > qrCodeImageUrl: 'https://malga.io', > expiresIn: 3600, > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com Pix **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com Pix sempre será `pix` **expiresIn** `number` *required* Tempo de expiração do Pix em segundos **additionalInfo** `array` Dados adicionais para o pagamento **Parâmetros do additionalInfo** **name** `string` *required* Nome do dado adicional **value** `string` *required* Valor do dado adicional **items** `array` Dados dos produtos do pedido **Parâmetros do items** **id** `string` *required* Identificador único do produto **title** `string` *required* Nome do produto **unitPrice** `number` *required* Preço do produto **quantity** `number` *required* Quantidade do produto **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` *required* ID do Customer que será usado na cobrança **customer** `object` *required* Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com cartão armazenado Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-saved-card Realize cobranças usando um cartão previamente salvo (cardId) na Malga via API SDK em Node.js ou PHP, sem digitar dados novamente. Crie cobranças com um cartão já armazenado e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > amount: 100, > paymentMethod: { > type: 'credit', > installments: 1, > cardId: '9d21af8e-0379-4217-af52-a7bcd4c8385e' > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pre_authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '9d21af8e-0379-4217-af52-a7bcd4c8385e', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com cartão **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com cartão de crédito sempre será `credit` **cardId** `uuid` *required* ID do cartão já armazenado **cardCvv** `string` CVV do cartão sem ser tokenizado para verificação do cartão **tokenCvv** `string` CVV tokenizado para verificação do cartão **installments** `number` *required* Número de parcelas **linkCardToCustomer** `boolean` Vincula o cartão automaticamente com o customer **capture** `boolean` Define se a cobrança deve ser capturada automaticamente **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **statementDescriptor** `string` Descrição da cobrança que irá aparecer na fatura do cartão **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **fraudAnalysis** `object` Dados para utilização das funcionalidades de antifraude **Parâmetros do fraudAnalysis** **sla** `number` Valor em minutos de SLA máximo de análise do pedido **customer** `object` Dados do cliente **Parâmetros do customer** **name** `string` Nome do cliente **email** `string` E-mail do cliente **phone** `string` Telefone do cliente **identity** `string` Número do documento do cliente **identityType** `string` Tipo do documento do cliente **registrationDate** `string` Data de registro do cliente **deliveryAddress** `object` Dados do endereço de entrega do cliente **Parâmetros do deliveryAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **billingAddress** `object` Dados do endereço de cobrança do cliente **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **browser** `object` Dados do navegador do cliente **Parâmetros do browser** **browserFingerprint** `string` *required* Fingerprint gerado dos dados do navegador **cookiesAccepted** `boolean` *required* Indica se os cookies foram aceitados **email** `string` *required* E-mail logado no navegador **hostName** `string` *required* Nome do host do usuário **ipAddress** `string` *required* Endereço de IP do usuário **type** `string` *required* User-Agent do navegador **cart** `object` Dados dos itens do carrinho **Parâmetros do cart** **items** `array` *required* **Parâmetros do items** **name** `string` *required* Nome do produto **quantity** `number` *required* Quantidade do produto **sku** `string` *required* Identificador único do item na loja **unitPrice** `number` *required* Preço de cada produto **risk** `string` *required* Definição do índice de risco do produto Os tipos suportados são: `Low` ou `High` **description** `string` Descrição do produto **categoryId** `string` Categoria do produto **locality** `string` Localidade onde ocorrerá o evento **date** `string` Data do evento **type** `number` Tipo do evento **genre** `string` Definição do gênero do evento **tickets** `object` Dados do ingresso **Parâmetros do tickets** **quantityTicketSale** `number` Quantidade total de ingressos à venda **quantityEventHouse** `number` Quantidade de vezes que o evento será realizado na casa **convenienceFeeValue** `number` Taxa de conveniência **quantityFull** `number` Quantidade de ingressos com valor integral **quantityHalf** `number` Quantidade de ingresso com desconto (meia entrada) **batch** `number` Lote do ingresso **location** `object` Dados do endereço do evento **Parâmetros do location** **city** `string` Cidade **country** `string` País **district** `string` Bairro **state** `string` Estado **street** `string` Nome da rua, avenida ou travessa **number** `string` Número da rua **zipCode** `string` Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **device** `object` Dados do aparelho do cliente **Parâmetros do device** **model** `string` Nome do modelo do aparelho **ramCapacity** `string` Capacidade da memória RAM do aparelho **diskCapacity** `string` Capacidade de armazenamento do aparelho **freeDiskSpace** `number` Quantidade de armazenamento livre do aparelho **resolution** `number` Resolução do aparelho **os** `object` Dados do sistema operacional do aparelho **Parâmetros do os** **type** `string` Tipo do sistema operacional **version** `string` Versão do sistema operacional **vendorAttributes** `object` Dados dos atributos do aparelho **Parâmetros do vendorAttributes** **flash** `boolean` Aparelho possui flash na câmera **phoneCalls** `boolean` Aparelho pode realizar chamadas **sendSms** `boolean` Aparelho pode enviar SMS **videoCamera** `boolean` Aparelho possui câmera de vídeo **cpuCount** `number` Quantidade de CPUs do aparelho **simulator** `boolean` Aparelho possui simulador **language** `string` Linguagem do aparelho **idiom** `string` Idioma do aparelho **platform** `string` Plataforma do sistema operacional **name** `string` Nome do aparelho **family** `string` Família do aparelho **retinaDisplay** `boolean` Aparelho possui display de retina **camera** `boolean` Aparelho possui câmera **model** `string` Modelo do aparelho **frontCamera** `boolean` Aparelho possui câmera frontal **vendors** `array` Dados adicionais do aparelho **Parâmetros do vendors** **name** `string` Nome do atributo do fornecedor **value** `string` Valor do atributo do fornecedor **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **threeDSecure** `object` Dados para utilização da funcionalidade de 3DS **Parâmetros do threeDSecure** **redirectURL** `string` *required* URL para redirecionamento da autenticação **requestorURL** `string` *required* URL de origem da requisição **browser** `object` *required* Dados do navegador do cliente **Parâmetros do browser** **acceptHeader** `string` *required* O Accept do cabeçalho de requisição HTTP **colorDepth** `number` *required* A profundidade de cores da tela **javaEnabled** `boolean` *required* Indica se o Java está habilitado **javaScriptEnabled** `boolean` *required* Indica se o JavaScript está habilitado **language** `string` *required* A linguagem utilizada pelo sistema do usuário **screenHeight** `number` *required* Altura da tela **screenWidth** `number` *required* Largura da tela **timeZoneOffset** `string` *required* Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual **userAgent** `string` *required* O User-Agent do cabeçalho de requisição HTTP **ip** `string` *required* Endereço de IP do usuário **billingAddress** `object` Dados do endereço de cobrança **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **shippingAddress** `object` Dados do endereço de envio **Parâmetros do shippingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **cardHolder** `object` Dados do titular do cartão **Parâmetros do cardHolder** **email** `string` *required* E-mail do titular do cartão **mobilePhone** `string` Telefone do titular do cartão **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com session Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-session Realize o pagamento de uma sessão na Malga via API SDK em Node.js ou PHP; as regras de split são herdadas da sessão e não desta chamada. Crie cobranças com session e comece a transacionar com Malga. Se a sessão foi criada **com split**, as regras ficam **gravadas na sessão** e são aplicadas automaticamente na cobrança. **Não** passe `splitRules` neste método — use `splitRules` apenas na **criação da sessão** (API `POST /v1/sessions`). Saiba mais em [Split em sessão ou link de pagamento](/documentations/split/split-em-sessao-link). ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > publicKey: '1ce3e1e0-a2d4-444c-acd1-4c62ad80a299', > sessionId: '26e04fc1-6531-4d24-96d5-aa8ae440be88', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > paymentMethod: { > type: 'pix', > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > sessionId: '26e04fc1-6531-4d24-96d5-aa8ae440be88' > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pending', > paymentMethod: { > paymentType: 'pix', > qrCodeData: '00020101021126430014BR.GOV.BCB.PIX010002173fcae964ec08d0ad9196d59e1e66304477C', > qrCodeImageUrl: 'https://malga.io', > expiresIn: 3600, > }, > paymentSource: { > sourceType: 'customer', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: null, > authorizationNsu: null, > requestStatus: 'success', > requestType: 'pending', > responseTs: '11ms', > pix: { > qrCodeData: '00020101021126430014BR.GOV.BCB.PIX010002173fcae964ec08d0ad9196d59e1e66304477C', > qrCodeImageUrl: 'https://malga.io', > expiresIn: 3600, > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **publicKey** `uuid` *required* Chave pública gerada unicamente para o pagamento da session **sessionId** `uuid` *required* ID da session que será usada para a cobrança **paymentMethod** `object` *required* Dados do pagamento conforme método de pagamento usado **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **fraudAnalysis** `object` Dados para utilização das funcionalidades de antifraude **Parâmetros do fraudAnalysis** **sla** `number` Valor em minutos de SLA máximo de análise do pedido **customer** `object` Dados do cliente **Parâmetros do customer** **name** `string` Nome do cliente **email** `string` E-mail do cliente **phone** `string` Telefone do cliente **identity** `string` Número do documento do cliente **identityType** `string` Tipo do documento do cliente **registrationDate** `string` Data de registro do cliente **deliveryAddress** `object` Dados do endereço de entrega do cliente **Parâmetros do deliveryAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **billingAddress** `object` Dados do endereço de cobrança do cliente **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **browser** `object` Dados do navegador do cliente **Parâmetros do browser** **browserFingerprint** `string` *required* Fingerprint gerado dos dados do navegador **cookiesAccepted** `boolean` *required* Indica se os cookies foram aceitados **email** `string` *required* E-mail logado no navegador **hostName** `string` *required* Nome do host do usuário **ipAddress** `string` *required* Endereço de IP do usuário **type** `string` *required* User-Agent do navegador **cart** `object` Dados dos itens do carrinho **Parâmetros do cart** **items** `array` *required* **Parâmetros do items** **name** `string` *required* Nome do produto **quantity** `number` *required* Quantidade do produto **sku** `string` *required* Identificador único do item na loja **unitPrice** `number` *required* Preço de cada produto **risk** `string` *required* Definição do índice de risco do produto Os tipos suportados são: `Low` ou `High` **description** `string` Descrição do produto **categoryId** `string` Categoria do produto **locality** `string` Localidade onde ocorrerá o evento **date** `string` Data do evento **type** `number` Tipo do evento **genre** `string` Definição do gênero do evento **tickets** `object` Dados do ingresso **Parâmetros do tickets** **quantityTicketSale** `number` Quantidade total de ingressos à venda **quantityEventHouse** `number` Quantidade de vezes que o evento será realizado na casa **convenienceFeeValue** `number` Taxa de conveniência **quantityFull** `number` Quantidade de ingressos com valor integral **quantityHalf** `number` Quantidade de ingresso com desconto (meia entrada) **batch** `number` Lote do ingresso **location** `object` Dados do endereço do evento **Parâmetros do location** **city** `string` Cidade **country** `string` País **district** `string` Bairro **state** `string` Estado **street** `string` Nome da rua, avenida ou travessa **number** `string` Número da rua **zipCode** `string` Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **device** `object` Dados do aparelho do cliente **Parâmetros do device** **model** `string` Nome do modelo do aparelho **ramCapacity** `string` Capacidade da memória RAM do aparelho **diskCapacity** `string` Capacidade de armazenamento do aparelho **freeDiskSpace** `number` Quantidade de armazenamento livre do aparelho **resolution** `number` Resolução do aparelho **os** `object` Dados do sistema operacional do aparelho **Parâmetros do os** **type** `string` Tipo do sistema operacional **version** `string` Versão do sistema operacional **vendorAttributes** `object` Dados dos atributos do aparelho **Parâmetros do vendorAttributes** **flash** `boolean` Aparelho possui flash na câmera **phoneCalls** `boolean` Aparelho pode realizar chamadas **sendSms** `boolean` Aparelho pode enviar SMS **videoCamera** `boolean` Aparelho possui câmera de vídeo **cpuCount** `number` Quantidade de CPUs do aparelho **simulator** `boolean` Aparelho possui simulador **language** `string` Linguagem do aparelho **idiom** `string` Idioma do aparelho **platform** `string` Plataforma do sistema operacional **name** `string` Nome do aparelho **family** `string` Família do aparelho **retinaDisplay** `boolean` Aparelho possui display de retina **camera** `boolean` Aparelho possui câmera **model** `string` Modelo do aparelho **frontCamera** `boolean` Aparelho possui câmera frontal **vendors** `array` Dados adicionais do aparelho **Parâmetros do vendors** **name** `string` Nome do atributo do fornecedor **value** `string` Valor do atributo do fornecedor **threeDSecure** `object` Dados para utilização da funcionalidade de 3DS **Parâmetros do threeDSecure** **redirectURL** `string` *required* URL para redirecionamento da autenticação **requestorURL** `string` *required* URL de origem da requisição **browser** `object` *required* Dados do navegador do cliente **Parâmetros do browser** **acceptHeader** `string` *required* O Accept do cabeçalho de requisição HTTP **colorDepth** `number` *required* A profundidade de cores da tela **javaEnabled** `boolean` *required* Indica se o Java está habilitado **javaScriptEnabled** `boolean` *required* Indica se o JavaScript está habilitado **language** `string` *required* A linguagem utilizada pelo sistema do usuário **screenHeight** `number` *required* Altura da tela **screenWidth** `number` *required* Largura da tela **timeZoneOffset** `string` *required* Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual **userAgent** `string` *required* O User-Agent do cabeçalho de requisição HTTP **ip** `string` *required* Endereço de IP do usuário **billingAddress** `object` Dados do endereço de cobrança **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **shippingAddress** `object` Dados do endereço de envio **Parâmetros do shippingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **cardHolder** `object` Dados do titular do cartão **Parâmetros do cardHolder** **email** `string` *required* E-mail do titular do cartão **mobilePhone** `string` Telefone do titular do cartão **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com cartão tokenizado Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-tokenized-card Crie cobranças com cartão tokenizado pela API SDK da Malga em Node.js ou PHP, processando os dados sensíveis com segurança via tokenId. Crie cobranças com cartão tokenizado e comece a transacionar com Malga. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.charges.create({ > merchantId: "2ed73b94-175a-438d-ae73-d11902492b75", > amount: 100, > paymentMethod: { > type: "credit", > installments: 1, > tokenId: "b6ba63e5-0dc5-4bf3-8294-d9fafa21cee9", > }, > }); > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pre_authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'token', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > tokenId: 'b6ba63e5-0dc5-4bf3-8294-d9fafa21cee9', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com cartão **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com cartão de crédito sempre será `credit` **tokenId** `uuid` *required* ID do cartão tokenizado **installments** `number` *required* Número de parcelas **linkCardToCustomer** `boolean` Vincula o cartão automaticamente com o customer **capture** `boolean` Define se a cobrança deve ser capturada automaticamente **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **statementDescriptor** `string` Descrição da cobrança que irá aparecer na fatura do cartão **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **fraudAnalysis** `object` Dados para utilização das funcionalidades de antifraude **Parâmetros do fraudAnalysis** **sla** `number` Valor em minutos de SLA máximo de análise do pedido **customer** `object` Dados do cliente **Parâmetros do customer** **name** `string` Nome do cliente **email** `string` E-mail do cliente **phone** `string` Telefone do cliente **identity** `string` Número do documento do cliente **identityType** `string` Tipo do documento do cliente **registrationDate** `string` Data de registro do cliente **deliveryAddress** `object` Dados do endereço de entrega do cliente **Parâmetros do deliveryAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **billingAddress** `object` Dados do endereço de cobrança do cliente **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **number** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **browser** `object` Dados do navegador do cliente **Parâmetros do browser** **browserFingerprint** `string` *required* Fingerprint gerado dos dados do navegador **cookiesAccepted** `boolean` *required* Indica se os cookies foram aceitados **email** `string` *required* E-mail logado no navegador **hostName** `string` *required* Nome do host do usuário **ipAddress** `string` *required* Endereço de IP do usuário **type** `string` *required* User-Agent do navegador **cart** `object` Dados dos itens do carrinho **Parâmetros do cart** **items** `array` *required* **Parâmetros do items** **name** `string` *required* Nome do produto **quantity** `number` *required* Quantidade do produto **sku** `string` *required* Identificador único do item na loja **unitPrice** `number` *required* Preço de cada produto **risk** `string` *required* Definição do índice de risco do produto Os tipos suportados são: `Low` ou `High` **description** `string` Descrição do produto **categoryId** `string` Categoria do produto **locality** `string` Localidade onde ocorrerá o evento **date** `string` Data do evento **type** `number` Tipo do evento **genre** `string` Definição do gênero do evento **tickets** `object` Dados do ingresso **Parâmetros do tickets** **quantityTicketSale** `number` Quantidade total de ingressos à venda **quantityEventHouse** `number` Quantidade de vezes que o evento será realizado na casa **convenienceFeeValue** `number` Taxa de conveniência **quantityFull** `number` Quantidade de ingressos com valor integral **quantityHalf** `number` Quantidade de ingresso com desconto (meia entrada) **batch** `number` Lote do ingresso **location** `object` Dados do endereço do evento **Parâmetros do location** **city** `string` Cidade **country** `string` País **district** `string` Bairro **state** `string` Estado **street** `string` Nome da rua, avenida ou travessa **number** `string` Número da rua **zipCode** `string` Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **device** `object` Dados do aparelho do cliente **Parâmetros do device** **model** `string` Nome do modelo do aparelho **ramCapacity** `string` Capacidade da memória RAM do aparelho **diskCapacity** `string` Capacidade de armazenamento do aparelho **freeDiskSpace** `number` Quantidade de armazenamento livre do aparelho **resolution** `number` Resolução do aparelho **os** `object` Dados do sistema operacional do aparelho **Parâmetros do os** **type** `string` Tipo do sistema operacional **version** `string` Versão do sistema operacional **vendorAttributes** `object` Dados dos atributos do aparelho **Parâmetros do vendorAttributes** **flash** `boolean` Aparelho possui flash na câmera **phoneCalls** `boolean` Aparelho pode realizar chamadas **sendSms** `boolean` Aparelho pode enviar SMS **videoCamera** `boolean` Aparelho possui câmera de vídeo **cpuCount** `number` Quantidade de CPUs do aparelho **simulator** `boolean` Aparelho possui simulador **language** `string` Linguagem do aparelho **idiom** `string` Idioma do aparelho **platform** `string` Plataforma do sistema operacional **name** `string` Nome do aparelho **family** `string` Família do aparelho **retinaDisplay** `boolean` Aparelho possui display de retina **camera** `boolean` Aparelho possui câmera **model** `string` Modelo do aparelho **frontCamera** `boolean` Aparelho possui câmera frontal **vendors** `array` Dados adicionais do aparelho **Parâmetros do vendors** **name** `string` Nome do atributo do fornecedor **value** `string` Valor do atributo do fornecedor **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **threeDSecure** `object` Dados para utilização da funcionalidade de 3DS **Parâmetros do threeDSecure** **redirectURL** `string` *required* URL para redirecionamento da autenticação **requestorURL** `string` *required* URL de origem da requisição **browser** `object` *required* Dados do navegador do cliente **Parâmetros do browser** **acceptHeader** `string` *required* O Accept do cabeçalho de requisição HTTP **colorDepth** `number` *required* A profundidade de cores da tela **javaEnabled** `boolean` *required* Indica se o Java está habilitado **javaScriptEnabled** `boolean` *required* Indica se o JavaScript está habilitado **language** `string` *required* A linguagem utilizada pelo sistema do usuário **screenHeight** `number` *required* Altura da tela **screenWidth** `number` *required* Largura da tela **timeZoneOffset** `string` *required* Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual **userAgent** `string` *required* O User-Agent do cabeçalho de requisição HTTP **ip** `string` *required* Endereço de IP do usuário **billingAddress** `object` Dados do endereço de cobrança **Parâmetros do billingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **shippingAddress** `object` Dados do endereço de envio **Parâmetros do shippingAddress** **city** `string` *required* Cidade **country** `string` *required* País **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **cardHolder** `object` Dados do titular do cartão **Parâmetros do cardHolder** **email** `string` *required* E-mail do titular do cartão **mobilePhone** `string` Telefone do titular do cartão **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Criar cobrança com voucher Source: https://docs.malga.io/sdks/api-sdks/docs/charges/create-charge-voucher Crie cobranças com cartão voucher (vale-refeição e vale-alimentação) através da API SDK da Malga em Node.js ou PHP, com payload completo. Crie cobranças com voucher e comece a transacionar com Malga. > [!NOTE] > > Vouchers funcionam de forma similar aos cartões de crédito na Malga, dessa forma você tem acesso às funcionalidades de tokenização e armazenamento dos seus cartões. > > Lembre-se que para gerenciar e armazenar dados de cartões diretamente no seu servidor é necessário o certificado PCI-DSS. > Caso sua empresa não tenha o certificado, utilize a tokenização de cartão para a criação de cobranças com voucher. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > amount: 100, > paymentMethod: { > type: 'voucher', > card: { > holderName: 'João da Silva', > number: '5453881028277600', > cvv: '170', > expirationDate: '10/2030', > }, > }, > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'authorized', > paymentMethod: { > paymentType: 'voucher', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na cobrança **amount** `number` *required* Valor da cobrança em centavos **paymentMethod** `object` *required* Dados do pagamento com voucher **Parâmetros do paymentMethod** **type** `string` *required* Método de pagamento que será utilizado na cobrança Com voucher sempre será `voucher` **card** `object` *required* Dados do cartão **Parâmetros do card** **holderName** `string` *required* Nome do portador do cartão **number** `string` *required* Número do cartão **cvv** `string` *required* Código de segurança do cartão **expirationDate** `string` *required* Data de validade do cartão **zeroDollar** `object` Dados da validação de cartão com Zero Dollar **Parâmetros do zeroDollar** **merchantId** `uuid` ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar **cvvCheck** `boolean` Valide o CVV do cartão no momento da criação **items** `array` Dados dos produtos do pedido **Parâmetros do items** **id** `string` *required* Identificador único do produto **title** `string` *required* Nome do produto **unitPrice** `number` *required* Preço do produto **quantity** `number` *required* Quantidade do produto **linkCardToCustomer** `boolean` Vincula o cartão automaticamente com o customer **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **providerReferenceKey** `string` Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor **description** `string` Descrição da cobrança **statementDescriptor** `string` Descrição da cobrança que irá aparecer na fatura do cartão **currency** `string` Moeda que será usada para a cobrança **customerId** `uuid` ID do Customer que será usado na cobrança **customer** `object` Dados do cliente para criação e vinculação automática à cobrança **Parâmetros do customer** **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados do endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **splitRules** `array` Dados para utilização da funcionalidade de Split **Parâmetros do splitRules** **sellerId** `uuid` *required* ID do Recebedor **processingFee** `boolean` *required* Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação **liable** `boolean` *required* Indica se o recebedor atrelado assumirá os riscos de chargeback da transação **percentage** `number` Porcentagem do valor da transação que será enviada ao recebedor **amount** `number` Valor que será enviado ao recebedor **fares** `object` Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag **Parâmetros do fares** **mdr** `number` *required* Indica o percentual a ser descontado do valor de uma transação, definido por produto (crédito/débito/boleto), bandeira e faixa de parcelamento **fee** `number` *required* Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira **paymentFlow** `object` Dados adicionais para uso em condicionais dos Fluxos Inteligentes **Parâmetros do paymentFlow** **metadata** `object` Dados adicionais da cobrança enviados na criação da mesma **appInfo** `object` Dados para a rastreabilidade da cobrança **Parâmetros do appInfo** **device** `object` Dados sobre o dispositivo **Parâmetros do device** **name** `string` *required* Nome do sistema operacional **version** `string` *required* Versão do sistema operacional **system** `object` Dados sobre o sistema proprietário de captura do merchant **Parâmetros do system** **name** `string` *required* Nome da empresa e/ou plataforma **version** `string` *required* Versão do software da plataforma # Buscar cobrança Source: https://docs.malga.io/sdks/api-sdks/docs/charges/find-charge Recupere os detalhes de uma cobrança específica pelo seu identificador usando o método de busca de cobrança da API SDK da Malga em Node.js. Busque uma cobrança pelo seu ID. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.find('2f97378a-f174-4865-9d14-6ffc10fb34f0') > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pre_authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da cobrança # Listar as cobranças Source: https://docs.malga.io/sdks/api-sdks/docs/charges/list-charges Liste cobranças de forma paginada com filtros usando o método de listagem da API SDK da Malga em Node.js ou PHP, com parâmetros completos. Liste todas as suas cobranças. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.list() > ``` > [tab] Response > > ```typescript theme={null} > { > items: [ > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: false, > isDispute: false, > status: 'pre_authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ], > meta: { > totalItems: 1 > itemCount: 1 > itemsPerPage: 15 > totalPages: 1 > currentPage: 1 > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **page** `number` Número da página que deverá ser listada **limit** `number` Limite de itens por página **sort** `string` Ordenação da listagem, padrão é `ASC` Os valores suportados são: `ASC` ou `DESC` **startDate** `string` Data inicial do período filtrado **endDate** `string` Data final do período filtrado **merchantId** `uuid` ID do Merchant **amount** `number` Valor da cobrança **orderId** `string` Identificador único da cobrança do lado do cliente para conciliação futura **hasSplit** `boolean` Cobranças que foram feitas com Split de pagamentos **sessionId** `uuid` Cobrança vinculada à Sessão **status** `array` Status atual da cobrança **paymentMethod** `array` Método de pagamento da cobrança **provider** `array` Provedor utilizado na cobrança # Estornar cobrança Source: https://docs.malga.io/sdks/api-sdks/docs/charges/refund-charge Estorne cobranças aprovadas de forma total ou parcial usando o método de estorno da API SDK da Malga em Node.js ou PHP, com suporte a split. Estorne cobranças autorizadas. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.charges.refund( > '2f97378a-f174-4865-9d14-6ffc10fb34f0', > { amount: 100 } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 0, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: true, > isDispute: false, > status: 'voided', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: 'ff59d15e-5837-42c5-bc3c-d3988b0486c7', > createdAt: '2023-12-31T19:19:45.013Z', > updatedAt: '2023-12-31T19:19:45.044Z', > idempotencyKey: 'bd99414d-9fdc-4801-818e-7482085ab77e', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'void', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > }, > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da cobrança **payload** `object` *required* Segundo parâmetro **Parâmetros de payload** **amount** `number` *required* Valor da cobrança a ser estornado **delayToCompose** `number` Número de dias para compor o valor a ser estornado. Utilizado apenas pela NuPay # Criar cliente Source: https://docs.malga.io/sdks/api-sdks/docs/customers/create-customer Cadastre novos customers (clientes) na Malga via API SDK em Node.js ou PHP, com suporte aos campos de endereço, documento e contato. Crie clientes para vincular em suas cobranças. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.create({ > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > name: 'João da Silva', > email: 'joao.silva@test.com', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > phoneNumber: '99999999999', > createdAt: '2023-12-31T19:36:30.741Z', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **name** `string` *required* Nome do cliente **email** `string` *required* E-mail do cliente **phoneNumber** `string` *required* Telefone do cliente **document** `object` Dados do documento do cliente **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` Dados de endereço do cliente **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista Também é possível passar um segundo parâmetro no método para ignorar as validações de duplicação de e-mail e documento **force** `boolean` Parâmetro para ignorar a duplicidade de clientes, o padrão é `false` # Buscar cliente Source: https://docs.malga.io/sdks/api-sdks/docs/customers/find-customer Recupere os detalhes de um customer cadastrado pelo seu identificador usando o método de busca de cliente da API SDK da Malga em Node.js. Busque um cliente pelo seu ID. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.find('e43a18fa-bb72-4c8d-afb2-382e195ab8a5') > ``` > [tab] Response > > ```typescript theme={null} > { > id: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > name: 'João da Silva', > email: 'joao.silva@test.com', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > phoneNumber: '99999999999', > createdAt: '2023-12-31T19:36:30.741Z', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID do cliente # Vincular cartão Source: https://docs.malga.io/sdks/api-sdks/docs/customers/link-card-customer Vincule um cartão de crédito a um customer cadastrado na Malga via API SDK em Node.js ou PHP para reutilizá-lo em cobranças futuras. Vincule cartões ao cliente. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.linkCard( > 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > { cardId: 'a7e38bca-80d7-47a4-8553-7bda4a308424' } > ) > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `string` *required* ID do cliente **payload** `object` *required* Segundo parâmetro **Parâmetros do payload** **cardId** `string` *required* ID do cartão que deseja vincular ao cliente # Listar cartões vinculados Source: https://docs.malga.io/sdks/api-sdks/docs/customers/list-cards-customer Liste os cartões de crédito vinculados a um customer cadastrado na Malga usando o método de listagem de cartões da API SDK em Node.js ou PHP. Liste os cartões vinculados ao cliente. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.cards('e43a18fa-bb72-4c8d-afb2-382e195ab8a5') > ``` > [tab] Response > > ```typescript theme={null} > [ > { > id: 'a7e38bca-80d7-47a4-8553-7bda4a308424', > status: 'active', > createdAt: '2023-12-31T03:00:00.000Z', > clientId: 'c13a47b7-f232-46bd-bac7-7effe39af877', > customerId: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > brand: 'Mastercard', > cardHolderName: 'João da Silva', > cvvChecked: true, > fingerprint: '/cddsad2sgTXxfNhdsadasdas2QSLsJ/dsadsadcxc=', > first6digits: '545388', > last4digits: '7600', > expirationMonth: '10', > expirationYear: '2030', > } > ] > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `string` *required* ID do cliente # Listar clientes Source: https://docs.malga.io/sdks/api-sdks/docs/customers/list-customers Liste customers cadastrados na Malga com paginação e filtros usando o método de listagem de clientes da API SDK em Node.js ou PHP. Liste todos os seus clientes. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.list() > ``` > [tab] Response > > ```typescript theme={null} > { > items: [ > { > id: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > name: 'João da Silva', > email: 'joao.silva@test.com', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > phoneNumber: '99999999999', > createdAt: '2023-12-31T19:36:30.741Z', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > } > ], > meta: { > totalItems: 1 > itemCount: 1 > itemsPerPage: 15 > totalPages: 1 > currentPage: 1 > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **page** `number` Número da página que deverá ser listada **limit** `number` Limite de itens por página **sort** `string` Ordenação da listagem, padrão é `ASC` Os valores suportados são: `ASC` ou `DESC` **documentType** `string` Tipo do documento **documentNumber** `string` Número do documento # Remover cliente Source: https://docs.malga.io/sdks/api-sdks/docs/customers/remove-customer Remova um customer cadastrado na Malga pelo seu identificador usando o método de exclusão de cliente da API SDK em Node.js ou PHP. Remova clientes criados. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.remove('e43a18fa-bb72-4c8d-afb2-382e195ab8a5') > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `string` *required* ID do cliente # Atualizar cliente Source: https://docs.malga.io/sdks/api-sdks/docs/customers/update-customer Atualize os dados cadastrais de um customer existente na Malga usando o método de atualização de cliente da API SDK em Node.js ou PHP. Atualize os dados do cliente. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.update( > 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > { > name: 'João da Silva', > phoneNumber: '99999999999', > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: 'e43a18fa-bb72-4c8d-afb2-382e195ab8a5', > updatedAt: '2023-12-31T20:36:30.741Z', > createdAt: '2023-12-31T19:36:30.741Z', > idempotencyKey: null, > requestId: null, > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > cardId: null, > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > documentNumber: '99999999999', > documentType: 'cpf', > documentCountry: 'BR', > address: { > country: 'BR', > id: 'cc108cc7-b782-48c7-97d7-ff236208fcba', > updatedAt: '2023-12-31T20:36:30.741Z', > createdAt: '2023-12-31T19:36:30.741Z', > idempotencyKey: null, > requestId: null, > street: 'Estrada da Gávea', > streetNumber: '696', > complement: 'Sala 214', > zipCode: '22610002', > state: 'RJ', > city: 'Rio de Janeiro', > district: 'São Conrado', > deletedAt: null > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `string` *required* ID do cliente **payload** `object` *required* Segundo parâmetro **Parâmetros do payload** **name** `string` Nome do cliente **phoneNumber** `string` Telefone do cliente **address** `object` Dados de endereço do cliente **Parâmetros do address** **city** `string` Cidade **country** `string` País **district** `string` Bairro **state** `string` Estado **street** `string` Nome da rua, avenida ou travessa **streetNumber** `string` Número da rua **zipCode** `string` Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista # Entendendo o Malga API SDK: configuração e uso Source: https://docs.malga.io/sdks/api-sdks/docs/intro Configure o Malga API SDK com API Key, Client ID e Merchant ID, conheça os métodos disponíveis, a chave de idempotência e o tratamento de erros da integração. Nessa seção você poderá compreender como configurar o API SDK, acessar as especificações detalhadas de cada método, além de entender como usar a Chave de Idempotência e fazer o tratamento de erros corretamente. ### Configuração Configurar o Malga API SDK é simples, inicialmente você precisará das credenciais que são o `API Key`, `Client ID` e `Merchant ID`. Se você ainda não tem uma conta Malga basta [clicar aqui](https://dashboard.malga.io/sign-up) e criar uma conta em nosso Dashboard e você terá acesso às credenciais para iniciar sua integração. Agora que você já está com as chaves de acesso, você só precisará baixar o pacote no seu projeto, importar o pacote no seu arquivo e usar o seguinte código: > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > options: { > sandbox: true, > http: { > retries: 3, > retryDelay: 10000, > }, > }, > }); > ``` Abaixo está a lista detalhada com todos os parâmetros de configuração disponíveis. **Parâmetros de Configuração** **apiKey** `uuid` *required* Chave de acesso à API **clientId** `uuid` *required* Identificador único da sua conta na Malga **options** `object` Configurações adicionais **Parâmetros de options** **sandbox** `string` Define se integração está rodando no ambiente de teste ou produção **http** `object` Configurações das requisições http **Parâmetros de http** **retries** `number` Número de retentativa de uma requisição em caso de falha para evitar condições de corrida **retryDelay** `number` Tempo entre uma retentativa e outra em milissegundos ### Chave de idempotência O Malga API SDK suporta chaves de idempotência para evitar duplicidade no processamento de requisições no caso de retentativas de uma mesma operação. Para que isso seja possível, cada um dos nossos métodos de criação suporta um parâmetro adicional chamado `idempotencyKey` para que seja definida a chave de idempotência. Abaixo está um exemplo de como utilizar: > [tab] Node > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.charges.create( > { > merchantId: "2ed73b94-175a-438d-ae73-d11902492b75", > amount: 100, > paymentMethod: { > type: "credit", > installments: 1, > card: { > holderName: "João da Silva", > number: "5453881028277600", > cvv: "170", > expirationDate: "10/2030", > }, > }, > }, > { idempotencyKey: "cebb41fa-e25e-482c-9bee-43328fbb8155" } > ); > ``` Basta [clicar aqui](/documentations/more/idempotency) para saber mais detalhes sobre a chave de idempotência. ### Tratamento de erros No Malga API SDK o tratamento de erros é padronizado, todos os erros são retornados da mesma forma com uma estrutura unificada. Dessa forma damos mais previsibilidade de como é o comportamento dos métodos. Abaixo está a estrutura detalhada de como é o retorno dos erros. **Tratamento de Erros** **error** `object` Objeto com os detalhes do erro **Parâmetros do error** **type** `string` Tipo do erro **code** `number` Status code da requisição **message** `string` Mensagem resumida do erro **details** `string | array` Mensagem detalhada do erro contendo os campos **declinedCode** `string | array` Códigos de negação repassado pelo provedor Basta [clicar aqui](/documentations/welcome/errors) para saber mais detalhes sobre o nosso tratamento de erros. # Alterar status do antifraude Source: https://docs.malga.io/sdks/api-sdks/docs/sandbox/change-antifraud-status Altere o status do antifraude em transações de teste no ambiente Sandbox da Malga via API SDK para validar fluxos de aprovação e negação. Altere os status do antifraude das suas cobranças em sandbox para simular cada cenário da sua integração. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > options: { sandbox: true } > }) > > await malga.sandbox.changeAntifraudStatus( > '2f97378a-f174-4865-9d14-6ffc10fb34f0', > { status: 'reproved' } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: true, > isDispute: false, > status: 'authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: 'ff59d15e-5837-42c5-bc3c-d3988b0486c7', > createdAt: '2023-12-31T19:19:45.013Z', > updatedAt: '2023-12-31T19:19:45.044Z', > idempotencyKey: 'bd99414d-9fdc-4801-818e-7482085ab77e', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'void', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > }, > { > id: 'ff59d15e-5837-42c5-bc3c-d3988b0486c7', > createdAt: '2023-12-31T19:19:45.013Z', > updatedAt: '2023-12-31T19:19:45.044Z', > idempotencyKey: 'bd99414d-9fdc-4801-818e-7482085ab77e', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'ANTIFRAUD_SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'anti_fraud', > responseTs: '19ms', > fraudAnalysis: { > score: 85, > status: 'reproved', > } > }, > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Cobrança **payload** `object` *required* Segundo parâmetro **Parâmetros do payload** **status** `string` *required* Define o status do antifraude.\\ Os tipos suportados são: `approved`, `reproved` ou `failed` # Alterar status da cobrança Source: https://docs.malga.io/sdks/api-sdks/docs/sandbox/change-charge-status Altere o status de uma cobrança no ambiente Sandbox da Malga via API SDK em Node.js ou PHP para simular cenários de aprovação e recusa. Altere os status das suas cobranças em sandbox para simular cada cenário da sua integração. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > options: { sandbox: true } > }) > > await malga.sandbox.changeChargeStatus( > '2f97378a-f174-4865-9d14-6ffc10fb34f0', > { status: 'authorized' } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '2f97378a-f174-4865-9d14-6ffc10fb34f0', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > description: null, > orderId: null, > providerReferenceKey: null, > createdAt: '2023-12-31T18:19:44.993Z', > amount: 100, > originalAmount: 100, > currency: 'BRL', > statementDescriptor: null, > capture: true, > isDispute: false, > status: 'authorized', > paymentMethod: { > installments: 1, > paymentType: 'credit', > }, > paymentSource: { > sourceType: 'card', > cardId: '5ee96a69-9ddf-4052-b454-f2421b547924', > }, > transactionRequests: [ > { > id: 'ff59d15e-5837-42c5-bc3c-d3988b0486c7', > createdAt: '2023-12-31T19:19:45.013Z', > updatedAt: '2023-12-31T19:19:45.044Z', > idempotencyKey: 'bd99414d-9fdc-4801-818e-7482085ab77e', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > }, > { > id: '25de917a-f977-4054-bed3-e94ed377896a', > createdAt: '2023-12-31T18:19:45.013Z', > updatedAt: '2023-12-31T18:19:45.044Z', > idempotencyKey: '86fde739-7506-48f6-a070-9eca62054415', > providerId: 'db46b9d6-daa1-4eae-ba90-15b6d3216a93', > providerType: 'SANDBOX', > transactionId: '12023934-42e4-4062-b4f3-f7218c694c15', > amount: 100, > authorizationCode: '123123', > authorizationNsu: '123123', > requestStatus: 'success', > requestType: 'pre_authorization', > responseTs: '11ms', > providerAuthorization: { > networkAuthorizationCode: '123123', > networkResponseCode: '123123', > } > } > ], > appInfo: null > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Cobrança **payload** `object` *required* Segundo parâmetro **Parâmetros do payload** **status** `string` *required* Define o novo status da cobrança.\\ Os tipos suportados são: `authorized`, `voided`, `charged_back`, `refund_pending` ou `failed` # Gerar cartão Source: https://docs.malga.io/sdks/api-sdks/docs/sandbox/generate-card Gere cartões de teste no ambiente Sandbox da Malga usando a API SDK em Node.js ou PHP para validar suas integrações com pagamentos. Gere cartões de teste em sandbox para simular cada cenário da sua integração. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > options: { sandbox: true } > }) > > await malga.sandbox.generateCard({ > brand: 'Mastercard', > status: 'expired_card' > }) > ``` > [tab] Response > > ```typescript theme={null} > { > number: '5462320441541663', > cvv: '830', > expirationDate: '03/2025', > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **brand** `string` *required* Bandeira do cartão Os tipos suportados são: `Mastercard`, `Visa`, `Amex`, `HiperCard` ou `DinersClub` **status** `string` *required* Status do cartão Os tipos suportados são: `authorized`, `unauthorized`, `blocked_card`, `canceled_card`, `expired_card`, `invalid_cvv`, `timeout` ou `authorized_or_timeout` # Criar recebedores Source: https://docs.malga.io/sdks/api-sdks/docs/sellers/create-seller Cadastre novos sellers (recebedores) para uso em split de pagamentos na Malga via API SDK em Node.js ou PHP, com dados bancários e fiscais. Crie recebedores para vincular em suas cobranças. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sellers.create({ > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 4040, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > } > }) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '469cd18c-fe20-45f1-bb19-d8871af60308', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > status: 'pending', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 4040, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31' > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > }, > providers: [{ > providerType: 'SANDBOX', > externalId: '1103976', > externalStatus: 'active', > externalStatusReason: 'ok', > status: 'active', > createdAt: '2023-12-31T16:08:39.536Z', > updatedAt: '2023-12-31T16:08:39.536Z' > }] > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será vinculado o recebedor **mcc** `number` *required* Código de segmento do lojista no adquirente **owner** `object` Dados do recebedor **Parâmetros do owner** **name** `string` *required* Nome do recebedor **email** `string` *required* E-mail do recebedor **phoneNumber** `string` *required* Telefone do recebedor **birthdate** `string` *required* Data de nascimento do recebedor **document** `object` *required* Dados do documento do recebedor **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` *required* Dados de endereço do recebedor **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **business** `object` Dados do estabelecimento do recebedor **Parâmetros do business** **name** `string` *required* Nome do estabelecimento do recebedor **email** `string` *required* E-mail do estabelecimento do recebedor **phoneNumber** `string` *required* Telefone do estabelecimento do recebedor **openingDate** `string` *required* Data de abertura do estabelecimento do recebedor **description** `string` *required* Descrição do estabelecimento do recebedor **website** `string` Site do estabelecimento do recebedor **twitter** `string` Twitter do estabelecimento do recebedor **facebook** `string` Facebook do estabelecimento do recebedor **document** `object` *required* Dados do documento do estabelecimento do recebedor **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` *required* Dados de endereço do estabelecimento do recebedor **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **bankAccount** `object` *required* Dados da conta bancária **Parâmetros do bankAccount** **holderName** `string` *required* Nome do portador da conta bancária **holderType** `string` Identificador de pessoa física ou jurídica Os tipos aceitos são: `individual` ou `company` **holderDocument** `string` *required* Documento do portador da conta bancária **bank** `string` *required* Código do banco **branchNumber** `string` *required* Número da agência bancária **branchCheckDigit** `string` Código verificador da agência bancária **accountNumber** `string` *required* Número da conta bancária **accountCheckDigit** `string` Número verificador da conta bancária **type** `string` *required* Tipo da conta Os tipos aceitos são: `conta_corrente`, `conta_poupanca`, `conta_corrente_conjunta` ou `conta_poupanca_conjunta` **transferPolicy** `object` *required* Dados da política de transferência **Parâmetros do transferPolicy** **transferDay** `string` *required* Dia em que o parceiro será pago **transferEnabled** `boolean` *required* Determina se as transferências estão autorizadas a acontecer **transferInterval** `boolean` *required* Intervalo entre as transferências Os tipos aceitos são: `daily`, `weekly` ou `monthly` **automaticAnticipationEnabled** `boolean` Determina se o recebedor receberá antecipações automaticamente **anticipatableVolumePercentage** `string` Indica a porcentagem do volume passível de ser antecipado para o recebedor **automaticAnticipationType** `string` Indica o tipo de antecipação automática que será configurado para a conta do recebedor **automaticAnticipationDays** `string` Indica a quantidade de dias de antecipação automática **automaticAnticipation1025Delay** `string` Indica a quantidade de dias que serão desconsiderados na contabilização do valor passível de ser antecipado. A contagem de dias é realizada a partir do dia da antecipação para trás **metadata** `object` Informações adicionais passadas com chave e valor # Buscar recebedor Source: https://docs.malga.io/sdks/api-sdks/docs/sellers/find-seller Recupere os detalhes de um seller cadastrado pelo seu identificador usando o método de busca de recebedor da API SDK da Malga em Node.js. Busque um recebedor pelo seu ID. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sellers.find('469cd18c-fe20-45f1-bb19-d8871af60308') > ``` > [tab] Response > > ```typescript theme={null} > { > id: '469cd18c-fe20-45f1-bb19-d8871af60308', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > status: 'pending', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 4040, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31' > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > }, > providers: [{ > providerType: 'SANDBOX', > externalId: '1103976', > externalStatus: 'active', > externalStatusReason: 'ok', > status: 'active', > createdAt: '2023-12-31T16:08:39.536Z', > updatedAt: '2023-12-31T16:08:39.536Z' > }] > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID do cartão # Listar recebedores Source: https://docs.malga.io/sdks/api-sdks/docs/sellers/list-sellers Liste de forma paginada os sellers cadastrados para split na Malga usando o método de listagem de recebedores da API SDK em Node.js ou PHP. Liste todos os seus recebedores. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.customers.list() > ``` > [tab] Response > > ```typescript theme={null} > { > items: [ > { > id: '469cd18c-fe20-45f1-bb19-d8871af60308', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > status: 'pending', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 4040, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31' > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > }, > providers: [{ > providerType: 'SANDBOX', > externalId: '1103976', > externalStatus: 'active', > externalStatusReason: 'ok', > status: 'active', > createdAt: '2023-12-31T16:08:39.536Z', > updatedAt: '2023-12-31T16:08:39.536Z' > }] > } > ], > meta: { > totalItems: 1 > itemCount: 1 > itemsPerPage: 15 > totalPages: 1 > currentPage: 1 > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **page** `number` Número da página que deverá ser listada **limit** `number` Limite de itens por página **sort** `string` Ordenação da listagem, padrão é `ASC` Os valores suportados são: `ASC` ou `DESC` **email** `string` E-mail do recebedor **status** `array` Status do recebedor # Remover recebedor Source: https://docs.malga.io/sdks/api-sdks/docs/sellers/remove-seller Remova um seller cadastrado pelo seu identificador usando o método de exclusão de recebedor da API SDK da Malga em Node.js ou PHP. Remova recebedores criados. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sellers.remove('469cd18c-fe20-45f1-bb19-d8871af60308') > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **holderName** `string` *required* Nome do portador do cartão **number** `string` *required* Número do cartão **cvv** `string` *required* Código de segurança do cartão **expirationDate** `string` *required* Data de validade do cartão # Atualizar recebedor Source: https://docs.malga.io/sdks/api-sdks/docs/sellers/update-seller Atualize os dados cadastrais de um seller existente na Malga usando o método de atualização de recebedor da API SDK em Node.js ou PHP. Atualize os dados do recebedor. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sellers.update( > '469cd18c-fe20-45f1-bb19-d8871af60308', > { > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 3030, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31', > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > } > } > ) > ``` > [tab] Response > > ```typescript theme={null} > { > id: '469cd18c-fe20-45f1-bb19-d8871af60308', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > status: 'pending', > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > mcc: 3030, > owner: { > name: 'João da Silva', > email: 'joao.silva@test.com', > phoneNumber: '99999999999', > birthdate: '2000-12-31' > document: { > number: '99999999999', > type: 'cpf', > country: 'BR' > }, > address: { > city: 'Rio de Janeiro', > complement: 'Sala 214', > country: 'BR', > district: 'São Conrado', > state: 'RJ', > street: 'Estrada da Gávea', > streetNumber: '696', > zipCode: '22610002' > } > }, > bankAccount: { > holderName: 'João da Silva' > holderDocument: '99999999999', > bank: '077' > branchNumber: '492', > accountNumber: '4929', > type: 'conta_corrente' > }, > transferPolicy: { > transferDay: '5' > transferEnabled: true > transferInterval: 'monthly' > }, > providers: [{ > providerType: 'SANDBOX', > externalId: '1103976', > externalStatus: 'active', > externalStatusReason: 'ok', > status: 'active', > createdAt: '2023-12-31T16:08:39.536Z', > updatedAt: '2023-12-31T16:08:39.536Z' > }] > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID do Recebedor **payload** `object` *required* Segundo parâmetro **Parâmetros do payload** **merchantId** `uuid` *required* ID do Merchant que será vinculado o recebedor **mcc** `number` *required* Código de segmento do lojista no adquirente **owner** `object` Dados do recebedor **Parâmetros do owner** **name** `string` *required* Nome do recebedor **email** `string` *required* E-mail do recebedor **phoneNumber** `string` *required* Telefone do recebedor **birthdate** `string` *required* Data de nascimento do recebedor **document** `object` *required* Dados do documento do recebedor **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` *required* Dados de endereço do recebedor **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **business** `object` Dados do estabelecimento do recebedor **Parâmetros do business** **name** `string` *required* Nome do estabelecimento do recebedor **email** `string` *required* E-mail do estabelecimento do recebedor **phoneNumber** `string` *required* Telefone do estabelecimento do recebedor **openingDate** `string` *required* Data de abertura do estabelecimento do recebedor **description** `string` *required* Descrição do estabelecimento do recebedor **website** `string` Site do estabelecimento do recebedor **twitter** `string` Twitter do estabelecimento do recebedor **facebook** `string` Facebook do estabelecimento do recebedor **document** `object` *required* Dados do documento do estabelecimento do recebedor **Parâmetros do document** **type** `string` *required* Tipo do documento **number** `string` *required* Número do documento **country** `string` País do documento **address** `object` *required* Dados de endereço do estabelecimento do recebedor **Parâmetros do address** **city** `string` *required* Cidade **country** `string` *required* País **district** `string` *required* Bairro **state** `string` *required* Estado **street** `string` *required* Nome da rua, avenida ou travessa **streetNumber** `string` *required* Número da rua **zipCode** `string` *required* Código postal **complement** `string` Complemento onde se localiza o endereço, caso exista **bankAccount** `object` *required* Dados da conta bancária **Parâmetros do bankAccount** **holderName** `string` *required* Nome do portador da conta bancária **holderType** `string` Identificador de pessoa física ou jurídica Os tipos aceitos são: `individual` ou `company` **holderDocument** `string` *required* Documento do portador da conta bancária **bank** `string` *required* Código do banco **branchNumber** `string` *required* Número da agência bancária **branchCheckDigit** `string` Código verificador da agência bancária **accountNumber** `string` *required* Número da conta bancária **accountCheckDigit** `string` Número verificador da conta bancária **type** `string` *required* Tipo da conta Os tipos aceitos são: `conta_corrente`, `conta_poupanca`, `conta_corrente_conjunta` ou `conta_poupanca_conjunta` **transferPolicy** `object` *required* Dados da política de transferência **Parâmetros do transferPolicy** **transferDay** `string` *required* Dia em que o parceiro será pago **transferEnabled** `boolean` *required* Determina se as transferências estão autorizadas a acontecer **transferInterval** `boolean` *required* Intervalo entre as transferências Os tipos aceitos são: `daily`, `weekly` ou `monthly` **automaticAnticipationEnabled** `boolean` Determina se o recebedor receberá antecipações automaticamente **anticipatableVolumePercentage** `string` Indica a porcentagem do volume passível de ser antecipado para o recebedor **automaticAnticipationType** `string` Indica o tipo de antecipação automática que será configurado para a conta do recebedor **automaticAnticipationDays** `string` Indica a quantidade de dias de antecipação automática **automaticAnticipation1025Delay** `string` Indica a quantidade de dias que serão desconsiderados na contabilização do valor passível de ser antecipado. A contagem de dias é realizada a partir do dia da antecipação para trás **metadata** `object` Informações adicionais passadas com chave e valor # Cancelar sessão Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/cancel-session Cancele uma sessão pendente na Malga pelo seu identificador usando o método de cancelamento de sessão da API SDK em Node.js ou PHP. Cancele sessões já criadas. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sessions.cancel('7936be48-fd3d-4d55-a9b3-c1b776a2cbab') > ``` > [tab] Response > > ```typescript theme={null} > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > status: 'canceled' > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Sessão # Criar sessão Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/create-session Crie sessões de pagamento (pedidos com itens e métodos de pagamento) na Malga via API SDK em Node.js ou PHP, com suporte a split de pagamentos. Crie sessões para ter cobranças mais seguras e gerenciar Links de Pagamento. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.sessions.create({ > merchantId: "2ed73b94-175a-438d-ae73-d11902492b75", > amount: 100, > dueDate: "2023-12-31T03:00:00.000Z", > name: "Link de Pagamento", > createLink: true, > maxPayments: 5, > paymentMethods: [ > { paymentType: "credit", installments: 1 }, > { paymentType: "drip" }, > { paymentType: "nupay" }, > { paymentType: "pix", expiresIn: 3600 }, > { paymentType: "boleto", expiresDate: "2023-12-31" }, > ], > items: [ > { > name: "Produto 1", > unitPrice: 100, > quantity: 1, > }, > ], > }); > ``` > [tab] Response > > ```typescript theme={null} > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > name: 'Link de Pagamento', > status: 'created', > isActive: true, > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > orderId: null, > amount: 100, > currency: 'BRL', > capture: null, > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > dueDate: '2023-12-31T03:00:00.000Z', > description: null, > statementDescriptor: null, > items: [ > { > name: 'Produto 1', > description: null, > unitPrice: 100, > quantity: 1, > tangible: null > } > ], > paymentLink: '', > paymentMethods: [ > { > paymentType: 'pix', > expiresIn: 500 > }, > { > paymentType: 'credit', > installments: 1, > recurrence: null > }, > { > paymentType: 'boleto', > expiresDate: '2023-12-31T00:00:00.000Z', > instructions: null > }, > { > paymentType: 'drip', > successRedirectUrl: null, > cancelRedirectUrl: null > }, > { > paymentType: 'nupay', > delayToAutoCancel: null, > orderUrl: null, > returnUrl: null, > cancelUrl: null > }, > ], > createdAt: '2023-01-31T00:00:00.000Z', > updatedAt: '2023-01-31T00:00:00.000Z', > publicKey: 'd6041197-4158-473d-82de-8594bbe69b59', > multiplePayments: { > allow: true, > maxPayments: 5, > paymentCount: 0, > pendingCount: 0, > status: 'active' > }, > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **merchantId** `uuid` *required* ID do Merchant que será usado na sessão **amount** `number` *required* Valor da sessão em centavos **dueDate** `string` *required* Data de expiração da sessão **name** `string` *required* Nome de identificação da sessão **paymentMethods** `array` *required* Dados dos métodos de pagamento disponíveis na sessão **Parâmetros de cartão de crédito** **paymentType** `string` *required* Identificador do tipo de pagamento, com cartão de crédito sempre será `credit` **installments** `number` *required* Número de parcelas possíveis na venda **Parâmetros de Pix** **paymentType** `string` *required* Identificador do tipo de pagamento, com Pix sempre será `pix` **expiresIn** `number` *required* Tempo de expiração do Pix em segundos **Parâmetros de boleto** **paymentType** `string` *required* Identificador do tipo de pagamento, com boleto sempre será `boleto` **expiresDate** `string` *required* Data de vencimento do boleto **instructions** `string` Instruções do boleto **interest** `object` Dados opcionais da condição de juros para pagamento em atraso **Parâmetros do interest** **days** `number` *required* Dias após a expiração do boleto em que ocorrerá a cobrança dos juros **amount** `number` Valor em centavos da taxa de juros que será cobrado ao dia **percentage** `number` Valor em porcentagem da taxa de juros que será cobrado ao mês **fine** `object` Dados opcionais da condição de multa para pagamento em atraso **Parâmetros do fine** **days** `number` *required* Dias após a expiração do boleto em que ocorrerá a cobrança da multa **amount** `number` Valor em centavos da multa **percentage** `number` Valor em porcentagem da multa **Parâmetros de Drip** **paymentType** `string` *required* Identificador do tipo de pagamento, com Drip sempre será `drip` **successRedirectUrl** `string` Link de redirecionamento em caso de aprovação do pagamento no ambiente de checkout da Drip **cancelRedirectUrl** `string` Link de redirecionamento em caso de cancelamento do pagamento no ambiente de checkout da Drip **Parâmetros de NuPay** **paymentType** `string` *required* Identificador do tipo de pagamento, com NuPay sempre será `nupay` **orderUrl** `string` URL de origem da cobrança **returnUrl** `string` URL para a qual o cliente será redirecionado após finalizar o pagamento **cancelUrl** `string` URL para onde o cliente será direcionado caso escolha não finalizar o pagamento e cancele o pedido **taxValue** `number` Total de taxas aplicadas em centavos **delayToAutoCancel** `number` Tempo em minutos para a expiração de uma cobrança criada que não tenha sido paga **items** `array` *required* Dados dos produtos da sessão **Parâmetros de items** **name** `string` *required* Nome do produto **unitPrice** `number` *required* Preço do produto **quantity** `number` *required* Quantidade do produto **description** `string` Descrição do produto **tangible** `boolean` Define se é um produto tangível **description** `string` Descrição da sessão **statementDescriptor** `string` Descrição da cobrança que irá aparecer na fatura do cartão **createLink** `boolean` Define se deve criar um link para pagamento com a funcionalidade de Link de Pagamento **maxPayments** `number` Configura a sessão como 1:N para múltiplos pagamentos. Use `-1` para permitir pagamentos ilimitados ou um número entre `1` e `99999` para definir um limite finito. Quando omitido, a sessão segue o fluxo 1:1. **orderId** `string` Identificador único da sessão do lado do cliente para conciliação futura **currency** `string` Moeda que será usada para a sessão **isActive** `boolean` Define se a sessão está ativa **capture** `boolean` Define se a sessão deve ser capturada automaticamente # Desabilitar sessão Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/disable-session Desabilite uma sessão ativa na Malga pelo seu identificador usando o método de desabilitar sessão da API SDK em Node.js ou PHP, sem removê-la. Desabilite sessões que estão habilitadas. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.sessions.disable("7936be48-fd3d-4d55-a9b3-c1b776a2cbab"); > ``` > [tab] Response > > ```typescript theme={null} > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > isActive: false > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Sessão # Habilitar sessão Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/enable-session Habilite uma sessão desabilitada na Malga pelo seu identificador usando o método de habilitar sessão da API SDK em Node.js ou PHP. Habilite sessões que estão desabilitadas. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.sessions.enable("7936be48-fd3d-4d55-a9b3-c1b776a2cbab"); > ``` > [tab] Response > > ```typescript theme={null} > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > isActive: true > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Sessão # Buscar sessão Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/find-session Recupere os detalhes de uma sessão de pagamento pelo seu identificador usando o método de busca de sessão da API SDK da Malga em Node.js. Busque uma sessão pelo seu ID. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > }); > > await malga.sessions.find("7936be48-fd3d-4d55-a9b3-c1b776a2cbab"); > ``` > [tab] Response > > ```typescript theme={null} > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > name: 'Link de Pagamento', > status: 'created', > isActive: true, > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > orderId: null, > amount: 100, > currency: 'BRL', > capture: null, > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > dueDate: '2023-12-31T03:00:00.000Z', > description: null, > statementDescriptor: null, > items: [ > { > name: 'Produto 1', > description: null, > unitPrice: 100, > quantity: 1, > tangible: null > } > ], > paymentLink: '', > paymentMethods: [ > { > paymentType: 'pix', > expiresIn: 500 > }, > { > paymentType: 'credit', > installments: 1, > recurrence: null > }, > { > paymentType: 'boleto', > expiresDate: '2023-12-31T00:00:00.000Z', > instructions: null > }, > { > paymentType: 'drip', > successRedirectUrl: null, > cancelRedirectUrl: null > } > ], > createdAt: '2023-01-31T00:00:00.000Z', > updatedAt: '2023-01-31T00:00:00.000Z', > publicKey: 'd6041197-4158-473d-82de-8594bbe69b59', > multiplePayments: { > allow: true, > maxPayments: 5, > paymentCount: 0, > pendingCount: 0, > status: 'active' > }, > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **id** `uuid` *required* ID da Sessão # Listar sessões Source: https://docs.malga.io/sdks/api-sdks/docs/sessions/list-sessions Liste sessões de pagamento criadas na Malga com paginação e filtros usando o método de listagem de sessões da API SDK em Node.js ou PHP. Liste todas as suas sessões. Você pode filtrar por status, estado de ativação e intervalo de data de criação. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.sessions.list({ > page: 1, > limit: 15, > status: ['created', 'paid'], > isActive: [true], > startDate: '2026-03-24T03:00:00.000Z', > endDate: '2026-04-01T02:59:00.000Z', > }) > ``` > [tab] Response > > ```typescript theme={null} > { > items: [ > { > id: '7936be48-fd3d-4d55-a9b3-c1b776a2cbab', > name: 'Link de Pagamento', > status: 'created', > isActive: true, > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > orderId: null, > amount: 100, > currency: 'BRL', > capture: null, > merchantId: '2ed73b94-175a-438d-ae73-d11902492b75', > dueDate: '2023-12-31T03:00:00.000Z', > description: null, > statementDescriptor: null, > items: [ > { > name: 'Produto 1', > description: null, > unitPrice: 100, > quantity: 1, > tangible: null > } > ], > paymentLink: '', > paymentMethods: [ > { > paymentType: 'pix', > expiresIn: 500 > }, > { > paymentType: 'credit', > installments: 1, > recurrence: null > }, > { > paymentType: 'boleto', > expiresDate: '2023-12-31T00:00:00.000Z', > instructions: null > }, > { > paymentType: 'drip', > successRedirectUrl: null, > cancelRedirectUrl: null > } > ], > createdAt: '2023-01-31T00:00:00.000Z', > updatedAt: '2023-01-31T00:00:00.000Z', > publicKey: 'd6041197-4158-473d-82de-8594bbe69b59', > } > ], > meta: { > totalItems: 1 > itemCount: 1 > itemsPerPage: 15 > totalPages: 1 > currentPage: 1 > } > } > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **page** `number` Número da página que deverá ser listada **limit** `number` Limite de itens por página **status** `array` Filtra sessões pelo status. O SDK envia os valores unidos por vírgula na query. Os valores suportados são: `created`, `paid`, `canceled`, `voided` **isActive** `array` Filtra sessões ativadas ou desativadas. O SDK envia os valores unidos por vírgula na query. Os valores suportados são: `true` ou `false` **startDate** `string` Data inicial do período filtrado. O SDK envia este valor como `created.gt` na API (RFC 3339). Exemplo: `2026-03-24T03:00:00.000Z` **endDate** `string` Data final do período filtrado. O SDK envia este valor como `created.lt` na API (RFC 3339). Exemplo: `2026-04-01T02:59:00.000Z` # Verificar assinatura do evento Source: https://docs.malga.io/sdks/api-sdks/docs/webhooks/verify-event Verifique a assinatura HMAC dos eventos de webhook recebidos da Malga usando a API SDK em Node.js ou PHP para garantir autenticidade. Verifique a assinatura dos eventos para que você tenha mais segurança. ### Método > [tab] Node.js > > ```typescript theme={null} > import { Malga } from 'malga' > > const malga = new Malga({ > apiKey: '8468a624-68c1-49a3-b9f1-a22455053a38', > clientId: 'ebb9c69c-4ad6-49fd-a565-a35cb4c967b3', > }) > > await malga.webhooks.verify({ > payload: '{"event":"ping","payload":{"object":{}}}', > publicKey: '-----BEGIN PUBLIC KEY-----\nMCwBQYDK2VwAyEASdad=\n-----END PUBLIC KEY-----\n', > signature: '5b20c43cfd55f0c1884196' > signatureTime: 1661795163719, > }) > ``` > [tab] Response > > ```typescript theme={null} > true > // or > false > ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. **publicKey** `string` *required* Chave pública retornada no momento da criação do webhook **payload** `json` *required* Dados enviados no corpo do evento **signature** `string` *required* Assinatura enviada pelo evento no header `X-Plug-Signature` **signatureTime** `number` *required* Data que o evento foi gerado, enviado pelo evento no header `X-Plug-Date` # Exemplos API SDKs Source: https://docs.malga.io/sdks/api-sdks/examples # Iniciando em Malga API SDKs Source: https://docs.malga.io/sdks/api-sdks/introduction Sua última integração de pagamentos agora mais simples e fácil de integrar. ### Quickstart Aprenda como configurar Malga no seu projeto. > [card] [Node.js Quickstart](/sdks/api-sdks/quickstart/nodejs/intro) ### Documentação Veja detalhadamente como cada um dos métodos funciona e entenda como usá-los no seu projeto. > [card] [Charges](/sdks/api-sdks/docs/charges/create-charge-credit) > > Comece a transacionar > [card] [Cards](/sdks/api-sdks/docs/cards/create-card) > > Gerencie cartões com segurança > [card] [Sessions](/sdks/api-sdks/docs/sessions/create-session) > > Crie sessões de pagamento ### Exemplos Confira os exemplos de projetos integrados com a Malga: > [card] [Node.js](https://github.com/plughacker/malga-node/tree/main/examples/nodejs) > > Veja o código completo > [card] [Express](https://github.com/plughacker/malga-node/tree/main/examples/express) > > Veja o código completo # Express Source: https://docs.malga.io/sdks/api-sdks/quickstart/nodejs/express Quickstart de integração da API SDK Malga com Express no Node.js, com instruções passo a passo para criar rotas e processar pagamentos. Aprenda como fazer sua primeira transação usando Express e o Malga Node.js SDK. ### Pré-requisitos Para que você consiga aproveitar ao máximo esse guia, será necessário ter chaves de integração de sandbox. Basta [clicar aqui](https://dashboard.malga.io/sign-up) e criar uma conta em nosso Dashboard. ### 1. Instalando o SDK Instale nosso SDK com o seu gerenciador de pacotes favorito. > [tab] npm > > ```bash theme={null} > npm install malga > ``` > [tab] yarn > > ```bash theme={null} > yarn add malga > ``` > [tab] pnpm > > ```bash theme={null} > pnpm add malga > ``` ### 2. Fazendo sua primeira cobrança Crie uma cobrança de forma simplificada. > [tab] Server > > ```typescript theme={null} > import express, { Request, Response } from "express"; > import { Malga } from "malga"; > > const app = express(); > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > options: { sandbox: true }, > }); > > app.post("/", (request: Request, response: Response) => { > try { > const data = await malga.charges.create({ > merchantId: "2ed73b94-175a-438d-ae73-d11902492b75", > amount: 100, > paymentMethod: { > type: "credit", > installments: 1, > card: { > holderName: "João da Silva", > number: "5453881028277600", > cvv: "170", > expirationDate: "10/2030", > }, > }, > }); > > response.json(data); > } catch (error) { > response.status(400).json(error); > } > }); > > app.listen(3000, () => { > console.log("Server running on http://localhost:3000"); > }); > ``` ### 3. Teste você mesmo > [card] [Exemplo Express](https://github.com/plughacker/malga-node/tree/main/examples/express) > > Veja o código completo # Node.js Source: https://docs.malga.io/sdks/api-sdks/quickstart/nodejs/intro Quickstart da API SDK Malga em Node.js: instalação, autenticação e primeiros passos para integrar pagamentos no seu backend JavaScript. Aprenda como fazer sua primeira transação usando o Malga Node.js SDK. ### Pré-requisitos Para que você consiga aproveitar ao máximo esse guia, será necessário ter chaves de integração de sandbox. Basta [clicar aqui](https://dashboard.malga.io/sign-up) e criar uma conta em nosso Dashboard. ### 1. Instalando o SDK Instale nosso SDK com o seu gerenciador de pacotes favorito. > [tab] npm > > ```bash theme={null} > npm install malga > ``` > [tab] yarn > > ```bash theme={null} > yarn add malga > ``` > [tab] pnpm > > ```bash theme={null} > pnpm add malga > ``` ### 2. Fazendo sua primeira cobrança Crie uma cobrança de forma simplificada. > [tab] server > > ```typescript theme={null} > import { Malga } from "malga"; > > const malga = new Malga({ > apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", > clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", > options: { sandbox: true }, > })(async function () { > try { > const data = await malga.charges.create({ > merchantId: "2ed73b94-175a-438d-ae73-d11902492b75", > amount: 100, > paymentMethod: { > type: "credit", > installments: 1, > card: { > holderName: "João da Silva", > number: "5453881028277600", > cvv: "170", > expirationDate: "10/2030", > }, > }, > }); > > console.log(data); > } catch (error) { > console.error(error); > } > })(); > ``` ### 3. Teste você mesmo > [card] [Exemplo Node.js](https://github.com/plughacker/malga-node/tree/main/examples/nodejs) > > Veja o código completo # Começando em UI SDK's Source: https://docs.malga.io/sdks/intro-sdk ### Checkout drop-in SDK O Malga Checkout e Malga Checkout Full são drop-ins (componentes) de interface para web e mobile altamente customizáveis e extensíveis. Através dos Checkouts SDKs você tem disponível para integração interfaces prontas para realizar cobranças por cartão de crédito, pix e boleto sem ter que desenvolver uma linha de código, basta plugar no seu site ou aplicativo e usar. | Funcionalidade | Malga Checkout | Malga Checkout Full | | :- | :- | :- | | Módulo Pix | | | | Módulo Cartão de Crédito | | | | Módulo Boleto | | | | Módulo NuPay | | | | Módulo Drip | | | | Tokenização de cartão | | | | Vincula cartão ao cliente | | | | Integra com sessões | | | | Altamente customizável | | | | Lista de itens do pedido | | | | Formulário de cadastro de cliente | | | | Suporta antifraude | | | | Suporta split | | | | Validação de cartões (Zero Dollar) | | | ## Live preview do Malga Checkout Você pode acessar uma demo do Malga Checkout [**neste link**](https://checkout.vanilla.malga.io/). > [!NOTE] > > Não é possível finalizar um pagamento no preview do Malga Checkout ![Malga Checkout](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/checkout.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=391f9b49a0819cdf92893c7fa69f0fbe) ## Live preview do Malga Checkout Full Você pode acessar uma demo do Malga Checkout Full [**neste link**](https://checkout-full.vanilla.malga.io/). > [!NOTE] > > Não é possível finalizar um pagamento no preview do Malga Checkout Full. ![Malga Checkout Full](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/malga-checkout-full.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=ff4cc3d48b3889b9218b5e996b836e35) ## Benefícios do Malga Checkout e Malga Checkout Full ### Responsivos O **Malga Checkout** foi projetado para ser responsivo e implementar os métodos de cobrança que você desejar, sem redirecionamento, tudo no seu site. Já o **Malga Checkout Full** entrega os mesmos benefícios de responsividade e métodos de cobrança, porém em uma página completa de checkout. ### Customizáveis Componentes altamente customizáveis pensados para que você tenha o máximo de flexibilidade para deixar a experiência do seu jeito. ### PCI Level 1 Em conformidade com as melhores práticas de segurança da indústria de pagamentos, com o **Malga Checkout** e **Malga Checkout Full** você pode salvar os dados de cartão para compra futura, de maneira segura. ### Fáceis de usar Nosso time de desenvolvedores pensou em tudo para simplificar o seu trabalho, o **Malga Checkout** e **Malga Checkout Full** são os únicos do mercado disponibilizados em diversos frameworks, você escolhe se quer usar em React, Angular, Vue, ou javascript vanilla. ## Primeiros passos 1. Crie uma chave pública de autenticação no seu backend. 2. Escolha o SDK que atende melhor a sua necessidade. 3. Inicialize o Malga Checkout escolhido no seu site ou aplicativo com a chave pública de autenticação criada. 4. O Checkout SDK irá coletar os dados necessários para cobrança e criar uma nova transação. 5. Implemente os métodos `paymentSuccess` e `paymentFailed` do Checkout SDK que você usará (verifique a documentação da implementação de cada tecnologia) para receber os dados da autorização criada. 6. Para os métodos de pagamento assíncronos, como Pix e Boleto, implemente o recebimento das notificações de webhooks no seu backend para ser avisado quando um pagamento é confirmado. ## Chave pública de autenticação É possível criar chaves públicas de acesso temporário à API com escopo e tempo de expiração limitados. Recomendamos o uso deste tipo de chave quando você tiver que expor a chave em uma aplicação client side. **Criando uma chave de autenticação pública `POST /v1/auth`** ```bash theme={null} curl --location --request POST 'https://api.malga.io/v1/auth' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "scope":["tokens"], "expires": 31104000 }' ``` **Resposta da chave pública criada** ```json theme={null} { "clientId": "", "publicKey": "", "scope": ["tokens"], "expires": 31104000, "createdAt": "20200110 00:00:00" } ``` > [!WARNING] > > A sua chave pública criada pode ser usada normalmente como se fosse a chave > secreta da sua conta, porém com a restrição imposta pelo escopo e sendo > invalidada após a expiração. ## Implemente o Checkout SDK no seu site ou app Escolha o SDK ideal para o seu site de acordo com o framework de sua preferência: * Implementações do Malga Checkout: * **[Javascript](/sdks/malga-checkout/js)** * **[React](/sdks/malga-checkout/react)** * **[Vue](/sdks/malga-checkout/vue)** * **[Angular](/sdks/malga-checkout/angular)** * Implementações do Malga Checkout Full: * **[Javascript](/sdks/malga-checkout-full/js)** * **[React](/sdks/malga-checkout-full/react)** * **[Vue](/sdks/malga-checkout-full/vue)** * **[Angular](/sdks/malga-checkout-full/angular)** # SDK Angular.js Source: https://docs.malga.io/sdks/malga-checkout-full/angular ## Get started ### Adicione como dependência no seu site o checkout full SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout-full/angular ``` ### Importe o Malga Checkout Full no seu `app.module.ts` ```jsx theme={null} import { MalgaCheckoutFullModule } from '@malga-checkout-full/angular' @NgModule({ declarations: [AppComponent], imports: [BrowserModule, MalgaCheckoutFullModule], providers: [], bootstrap: [AppComponent], }) ``` O seu `app.module.ts` deve ficar semelhante a isso ```jsx theme={null} import { NgModule } from "@angular/core"; import { BrowserModule } from "@angular/platform-browser"; import { MalgaCheckoutModule } from "@malga-checkout-full/angular"; import { AppComponent } from "./app.component"; @NgModule({ declarations: [AppComponent], imports: [BrowserModule, MalgaCheckoutModule], providers: [], bootstrap: [AppComponent], }) export class AppModule {} ``` Agora basta você usar o Malga Checkout Full em um dos seus componentes no arquivo `component.html` ```jsx theme={null} ``` E no arquivo `component.ts` ```ts theme={null} @Component({ selector: "app-root", templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent { paymentMethods = { pix: { expiresIn: 600, items: [ { id: "123", title: "Produto", quantity: 1, unitPrice: 100, }, ], }, credit: { installments: { quantity: 1, show: true, }, showCreditCard: true, }, boleto: { expiresDate: "2022-12-31", instructions: "Instruções para pagamento do boleto", interest: { days: 1, amount: 100, }, fine: { days: 2, amount: 200, }, items: [ { id: "123", title: "Produto", quantity: 1, unitPrice: 100, }, ], }, drip: { browser: { ipAddress: "127.0.0.1", browserFingerprint: "123123123", }, successRedirectUrl: "https://example.com", cancelRedirectUrl: "https://example.com", }, nupay: { taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }, }; pageConfig = { brandUrl: "https://exampleurl/assets/images/logo.png", footerDescription: "Todos os direitos reservados © 2022 Malga.", backRoute: "https://www.malga.io/", delivery: 0, products: [ { name: "Produto 1", quantity: 2, amount: 50, description: "Descrição do produto 1", sku: "123", risk: "Low", }, { name: "Produto 2", quantity: 2, amount: 40, description: "Descrição do produto 2", sku: "124", risk: "Low", }, ], }; transactionConfig = { statementDescriptor: "#1 Demonstration Malga Checkout", amount: 100, description: "", orderId: "", customerId: "", currency: "BRL", capture: false, }; dialogConfig = { show: true, actionButtonLabel: "Continuar", errorActionButtonLabel: "Tentar novamente", successActionButtonLabel: "Continuar", successRedirectUrl: "https://www.malga.io/", }; handlePaymentSuccess(data: MalgaCheckoutFullTransactionSuccessEvent) { // Your specifications here } handlePaymentFailed(error: MalgaCheckoutFullTransactionErrorEvent) { // Your specifications here } } ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `pageConfig` | Objeto que define a configuração de elementos da página. | `function` | `undefined` | | `transactionSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `transactionFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). > [!NOTE] > > Configurando itens na Drip Na integração com a Drip é possível enviar uma > lista de itens. Por padrão iremos usar os produtos que você configurou em > `pageConfig.products`, mas é possível sobrescrever os produtos enviados para > a drip usando a propriedade `items`. #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: ""}], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um `customerId` pelo `transactionConfig` **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | #### `pageConfig` Abaixo a lista de propriedades disponíveis para a configuração da página. | Property | Description | Type | Default | Example | | - | - | - | - | - | | `brandUrl` | Define a URL da imagem que será exibida no cabeçalho da página. | `string` | `""` | | | `footerDescription` | Define o texto exibido no rodapé da página. | `string` | `""` | | | `backRoute` | URL para o redirecionamento do botão voltar. | `string` | `""` | | | `delivery` | Valor em CENTAVOS usado de frete. | `number` | `0` | | | `products` | Lista de objetos que compõem os itens do pedido exibidos na página. | `array` | `[]` | `[ { name: 'Produto 1', quantity: 2, amount: 50, description: 'Descrição do produto 1', sku: '123', risk: 'Low', }, { name: 'Produto 2', quantity: 2, amount: 40, description: 'Descrição do produto 2', sku: '124', risk: 'High', }, ],` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. Além disso, na versão MalgaCheckoutFull, o usuário pode alternar entre as línguas suportadas utilizando um menu no cabeçalho da aplicação. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-full-angular/blob/main/src/styles.css). # Checkout Full SDK em Javascript Source: https://docs.malga.io/sdks/malga-checkout-full/js ## Get started ### Adicione como dependência no seu site o checkout full SDK ```html theme={null} ``` ### Inicie o componente `` no seu arquivo HTML ```md theme={null} Malga Checkout Full Components
``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `pageConfig` | Objeto que define a configuração de elementos da página. | `function` | `undefined` | | `transactionSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `transactionFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). > [!NOTE] > > Configurando itens na Drip Na integração com a Drip é possível enviar uma > lista de itens. Por padrão iremos usar os produtos que você configurou em > `pageConfig.products`, mas é possível sobrescrever os produtos enviados para > a drip usando a propriedade `items`. #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um `customerId` pelo `transactionConfig` **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | #### `pageConfig` Abaixo a lista de propriedades disponíveis para a configuração da página. | Property | Description | Type | Default | Example | | - | - | - | - | - | | `brandUrl` | Define a URL da imagem que será exibida no cabeçalho da página. | `string` | `""` | | | `footerDescription` | Define o texto exibido no rodapé da página. | `string` | `""` | | | `backRoute` | URL para o redirecionamento do botão voltar. | `string` | `""` | | | `delivery` | Valor em CENTAVOS usado de frete. | `number` | `0` | | | `products` | Lista de objetos que compõem os itens do pedido exibidos na página. | `array` | `[]` | `[ { name: 'Produto 1', quantity: 2, amount: 50, description: 'Descrição do produto 1', sku: '123', risk: 'Low', }, { name: 'Produto 2', quantity: 2, amount: 40, description: 'Descrição do produto 2', sku: '124', risk: 'High', }, ],` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. Além disso, na versão MalgaCheckoutFull, o usuário pode alternar entre as línguas suportadas utilizando um menu no cabeçalho da aplicação. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-full-vanilla/blob/main/index.css). # SDK React.js Source: https://docs.malga.io/sdks/malga-checkout-full/react ## Get started ### Adicione como dependência no seu site o checkout full SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout-full/react ``` ### Importe o Malga Checkout Full em um dos seus componentes ```jsx theme={null} import MalgaCheckoutFull from "@malga-checkout-full/react"; { // Your specifications here }} onTransactionFailed={(error) => { // Your specifications here }} />; ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `pageConfig` | Objeto que define a configuração de elementos da página. | `function` | `undefined` | | `transactionSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `transactionFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). > [!NOTE] > > Configurando itens na Drip Na integração com a Drip é possível enviar uma > lista de itens. Por padrão iremos usar os produtos que você configurou em > `pageConfig.products`, mas é possível sobrescrever os produtos enviados para > a drip usando a propriedade `items`. #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um `customerId` pelo `transactionConfig` **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | #### `pageConfig` Abaixo a lista de propriedades disponíveis para a configuração da página. | Property | Description | Type | Default | Example | | - | - | - | - | - | | `brandUrl` | Define a URL da imagem que será exibida no cabeçalho da página. | `string` | `""` | | | `footerDescription` | Define o texto exibido no rodapé da página. | `string` | `""` | | | `backRoute` | URL para o redirecionamento do botão voltar. | `string` | `""` | | | `delivery` | Valor em CENTAVOS usado de frete. | `number` | `0` | | | `products` | Lista de objetos que compõem os itens do pedido exibidos na página. | `array` | `[]` | `[ { name: 'Produto 1', quantity: 2, amount: 50, description: 'Descrição do produto 1', sku: '123', risk: 'Low', }, { name: 'Produto 2', quantity: 2, amount: 40, description: 'Descrição do produto 2', sku: '124', risk: 'High', }, ],` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. Além disso, na versão MalgaCheckoutFull, o usuário pode alternar entre as línguas suportadas utilizando um menu no cabeçalho da aplicação. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-full-react/blob/main/src/index.css). # SDK Vue.js Source: https://docs.malga.io/sdks/malga-checkout-full/vue ## Get started Para Vue há configurações diferentes conforme a versão que você usa em seu projeto, abaixo será explicado como configurar para o Vue2 e Vue3. ### Vue3 #### Adicione como dependência no seu site o checkout full SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout-full/vue @malga-checkout/core ``` #### Configure seu `main.ts` Importe as configurações ```ts theme={null} import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; ``` Agora adicione os `customElements` e aplique os `polyfills` para garantir o funcionamento do Web Component ```ts theme={null} applyPolyfills().then(() => { defineCustomElements().then(() => { app.mount("#app"); }); }); ``` Seu `main.ts` deve ficar semelhante a isso ```ts theme={null} import { createApp } from "vue"; import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; import App from "./App.vue"; const app = createApp(App); applyPolyfills().then(() => { defineCustomElements().then(() => { app.mount("#app"); }); }); ``` #### Importe o Malga Checkout Full em um dos seus componentes ```jsx theme={null} ``` #### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `:publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `:merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `:sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `:locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `:transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `:dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `:paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `:pageConfig` | Objeto que define a configuração de elementos da página. | `function` | `undefined` | | `@transactionSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `@transactionFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Vue2 #### Adicione como dependência no seu site o checkout full SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout/core ``` #### Configure seu `main.ts` Importe as configurações ```ts theme={null} import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; ``` Agora adicione os `customElements` e aplique os `polyfills` para garantir o funcionamento do Web Component ```ts theme={null} Vue.config.ignoredElements = [/malga-\w*/]; applyPolyfills().then(() => { defineCustomElements(); }); ``` Seu `main.ts` deve ficar semelhante a isso ```ts theme={null} import Vue from "vue"; import App from "./App.vue"; import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; Vue.config.productionTip = false; Vue.config.ignoredElements = [/malga-\w*/]; applyPolyfills().then(() => { defineCustomElements(); }); new Vue({ render: (h) => h(App), }).$mount("#app"); ``` #### Importe o Malga Checkout Full em um dos seus componentes ```jsx theme={null} ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `:publicKey.prop` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:clientId.prop` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `:merchantId.prop` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:sessionId.prop` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:sandbox.prop` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `:locale.prop` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `:transactionConfig.prop` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `:dialogConfig.prop` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `:paymentMethods.prop` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `:pageConfig` | Objeto que define a configuração de elementos da página. | `function` | `undefined` | | `@transactionSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `@transactionFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props ##### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Setting up Card Validation > To set up card validation via Zero Dollar, simply define the `cvvCheck: true` property within the credit object. > By default, we will use the `merchantId` configured in the transaction. If you wish to use a different one, simply define the new `merchantId` in the `cvvCheckMerchantId` property. > > To learn more, see [card validation and Zero Dollar](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). > [!NOTE] > > Configurando itens na Drip Na integração com a Drip é possível enviar uma > lista de itens. Por padrão iremos usar os produtos que você configurou em > `pageConfig.products`, mas é possível sobrescrever os produtos enviados para > a drip usando a propriedade `items`. ##### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um `customerId` pelo `transactionConfig` **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. ##### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | | `boletoWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Boleto. | `string` | `"Pedido aguardando pagamento!"` | | `pixWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Pix. | `string` | `"Pedido aguardando pagamento!"` | | `pixImportantMessages` | Lista de textos utilizados para as informações importantes do pagamento com Pix. | `array` | `["Vamos avisar por e-mail quando o banco identificar o depósito. Esse processo é automático.", "Caso o tempo de pagamento tenha expirado e o Pix não tenha sido pago, seu pedido será cancelado automaticamente. Não pague após este horário." ]` | | `pixFilledProgressBarColor` | Cor que indica o preenchimento do contador do Pix. | `string` | `"#2FAC9B"` | | `pixEmptyProgressBarColor` | Cor que indica o fundo do contador do Pix. | `string` | `"#D8DFF0"` | #### `pageConfig` Abaixo a lista de propriedades disponíveis para a configuração da página. | Property | Description | Type | Default | Example | | - | - | - | - | - | | `brandUrl` | Define a URL da imagem que será exibida no cabeçalho da página. | `string` | `""` | | | `footerDescription` | Define o texto exibido no rodapé da página. | `string` | `""` | | | `backRoute` | URL para o redirecionamento do botão voltar. | `string` | `""` | | | `delivery` | Valor em CENTAVOS usado de frete. | `number` | `0` | | | `products` | Lista de objetos que compõem os itens do pedido exibidos na página. | `array` | `[]` | `[ { name: 'Produto 1', quantity: 2, amount: 50, description: 'Descrição do produto 1', sku: '123', risk: 'Low', }, { name: 'Produto 2', quantity: 2, amount: 40, description: 'Descrição do produto 2', sku: '124', risk: 'High', }, ],` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. Além disso, na versão MalgaCheckoutFull, o usuário pode alternar entre as línguas suportadas utilizando um menu no cabeçalho da aplicação. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-full-vue3/blob/main/src/App.vue). # SDK Angular.js Source: https://docs.malga.io/sdks/malga-checkout/angular ## Get started ### Adicione como dependência no seu site o checkout SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout/angular ``` ### Importe o Malga Checkout no seu `app.module.ts` ```jsx theme={null} import { MalgaCheckoutModule } from '@malga-checkout/angular' @NgModule({ declarations: [AppComponent], imports: [BrowserModule, MalgaCheckoutModule], providers: [], bootstrap: [AppComponent], }) ``` O seu `app.module.ts` deve ficar semelhante a isso ```jsx theme={null} import { NgModule } from "@angular/core"; import { BrowserModule } from "@angular/platform-browser"; import { MalgaCheckoutModule } from "@malga-checkout/angular"; import { AppComponent } from "./app.component"; @NgModule({ declarations: [AppComponent], imports: [BrowserModule, MalgaCheckoutModule], providers: [], bootstrap: [AppComponent], }) export class AppModule {} ``` Agora basta você usar o Malga Checkout em um dos seus componentes no arquivo `component.html` ```jsx theme={null} ``` E no arquivo `component.ts` ```ts theme={null} @Component({ selector: "app-root", templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent { paymentMethods = { pix: { expiresIn: 600, items: [ { id: "123", title: "Produto", quantity: 1, unitPrice: 100, }, ], }, credit: { installments: { quantity: 1, show: true, }, showCreditCard: true, }, boleto: { expiresDate: "2022-12-31", instructions: "Instruções para pagamento do boleto", interest: { days: 1, amount: 100, }, fine: { days: 2, amount: 200, }, items: [ { id: "123", title: "Produto", quantity: 1, unitPrice: 100, }, ], }, drip: { items: [ { id: "123", title: "Produto", quantity: 1, unitPrice: 100, }, ], browser: { ipAddress: "127.0.0.1", browserFingerprint: "123123123", }, successRedirectUrl: "https://example.com", cancelRedirectUrl: "https://example.com", }, nupay: { taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }, }; transactionConfig = { statementDescriptor: "#1 Demonstration Malga Checkout", amount: 100, description: "", orderId: "", customerId: "", currency: "BRL", capture: false, }; dialogConfig = { show: true, actionButtonLabel: "Continuar", errorActionButtonLabel: "Tentar novamente", successActionButtonLabel: "Continuar", successRedirectUrl: "https://www.malga.io/", pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0", }; handlePaymentSuccess(data: MalgaCheckoutSuccess) { // Your specifications here } handlePaymentFailed(error: MalgaCheckoutError) { // Your specifications here } } ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `paymentSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `paymentFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um customer pelo `transactionConfig`, seja objeto completo ou `customerId`, **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | | `boletoWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Boleto. | `string` | `"Pedido aguardando pagamento!"` | | `pixWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Pix. | `string` | `"Pedido aguardando pagamento!"` | | `pixImportantMessages` | Lista de textos utilizados para as informações importantes do pagamento com Pix. | `array` | `["Vamos avisar por e-mail quando o banco identificar o depósito. Esse processo é automático.", "Caso o tempo de pagamento tenha expirado e o Pix não tenha sido pago, seu pedido será cancelado automaticamente. Não pague após este horário." ]` | | `pixFilledProgressBarColor` | Cor que indica o preenchimento do contador do Pix. | `string` | `"#2FAC9B"` | | `pixEmptyProgressBarColor` | Cor que indica o fundo do contador do Pix. | `string` | `"#D8DFF0"` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-angular/blob/main/src/styles.css). # Checkout SDK em Javascript Source: https://docs.malga.io/sdks/malga-checkout/js ## Get started ### Adicione como dependência no seu site o checkout SDK ```html theme={null} ``` ### Inicie o componente `` no seu arquivo HTML ```md theme={null} Malga Checkout Components
``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `paymentSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `paymentFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um customer pelo `transactionConfig`, seja objeto completo ou `customerId`, **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | | `boletoWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Boleto. | `string` | `"Pedido aguardando pagamento!"` | | `pixWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Pix. | `string` | `"Pedido aguardando pagamento!"` | | `pixImportantMessages` | Lista de textos utilizados para as informações importantes do pagamento com Pix. | `array` | `["Vamos avisar por e-mail quando o banco identificar o depósito. Esse processo é automático.", "Caso o tempo de pagamento tenha expirado e o Pix não tenha sido pago, seu pedido será cancelado automaticamente. Não pague após este horário." ]` | | `pixFilledProgressBarColor` | Cor que indica o preenchimento do contador do Pix. | `string` | `"#2FAC9B"` | | `pixEmptyProgressBarColor` | Cor que indica o fundo do contador do Pix. | `string` | `"#D8DFF0"` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-vanilla/blob/main/index.css). # Malga Checkout SDK para React.js Source: https://docs.malga.io/sdks/malga-checkout/react Instale e configure o Malga Checkout SDK em React.js para aceitar pagamentos com Pix, cartão de crédito e boleto no seu site, com exemplos de uso do componente. ## Get started ### Adicione como dependência no seu site o checkout SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout/react ``` ### Importe o Malga Checkout em um dos seus componentes ```jsx theme={null} import MalgaCheckout from "@malga-checkout/react"; { // Your specifications here }} onPaymentFailed={(error) => { // Your specifications here }} />; ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `sessionId` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `onPaymentSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `onPaymentFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props #### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). #### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um customer pelo `transactionConfig`, seja objeto completo ou `customerId`, **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. #### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | | `boletoWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Boleto. | `string` | `"Pedido aguardando pagamento!"` | | `pixWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Pix. | `string` | `"Pedido aguardando pagamento!"` | | `pixImportantMessages` | Lista de textos utilizados para as informações importantes do pagamento com Pix. | `array` | `["Vamos avisar por e-mail quando o banco identificar o depósito. Esse processo é automático.", "Caso o tempo de pagamento tenha expirado e o Pix não tenha sido pago, seu pedido será cancelado automaticamente. Não pague após este horário." ]` | | `pixFilledProgressBarColor` | Cor que indica o preenchimento do contador do Pix. | `string` | `"#2FAC9B"` | | `pixEmptyProgressBarColor` | Cor que indica o fundo do contador do Pix. | `string` | `"#D8DFF0"` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-react/blob/main/src/index.css). # SDK Vue.js Source: https://docs.malga.io/sdks/malga-checkout/vue ## Get started Para Vue há configurações diferentes conforme a versão que você usa em seu projeto, abaixo será explicado como configurar para o Vue2 e Vue3. ### Vue3 #### Adicione como dependência no seu site o checkout SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout/vue @malga-checkout/core ``` #### Configure seu `main.ts` Importe as configurações ```ts theme={null} import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; ``` Agora adicione os `customElements` e aplique os `polyfills` para garantir o funcionamento do Web Component ```ts theme={null} applyPolyfills().then(() => { defineCustomElements().then(() => { app.mount("#app"); }); }); ``` Seu `main.ts` deve ficar semelhante a isso ```ts theme={null} import { createApp } from "vue"; import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; import App from "./App.vue"; const app = createApp(App); applyPolyfills().then(() => { defineCustomElements().then(() => { app.mount("#app"); }); }); ``` #### Importe o Malga Checkout em um dos seus componentes ```jsx theme={null} ``` #### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `:publicKey` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/api-reference/tokens/criar-um-novo-token) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `:merchantId` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:idempotencyKey` | Chave de idempotência, se não informada, o próprio checkout gerará uma e vinculará com a cobrança. [Clique aqui](/documentations/more/idempotency) para ler mais sobre isso na documentação. | `string` | `uuidv4` | | `:sandbox` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `:locale` | String que define a língua do MalgaCheckout. | `string` | `undefined` | | `:transactionConfig` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `:dialogConfig` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `:paymentMethods` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `@paymentSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `@paymentFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Vue2 #### Adicione como dependência no seu site o checkout SDK ```bash npm2yarn theme={null} npm install --save @malga-checkout/core ``` #### Configure seu `main.ts` Importe as configurações ```ts theme={null} import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; ``` Agora adicione os `customElements` e aplique os `polyfills` para garantir o funcionamento do Web Component ```ts theme={null} Vue.config.ignoredElements = [/malga-\w*/]; applyPolyfills().then(() => { defineCustomElements(); }); ``` Seu `main.ts` deve ficar semelhante a isso ```ts theme={null} import Vue from "vue"; import App from "./App.vue"; import { applyPolyfills, defineCustomElements, } from "@malga-checkout/core/loader"; Vue.config.productionTip = false; Vue.config.ignoredElements = [/malga-\w*/]; applyPolyfills().then(() => { defineCustomElements(); }); new Vue({ render: (h) => h(App), }).$mount("#app"); ``` #### Importe o Malga Checkout em um dos seus componentes ```jsx theme={null} ``` ### Props Abaixo a lista de propriedades de customização implementadas pelo componente de interface, use de acordo com suas necessidades de personalização. | Property | Description | Type | Default | | - | - | - | - | | `:publicKey.prop` | Chave pública para aplicações client-side, gerada pela API da Malga. [Clique aqui](/documentations/welcome/authentication#sub-keys) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:clientId.prop` | Chave para identificar o cliente na Malga. [Clique aqui](/documentations/welcome/authentication) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:merchantId.prop` | Identificação de subcontas na Malga. [Clique aqui](/api-reference/merchants/listagem-de-merchants-cadastrados) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:sessionId.prop` | Identificação de uma sessão na Malga. [Clique aqui](/api-reference/sessions/criar-nova-sessao) para ler mais sobre isso na documentação. | `string` | `undefined` | | `:sandbox.prop` | Flag para definir se a chamada na API da Malga deve ser feita em ambiente de homologação ou produção. | `boolean` | `false` | | `:transactionConfig.prop` | Objeto que configura as propriedades da transação. | `object` | `{ statementDescriptor: '', amount: 0, description: '', orderId: '', customerId: '', currency: 'BRL', capture: false, customer: null, fraudAnalysis: null, paymentFlowMetadata: null, splitRules: null }` | | `:dialogConfig.prop` | Objeto que configura o dialog que exibe o status da transação. | `object` | `{ show: true, actionButtonLabel: 'Continuar', successActionButtonLabel: 'Continuar', errorActionButtonLabel: 'Tentar Novamente', successRedirectUrl: '', pixFilledProgressBarColor: "#2FAC9B", pixEmptyProgressBarColor: "#D8DFF0" }` | | `:paymentMethods.prop` | Objeto que configura os métodos de pagamento que devem ser renderizados. | `object` | `{ pix: undefined, credit: undefined, boleto: undefined, drip: undefined, nupay: undefined }` | | `@paymentSuccess` | Evento chamado após o sucesso em uma transação. | `function` | `undefined` | | `@paymentFailed` | Evento chamado após a falha em uma transação. | `function` | `undefined` | ### Detalhes das Props ##### `paymentMethods` Abaixo a lista de propriedades disponíveis para a configuração dos métodos de pagamento que devem ser renderizados. | Property | Description | Type | Default | | - | - | - | - | | `pix` | Objeto que configura o pagamento com Pix. | `object` | `{ expiresIn: 600 }` | | `boleto` | Objeto que configura o pagamento com Boleto. | `object` | `{ expiresDate: "yyyy-mm-dd", instructions: "", interest: { days: 1, amount: 100 }, fine: { days: 1, amount: 200 }}` | | `credit` | Objeto que configura o pagamento com Cartão de Crédito. | `object` | `{ installments: { quantity: 1, show: true }, checkedSaveCard: false, showCreditCard: true, cvvCheck: false, cvvCheckMerchantId: '', recurrence: undefined },` | | `drip` | Objeto que configura o pagamento com Drip. | `object` | `{ items: [{ id: '123', title: 'Product', quantity: 1, unitPrice: 100 }], browser: { ipAddress: '127.0.0.1', browserFingerprint: '123123' }, successRedirectUrl: 'https://example.com', cancelRedirectUrl: 'https://example.com' },` | | `nupay` | Objeto que configura o pagamento com NuPay. | `object` | `{ taxValue: 10, delayToAutoCancel: 60, orderUrl: "http://127.0.0.1", }` | > [!NOTE] > > Configurando Validação de Cartão > Para configurar a validação de cartão via Zero Dollar, basta definir a propriedade `cvvCheck: true` dentro do objeto de `credit`. > Por padrão usaremos o `merchantId` configurado na transação. Caso deseje usar outro, basta definir o novo `merchantId` na propriedade `cvvCheckMerchantId`. > > Para saber mais sobre validação de cartão e Zero Dollar, [clique aqui](/documentations/tokenization/zero-dollar). > [!NOTE] > > Configurando Recorrência > Para configurar cobranças recorrentes com cartão de crédito, defina a propriedade `recurrence` dentro do objeto `credit` com um dos valores: `'initial'` (primeira cobrança da recorrência), `'subsequent'` (cobranças seguintes) ou `'unscheduled'` (cobranças sem agendamento fixo). > > Exemplo: `credit: { recurrence: 'initial' }` > > Quando utilizado com sessions via link de pagamento, o valor de `recurrence` configurado no link é a fonte de verdade e sobrescreve qualquer configuração do SDK. > > Para saber mais sobre recorrência, [clique aqui](/documentations/more/recurrence/charges). ##### `transactionConfig` Abaixo a lista de propriedades disponíveis para a configuração de uma transação. | Property | Description | Type | Default | | - | - | - | - | | `statementDescriptor` | Descrição visível para o comprador. | `string` | `""` | | `amount` | Valor TOTAL da transação em CENTAVOS. | `number` | `0` | | `description` | Descrição da cobrança para consulta futura. | `string` | `""` | | `orderId` | Identificador único da cobrança do lado do cliente para conciliação futura. | `string` | `""` | | `currency` | Identificador da moeda para processamento da cobrança. | `string` | `"BRL"` | | `capture` | Determina se a transação deve ser capturada imediatamente. | `boolean` | `false` | | `customerId` | Identificador de um customer já criado para vincular a transação. | `string` | `""` | | `customer` | Objeto para criação de um customer automaticamente ao fazer uma transação quando o `customerId` não for informado. | `object` | `{ name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" } }` | | `fraudAnalysis` | Objeto para passagem dos parâmetros do antifraude. Caso o objeto de `customer` já tenha sido configurado no `transactionConfig`, não será necessário passá-lo dentro do objeto do `fraudAnalysis` | `object` | `{ browserFingerprint: "", usePartialCustomer: false, cart: [{ name: "", quantity: 0, sku: "", unitPrice: 0, risk: "Low or High", categoryId: "" }], customer: { name: "", email: "", phoneNumber: "", document: { type: "", number: "", country: "" }, address: { zipCode: "", street: "", number: "", complement: "", neighborhood: "", city: "", state: "", country: "" }}}` | | `paymentFlowMetadata` | Objeto para envio das informações de `metadata` para ser usado na Orquestração de Fluxos Inteligentes. Basta passar um objeto com as chaves definidas na configuração do Fluxo Inteligente e o valor dinâmico que será usado na decisão do Fluxo Inteligente | `object` | `{ chave: valor }` | | `splitRules` | Objeto para envio das informações de split de pagamentos. | `array` | `[{ sellerId: "", percentage: "", amount: 0, processingFee: false, liable: false, fares: { mdr: 0, fee: 0 }}]` | | `providerReferenceKey` | Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do adquirente/provedor. Caso não enviado, a gestão dessa informação será feita pela Malga, que gerará um UUID para cada requisição nova aos provedores. | `string` | `""` | > [!NOTE] > > Configurando Customer no Antifraude > Reaproveitando um customer do `transactionConfig`: Caso você configure um customer pelo `transactionConfig`, seja objeto completo ou `customerId`, **e você tenha um nó de `fraudAnalysis` configurado**, este será reaproveitado no `fraudAnalysis`. > > O Malga Checkout também pode ser configurado para enviar ou não este customer, caso ele tenha ou não endereço. Este caso é necessário em alguns provedores, utilizando a flag `usePartialCustomer` é possível ter os seguintes comportamentos: > > * Se configurado como **true**, o customer configurado será enviado independentemente do nó de endereço existir; > * Se configurado como **false**, o customer só será enviado caso **possua** o nó de endereço. > > Caso o `fraudAnalysis` tenha um customer configurado dentro dele, este sempre irá ser utilizado no lugar do customer do `transactionConfig`, mas também respeitando as regras do `usePartialCustomer`. ##### `dialogConfig` Abaixo a lista de propriedades disponíveis para a configuração do dialog de status da transação. | Property | Description | Type | Default | | - | - | - | - | | `show` | Define se o dialog deve ser renderizado. | `boolean` | `true` | | `actionButtonLabel` | Rótulo padrão para os botões de ação do dialog. | `string` | `"Continuar"` | | `successActionButtonLabel` | Rótulo para sucesso nos botões de ação do dialog. | `string` | `"Continuar"` | | `successRedirectUrl` | URL para redirecionamento após o sucesso da transação. | `string` | `""` | | `errorActionButtonLabel` | Rótulo para erro nos botões de ação do dialog. | `string` | `"Tentar Novamente"` | | `boletoWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Boleto. | `string` | `"Pedido aguardando pagamento!"` | | `pixWaitingPaymentMessage` | Rótulo utilizado no cabeçalho do modal de pagamento do Pix. | `string` | `"Pedido aguardando pagamento!"` | | `pixImportantMessages` | Lista de textos utilizados para as informações importantes do pagamento com Pix. | `array` | `["Vamos avisar por e-mail quando o banco identificar o depósito. Esse processo é automático.", "Caso o tempo de pagamento tenha expirado e o Pix não tenha sido pago, seu pedido será cancelado automaticamente. Não pague após este horário." ]` | | `pixFilledProgressBarColor` | Cor que indica o preenchimento do contador do Pix. | `string` | `"#2FAC9B"` | | `pixEmptyProgressBarColor` | Cor que indica o fundo do contador do Pix. | `string` | `"#D8DFF0"` | #### `locale` A propriedade `locale` permite alternar a língua do MalgaCheckout entre português e inglês, as seguintes configurações estão disponíveis: * Não enviar a propriedade: o MalgaCheckout irá configurar a língua baseado nas configurações do navegador do usuário; * `pt-BR`, `pt_BR`, `pt`: configuração em português; * `en-US`, `en_US`, `en`: configuração em inglês. ### Tema Para customização do tema (cor, espaço, tipografia, etc.) você pode sobrescrever as variáveis no arquivo CSS principal do seu site. Abaixo a lista de variáveis suportadas: ```css theme={null} :root { /* Colors */ --malga-checkout-color-page-background: #eef2f6; --malga-checkout-color-brand-accent-light: #79dbd4; --malga-checkout-color-brand-accent-normal: #39bfad; --malga-checkout-color-brand-clean: #c3f4ef; --malga-checkout-color-brand-light: #79dbd4; --malga-checkout-color-brand-normal: #39bfad; --malga-checkout-color-brand-middle: #2fac9b; --malga-checkout-color-brand-dark: #147f70; --malga-checkout-color-grey-light: #666666; --malga-checkout-color-grey-normal: #4d4d4d; --malga-checkout-color-grey-middle: #333333; --malga-checkout-color-grey-dark: #1a1a1a; --malga-checkout-color-grey-darkness: #000000; --malga-checkout-color-accent-light: #ffffff; --malga-checkout-color-accent-normal: #f1f1f1; --malga-checkout-color-accent-middle: #cbcbcb; --malga-checkout-color-warning-light: #fff8e6; --malga-checkout-color-warning-normal: #f9df8d; --malga-checkout-color-warning-middle: #ffa400; --malga-checkout-color-modal-success: #00ae42; --malga-checkout-color-modal-error: #ed3a3d; --malga-checkout-color-modal-neutral: #4d4d4d; --malga-checkout-color-modal-action-button-error: #000000; --malga-checkout-color-modal-action-button-error-hover: #333333; --malga-checkout-color-modal-action-button-success: #000000; --malga-checkout-color-modal-action-button-success-hover: #333333; --malga-checkout-color-modal-action-button-success-font-color: #ffffff; --malga-checkout-color-modal-action-button-error-font-color: #ffffff; /* Typography */ --malga-checkout-typography-family: "Inter", sans-serif; /* Spacings */ --malga-checkout-spacing-xxs: 4px; --malga-checkout-spacing-xs: 8px; --malga-checkout-spacing-sm: 16px; --malga-checkout-spacing-default: 24px; --malga-checkout-spacing-md: 32px; --malga-checkout-spacing-lg: 48px; --malga-checkout-spacing-xlg: 64px; --malga-checkout-spacing-xxlg: 96px; /* Sizes */ --malga-checkout-size-min-width: 250px; /* Border Radius */ --malga-checkout-border-radius-default: 4px; --malga-checkout-border-radius-md: 6px; --malga-checkout-border-radius-lg: 20px; /* Transitions Time */ --malga-checkout-transition-slow: 0.3s; --malga-checkout-transition-default: 0.5s; } ``` Veja um exemplo [clicando aqui](https://github.com/plughacker/demo-malga-checkout-vue3/blob/main/src/App.vue). # Conector Malga para lojas VTEX Source: https://docs.malga.io/sdks/plugins/vtex-connector Ative o conector Malga na sua loja VTEX para processar pagamentos com cartão de crédito, Pix e boleto usando o Fluxo Inteligente e os provedores da Malga. Através do **conector Malga**, é possível processar pagamentos de crédito, Pix e boleto na sua loja [VTEX](http://vtex.com/) utilizando todos os recursos e provedores do [Fluxo Inteligente Malga](/documentations/flow-guide/flow-dash). Com a ativação do conector, você utiliza os recursos da nossa infraestrutura e pode realizar alterações nas configurações de pagamento da sua loja pelo [Dashboard Malga](https://dashboard.malga.io/sign-up), sem precisar desenvolver integrações, e também fazer o acompanhamento das cobranças através das soluções de [Painel de Dados](/documentations/dashboard/insights),[ Analytics API](/analytics/intro) e [Exportação de cobranças](/documentations/dashboard/export-data). A integração da Malga com a VTEX foi desenvolvida através do Payment Provider Protocol e conta com **certificado PCI**, em conformidade aos padrões de segurança exigidos para garantir a proteção dos dados do seu cliente. Utilizando o conector Malga, é possível ter mais autonomia para construir o fluxo de pagamentos ideal para a sua loja, aumentando a aprovação das vendas e reduzindo custos de tecnologia e de taxas, a partir das [diversas opções de provedores e antifraude](/documentations/type-tables/payment-methods-by-providers) que oferecemos, potencializando os resultados do seu negócio. **Confira o passo a passo para a configuração do conector Malga e os recursos disponíveis para a sua loja:** ## Recursos Malga para lojas VTEX | **Recurso** | **Suporte do conector** | | - | - | | Suporte a pagamento por Pix, cartão de crédito e boleto | | | Tokenização de cartão | | | Certificado PCI compliance | | | Suporte aos [provedores de pagamento](/documentations/type-tables/payment-methods-by-providers) pela Malga | | | Suporta [antifraude](/documentations/type-tables/antifraude-providers) | | | Suporta adição de condicionais no [fluxo inteligente](/documentations/flow-guide/flow-dash) de pagamentos, exceto envio de campo personalizado na cobrança | | | Estorno e captura de cobranças pelo painel VTEX | | | Acompanhamento das cobranças e disputas pelo Dashboard Malga | | | Acesso aos Dados através da Exportação em .csv, Analytics API e Painel | | | Gestão do fluxo de pagamentos pelo Dashboard Malga | | ## Conector Malga VTEX​ O **conector Malga** está disponível no painel de Administração da sua loja VTEX, em configurações de **Pagamentos > Provedores**. Para realizar a ativação do conector, você precisará do par de chaves de **Token de aplicação e Chave de aplicação**, que são criadas pelo time da Malga e enviadas ao administrador da conta. Acione o nosso atendimento através do email [**suporte@malga.io**](mailto:suporte@malga.io) para a configuração das chaves; ![Vtex Payment Configuration](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-payment-configuration.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=dde67cdeedeed83e8b468d90a34a5268) Configurações de pagamentos no painel VTEX > Afiliações de gateways > Outros > Malga ![Vtex Gateway Configuration](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-gateway-configuration.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=e59b68c606a5eb12ffbd806fab177d38) Configurações de pagamentos no painel VTEX > Afiliações de gateways ## Criação da sua conta Malga Após o recebimento da sua solicitação através do email [[suporte@malga.io](mailto:suporte@malga.io)](mailto:suporte@malga.io), nosso time irá criar a sua conta na Malga e realizar as seguintes etapas: **Criação de Subconta Malga** 1. Na subconta (`merchant-id`), são validadas as **credenciais dos provedores de pagamento e de antifraude** que você irá utilizar nas cobranças da sua loja. Confira as opções disponíveis nesta [documentação](/documentations/type-tables/payment-methods-by-providers); 2. Caso já possua **conta em provedores**, nosso time irá solicitar as chaves para a configuração da subconta com estas credenciais; 3. Caso necessite de **cotação de taxas e abertura de conta em provedores**, você também conta com o nosso suporte; 4. A **subconta criada na Malga deverá ser de uso exclusivo na sua loja Vtex**, para rastreamento das cobranças através do Painel da loja e do Dashboard Malga. Avise nosso time caso precise de uma subconta adicional para utilização do [Link de Pagamento](/documentations/payment-link/intro) ou em outras plataformas; 5. Você poderá consultar os **provedores e métodos de pagamento configurados na sua subconta** após a criação da sua conta de usuário no Dashboard Malga, através do menu de [Subcontas](https://dashboard.malga.io/app/merchants "https://dashboard.malga.io/app/merchants"); **Geração e envio das chaves VTEX** A partir da subconta criada, será gerado um par de chaves para utilização da Malga na sua loja VTEX (chave e token de aplicação), que serão enviadas ao email do administrador responsável pela loja. > [!NOTE] > > **SEGURANÇA** Por medida de segurança, recomendamos a exclusão do e-mail com as chaves após a inserção no painel da sua loja VTEX. Avise o nosso time através do email \[[suporte@malga.io](mailto:suporte@malga.io)]\(mailto:[suporte@malga.io](mailto:suporte@malga.io)), caso precise de um novo par de chaves ou realizar a exclusão das chaves criadas anteriormente; ## **Configuração do conector na loja VTEX** 1. **Inserção das chaves na VTEX e ativação do conector | Provedores** No painel da sua loja VTEX, acesse a área de Configurações da Loja > Pagamentos > Provedores, selecionando a Malga nas opções de **Provedores**, e realize as seguintes etapas: * Adicione o par de chaves **Application Key e Application Token** enviados pela Malga, nos respectivos campos; * Defina um **Nome** para a conexão com a Malga; * Utilize a opção de **"Ativar modo teste"**, caso queira realizar transações de teste utilizando a Malga; * Em **"Liquidação Automática"**, selecione a opção "Use o Comportamento Recomendado pelo Processador de Pagamentos", que neste caso irá capturar as cobranças em até 7 dias após sua ocorrência. Caso tenha dúvida sobre esta configuração ou necessite de captura imediata, converse com nosso time para que possamos orientá-lo sobre a configuração; * Clique em **Salvar**; ![Configurações de pagamentos no painel VTEX](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-gateway-configuration.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=e59b68c606a5eb12ffbd806fab177d38) Configurações de pagamentos no painel VTEX > Afiliações de gateways ![Captura automática de pagamentos](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-gateway-configuration-auto-capture-select.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=e397810f8565b277713ff81edb744333) Painel VTEX > Afiliações de gateways > Captura automática de pagamentos > [!NOTE] > > Após esta etapa, o conector Malga VTEX estará ativo nas suas Condições de Pagamento, porém ainda não configurado para processar pagamentos da loja. Para finalizar a integração, siga para a próxima etapa e realize a configuração das Condições de Pagamento com o conector. ## **Configuração das Condições de Pagamento na loja VTEX** Após ativar o conector Malga na área de **Provedores**, acesse o menu de **Configurações > Condições de Pagamento**, para realizar as configurações de cada método de pagamento da loja. O conector Malga VTEX suporta cobranças nos métodos de crédito, Pix e boleto, e devem ser configurados conforme as instruções: ### **Pagamento > Boleto Bancário** Busque pelo método **Boleto Bancário**, dentre as opções de Condições de Pagamento e realize as seguintes configurações: * No campo **"Processar com o provedor"**, selecione Malga; * Defina o status "Ativa" * Configure as condições comerciais do método de acordo com a política da sua loja (vencimento, nome, condição); * Clique em "Salvar"; * Acesse as Condições de pagamento, em Boleto Bancário e defina a Malga como padrão caso possua outro provedor configurado; * Pronto! As mudanças podem demorar até 10 minutos para estar refletidas na loja; ![Condições de pagamento > Método Boleto Bancário](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-boleto-configuration.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=1a23b812fd1cf4d98a27e069e75da144) Condições de pagamento > Método Boleto Bancário ![Condições de pagamento > Método Boleto Bancário](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-boleto-configuration-saved.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=6fb5896c92e8a942d900146c4686e090) Condições de pagamento > Método Boleto Bancário ![Condições de pagamento > Método Boleto Bancário > Padrão](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-boleto-default.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=467c0611dc0da29bbe2f8d9c9ab27e58) Condições de pagamento > Método Boleto Bancário > Padrão ![Condições de pagamento > Método Boleto Bancário > Padrão > Malga definida como Padrão](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-boleto-configuration-finish.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=82554a268e32f12bf988c0fa537ca1d4) Condições de pagamento > Método Boleto Bancário > Padrão > Malga definida como Padrão ### **Pagamento > Pix** Busque por **Pix** nas opções de Condições de Pagamento e realize as seguintes configurações: * No campo **"Processar com o provedor"**, selecione Malga; * Defina o status "Ativa"; * Configure as condições comerciais do método de acordo com a política da sua loja (vencimento, nome, condição); * Clique em "Salvar"; * Acesse as Condições de pagamento, em Pix e defina a Malga como padrão caso possua outro provedor configurado; * Pronto! As mudanças podem demorar até 10 minutos para estar refletidas na loja; ![Condições de pagamento > Método Pix](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-pix-configuration.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=f7e7ec19505e76d11a4a848eea99d745) Condições de pagamento > Método Pix ![Condições de pagamento > Método Pix > Malga](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-pix-configuration-saved.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=5d5c30cb7a2b3e18a1f75a4c458252ca) Condições de pagamento > Método Pix > Malga ### **Pagamento > Cartão de Crédito** Os pagamentos por cartão de crédito devem ser configurados para cada **Bandeira de cartão**, conforme o exemplo: ![Condições de pagamento > Cartão de Crédito](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-credit-brand-select.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=1f7dd6f2357d76170b39166bc0b11c90) Condições de pagamento > Cartão de Crédito Após selecionar a **Bandeira**, realize as seguintes etapas de configuração: * No campo **"Processar com o provedor"**, selecione Malga; * Defina o status "Ativa"; * Configure as condições comerciais do método de acordo com a política da sua loja para pagamentos à vista e parcelado; * Clique em "Salvar"; * Acesse as Condições de pagamento e defina a Malga como padrão caso já possua outro provedor configurado; * Pronto! As mudanças podem demorar até 10 minutos para estar refletidas na loja; ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-credit-installments-config.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=d70d403d5afbd55c646ffebe037866a7) Fluxo inteligente de Pagamento Malga > Condicional de Balanceador ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-credit-default-configuration-to-brand.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=7fdb33b66662c26400d4c4997801c5a4) Condições de pagamento > Cartão de Crédito > Bandeira American Express > Malga como Padrão > [!NOTE] > > Com a ativação do conector Malga em **Provedores** e **Condições de Pagamento** para cada método e bandeira de cartão, a sua loja estará processando cobranças através de nosso conector. > > Importante: Na VTEX, só é possível utilizar um provedor para cada método e bandeira, podendo ser alterado diretamente do menu de Condições de Pagamento; ## **Recursos adicionais Malga VTEX** ## **Fluxo Inteligente no Dashboard** Além do **acompanhamento das cobranças** realizadas na sua loja VTEX pelo Dashboard Malga, também é possível fazer alterações e configurações nas regras de processamento do seu fluxo inteligente de pagamentos sem a necessidade de fazer edições nas configurações da loja. Através do menu [**Fluxos Inteligentes**](https://dashboard.malga.io/app/smart-flows "https://dashboard.malga.io/app/smart-flows"), você poderá adicionar, excluir e editar provedores do seu fluxo com total autonomia, e também utilizar os condicionais para distribuir as cobranças conforme as características mais interessantes para o seu negócio, como valor e parcelamento. **Saiba mais nesta documentação**: [Fluxos Inteligentes no Dashboard Malga | Malga](/documentations/flow-guide/flow-dash) ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-smart-flow.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=e634852cac3fb051963cc4cedd8ce8a6) Fluxo inteligente de Pagamento Malga > Condicional de Balanceador > [!NOTE] > > **FLUXO INTELIGENTE MALGA** É possível utilizar todos os condicionais do fluxo Malga (valor, balanceador, moeda, parcelas, bandeira e número do cartão), realizando as configurações pelo Dashboard, exceto o condicional de campo personalizado que não é enviado na cobrança processada pela loja VTEX; ## **Identificação dos pagamentos na Malga** Para acessar o [Dashboard Malga](https://dashboard.malga.io/ "https://dashboard.malga.io/"), você deverá realizar o seu cadastro através [deste link](https://dashboard.malga.io/sign-up "https://dashboard.malga.io/sign-up") e avisar o nosso time através do email [suporte@malga.io](mailto:suporte@malga.io). Após concluir o cadastro, você terá acesso ao ambiente sandbox e iremos liberar acesso ao ambiente de produção da sua conta e empresa, onde poderá consultar as cobranças processadas da loja VTEX pela Malga e os detalhes dos pagamentos nos provedores, além dos outros recursos do Administrador de conta na Malga. O identificador único dos pedidos da loja VTEX na Malga é **ID do Pedido**. Acessando o menu Pedidos > Todos os pedidos, você poderá visualizar a listagem de pedidos da sua loja e copiar o número de pedido para encontrar a cobrança no Dashboard Malga \[filtro ID do pedido], conforme ilustrado nas imagens: ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-getting-orderId.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=c2da6ea179fb7819e0b9a63cb5e77d70) Loja VTEX > Todos os pedidos > ID do pedido ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-search-by-orderId.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=a197f96669f0dc59d09a21a896177782) Dashboard Malga > Cobranças > Busca por ID do pedido Para identificação dos pagamentos no Dashboard Malga, você poderá consultar a área de [Cobranças](https://dashboard.malga.io/app/charges "https://dashboard.malga.io/app/charges"). Clicando em uma cobrança específica, irá visualizar os IDs correspondentes em Detalhe de cobrança: no campo Pedido (**ID do Pedido**) e campo Descrição (**VTEX Transaction ID**), conforme a imagem: ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-charge-details.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=33610bb88a7be76e54d106b5e9b1726e) Dashboard Malga > Cobranças > Detalhe de cobrança ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-dashboard-charge.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=b7566a6459609f3222632024af99eb30) Detalhe de cobranças na loja VTEX > ID da transação ![Vtex Detalhes da Charge DashboardVtex](https://mintcdn.com/malga/UNwWMYGJx-7zc-IL/assets/images/sdks/vtex-connector/vtex-dashboard-charges.png?fit=max\&auto=format\&n=UNwWMYGJx-7zc-IL\&q=85\&s=80e655db3f979ec07ac16c52127e45f9) Cobranças na loja VTEX > [!NOTE] > > **ESTORNO / CAPTURA DE COBRANÇAS** As operações de captura e estorno parcial ou total devem ser realizadas pelo painel da loja VTEX, onde você pode cancelar parte do pedido ou dos itens adquiridos na compra. Receberemos sua solicitação através da nossa integração e faremos a requisição de estorno no provedor de pagamento responsável pelo pagamento e a respectiva atualização do status da cobrança no Dashboard Malga; ## **Relatórios & Dados** Para facilitar a análise da performance das cobranças processadas na Malga através do conector VTEX, disponibilizamos as seguintes ferramentas com dados e informações: * [Exportação das cobranças](/documentations/dashboard/export-data) - disponibilização de arquivo .csv com a listagem e detalhes das cobranças através do Dashboard; * [Painel de Dados](/documentations/dashboard/insights) - painel com a visão gerencial da loja e informações sobre as cobranças autorizadas, perdidas, taxa de aprovação geral e por provedor, distribuição das vendas por método de pagamento e principais motivos de perda de transações; * [Analytics API](/analytics/intro) - serviço que disponibiliza os dados dos pagamentos, clientes e processamento, desenvolvido em linguagem de consulta GraphQL, com um ambiente de testes e alto desempenho e flexibilidade para a realização de consultas; ![Vtex Painel de Dados](https://mintcdn.com/malga/gkKFDsvWcgLjJtMs/assets/images/dashboard/insights/overview-dashboard-light.webp?fit=max\&auto=format\&n=gkKFDsvWcgLjJtMs\&q=85\&s=4d0176e4e389bd345be229fb08db9069) > [!NOTE] > > **SUPORTE MALGA** Acione o nosso time de atendimento através do email [suporte@malga.io](mailto:suporte@malga.io) para acompanhar a configuração do conector na sua loja VTEX e também na utilização do Dashboard e demais produtos Malga. # Exemplos de Tokenização Source: https://docs.malga.io/sdks/tokenization/v1/examples # Começando em SDK de Tokenização Source: https://docs.malga.io/sdks/tokenization/v1/intro Tokenize dados de cartão no client-side com o SDK de Tokenização v1 da Malga, mantendo informações sensíveis fora dos seus servidores (PCI). > [!WARNING] > > Esta versão do SDK foi depreciada e será removida em breve. Atualize sua > integração para a [versão 2.0](/sdks/tokenization/v2/intro). O SDK para potencializar sua integração: uma ferramenta que não só simplifica, mas também fortalece a segurança ao tokenizar cartões no client-side. ### Configuração Configurar o SDK de Tokenização é simples: basta possuir as credenciais da Malga, que consistem na `API Key` e no `Client ID`. Se ainda não tem uma conta na Malga, é só [clicar aqui](https://dashboard.malga.io/sign-up) para criar uma conta em nosso Dashboard e obter as credenciais necessárias para iniciar a integração. Agora que você possui as chaves de acesso, basta baixar o pacote para o seu projeto, importá-lo e utilizar o seguinte código: ```typescript theme={null} import { MalgaTokenization } from "@malga/tokenization"; const malgaTokenization = new MalgaTokenization({ apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", options: { sandbox: true, elements: { form: "data-malga-tokenization-form", holderName: "data-malga-tokenization-holder-name", cvv: "data-malga-tokenization-cvv", expirationDate: "data-malga-tokenization-expiration-date", number: "data-malga-tokenization-number", }, }, }); ``` Abaixo está a lista detalhada com todos os parâmetros de configuração disponíveis. > [accordion] Parâmetros de Configuração > > **apiKey** `uuid` *required* > > Chave de acesso à API > > **clientId** `uuid` *required* > > Identificador único da sua conta na Malga > > **options** `object` > > Configurações Adicionais > > > [accordion] Parâmetros de Configuração > > > > **form** `string` (default: data-malga-tokenization-form) > > > > Identificador da tag form \\ > > > > **holderName** `string` (default: data-malga-tokenization-holder-name) > > > > Identificador do campo de portador do cartão \\ > > > > **cvv** `string` (default: data-malga-tokenization-cvv) > > > > Identificador do campo de CVV > > > > **expirationDate** `string` (default: data-malga-tokenization-expiration-date) > > > > Identificador do campo de data de expiração > > > > **number** `string` (default: data-malga-tokenization-number) > > > > Identificador do campo de número do cartão ### Quickstart Aprenda como configurar o Tokenization SDK e defina o que se encaixa melhor com o seu projeto. > [card] [Quickstart](/sdks/tokenization/v1/quickstart) > > A forma mais simples de tokenizar cartões ### Exemplos Confira os exemplos de projetos integrados com a Malga: > [card] [Sync Tokenization](https://github.com/plughacker/malga-tokenization/tree/main/examples/v1/sync-tokenization) > > Veja o código completo > [card] [Form Handling Tokenization](https://github.com/plughacker/malga-tokenization/tree/main/examples/v1/form-handling-tokenization) > > Veja o código completo # Getting Started Source: https://docs.malga.io/sdks/tokenization/v1/quickstart Aprenda como tokenizar seus cartões usando o Malga Tokenization SDK. ### Pré-requisitos Para que você consiga aproveitar ao máximo esse guia, será necessário ter chaves de integração de sandbox. Basta [clicar aqui](https://dashboard.malga.io/sign-up) e criar uma conta em nosso Dashboard. Antes de começarmos os passos de configuração e utilização do SDK, há duas formas de tokenizar cartões com a lib, chamamos elas de: * `Sync Tokenization`: Você controla o momento da chamada de tokenização; * `Form Handling Tokenization`: A tokenização acontece automaticamente no submit do formulário e você só receberá o `tokenId` no seu back-end. Dessa forma você pode escolher o que se encaixa melhor com o seu projeto. ### 1. Instalando o SDK Instale nosso SDK com o seu gerenciador de pacotes favorito. > [tab] npm > > ```bash theme={null} > npm install @malga/tokenization > ``` > [tab] yarn > > ```bash theme={null} > yarn add @malga/tokenization > ``` > [tab] pnpm > > ```bash theme={null} > pnpm add @malga/tokenization > ``` ### 2. Configurando o formulário Primeiro é necessário adicionar `data-attributes` nos elementos do seu formulário para que consigamos pegar o valor dos campos automaticamente. > [tab] Sync Tokenization > > ```jsx theme={null} >
onSubmit={handleSubmit} > data-malga-tokenization-form> > data-malga-tokenization-holder-name > name="holderName" > type="text" > placeholder="Card Holder Name" > /> > data-malga-tokenization-number > name="number" > type="number" > placeholder="Card Number" > /> > data-malga-tokenization-expiration-date > name="expirationDate" > type="text" > placeholder="Card Expiration Date" > /> > data-malga-tokenization-cvv > name="cvv" > type="number" > placeholder="Card CVV" > /> > >
> ``` > [tab] Form Handling Tokenization > > ```html theme={null} >
data-malga-tokenization-form > action="/checkout" > method="POST"> > data-malga-tokenization-holder-name > name="holderName" > type="text" > placeholder="Card Holder Name" > /> > data-malga-tokenization-number > name="number" > type="number" > placeholder="Card Number" > /> > data-malga-tokenization-expiration-date > name="expirationDate" > type="text" > placeholder="Card Expiration Date" > /> > data-malga-tokenization-cvv > name="cvv" > type="number" > placeholder="Card CVV" > /> > >
> ``` ### 3. Tokenizando o cartão Agora que já estamos com nosso formulário configurado basta instanciar o SDK e chamarmos os métodos para cada tipo de integração. #### Sync Tokenization Basta chamar o método `tokenize` do SDK na função que lida com o `submit` do seu formulário. A mesma irá retornar o `tokenId` do cartão já tokenizado automaticamente. ```typescript theme={null} const malgaTokenization = new MalgaTokenization({ apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", }); async function handleSubmit(event) { event.preventDefault(); const { tokenId } = await malgaTokenization.tokenize(); console.log(tokenId); } ``` #### Form Handling Tokenization Você só precisará chamar o método `init` do SDK no seu arquivo JS principal, o entrypoint da sua aplicação. Dessa forma quando acontecer o `submit` do seu formulário a tokenização já ocorrerá automaticamente. Não se preocupe, os campos do formulário que não estão com o `data-attributes` do SDK ainda continuarão sendo enviados para o seu back-end. ```typescript theme={null} const malgaTokenization = new MalgaTokenization({ apiKey: "8468a624-68c1-49a3-b9f1-a22455053a38", clientId: "ebb9c69c-4ad6-49fd-a565-a35cb4c967b3", }); malgaTokenization.init(); ``` Pronto, agora seus cartões já estão sendo tokenizados com segurança! :rocket: ### 4. Teste você mesmo > [card] [Exemplo Sync Tokenization](https://github.com/plughacker/malga-tokenization/tree/main/examples/v1/sync-tokenization) > > Veja o código completo > [card] [Exemplo Form Handling Tokenization](https://github.com/plughacker/malga-tokenization/tree/main/examples/v1/form-handling-tokenization) > > Veja o código completo # Configuração Source: https://docs.malga.io/sdks/tokenization/v2/configuration Para iniciar a configuração do SDK é preciso criar elementos na tela que serão hidratados com os campos de texto. Esses campos serão preenchidos com os dados do cartão de crédito (número, nome, data e cvv). ```typescript theme={null}
``` > [!WARNING] > > O `id` de cada `div` é o `container` configurado no campo. Ele pode ser qualquer `id`, desde que não se repita na página. ## Props Abaixo está a lista de propriedades de customização do SDK. Utilize-as conforme necessário para configurar a tokenização de cartões. | Propriedade | Descrição | Tipo | Default | | - | - | - | - | | `apiKey` | Chave privada para realizar transações na Malga. | `string` | `undefined` | | `clientId` | Chave para identificar o cliente na Malga. | `string` | `undefined` | | `options` | Objeto que contém configurações dos campos, estilos e segurança. | `object` | `{}` | ### Detalhes das Props #### `options` A propriedade options contém diversas configurações para personalização do SDK. | Propriedade | Descrição | Tipo | Default | | - | - | - | - | | `config` | Configuração dos campos do cartão e estilos dos inputs. | `object` | `{}` | | `sandbox` | Define se a tokenização será feita no ambiente de sandbox. | `boolean` | `true` | #### `options.config` A propriedade config permite configurar os campos de entrada dos cartões e seus respectivos estilos. ##### `config.fields` | Propriedade | Descrição | Tipo | Default | | - | - | - | - | | `container` | ID do elemento HTML onde o campo será renderizado. Aceita qualquer `id` único na página. | `string` | `""` | | `type` | Tipo do input (ex: text). | `string` | `"text"` | | `placeholder` | Texto de placeholder do campo. | `string` | `""` | | `needMask` | Define se o campo deve ter máscara de formatação. | `boolean` | `true` | | `defaultValidation` | Indica se as validações padrão devem ser aplicadas. | `boolean` | `true` | Quando a propriedade needMask possuir valor true, ela vai aplicar as seguintes máscaras: | Campo | Máscara | | - | - | | `card-number` | Cartões até 16 dígitos: `9999 9999 9999 9999` | | | Cartões superiores a 16 dígitos: `9999 9999 9999 999999` | | `card-expiration-date` | `MM/YY` | > [!WARNING] > > Os campos devem ser configurados utilizando as chaves em camelCase: `cardNumber`, `cardHolderName`, `cardCvv`, `cardExpirationDate`. > > O `container` é livre: `card-number`, `numero` ou `card.number` funcionam da mesma forma, porque os dados do cartão são identificados pela chave do campo, e não pelo nome do `container`. A única regra é não repetir o mesmo `id` na página. Para tokenizar dois ou mais cartões, veja [Tokenizando mais de um cartão](/sdks/tokenization/v2/multiple-cards). ##### `config.preventAutofill` | Propriedade | Descrição | Tipo | Default | | - | - | - | - | | `preventAutofill` | Impede que o navegador sugira preenchimento automático. | `boolean` | `false` | ##### `config.styles` Vamos tratar sobre estilização separadamente no tópico específico para [estilos](/sdks/tokenization/v2/styles). ### Validações padrão Quando a propriedade defaultValidation estiver definida como true, algumas validações serão aplicadas automaticamente aos campos durante a digitação do cliente. O resultado dessas validações pode ser acessado por meio do evento validity, que será abordado no próximo tópico. A seguir, estão as validações aplicadas quando defaultValidation for true: ### Validações | Campo | Tipo | Validações | | - | - | - | | `card-number` | `string` | Mínimo: 14 caracteres Máximo: 22 caracteres Validação extra: Usa a biblioteca card-validation para verificar a validade do número do cartão. | | `card-holder-name` | `string` | Mínimo: 3 caracteres Máximo: 30 caracteres | | `card-cvv` | `string` | Mínimo: 3 caracteres Máximo: 4 caracteres | | `card-expiration-date` | `string` | Mínimo: 1 caractere Máximo: 5 caracteres Data: Deve ser superior à data atual Mês: Deve ser igual ou superior ao atual Ano: Deve ser igual ou superior ao atual | > [!NOTE] > > Regras adicionais: > > `card-number`: Permite apenas a digitação de números. > > `card-holder-name`: Permite apenas letras e espaços. > > `card-cvv`: Permite apenas a digitação de números. > > `card-expiration-date`: Permite apenas a digitação de números. > [card] [Estilos](/sdks/tokenization/v2/styles) > > Aprenda a estilizar os campos. > [card] [Mais de um cartão](/sdks/tokenization/v2/multiple-cards) > > Aprenda a tokenizar dois ou mais cartões na mesma página. # Utilizando os eventos Source: https://docs.malga.io/sdks/tokenization/v2/events A aplicação possui três métodos principais: `on`, `tokenize` e `destroy`. ### on(eventType, function) O método on permite escutar eventos e executar um callback quando um determinado evento ocorre. Ele retorna uma função que remove o callback registrado: ```typescript theme={null} const removeListener = malgaTokenization.on('validity', (data) => console.log(data)) removeListener() ``` > [!NOTE] > > Cada instância de `MalgaTokenization` tem seus próprios eventos. Ao tokenizar [mais de um cartão](/sdks/tokenization/v2/multiple-cards), registre o `on` na instância de cada cartão. Nos eventos, `field` é o `container` configurado no campo, por exemplo `card-number-2`. #### Eventos disponíveis ##### `cardTypeChanged` Disparado quando o valor do campo de número do cartão é alterado. **Objeto de retorno:** ```typescript theme={null} { field: string // container do campo, ex: 'card-number' parentNode: Element card?: { niceType: string type: string patterns: (number | number[])[] gaps: number[] lengths: number[] code: { name: string size: number } } } ``` **Exemplo de uso** ```typescript theme={null} malgaTokenization.on('cardTypeChanged', () => console.log('cardTypeChanged')) ``` ##### `validity` Disparado quando há uma alteração nos campos e a validação padrão (defaultValidation) está ativada. **Objeto de retorno:** ```typescript theme={null} { field: string // container do campo, ex: 'card-number' valid: boolean error: { field: string // container do campo, ex: 'card-number' message: string code: string } empty: boolean potentialValid: boolean parentNode: Element | null } ``` **Exemplo de uso** ```typescript theme={null} malgaTokenization.on('validity', () => console.log('validity')) ``` ##### `focus` e `blur` Eventos disparados quando um campo recebe ou perde foco. **Objeto de retorno:** ```typescript theme={null} { field: string // container do campo, ex: 'card-number' parentNode: Element } ``` **Exemplo de uso** ```typescript theme={null} malgaTokenization.on('blur', () => console.log('blur')) malgaTokenization.on('focus', () => console.log('focus')) ``` ##### `loading` Disparado quando a tokenização começa (`isLoading: true`) e quando termina (`isLoading: false`), com sucesso, com erro ou por tempo esgotado. Útil para desabilitar o botão de envio enquanto o cartão é tokenizado. **Objeto de retorno:** ```typescript theme={null} { isLoading: boolean } ``` **Exemplo de uso** ```typescript theme={null} malgaTokenization.on('loading', ({ isLoading }) => { submitButton.disabled = isLoading }) ``` ### tokenize() Método responsável por enviar os dados do cartão para tokenização. Com mais de um cartão na página, chame `tokenize()` na instância de cada cartão. Cada instância retorna o resultado do próprio cartão, mesmo quando as chamadas são executadas ao mesmo tempo. Se o iframe do número do cartão não responder em 30 segundos, `tokenize()` retorna `tokenId` vazio e um `error` com `type: 'timeout'`, e o evento `loading` volta para `false`. A partir da versão 5.0.0, `tokenize()` confere antes se todos os campos configurados em `config.fields` foram preenchidos. Se faltar algum, o método retorna na hora, sem enviar nada à API e sem disparar o evento `loading`, com `tokenId` vazio e um `error` com `type: 'invalid_request_error'`. O `details` lista os campos que faltam, por exemplo `['cardCvv', 'cardExpirationDate']`. Campos que não estão em `config.fields` não são exigidos. ```typescript theme={null} const { tokenId, error } = await malgaTokenization.tokenize() if (error?.type === 'invalid_request_error') { // error.details: campos que faltam, ex.: ['cardCvv'] mostrarCamposPendentes(error.details) return } ``` > [!WARNING] > > Quando o campo de número do cartão não está na página, `tokenize()` é rejeitado com um erro. Trate esse caso com `try/catch`. **Objeto de retorno:** ```typescript theme={null} { tokenId: string error: { type: string code: number message: string details?: string | string[] declinedCode?: string } } ``` **Exemplo de uso** ```typescript theme={null} try { const { tokenId, error } = await malgaTokenization.tokenize() if (error) { console.error('Error', error.message) return } console.log('TokenId:', tokenId) } catch (exception) { // Campo de número do cartão fora da página console.error('Tokenization failed', exception) } ``` Método responsável por criptografar os dados do cartão, enviá-los para tokenização e retornar o tokenID em caso de sucesso. ### destroy() Desmonta a instância de `MalgaTokenization`. O método remove os iframes dos containers, o listener de mensagens e os callbacks registrados com `on`, apaga os dados do cartão coletados e libera os containers para uma nova instância. > [!NOTE] > > Disponível a partir da versão 5.0.0 do `@malga/tokenization`. Chame `destroy()` sempre que o checkout sair da tela. Em aplicações de página única, como React, Vue e Angular, montar a tela de novo sem chamar `destroy()` faz o construtor lançar `ContainerInUseError`, porque a instância anterior ainda ocupa os containers. > [!WARNING] > > Até a versão 4.x, criar uma nova instância nos mesmos containers sem chamar `destroy()` não dava erro: empilhava um segundo conjunto de iframes e mantinha o listener anterior ativo. A partir da 5.0.0, o construtor lança `ContainerInUseError`. Se a tela do checkout pode ser montada mais de uma vez (um `useEffect` sem função de limpeza, o `StrictMode` do React ou a volta para a rota), chame `destroy()` na desmontagem antes de atualizar. Depois de `destroy()`, `tokenize()` lança um erro. Chamar `destroy()` mais de uma vez não tem efeito. **Exemplo de uso** Crie a instância quando o componente do checkout é montado e chame `destroy()` quando ele é desmontado: ao trocar de rota, ao voltar para o carrinho ou ao entrar de novo na tela de pagamento. Assim, cada montagem tem a sua própria instância, e a anterior já liberou os containers. ```typescript checkout-config.ts theme={null} export const configurations = { apiKey: 'YOUR_API_KEY', clientId: 'YOUR_CLIENT_ID', options: { sandbox: true, config: { fields: { cardNumber: { container: 'card-number' }, cardHolderName: { container: 'card-holder-name' }, cardCvv: { container: 'card-cvv' }, cardExpirationDate: { container: 'card-expiration-date' }, }, }, }, } ``` ```tsx React theme={null} import { useEffect, useRef } from 'react' import { MalgaTokenization } from '@malga/tokenization' import { configurations } from './checkout-config' export function Checkout() { const malgaTokenization = useRef(null) useEffect(() => { const instance = new MalgaTokenization(configurations) malgaTokenization.current = instance // Desmontagem: troca de rota e também a segunda montagem do StrictMode return () => instance.destroy() }, []) async function handleSubmit(event: React.FormEvent) { event.preventDefault() const { tokenId, error } = await malgaTokenization.current!.tokenize() // Envie o tokenId para o seu backend } return (
) } ``` ```html Vue theme={null} ``` ```typescript Angular theme={null} import { Component, OnDestroy, OnInit } from '@angular/core' import { MalgaTokenization } from '@malga/tokenization' import { configurations } from './checkout-config' @Component({ selector: 'app-checkout', template: `
`, }) export class CheckoutComponent implements OnInit, OnDestroy { private malgaTokenization?: MalgaTokenization ngOnInit() { this.malgaTokenization = new MalgaTokenization(configurations) } ngOnDestroy() { this.malgaTokenization?.destroy() } async handleSubmit() { const { tokenId, error } = await this.malgaTokenization!.tokenize() // Envie o tokenId para o seu backend } } ``` Sem framework, a regra é a mesma: chame `destroy()` no ponto em que o seu código remove o formulário de pagamento da página, antes de criar outra instância com os mesmos containers. #### Containers em uso Cada `container` pertence a uma única instância enquanto ela não for destruída. O construtor lança um erro, antes de renderizar qualquer campo, quando: * o `container` já é usado por outra instância ativa: `ContainerInUseError`; * o mesmo `container` aparece em dois campos da mesma configuração: `DuplicatedContainerError`. Se o construtor lançar qualquer erro, nenhum container fica reservado: corrija a configuração e crie a instância de novo. Os dois erros trazem o nome do container repetido na propriedade `container` e podem ser importados do pacote: ```typescript theme={null} import { MalgaTokenization, ContainerInUseError } from '@malga/tokenization' try { const malgaTokenization = new MalgaTokenization(configurations) } catch (error) { if (error instanceof ContainerInUseError) { // Chame destroy() na instância anterior antes de criar a nova console.error('Container já em uso:', error.container) } } ``` > [card] [Exemplos de tokenização](https://github.com/plughacker/malga-tokenization/tree/main/examples/v2/tokenization-v2) > > Veja o código completo # Exemplos de Tokenização Source: https://docs.malga.io/sdks/tokenization/v2/examples # Começando em SDK de Tokenização v2 com Hosted Fields Source: https://docs.malga.io/sdks/tokenization/v2/intro Tokenize cartões com o SDK de Tokenização v2 da Malga usando Hosted Fields em iframes seguros, com dados criptografados em ambiente PCI DSS Level 1. O SDK que potencializa sua integração: uma solução que não apenas simplifica o processo, mas também reforça a segurança ao tokenizar cartões. Com ele, você garante a proteção dos dados dos cartões de seus clientes, assegurando que a tokenização ocorra em um ambiente certificado PCI DSS Level I. Todos os cartões processados via SDK são criptografados, impossibilitando que os dados sejam acessados durante a comunicação do navegador com o servidor. O que garante esse maior nível de segurança é a utilização de Hosted Fields. ### Hosted Fields Os Hosted Fields são campos de entrada (inputs) encapsulados dentro de iframes seguros, garantindo que dados sensíveis, como números de cartão, nunca sejam expostos diretamente ao navegador ou ao front-end da aplicação. O SDK utiliza nossa aplicação de Hosted Fields que permite que a coleta de dados do cartão ocorra em um ambiente compatível com **PCI DSS Level I**. Sendo o Hosted Fields o responsável por criar e adicionar os inputs na tela, garantindo total conformidade com os padrões de segurança. ![SDK de Tokenização com Hosted Fields](https://mintcdn.com/malga/vYWnjE_PEfqgCqeH/assets/images/tokenization/sdk-tokenization-light.png?fit=max\&auto=format\&n=vYWnjE_PEfqgCqeH\&q=85\&s=cb8ebef070684148132eae8da188a31c) Além disso, todos os campos podem ser personalizados para se ajustarem ao design da sua aplicação, oferecendo uma experiência intuitiva e sem redirecionamentos desnecessários. > [card] [Getting Started](/sdks/tokenization/v2/quickstart) > > Aprenda a tokenizar cartões de forma segura usando o Malga Tokenization SDK. # Tokenizando mais de um cartão Source: https://docs.malga.io/sdks/tokenization/v2/multiple-cards Para tokenizar dois ou mais cartões na mesma página, crie uma instância de `MalgaTokenization` para cada cartão. Cada instância tem seus próprios campos, eventos e token. O que muda em relação a um único cartão é o `container`: ele aceita qualquer `id`, desde que seja **único na página**. As chaves de `config.fields` continuam as mesmas (`cardNumber`, `cardHolderName`, `cardCvv`, `cardExpirationDate`). O sufixo numérico do exemplo abaixo é só uma convenção: `numero-titular` e `numero-dependente` funcionam igual. ```html theme={null}
``` ```typescript theme={null} const buildOptions = (suffix: string) => ({ sandbox: true, config: { fields: { cardNumber: { container: `card-number-${suffix}` }, cardHolderName: { container: `card-holder-name-${suffix}` }, cardCvv: { container: `card-cvv-${suffix}` }, cardExpirationDate: { container: `card-expiration-date-${suffix}` }, }, }, }) const firstCard = new MalgaTokenization({ apiKey: 'API_KEY', clientId: 'CLIENT_ID', options: buildOptions('1'), }) const secondCard = new MalgaTokenization({ apiKey: 'API_KEY', clientId: 'CLIENT_ID', options: buildOptions('2'), }) const [first, second] = await Promise.all([ firstCard.tokenize(), secondCard.tokenize(), ]) ``` > [!NOTE] > > Os eventos não são compartilhados entre as instâncias: um `on` registrado em `firstCard` só recebe eventos dos campos do primeiro cartão. O campo `field` dos eventos devolve o `container` configurado, por exemplo `card-number-1`. > [!NOTE] > > Cada instância aplica o próprio `config.styles` aos seus campos, e a classe de cada input é o seu `container`. Por isso, no segundo cartão, o seletor do número é `.card-number-2`, e não `.card-number`. Veja [Estilos](/sdks/tokenization/v2/styles). > [!WARNING] > > Não reutilize o mesmo `container` em duas instâncias. Os campos são localizados pelo `id` na página, e um `id` repetido faz os dados de um cartão se misturarem com os do outro. > > A partir da versão 5.0.0, o construtor recusa esse caso com `ContainerInUseError`, antes de renderizar qualquer campo. Para trocar o cartão de uma instância, chame [`destroy()`](/sdks/tokenization/v2/events#destroy) nela antes de criar a nova. > [card] [Eventos](/sdks/tokenization/v2/events) > > Aprenda a utilizar os eventos disponíveis. # Getting Started Source: https://docs.malga.io/sdks/tokenization/v2/quickstart Aprenda a tokenizar cartões de forma segura usando o Malga Tokenization SDK. ### Pré-requisitos Antes de começar, certifique-se de que possui as **chaves de integração** (X-Client-ID e X-API-Key) para ambiente de sandbox. Caso ainda não tenha, basta [criar uma conta](https://dashboard.malga.io/sign-up) em nosso **Dashboard** para obter suas credenciais. ![Suas chaves de integração no Dashboard](https://mintcdn.com/malga/yFpBr5XA06IYHvxL/assets/images/welcome/getting-started/your-keys-light.webp?fit=max\&auto=format\&n=yFpBr5XA06IYHvxL\&q=85\&s=109a1b851a275e2a2b0653ca125f6489) ### Instalando o SDK Instale nosso SDK com o seu gerenciador de pacotes favorito. > [tab] npm > > ```bash theme={null} > npm install @malga/tokenization > ``` > [tab] yarn > > ```bash theme={null} > yarn add @malga/tokenization > ``` > [tab] pnpm > > ```bash theme={null} > pnpm add @malga/tokenization > ``` Com as chaves em mãos e o SDK instalado, vamos à configuração. > [card] [Configuração](/sdks/tokenization/v2/configuration) > > Aprenda a configurar e usar nosso SDK. # Estilizando os campos Source: https://docs.malga.io/sdks/tokenization/v2/styles Buscando oferecer mais flexibilidade, disponibilizamos um objeto que permite aplicar os estilos desejados nos inputs da nossa aplicação. Existem algumas regras para a utilização desse objeto, que estão detalhadas abaixo. ```typescript theme={null} // Aplicação em todos os inputs do hosted fields. styles: { input: { color: "orange", "font-size": "16px", }, } // Mudando a cor do texto apenas de um input. A classe é o `container` // configurado no campo: aqui, `card-number` (serve para os demais) ".card-number": { color: "blue", } // Mudando a cor do text na hora do focus para todos os inputs ":focus": { color: "red", } // Exemplo contendo as 3 mudanças citadas. styles: { input: { color: "orange", "font-size": "16px", }, ".card-number": { color: "blue", }, ":focus": { color: "red", }, } ``` > [!NOTE] > > Cada input recebe como classe o `container` do seu campo. Se o `container` do número do cartão for `numero` ou `card-number-1`, use `.numero` ou `.card-number-1` para aplicar o estilo Além disso, temos quatro classes específicas para lidar com estado do input, são elas: | Classe | Descrição | | - | - | | `malga-hosted-field` | Aplicada ao elemento pai do iframe. Responsável por estilizar a área externa do input (recomenda-se definir border, border-radius, etc.). | | `malga-hosted-field-focused` | Aplicada quando o input recebe foco. | | `malga-hosted-field-valid` | Aplicada quando a validação é bem-sucedida (`valid === true`). | | `malga-hosted-field-invalid` | Aplicada quando há um erro e a validação falha (`valid === false`). | Essas classes podem ser adicionadas na folha de estilo da sua aplicação. ```css theme={null} .malga-hosted-field { background-color: white border: 2px solid #39BFAD border-radius: 8px } .malga-hosted-field-focused { border-color: #147F70 } .malga-hosted-field-valid { border-color: green } .malga-hosted-field-invalid { border-color: red } ``` > [card] [Eventos](/sdks/tokenization/v2/events) > > Aprenda a utilizar os eventos disponíveis