> ## 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 }' ``` 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 Headers localizado na janela inferior do ambiente, conforme o exemplo abaixo: Autenticação no Playground GraphiQL # 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. ## 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": "523afbe7-36dc-4654-9dba-e7167d0e5e2d", "id": "2098ba98-7ad4-4d2c-a6b6-a6b911fdcacd", "createdAt": "2023-09-02T22:18:55.863042", "description": "Loja 1", "orderId": null, "originalAmount": 100, "paymentMethod": { "installments": 1, "paymentType": "credit" }, "status": "failed", "transactionRequests": [ { "id": "b6eb472b-1d2f-4648-8b96-b00ea61276e7", "amount": "100", "createdAt": "2023-09-02T22:18:56.007904", "transactionId": "e18a7106-db5f-4662-b80b-f6faaf20a00e", "idempotencyKey": "22035412-9d5e-4635-b72b-7893c5cd34c0", "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 Cada parte de um esquema em GraphQL é um tipo de objeto, que consiste em uma lista de campos e o valor de cada campo. 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. 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. Cada campo corresponde a uma unidade de dados que é retornada dentro do objeto. 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. A feature identifica o contexto do saldo do subadquirente. Valores possíveis: NUPAY, SUBACQUIRER, GENERAL e SUBACQUIRER\_PREPAYMENT. O padrão é SUBACQUIRER. 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. 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. Ajustes conciliados (subacquirer\_reconciled\_adjustment) aplicáveis às features suportadas, somados ao saldo. Lotes de pagamento (subacquirer\_payment\_batch) pendentes (status pending ou failed), somando o final\_balance ao saldo. 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 **GraphQL**, 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. 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: Linguagem de consulta **GraphQL** e o playground GraphQL da Analytics API. Como fazer chamadas na API através do seu browser usando suas **credenciais da Malga.** 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] 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] A lista de conexões de uma cobrança
pageInfo \[PageInfo] Informações da paginação
totalCount Int! Total de registros retornados pela consulta
# Cart Source: https://docs.malga.io/analytics/objects/cart 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] 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] Informações sobre o método de pagamento da cobrança
paymentSource \[PaymentSource] 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] 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] A lista de conexões de uma cobrança
pageInfo \[PageInfo] 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] 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] Endereço de cobrança
deliveryAddress \[DeliveryAddress] 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.
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] Detalhe do carrinho de produtos
customer \[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] 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] Informações sobre a forma de pagamento por Nupay
pix \[Pix] Informações sobre a forma de pagamento por Pix
providerAuthorization \[ProviderAuthorization] Dados adicionais do retorno da autorização do provider no processamento da transação
providerError \[ProviderError] 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 # Authorization Rate Source: https://docs.malga.io/analytics/queries/authorization-rate 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 **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
# Dashboard Source: https://docs.malga.io/analytics/queries/dashboard O grupo de consultas Dashboard disponibiliza informações para o Painel de Dados 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]
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 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 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 Crie e armazene cartões dos seus clientes com segurança para realizar novas cobranças ### Pagamentos 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`; 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; 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. 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; 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; 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; 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 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 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 Com a API de Analytics é possível consultar dados de transações processadas, permitindo análises gerenciais e acompanhamento dos pagamentos 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 # 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 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`. 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 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`. 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. 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 | 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`. 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. ## 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 Chame `POST /v1/auth` com os mesmos escopos da sub-key atual. Troque a sub-key antiga pela nova na aplicação e confirme que as chamadas funcionam. 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). 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. | `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 Conceitos de sessão 1:1 e 1:N e acompanhamento de status. 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} # Atualizar configurações do cliente Source: https://docs.malga.io/api-reference/subscriptions/atualizar-configuracoes-do-cliente patch /v1/subscriptions/settings Atualiza as configurações do cliente para assinaturas (retry policy, statement descriptor, etc.) # Cancelar assinatura Source: https://docs.malga.io/api-reference/subscriptions/cancelar-assinatura patch /v1/subscriptions/{id}/cancel # Criação de uma nova assinatura Source: https://docs.malga.io/api-reference/subscriptions/criacao-de-uma-nova-assinatura post /v1/subscriptions # Listagem de assinaturas Source: https://docs.malga.io/api-reference/subscriptions/listagem-de-assinaturas get /v1/subscriptions # Listar cycles de uma assinatura Source: https://docs.malga.io/api-reference/subscriptions/listagem-de-cycles-de-uma-assinatura get /v1/subscriptions/{id}/cycles # Obter configurações do cliente Source: https://docs.malga.io/api-reference/subscriptions/obter-configuracoes-do-cliente get /v1/subscriptions/settings Recupera as configurações atuais do cliente para assinaturas (retry policy, statement descriptor, etc.) # Pausar assinatura Source: https://docs.malga.io/api-reference/subscriptions/pausar-assinatura patch /v1/subscriptions/{id}/pause # Reativar assinatura Source: https://docs.malga.io/api-reference/subscriptions/reativar-assinatura patch /v1/subscriptions/{id}/resume # 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} # 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, basta incluir todos os campos de 3DS e definir a propriedade `threeDSecure2.dataOnly: true`. **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. [Veja aqui](https://docs.malga.io/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": "469ed9e8-97d1-433a-a586-2fd282b7d9a4", "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" } } }' ``` 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, é necessário preparar sua conta Malga com as configurações adequadas: ## 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 você possui ou configurou um provedor de pagamento que suporte 3DS2 em sua conta Malga. Você pode consultar a lista de provedores suportados nesse link [Introdução - Malga (3DS2\_Malga)](/documentations/3ds2-malga/intro) ## 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`. **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): ```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 }' ``` ```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. É necessário criar (ou atualizar) um fluxo de pagamento específico para 3DS2, indicando o merchant e o provedor configurado acima. Defina o atributo `paymentMethod` como "3ds2\_malga" para que a Malga saiba que esse fluxo usará a solução 3DS2 própria. 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. **Recomendação:** Esta etapa pode ser feita pelo Dashboard Malga, para tornar a configuração mais simples e prática. # Principais erros Source: https://docs.malga.io/documentations/3ds2-malga/3ds-malga/principais-erros 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. | 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 **Importante:** Se uma transação 3DS2 falhar por qualquer motivo (timeout, erro de tokenização, erro de autenticação, etc.), **não é permitido reutilizar o mesmo `setupId`** para tentar novamente. O `setupId` retornado no setup é válido apenas para **uma única tentativa de cobrança**. Para retentar uma transação que falhou, 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 o mesmo `setupId` em uma retentativa resultará em erro e impedirá o processamento da transação. # 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):** ```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": "123e4567-e89b-12d3-a456-426614174000" }' ``` ```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": "123e4567-e89b-12d3-a456-426614174000" }' ``` 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": "11111111-2222-3333-4444-555555555555", "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. 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": "123e4567-e89b-12d3-a456-426614174000" }, "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:** Indica se você exige o liability shift. Se true, a transação só prosseguirá se houver mudança de responsabilidade para o emissor. 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. 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. 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. 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). 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).
 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). 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.). 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. Realizar uma nova coleta de dados do dispositivo (Passo 2)
  3. Criar uma nova cobrança com o novo setupId obtido (Passo 3)
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 `6607c9b8-f6a3-48e2-9918-518d41d2fa60`. Você pode consultá-la assim: ```bash theme={null} curl --request GET 'https://api.malga.io/v1/charges/6607c9b8-f6a3-48e2-9918-518d41d2fa60' \ --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 funcione. 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. 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. 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. 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 ``` 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. Se você não quer lidar com a complexidade de autenticação, recomendamos usar 3DS2 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": "9502fcb2-f483-4e4f-b9c9-70e01d8f49e2", "threeDSServerTransactionId": "4830a4b7-b80e-4eeb-bff2-d21699e771f0", "directoryServerTransactionId": "4e8567db-2f9e-4c9d-9d8c-3da3c2f7ed32", "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 com 3DS2 na Malga](/documentations/type-tables/payment-methods-by-providers), pois apenas esses provedores oferecem suporte à autenticação via MPI. ## 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 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. | | **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). | | **PAReq / PARes** | Mensagens Payer Authentication Request/Response da especificação 3DS 1.x. | | **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 *** ## 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. ## Conheça mais sobre o 3DS 2.0 Análise de risco sem interrupção do checkout Autenticação com MPI externo Termos técnicos do 3DS 2.0 # Fluxo do Antifraude Assíncrono Source: https://docs.malga.io/documentations/anti-fraud/async-anti-fraud 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 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 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. 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 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": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "074c1ee676ed4998ab66491013c565e2", "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": "713d1e9d-3e05-4258-9c38-d5b474cdca7f", "clientId": "", "merchantId": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "2aba421f-db81-4c2d-a6e8-3379c192a7c5" }, "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": "72e788f6-c767-4688-8b23-4f3c9313458f", "createdAt": "2022-08-25T20:56:37.796Z", "updatedAt": "2022-08-25T20:56:37.796Z", "idempotencyKey": null, "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "SANDBOX", "transactionId": "1737284", "amount": 100, "authorizationCode": "6076640", "authorizationNsu": "3028818", "requestStatus": "success", "requestType": "capture", "responseTs": "8ms", "providerAuthorization": { "networkAuthorizationCode": "7354551", "networkResponseCode": "5759371" } }, { "id": "f4c59668-c513-4e81-a5b2-9988866f3af4", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": 85, "status": "approved" } }, { "id": "f4c59668-c513-4e81-a5b2-9988866f3af4", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "67a55426-defc-4f75-92d0-97f93ef55e39", "createdAt": "2022-08-25T20:56:37.432Z", "updatedAt": "2022-08-25T20:56:37.866Z", "idempotencyKey": "97cfcd40-d9f0-469a-bc7f-b5cda1e2d8ac", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "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": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "074c1ee676ed4998ab66491013c565e2", "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": "713d1e9d-3e05-4258-9c38-d5b474cdca7f", "clientId": "", "merchantId": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "2aba421f-db81-4c2d-a6e8-3379c192a7c5" }, "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": "3973bbb2-21e0-453e-8c2b-09c2234079e4", "createdAt": "2023-11-08T20:02:20.249Z", "updatedAt": "2023-11-08T20:02:20.249Z", "idempotencyKey": null, "providerId": "91850c78-8739-4417-95f4-6a830d10dadc", "providerType": "SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "responseTs": null }, { "id": "3dd57c15-09b2-48b8-825f-848d76f12411", "createdAt": "2023-11-08T20:02:19.984Z", "updatedAt": "2023-11-08T20:02:20.249Z", "idempotencyKey": null, "providerId": "f1370767-28c7-45fb-af45-8163c5d2e6b2", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": null, "fraudAnalysis": { "score": null, "status": "reproved" } }, { "id": "5ac0f30b-7c42-4885-8edd-e75677aadff4", "createdAt": "2023-11-08T20:01:35.769Z", "updatedAt": "2023-11-08T20:01:35.769Z", "idempotencyKey": "6cf90159-9b51-462d-9eeb-010537a28ebc", "providerId": "f1370767-28c7-45fb-af45-8163c5d2e6b2", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "3262306", "amount": 500, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "90ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "7fe317d9-02b0-413e-ad19-17cce732c237", "createdAt": "2023-11-08T20:01:34.157Z", "updatedAt": "2023-11-08T20:01:34.454Z", "idempotencyKey": "6cf90159-9b51-462d-9eeb-010537a28ebc", "providerId": "91850c78-8739-4417-95f4-6a830d10dadc", "providerType": "SANDBOX", "transactionId": "3b0625b8-8947-4c4f-ab5e-852be2394bdd", "amount": 500, "authorizationCode": "2234373", "authorizationNsu": "6727421", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "113ms", "providerAuthorization": { "networkAuthorizationCode": "9761119", "networkResponseCode": "5098365" } } ] } ``` 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` não existe pré-autorização a manter, e o desfecho é definido pelo `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": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "074c1ee676ed4998ab66491013c565e2", "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": "713d1e9d-3e05-4258-9c38-d5b474cdca7f", "clientId": "", "merchantId": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "2aba421f-db81-4c2d-a6e8-3379c192a7c5" }, "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": "8b685a49-7a75-475a-91be-b8d12302aa14", "createdAt": "2023-11-08T20:03:41.481Z", "updatedAt": "2023-11-08T20:03:41.565Z", "idempotencyKey": null, "providerId": "f1370767-28c7-45fb-af45-8163c5d2e6b2", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": null, "amount": null, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "failed", "requestType": "anti_fraud", "responseTs": null, "fraudAnalysis": { "score": null, "status": "failed" } }, { "id": "6f55ec9a-764e-4878-b530-c56869847525", "createdAt": "2023-11-08T20:03:30.962Z", "updatedAt": "2023-11-08T20:03:30.962Z", "idempotencyKey": "447853da-d045-4b5d-901b-e20610570f04", "providerId": "f1370767-28c7-45fb-af45-8163c5d2e6b2", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "4027144", "amount": 500, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "106ms", "fraudAnalysis": { "score": null, "status": "pending" } }, { "id": "93aba631-96fc-4925-8119-f76927ddeadc", "createdAt": "2023-11-08T20:03:28.948Z", "updatedAt": "2023-11-08T20:03:29.756Z", "idempotencyKey": "447853da-d045-4b5d-901b-e20610570f04", "providerId": "91850c78-8739-4417-95f4-6a830d10dadc", "providerType": "SANDBOX", "transactionId": "f967511b-89f3-43ed-91fb-1aa90563d692", "amount": 500, "authorizationCode": "8128049", "authorizationNsu": "7221186", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "301ms", "providerAuthorization": { "networkAuthorizationCode": "8852082", "networkResponseCode": "3142846" } } ] } ``` 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` esse cenário não se aplica, porque a transação já foi capturada. 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 | Option | 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. | apenas em cobranças com `capture: false` | | `captureOnReproved` | Captura a transação mesmo quando o provedor antifraude **reprova**. | apenas em cobranças com `capture: false` | | `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`, 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 | **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. 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. ### 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. 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 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: 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 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 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` | Autorizamos e capturamos de uma vez. A avaliação só pode desfazer o que já foi capturado. | `refundOnReproved`, `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 | Com `capture: true`, as opções `captureOnApproved` e `captureOnReproved` não têm efeito. A transação já foi capturada no adquirente, então o único desfecho que a avaliação de risco ainda pode produzir é o estorno. Se você quer que o resultado do antifraude decida os dois lados, capturar ou não, envie `capture: false`. ## 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 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": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "074c1ee676ed4998ab66491013c565e2", "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": "713d1e9d-3e05-4258-9c38-d5b474cdca7f", "clientId": "", "merchantId": "5002bdcd-e816-4741-871c-6de4f31ea966", "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": "2aba421f-db81-4c2d-a6e8-3379c192a7c5" }, "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": "72e788f6-c767-4688-8b23-4f3c9313458f", "createdAt": "2022-08-25T20:56:37.796Z", "updatedAt": "2022-08-25T20:56:37.796Z", "idempotencyKey": null, "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "SANDBOX", "transactionId": "1737284", "amount": 100, "authorizationCode": "6076640", "authorizationNsu": "3028818", "requestStatus": "success", "requestType": "capture", "responseTs": "8ms", "providerAuthorization": { "networkAuthorizationCode": "7354551", "networkResponseCode": "5759371" } }, { "id": "f4c59668-c513-4e81-a5b2-9988866f3af4", "createdAt": "2022-08-25T20:56:37.645Z", "updatedAt": "2022-08-25T20:56:37.645Z", "idempotencyKey": null, "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "ANTIFRAUD_SANDBOX", "transactionId": "9475312", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "19ms", "fraudAnalysis": { "score": 85, "status": "approved" } }, { "id": "67a55426-defc-4f75-92d0-97f93ef55e39", "createdAt": "2022-08-25T20:56:37.432Z", "updatedAt": "2022-08-25T20:56:37.866Z", "idempotencyKey": "97cfcd40-d9f0-469a-bc7f-b5cda1e2d8ac", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "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": "2f837bc1-9dc5-4683-9610-6e75ed9e5aa5", "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":"074c1ee676ed4998ab66491013c565e2", "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": "72dd8608-3741-48fd-9aab-5573408820fa", "clientId": "", "merchantId": "2f837bc1-9dc5-4683-9610-6e75ed9e5aa5", "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": "4a986611-0534-4628-8c2e-2845a3f6d185" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "id": "c3eb8208-760d-4f21-b54f-70601db69aee", "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": "e03d2e8f-a279-4227-8753-ad7e248e242e", "createdAt": "2022-08-10T19:21:21.910Z", "updatedAt": "2022-08-10T19:21:21.910Z", "idempotencyKey": null, "providerId": "91d0191d-75fa-4abc-bc8b-f2c5d0170ebc", "providerType": "PAGARME_V5", "transactionId": "17979806", "amount": 991, "authorizationCode": "386630", "authorizationNsu": "17979806", "requestStatus": "success", "requestType": "void", "responseTs": "333ms", "providerAuthorization": { "networkAuthorizationCode": "386630", "networkResponseCode": "authorized" } }, { "id": "9e15983b-eb1f-4407-b00f-e28c2a98bd51", "createdAt": "2022-08-10T19:21:21.393Z", "updatedAt": "2022-08-10T19:21:21.393Z", "idempotencyKey": null, "providerId": "8355537a-1d61-4426-aa8e-8905c15a2489", "providerType": "CLEARSALE", "transactionId": "0AE2DE127C8242579EF7D192DC4EAB16", "amount": 991, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "anti_fraud", "responseTs": "1340ms", "fraudAnalysis": { "score": 97, "status": "reproved" } }, { "id": "f3e23e9e-52ff-40e4-b858-cffa32f10622", "createdAt": "2022-08-10T19:21:19.532Z", "updatedAt": "2022-08-10T19:21:21.982Z", "idempotencyKey": "c9b417bd-fd21-42fc-9123-88dcb035449a", "providerId": "91d0191d-75fa-4abc-bc8b-f2c5d0170ebc", "providerType": "PAGARME_V5", "transactionId": "17979806", "amount": 991, "authorizationCode": "386630", "authorizationNsu": "17979806", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "418ms", "providerAuthorization": { "networkAuthorizationCode": "386630", "networkResponseCode": "authorized" } } ] } ``` 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` não existe pré-autorização a manter, e o desfecho é definido pelo `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": "2f837bc1-9dc5-4683-9610-6e75ed9e5aa6", "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": "9b7f2329-5f0b-417d-8e43-022a1057fded", "clientId": "", "merchantId": "2f837bc1-9dc5-4683-9610-6e75ed9e5aa6", "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": "d96fbcae-065e-4cd0-ac1e-b27714618c95" }, "fraudAnalysisMetadata": { "sla": 10, "customer": { "id": "c3eb8208-760d-4f21-b54f-70601db69aee", "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": "52efd018-c005-4b20-b28f-2cf390c794ef", "createdAt": "2022-08-10T19:26:56.388Z", "updatedAt": "2022-08-10T19:26:56.388Z", "idempotencyKey": "11f4bd50-4110-43bf-91e7-28ae8d0d243b", "providerId": "8355537a-1d61-4426-aa8e-8905c15a2489", "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": "65199fff-b961-473a-a75f-2b5717d73089", "createdAt": "2022-08-10T19:26:55.802Z", "updatedAt": "2022-08-10T19:26:56.412Z", "idempotencyKey": "11f4bd50-4110-43bf-91e7-28ae8d0d243b", "providerId": "91d0191d-75fa-4abc-bc8b-f2c5d0170ebc", "providerType": "PAGARME_V5", "transactionId": "17981570", "amount": 991, "authorizationCode": "430210", "authorizationNsu": "17981570", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": "467ms", "providerAuthorization": { "networkAuthorizationCode": "430210", "networkResponseCode": "authorized" } } ] } ``` 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` esse cenário não se aplica, porque a transação já foi capturada. # Testando em Sandbox Source: https://docs.malga.io/documentations/anti-fraud/testing É possível utilizar o provedor de sandbox da Malga para o controle dos resultados de transações de teste com retornos de antifraude. Este controle é feito através do documento de identidade do `customer` enviado junto aos dados de `fraudAnalysis`. O número da identidade pode ser gerado a partir de qualquer gerador de identidades, seguindo a seguinte regra: | Documento | Autorizado? | Status | Declined Code | | - | - | - | - | | Final 0 | NÃO | Pendente | Nulo | | Final 1 | SIM | Aprovado | Nulo | | Final 2 | NÃO | Falha | Aleatório `timeout` ou `processing_error` | | Qualquer outro final | NÃO | Reprovado | Nulo | Para simular o fluxo do antifraude assíncrono, 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 seu provedor antifraude de sandbox você precisa criar um **merchant** utilizando o provedor de transação `"SANDBOX"` e o provedor antifraude `"ANTIFRAUD_SANDBOX"` e determinar o comportamento automático do antifraude utilizando as flags no objeto de `options`. # Exemplo de criação de merchant com sandbox de antifraude ```bash theme={null} curl --location --request POST 'https://api.dev.malga.io/v1/merchants' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw ' { "mcc": "4789", "providers": [ { "name": "sandbox", "priority": 1, "credentials": { "type": "SANDBOX", // Sandbox transactions provider "apiKey": "" } }, { "name": "antifraud_sandbox", "priority": 1, "credentials": { "type": "ANTIFRAUD_SANDBOX", // Sandbox anti-fraud provider "apiKey": "" }, "options": { "type": "ANTIFRAUD", "captureOnError": false, "refundOnError": false, "captureOnApproved": true, "refundOnReproved": true } } ] }' ``` # 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. 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 Listagem de cobranças **Filtros e pesquisas disponíveis para encontrar cobranças:** * Pesquisas em tempo real por **ID da cobrança**, **ID do pedido**, **NSU**, **Documento do cliente**, **Email do cliente** e **4 últimos dígitos do cartão de crédito** * Filtros por **período** (data de criação da cobrança), **método de pagamento**, **provedor**, **status**, **recebedor**, **cobranças com split ou em disputa** e, na visão Empresa, **subconta** 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 Filtros da área de Cobranças Filtros da área de Cobranças em Subconta Filtros da área de Cobranças em Subconta #### Pesquisas na área de cobranças Search Charges Light Search Charges Light #### Exportar cobranças em relatório .csv Export Charge Export Charge 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. No detalhe são exibidas: * **Informações da cobrança:** ID da cobrança (charge ID), ID do pedido (order ID) e método de pagamento * **Detalhes do pagamento:** data de pagamento, valor original e atual, status, provedor responsável, NSU, nome do cliente, número do cartão, entre outros dados de acordo com o método de pagamento * **Detalhes do cliente:** dados do cliente final (pagador), se enviados através do objeto [customer](/api-reference/customers/criacao-de-novo-customer-para-cobranca) * **Detalhes do split:** se a cobrança possuir split, serão exibidos os detalhes dos recebedores associados àquela cobrança * **Detalhes de recorrência:** se a cobrança possuir serviço de recorrência, serão 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 #### Detalhe de uma cobrança Detalhe de uma cobrança Detalhe de uma cobrança EXIBIÇÃO DE CLIENTE E CARTÃO ASSOCIADOS À COBRANÇA Para a visualização dos detalhes do cliente final (pagador) e do cartão, deverá ser feita a integração da nossa [API Customers](/api-reference/customers/criacao-de-novo-customer-para-cobranca) e da [Tokenização de cartões](/api-reference/tokens/criar-um-novo-token) através da Malga. A loja pode optar por não enviar estas informações na cobrança, acarretando 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-transacao). | Status | Descrição | | - | - | | pending | Transação criada porém não concluiu processamento ou ainda não foi paga | | pre\_authorized | Transação pré-autorizada com sucesso pendente da captura | | authorized | Transação autorizada e capturada com sucesso | | failed | Transação não autorizada, verifique o erro para identificar o motivo | | canceled | Transação estornada após aprovada porém não capturada | | voided | Transação estornada após aprovada e capturada | | charged\_back | Transação foi contestada por fraude, não reconhecimento da compra ou devolução | | created | Transação criada que sofreu um erro desconhecido em seu processamento | | capture\_pending | Transação pré-autorizada com requisição de captura em andamento | | refund\_pending | Transação autorizada com requisição de estorno em andamento | #### **Status de acordo com o método de pagamento** | Status | Boleto | Credit | Drip | Nupay | Pix | Voucher | | - | - | - | - | - | - | - | | Authorized | | | | | | | | Canceled | | | | | | | | Capture Pending | | | | | | | | Charged Back | | | | | | | | Created | | | | | | | | Failed | | | | | | | | Pending | | | | | | | | Pre-Authorized | | | | | | | | Refund Pending | | | | | | | | Voided | | | | | | | #### **Alterações no status de cobrança → Estorno e ChargeBack** | Status inicial | Evento na cobrança | Status durante o evento | Status final após o evento | | - | - | - | - | | Pre-Authorized | Estorno completo | Refund\_pending | Canceled | | Authorized | Estorno parcial | Authorized | Authorized | | Authorized | Estorno completo | Refund\_pending | Voided | | Authorized | Abertura de disputa (flag: is dispute) | Authorized | Authorized (disputa encerrada com ganho da loja) | | Authorized | Abertura de disputa (flag: is dispute) | Authorized | 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 | | | 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. ### **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 Estornar e Capturar no Detalhe de Cobrança **Realizando estorno total e parcial:** É possível estornar cobranças dos métodos de pagamento de crédito, pix, Nupay e Drip, de acordo com a [documentação](/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 Estornar Cobrança Após a operação de **Estorno**, a cobrança autorizada terá seu status alterado para **Estornada** e a requisição de estorno bem-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 Detalhes de uma transação após estorno #### Cobrança com status estornada Cobrança com status Estornada Cobrança com status Estornada AMOUNT / ORIGINAL AMOUNT DA COBRANÇA APÓS O ESTORNO O valor original bruto da cobrança **(originalAmount)** corresponde ao valor inicial autorizado na transação, correspondente à venda na loja. Já o atributo valor atual da cobrança **(amount)** é alterado a cada solicitação de estorno parcial, exibindo o saldo residual da cobrança. No histórico de operações de uma **requisição de estorno bem-sucedida**, são exibidos: - Valor atual da cobrança (valor da cobrança no momento da requisição de estorno) - Valor do estorno (valor a ser debitado da cobrança) - Valor restante após o estorno (valor da cobrança após o estorno parcial ou total) **Realizando a captura manual de uma cobrança** No método de crédito, é possível configurar para que a cobrança seja criada com [pré-autorização](/documentations/payment-methods/credit-card#pre-autorizacao-e-captura), necessitando de captura manual (capture: false), que pode ser feita pelo Dashboard ou pela API. No detalhe da cobrança, é possível realizar a **captura parcial** ou **total** da cobrança, conforme o passo a passo: #### Capturar cobrança pré-autorizada Capturar cobrança pré-autorizada Capturar cobrança pré-autorizada STATUS APÓS A CAPTURA PARCIAL OU TOTAL A **cobrança pré-autorizada** pode sofrer uma **captura parcial** ou **total** do seu valor, tendo seu status alterado para “Autorizada” após a confirmação da captura. É possível conferir a requisição de captura bem-sucedida no Histórico de Operações e também consultar o valor bruto e o valor atual, refletidos no detalhe da cobrança. ### Histórico de Operações da cobrança O **Histórico de Operações** é um recurso muito importante no detalhe da cobrança, permitindo a análise e monitoramento dos pagamentos da loja. Nele estão contidos o histórico de eventos ocorridos na transação e seu status, em ordem cronológica pela alteração mais recente, exibindo detalhes de autorização, captura, e outras requisições dos provedores de pagamento e antifraude. É possível obter informações acerca dos serviços de split e recorrência de uma cobrança e também sinalizadores indicando quando uma transação estiver em disputa ou com reversão de estorno. #### Disputa em aberto Disputa aberta Disputa aberta #### Disputa fechada Disputa fechada Disputa fechada ### **Máquina de estados das transações** Dentro do **Histórico de Operações**, cada evento exibido reflete uma **requisição da API Malga** e o **retorno do provedor**, correspondendo a um **tipo de requisição** (request Type), um **status de requisição** (request Status) e um **tempo de resposta da requisição** (response TS). Abaixo apresentamos a **máquina de estados das requisições** e respectivos status exibidos no Histórico do Dashboard: | Requisição / Retorno para o usuário | Sucesso (requisição bem-sucedida) | Em Andamento / Processamento | Falha | Timeout (falhou por tempo excedido) | Erro Interno (falhou por erro interno) | | - | - | - | - | - | - | | Pré-autorização | | | | | | | Autorização | | | | | | | 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 Histórico de Operações de uma cobrança autorizada **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 Histórico de Operações de uma cobrança pela sonda 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. CARACTERÍSTICAS DE UMA COBRANÇA COM ESTORNO FEITO PELA SONDA Detalhe da Cobrança > Histórico de Operações - Possui uma requisição de pré-autorização ou autorização com falha em um provedor - Possui uma requisição de pré-autorização ou autorização bem-sucedida em outro provedor - Possui uma requisição de estorno bem-sucedida em outros provedores, que não o provedor responsável pela cobrança, exibido no detalhe da cobrança - Se pré-autorizada ou autorizada, pode sofrer novo estorno pelo usuário através do Dashboard ou da API ### Identificadores de uma transação na Malga A seguir, apresentamos a descrição dos diferentes **identificadores de uma cobrança** na Malga: **Chaves principais** | Identificador | Origem | Conceito | | - | - | - | | Order ID | Cliente | ID do pedido - Número da cobrança enviado do sistema do cliente para a Malga (envio opcional) | | Charge ID | Malga | ID da cobrança - Refere-se à cobrança criada na Malga e possui várias requisições associadas (transaction request ID) e um transaction ID no provedor (network transaction ID) | | Transaction ID | Provedor | ID da transação - Refere-se à cobrança no provedor (Network Transaction ID), correspondendo ao identificador único da transação retornado pelo provedor, e pode ser usado para recuperar a transação nas APIs ou Dashboard do provedor | | Transaction request ID | Malga | ID da requisição da Malga para o provedor, contendo um request type associado ao tipo da requisição (autorização, estorno, captura etc.) | **Identificadores únicos de cobrança** | Identificador | Origem | Unicidade | Conceito | | - | - | - | - | | Transaction ID (networkTransactionId) | Provedor | Identificador único entre a Malga e o provedor | Identificação única da transação no provedor, gerada dinamicamente, retornado para a Malga | | NSU (authorizationNsu) | Provedor | Identificador único entre o provedor e a Malga | Número sequencial único associado à autorização (Unique sequence number), presente nas cobranças de crédito, voucher e boleto | | Código de autorização (authorizationCode) | Provedor | Identificador único entre o provedor e a Malga, para transação de crédito | Código de autorização retornado pelo provedor, que autoriza especificamente a captura de fundos (método crédito) | | providerReferenceKey (external) | Cliente | Identificador enviado pelo cliente para a Malga e para o provedor | Chave opcional enviada pelo cliente para ser encaminhada ao provedor pela Malga e registrada como identificador adicional.

Se enviada, sobrescreve a idempotency key da cobrança | | Idempotency key (Charge) | Cliente | Identificador único de uma operação | Identificador enviado pelo cliente e pela Malga (chave de referência originadora da transação) | | Idempotency key (Transaction request) | Malga | Identificador de uma requisição | Identificador enviado pela Malga para aquele provedor (chave de referência da requisição) | | Session ID (ID da sessão) | Malga | Identificador de uma cobrança da API Sessions ou Link de Pagamento | Identifica unicamente o pedido associado a esta transação. Este código é normalmente usado para vincular a transação ao item ou serviço específico que foi comprado | CHAVE DE IDEMPOTÊNCIA Confira mais informações sobre a utilização 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 Identificadores no Histórico de Operações *** ### Links e documentações úteis * [Provedores e métodos disponíveis na Malga](/documentations/type-tables/payment-methods-by-providers) * [Monitore sua operação através do Painel de dados](/documentations/dashboard/insights) * [Gerenciando subcontas na Malga](/documentations/dashboard/merchants) * [Exportando dados do Dashboard](/documentations/dashboard/export-data) * [Analytics API](/analytics/intro) SUPORTE MALGA Acione o nosso time através do email [suporte@malga.io](mailto:suporte@malga.io), para dúvidas e mais informações sobre o funcionamento dos recursos do Dashboard e da Malga. # 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 ## 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 Clique no nome da empresa (ou da subconta ativa), no topo do menu lateral. 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. 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**. 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 Através da **Exportação de Cobranças** no [Dashboard Malga](https://dashboard.malga.io/), é possível extrair o arquivo em formato .csv com os detalhes das transações e pagamentos da loja. Acessando o **menu de Cobranças**, através do ícone de exportação na lateral direita da tela, é possível configurar o relatório a ser exportado selecionando: * **Período de criação da cobrança**, equivalente à venda na loja, inserindo a data inicial e final (obrigatório); * **Tipo de relatório**, entre as opções de **relatório** [**simples**](/documentations/dashboard/simple-report) ou [**completo**](/documentations/dashboard/full-report); 🔗(obrigatório); * **Filtros de status da cobrança, método de pagamento e subconta (opcionais);** na visão Empresa, estão disponíveis os filtros de subconta e de recebedor. Na visão de uma subconta, a exportação considera apenas a subconta ativa no seletor de contexto. Após as configurações e a solicitação de exportação, o pedido é recebido pela Malga e, após o processamento, o arquivo é enviado para o e-mail cadastrado no Dashboard, garantindo a segurança das informações. Export Charge Export Charge Além da filtragem em Exportar Cobranças, também é possível realizar a exportação do relatório .csv com os **filtros aplicados através da listagem de Cobranças** (por método, status e, na visão Empresa, subconta e recebedor) ou removê-los na configuração da exportação, refletindo as transações selecionadas; #### Observações * Extrair cobranças de todo o período em que o cliente processou pagamentos na Malga, em range máximo de 6 meses na seleção do filtro de período * Exportação no ambiente de testes do Dashboard, através do menu de Cobranças em sandbox * O arquivo exportado fica disponível por 30 dias em nosso servidor, tendo seu acesso expirado após esse período FILTRO DE PERÍODO DE COBRANÇAS A exportação de cobranças permite a geração de relatórios do tipo simples e completo com o **range máximo de período de até 31 dias** de cobranças realizadas. Cada arquivo .csv gerado possui até 40 mil linhas, com o envio dos links para download no e-mail, visando facilitar a análise gerencial das informações; | 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 e podem ser consultados [aqui](/documentations/dashboard/simple-report) | | Completo | Cobrança, pagamento, recusa, cliente e histórico completo das transações | report type \[transaction\_history] | Contempla todos os dados para análise do histórico de operações e podem ser consultados [aqui](/documentations/dashboard/full-report) | EXEMPLOS DE RELATÓRIO Através dos links abaixo, é possível baixar exemplos dos relatórios e conferir o formato e 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) 🔗 ### Passo a passo para exportar dados pelo Dashboard Faça login no [Dashboard Malga](https://dashboard.malga.io) e acesse a área de [Cobranças](https://dashboard.malga.io/app/charges); Clicando no botão de **Exportar cobranças**, na lateral direita da listagem, é aberto o menu para configuração do relatório com o **filtro de período** e a seleção do **tipo de relatório**; **Selecione o período pela data de criação da cobrança e o tipo de relatório** que deseja exportar, entre o relatório simples (confira os dados deste relatório [aqui](/documentations/dashboard/simple-report) 🔗) e o **relatório completo** (confira os dados disponíveis [aqui](/documentations/dashboard/full-report) 🔗); Caso necessário, utilize os **filtros adicionais opcionais** de status da cobrança, método de pagamento, subconta e recebedor, para configuração do arquivo; Clique em **Solicitar exportação** para confirmar o seu pedido de relatório na Malga; Após o processamento, os arquivos serão **enviados para o e-mail** cadastrado no Dashboard; Acesse sua caixa de e-mail e realize o **download dos arquivos .csv através dos links contidos no e-mail da Malga, com o título** \[Cobranças - período das cobranças exportadas | Malga]; Faça o **download dos arquivos e abra na ferramenta** utilizada para análise e edição da planilha .csv; Caso você realize a exportação com filtros que não retornem cobranças no período indicado (arquivo vazio), enviaremos um e-mail com a orientação para realizar uma nova exportação; Email com o link para download do relatório ENVIO DOS ARQUIVOS POR E-MAIL O **tempo de espera para recebimento dos arquivos no seu e-mail** pode variar, conforme o período selecionado para exportação das cobranças e o tipo de relatório. Informaremos pelo e-mail sobre o processamento da sua solicitação; Caso ainda não possua **acesso ao Dashboard**, realize o [cadastro através link](https://dashboard.malga.io/sign-up), e se precisar de ajuda na configuração da sua conta, acione o nosso time através do [suporte@malga.io](mailto:suporte@malga.io). **Ciclo de vida de uma exportação da API Reports:** # 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 contendo 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, as cobranças são detalhadas em diferentes linhas, onde cada linha corresponde a uma requisição (pré-autorização, autorização, estorno, abertura de disputa, entre outros) ou movimentação na cobrança. Logo, é possível analisar: * Performance dos provedores nos Fluxo Inteligente * Tentativas de autorização * Cobranças com falhas * Dados do cliente * Análise de risco * Operações de estorno * Acompanhamento de disputas Também é possível aplicar filtragens adicionais antes de exportar o relatório, facilitando 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 um relatório simplificado, contendo apenas o último status da cobrança pelo provedor responsável, realize a exportação do relatório do tipo "**Simples**". Você pode consultar os detalhes desse relatório através da nossa documentação. 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). 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. Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo [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 Overview Demo Light 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: Confira as informações gerais do **Painel de dados Malga**, incluindo suas restrições de acesso: * **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ário **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 processamentos 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 Visão geral do Painel de dados Malga 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. **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. **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 Visão métodos de pagamentos e provedores #### 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; **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 Visão geral das cobranças #### 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 Visão geral do Painel de dados Malga Através dos filtros de período, moeda, subconta e 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. **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. 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 Performance ## 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. **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. **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 Taxa de aprovação por retentativa 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. 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 Taxa de aprovação por provedor e por tentativa 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. 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 Cobranças recuperadas 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 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 Histórico de fluxos inteligentes 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 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**. # Subcontas Source: https://docs.malga.io/documentations/dashboard/merchants 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. 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 Detalhe da subconta 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 Detalhe de provedor de um merchant 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. 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 }' ``` Contrato completo do endpoint de criação de subcontas. Contrato completo do endpoint de atualização de subcontas. ## Renomear Subcontas Confira o **passo a passo para nomear as 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. 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 Digite o nome personalizado que deseja atribuir e clique em Salvar 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 Edição do nome da subconta # 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 de cobranças pelo último status, contém também os dados do cliente final, além da recusa no provedor caso tenha ocorrido. Na estrutura deste relatório, cada cobrança é representada por uma linha, sendo possível realizar a **consolidação das vendas** de um período, através de informações como: * Provedor responsável * Último status da cobrança * Análise de risco * Motivos de recusa * Dados do cliente Também é possível aplicar filtragens adicionais antes de exportar o relatório, facilitando 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 um relatório contendo todos os eventos da cobrança representados pelas requisições (transaction requests), com detalhes de pré-autorização, estorno, captura, entre outras, realize a exportação do relatório do tipo "**Completo**". Você pode consultar os detalhes desse relatório na nossa documentação. 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). Caso a exportação de cobranças realizada não contenha informações para as colunas, as mesmas serão suprimidas 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. Caso haja dúvida durante o processo de análise do arquivo, acione o nosso time pelo [suporte@malga.io](mailto:suporte@malga.io) # Usuários e Permissões Source: https://docs.malga.io/documentations/dashboard/users 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. | 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 | | | | | | | 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 Convida usuário 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 Ações na listagem de usuários ### 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. 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 Menu lateral para adição de condicionais 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)** 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 Configuração do condicional de Balanceador, indicando a distribuição de carga #### Card de distribuição de carga Card de distribuição de carga Card de distribuição de carga ### 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 Menu lateral para adicionar condicional de Bandeira #### Adição Visualização do condicional de bandeira no fluxo Visualização do condicional de bandeira no fluxo 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 Condicionais Metadado (número) Drawer Light 3x #### **Tipo número - Adição** Condicionais Metadado (número) Canva Light 3x Condicionais Metadado (número) Canva Light 3x #### **Tipo texto - Configuração** Condicionais Metadado (texto) Drawer Light 3x Condicionais Metadado (texto) Drawer Light 3x #### **Tipo texto - Adição** Condicionais Metadado (texto) Canva Light 3x Condicionais Metadado (texto) Canva Light 3x #### **Tipo booleano - Configuração** Condicionais Metadado (booleano) Drawer Light 3x Condicionais Metadado (booleano) Drawer Light 3x \\ #### **Tipo booleano - Adição** Condicionais Metadado (booleano) Canva Light Condicionais Metadado (booleano) Canva Dark ### 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 Configuração de condicional de Moeda #### Adição Card condicional de Moeda Card condicional de Moeda ### 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 Configuração de condicional de Número de cartão #### Adição Card condicional de Número de cartão Card condicional de Número de cartão ### 6. Parcelas **Conceito**: Utilizar o número da 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 Configuração de condicional de Parcelas #### Adição Card condicional de Parcelas Card condicional de Parcelas ### 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 Configuração de condicional de Valor #### Adição Card condicional de Valor Card condicional de Valor ### 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 Configuração do condicional de Combinações - Operador lógico E #### Operador lógico "E" Configuração do condicional de Combinações - Operador lógico OU Configuração do condicional de Combinações - Operador lógico OU #### Exibição do card combinações Exibição do card combinações no fluxo Exibição do card combinações no fluxo #### Feedback em caso de inserção inválida - Condicionais iguais Feedback em caso de inserção inválida - Condicionais iguais Feedback em caso de inserção inválida - Condicionais iguais #### 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 | 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 Opções de edição do card de provedor de cobrança ou antifraude #### Exclusão Opções de remoção do card de provedor de cobrança ou antifraude Opções de remoção do card de provedor de cobrança ou antifraude ## 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 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 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 Confirmando a exclusão de um card condicional no fluxo # 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 pertencem 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 Modificando a ordem dos provedores ## 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 Utilizando condicionais no fluxo de crédito ## 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 Uso da metadata como condicional para antifraude 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. 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). 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 Fluxo inteligente no Dashboard ### 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 Historic Flow Light 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 Exemplo de Fluxo Inteligente 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 | 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 Exemplo de Distribuição de Carga ## 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`. 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. 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 Botão de iniciar novo fluxo ## 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 Card Dark | | **Provedor antifraude**
**\[1 provedores de antifraude]** | Disponível para crédito
• Clearsale | Card Antifraude Card Antifraude Dark | | **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 Card Conditional Dark | 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 Menu lateral para adição/edição de provedores de cobrança e antifraude do fluxo # 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; 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 Success Light **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 nã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 Confirmação de saída de um fluxo em edição com alterações não publicadas # 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 (vinculados 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 Zoom In | | **Zoom out** | Aplicar zoom para reduzir a visualização | Zoom Out Zoom Out | | **Centralização** | Centralizar a visualização | Centralize Centralize | 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 Seleção de subconta e método de pagamento | botões de criar, histórico e publicar 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 New Flow | | **Histórico** | Consultar histórico de fluxos e restaurar fluxos | History History | | **Publicar fluxo** | Validar e ativar fluxo configurado | Publish Publish | #### 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 Status Active Dark | | **Novo** | Fluxo de pagamentos criado e ainda sem configurações | Status New Status New Dark | | **Em edição** | Fluxo de pagamentos ativo que possui alterações ainda não publicadas pelo usuário | Status Edditing Status Edditing Dark | | **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 Status Restored Dark | ## 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 Elementos visuais para identificação das regras de processamento do fluxo **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 Card Dark | | **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 Retry Dark | | **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 Authorized Dark | | **Distribuição de carga \[condicional]** | Através do [condicional de distribuição de carga](/documentations/flow-guide/introduction#distribuicao-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á direcionado para cada ramificação. | Percentage Percentage Dark | | **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 Yes Dark
No No Dark | | **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 Add New Dark | # 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. 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: 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 Se a sua integração repete o estorno automaticamente, não faça uma nova tentativa antes do horário de `retry_after_at`. Não repita a requisição: a resposta continua sendo `422`, mesmo depois de algum tempo. 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. 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 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 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. 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). 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) 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 Liste os recebíveis disponíveis para antecipação e o valor total disponível. Crie uma simulação informando a data-limite (`endDate`) do período a antecipar. Consulte o histórico paginado das suas simulações e antecipações. Consulte o status e os detalhes de uma simulação ou antecipação. 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). 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 | | 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) Tentativa inicial no dia da fatura Primeira retentativa (1 dia depois) Segunda retentativa (4 dias depois) Terceira retentativa (9 dias depois) Última retentativa (16 dias depois) Você também pode personalizar a estratégia de retentativas através do campo `retryPolicy` 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). 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} { "clientId": "YOUR_CLIENT_ID", "retryPolicy": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 4}, {"daysAfterLastAttempt": 9}, {"daysAfterLastAttempt": 16} ], "statementDescriptor": "MINHA EMPRESA", "cancelAfterAllRetries": false, "createdAt": "2025-01-31T10:00:00Z", "updatedAt": "2025-01-31T10:00:00Z" } ``` ### 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 '{ "retryPolicy": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 3}, {"daysAfterLastAttempt": 7} ], "statementDescriptor": "NOVA EMPRESA", "cancelAfterAllRetries": true }' ``` ```json Response theme={null} { "clientId": "YOUR_CLIENT_ID", "retryPolicy": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 3}, {"daysAfterLastAttempt": 7} ], "statementDescriptor": "NOVA EMPRESA", "cancelAfterAllRetries": true, "createdAt": "2025-01-31T10:00:00Z", "updatedAt": "2025-01-31T15:30:00Z" } ``` ## Conheça os parâmetros O campo `retryPolicy` 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. 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} { "retryPolicy": [ {"daysAfterLastAttempt": 1}, {"daysAfterLastAttempt": 2}, {"daysAfterLastAttempt": 4}, {"daysAfterLastAttempt": 7}, {"daysAfterLastAttempt": 10} ] } ``` Regras de validação: * **Máximo 6 regras** de retry * **Valores crescentes**: Cada regra deve ter mais dias que a anterior * **Valores válidos**: Entre 1 e 30 dias por regra * **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 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 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 Use suas configurações personalizadas na primeira assinatura 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. 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": "6204fc5c-434c-4b7f-a1e1-fbc3e5c55ad4", "name": "Maria Fernanda Souza", "email": "maria.souza@example.com", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "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. 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": "cc0b1e41-2936-45c5-947f-93995ffcdc00" } ``` ### Salvar o Cartão Agora, use o token para salvar o cartão. 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": "cc0b1e41-2936-45c5-947f-93995ffcdc00" }' ``` ```bash Response theme={null} { "id": "4b12023e-9c76-4540-b720-5525066749c8", "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": "4b12023e-9c76-4540-b720-5525066749c8" }' ``` ## Passo 3: Criar a assinatura Agora você pode criar a assinatura recorrente com todos os dados necessários. 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": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5" }, "installments": 1 }, "status": "created", "amount": 29900, "liveMode": true, "createdAt": "2025-07-30T20:14:12.191866Z", "updatedAt": "2025-07-30T20:14:12.606647259Z" } ``` 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", "dayOfMonth": 15 }, "trialEnd": "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", "trialEnd": "2025-02-01", "amount": 9990, "recurrence": { "interval": "monthly", "dayOfMonth": 15, "startAt": "2025-02-01T00:00:00Z", "actualCycle": 0 }, "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) O campo `trialEnd` deve ser uma data 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. ## Próximos passos Agora que sua assinatura está criada, você pode: Saiba como realizar cobranças instantâneas com a assinatura e entenda as suas particularidades. Ative, pause ou cancele a assinatura conforme necessário. 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. Configure períodos de trial gratuito para suas assinaturas. Personalize retentativas e statement descriptors. Configure regras de retentativa personalizadas para suas assinaturas. Revise a documentação completa da API de Subscriptions. 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. **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" } ``` **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

**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 422. 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 422. As mensagens de erro de validação da API são retornadas em inglês (por exemplo, em caso de falha com HTTP 422). ### 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 422 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 validação de **data** é **independente** de `startAt`: `scheduledCancellationAt` deve estar **no mínimo um dia no futuro** em relação à data atual (comparação por calendário). Detalhes em [Cancelamento agendado — Validações implementadas](/documentations/more/recurrence/engine/scheduled-cancellation#validacoes-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| err422a(["422: 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| err422b(["422: 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 err422a fill:#7f1d1d,stroke:#ef4444,color:#fee2e2 style err422b 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 Aprenda como gerenciar assinaturas após a criação 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 `trialEnd` após criação * ⚠️ **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 **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 Atualize uma assinatura recorrente com os métodos de pagamento disponíveis na Malga. Ao alterar `cycles`, o novo valor **não pode** ser menor do que a quantidade de faturas já cobradas. Pause uma assinatura recorrente. Configure regras de retentativa personalizadas para suas assinaturas. Configure notificações em tempo real sobre mudanças de status. Retomar uma assinatura recorrente. Cancelar uma assinatura recorrente. 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. **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. **`trialEnd`** (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 trialEnd] 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 (trialEnd 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 `trialEnd` 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`, `trialing`, `created` ou `unpaid` * A assinatura não está já cancelada (`canceled`) ou expirada (`expired`) * A data de cancelamento (se especificada) está **pelo menos um dia no futuro** em relação à data atual usada na validação (comparação por calendário) ### Validações Implementadas * **`scheduledCancellationAt` (data mínima)**: Se fornecido, deve ser **no mínimo o dia seguinte** à data atual usada na validação (comparação por calendário **YYYY-MM-DD**; **hoje** e datas passadas são rejeitadas). Essa regra **não** é a mesma da validação de `recurrence.startAt` em [Cobrança instantânea](/documentations/more/recurrence/engine/instant-payment#startat-atualizacao-scheduler), onde `startAt` admite outra janela (até um dia no passado). * **`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 > trialEnd > nextDueDate` garante comportamento previsível: * **Assinatura em trial com data específica**: Se `scheduledCancellationAt` for anterior a `trialEnd`, o cancelamento ocorrerá na data especificada (antes do fim do trial) * **Assinatura sem trial**: Se não houver `trialEnd`, 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. 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-subscriptioncancelation_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-subscriptioncancelation_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-subscriptioncanceled). ## 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 `trialEnd` como data efetiva * Se `scheduledCancellationAt` for fornecido, tem prioridade sobre `trialEnd` * 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 `trialEnd` se `scheduledCancellationAt` não fornecido | | `created` | ✅ Sim | Cancelamento ocorre antes da primeira cobrança | | `unpaid` | ✅ Sim | Cancelamento ocorre na data efetiva | | `paused` | ❌ Não | Assinatura pausada não pode ter cancelamento agendado | | `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 Aprenda como gerenciar assinaturas durante e após o período de trial 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": "31c142ad-4c30-4964-ba24-2df0f2bbb745", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "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: 5616b19e-4d99-4bd3-b415-4990e5cab4f4 > X-Plug-Date: 1660053072711 > X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75 > HTTP/2 { "id": "019a362f-f69c-7789-b535-7051a0031bbe", "apiVersion": "1.1", "object": "subscription", "event": "created", "data": { "subscription": { "id": "019a362f-f69c-7789-b535-7051a0031bbe", "name": "Test Subscription for Events", "clientId": "e0d26950-541b-4b28-b4ec-a95fb61f1a0d", "merchantId": "3e452afd-4b0f-4d11-87bb-6ad3345709d7", "customerId": "a3994087-d867-4c30-8b07-fe0a2f3db77b", "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": "5e334112-6f22-4c31-8e24-2f89ff77e21c" } }, "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": "5616b19e-4d99-4bd3-b415-4990e5cab4f4", "apiVersion": "1.1", "object": "subscription", "event": "created", "createdAt": "2021-07-05T18:56:08.672Z", "data": { "subscription": { "id": "01985cf8-96df-7d37-b17c-a9985a1e78bb", "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": "019a362f-f69d-70b7-bb30-a86b6e1cb687", "apiVersion": "1.1", "object": "subscription", "event": "trial_started", "data": { "subscription": { "id": "019a362f-f69d-70b7-bb30-a86b6e1cb687", "name": "Test Subscription for Events", "clientId": "15af5e05-c807-4f33-8d74-5c3e2aded5be", "merchantId": "bf9e5b23-8223-4445-b6b0-8af2ea6c02fe", "customerId": "c6b8d0a1-37e0-420f-aeb2-4ef0c2758e52", "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": "f6c9e6b2-d164-461c-afb3-c8093270e2b1" } }, "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": "019a353e-bae2-7e5f-96e3-c0eab8681652", "apiVersion": "1.1", "object": "subscription", "event": "activated", "data": { "subscription": { "id": "019a353e-bae2-7e5f-96e3-c0eab8681652", "name": "Assinatura Premium com Eventos", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0", "customerId": "2a8b64ce-904c-4256-b79a-49525808609c", "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": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T13:11:34.882942Z", "updatedAt": "2025-10-30T13:11:35.921247966Z" }, "cycle": { "id": "019a353e-bafa-774b-9664-8217b3d19da6", "customerId": "2a8b64ce-904c-4256-b79a-49525808609c", "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0", "cycle": 1, "status": "authorized", "amount": 29900, "scheduledAt": "2025-10-30", "paymentHistory": [ { "id": "d6738023-a45c-4d58-a303-456da757cca6", "createdAt": "2025-10-30T13:11:34.917233965Z", "executedAt": "2025-10-30T13:11:34.905674924Z", "chargeId": "fe703f43-8f77-4780-80d1-b1c4ad44db6c", "attemptNumber": 1, "paymentMethod": { "type": "credit", "card": { "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5" }, "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": "a1ec4c84-8d10-4cb8-b390-f7ae1f204638", "apiVersion": "1.1", "object": "subscription", "event": "unpaid", "data": { "subscription": { "id": "a1ec4c84-8d10-4cb8-b390-f7ae1f204638", "name": "Premium Subscription", "clientId": "a2a780a7-1f53-4766-88f9-85facc7ef0a3", "merchantId": "ad2c70ac-e1a5-4921-a0a5-b264d8bb5045", "customerId": "8b4b0bbe-3cf1-4fd4-95b5-b2700321fdc3", "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": "dbacd004-124f-40e4-80f7-655122a08355" }, "installments": 1 }, "status": "unpaid", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T18:05:30.401145Z", "updatedAt": "2025-10-30T18:05:30.401145Z" }, "cycle": { "id": "fc532536-9862-40e5-9613-2df214ae9b36", "customerId": "8b4b0bbe-3cf1-4fd4-95b5-b2700321fdc3", "merchantId": "ad2c70ac-e1a5-4921-a0a5-b264d8bb5045", "cycle": 1, "status": "failed", "amount": 29900, "scheduledAt": "2025-10-31", "paymentHistory": [ { "id": "db137d73-d1e8-4830-8d56-e8e793541cfb", "createdAt": "2025-10-30T18:05:30.401145Z", "executedAt": "2025-10-31T19:05:30.401145Z", "chargeId": null, "attemptNumber": 5, "paymentMethod": { "type": "credit", "card": { "cardId": "dbacd004-124f-40e4-80f7-655122a08355" }, "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": "ddb07491-4992-45d4-abac-bef72c6806a9", "apiVersion": "1.1", "object": "subscription", "event": "expired", "data": { "subscription": { "id": "ddb07491-4992-45d4-abac-bef72c6806a9", "name": "Premium Subscription", "clientId": "3398028c-382d-4ab5-bcf9-67c8588a00e6", "merchantId": "fd401e88-bdd3-4325-af08-27f06293f114", "customerId": "5fc705b1-1114-496a-af6f-a645161bbe9b", "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": "4b56baed-66e8-4972-bc63-cf2d85fddf2c" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T17:35:04.349231Z", "updatedAt": "2025-10-30T17:35:04.349231Z" }, "cycle": { "id": "b4159786-1c9e-4ae7-b30c-0b4d138b4d48", "customerId": "5fc705b1-1114-496a-af6f-a645161bbe9b", "merchantId": "fd401e88-bdd3-4325-af08-27f06293f114", "cycle": 1, "status": "authorized", "amount": 29900, "scheduledAt": "2025-10-31", "paymentHistory": [ { "id": "cd613dd4-1403-4ff1-ad00-9d35e0da8525", "createdAt": "2025-10-30T17:35:04.349231Z", "executedAt": "2025-10-31T18:35:04.349231Z", "chargeId": "1a9ab4ee-9ec5-4b36-a592-cc3d9933a1fa", "attemptNumber": 1, "paymentMethod": { "type": "credit", "card": { "cardId": "4b56baed-66e8-4972-bc63-cf2d85fddf2c" }, "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": "019a362f-f69d-7461-9ad9-738cca7b896d", "apiVersion": "1.1", "object": "subscription", "event": "canceled", "data": { "subscription": { "id": "019a362f-f69d-7461-9ad9-738cca7b896d", "name": "Test Subscription for Events", "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408", "merchantId": "f441fdec-230a-41e3-b954-c222398e052e", "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150", "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": "3d655e9d-a4f8-4534-bf10-ec4ace54439d" } }, "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": "019a362f-f69d-7461-9ad9-738cca7b896d", "apiVersion": "1.1", "object": "subscription", "event": "canceled", "data": { "subscription": { "id": "019a362f-f69d-7461-9ad9-738cca7b896d", "name": "Test Subscription for Events", "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408", "merchantId": "f441fdec-230a-41e3-b954-c222398e052e", "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150", "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": "3d655e9d-a4f8-4534-bf10-ec4ace54439d" } }, "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": "019a362f-f69d-7461-9ad9-738cca7b896d", "apiVersion": "1.1", "object": "subscription", "event": "cancelation_scheduled", "data": { "subscription": { "id": "019a362f-f69d-7461-9ad9-738cca7b896d", "name": "Test Subscription for Events", "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408", "merchantId": "f441fdec-230a-41e3-b954-c222398e052e", "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150", "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": "3d655e9d-a4f8-4534-bf10-ec4ace54439d" } }, "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": "019a362f-f69d-7461-9ad9-738cca7b896e", "apiVersion": "1.1", "object": "subscription", "event": "cancelation_scheduled_removed", "data": { "subscription": { "id": "019a362f-f69d-7461-9ad9-738cca7b896d", "name": "Test Subscription for Events", "clientId": "db33d3a9-5092-47ed-9672-100dd2d36408", "merchantId": "f441fdec-230a-41e3-b954-c222398e052e", "customerId": "fb6730f8-f8c5-4e86-8cb3-65df5eee8150", "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": "3d655e9d-a4f8-4534-bf10-ec4ace54439d" } }, "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 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": "019a362f-f69d-7b04-adbc-12cb755d371e", "apiVersion": "1.1", "object": "subscription", "event": "paused", "data": { "subscription": { "id": "019a362f-f69d-7b04-adbc-12cb755d371e", "name": "Test Subscription for Events", "clientId": "9ae1968f-d520-4045-8f84-ca982556084a", "merchantId": "a2cf2027-7821-4c10-a102-dc9024de7b9a", "customerId": "def4804e-3fcb-443d-b34a-132402f74bbc", "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": "8e3870d6-8c59-41c6-bfdb-7bd82cee64a4" } }, "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": "019a362f-f69d-7dda-af2e-6f95dbca0513", "apiVersion": "1.1", "object": "subscription", "event": "resumed", "data": { "subscription": { "id": "019a362f-f69d-7dda-af2e-6f95dbca0513", "name": "Test Subscription for Events", "clientId": "e58a463e-1bdf-4583-b067-9a926841c442", "merchantId": "e96d4f07-77a4-4ee1-8223-a0fc0501745d", "customerId": "7e71982d-246b-4b7b-9cee-05007d88dcf5", "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": "49bc7302-ca69-4f17-a235-8e40337e90cd" } }, "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": "019a362f-f69d-7f0f-a9fa-ef1979ebdd7f", "apiVersion": "1.1", "object": "subscription", "event": "updated", "data": { "subscription": { "id": "019a362f-f69d-7f0f-a9fa-ef1979ebdd7f", "name": "Test Subscription for Events", "clientId": "e4ca93ec-4d9e-42be-a80a-4702b0c9c0d4", "merchantId": "4ce78ca0-bd7b-4c5a-bd95-2fe356f8897d", "customerId": "ed5f23e5-0bdb-492f-9536-7e4475c76ae6", "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": "3e7e4644-4622-4acb-a387-23a214a3e5d6" } }, "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": "aa0e8400-e29b-41d4-a716-446655440000" } }, "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: **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": "5616b19e-4d99-4bd3-b415-4990e5cab4f4", "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: 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. 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). 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. 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": "c1db83fa-723c-4e1f-9722-bc19d1be6791", "name": "Pedido 1", "status": "created", "isActive": true, "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1", "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/c1db83fa-723c-4e1f-9722-bc19d1be6791", "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": "8be71cdf-01dc-4b1a-823a-4c58be6e4cf1" } ``` 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": "148d5db0-f1c3-439f-902d-f1f268086e1d", "status": "pending", "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1", "orderId": "b84b7694-d22f-4083-bee7-c1274b16eb4a", "customerId": "eb70b146-85fd-4100-8fd4-a4dbb647aed3", "amount": 100, "originalAmount": 100, "currency": "BRL", "capture": true, "merchantId": "9930c8d9-a7a8-4039-9faf-3715ad87baf8", "statementDescriptor": "LOJA JOAO", "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d" }, "transactionRequests": [ { "id": "78601913-a176-4d71-b7e8-abb6fc49a340", "idempotencyKey": "fafe857b176e45d6b12e32fcaf228996", "providerId": "2c3b57d8-ee43-4b19-bc8a-949a88c51df1", "providerType": "STRIPE", "transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob", "amount": 100, "authorizationNsu": "1cc8391c-f0d5-4b7a-9fcf-653cea26be13", "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. | 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`. 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. 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. 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 Garanta que seu merchant tenha suporte a 3DS2 Malga. Saiba mais [**aqui**](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao). Adicione um novo fluxo inteligente dentro do seu merchant para processar as transações com 3DS2. 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. Indica se o 3DS2 está habilitado para o método de pagamento 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": "b1d0b4b4-c4c6-41df-ac24-07a21228187d", "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/b1d0b4b4-c4c6-41df-ac24-07a21228187d", "createdAt": "2025-11-24T09:41:10.129Z", "updatedAt": "2025-11-24T09:41:10.129Z", "publicKey": "a09605bb-8e2c-4474-a653-7c3c9dca0ce1", "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. ## 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.mdx). 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. 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": "1a349417-5f01-45b1-8b49-977af564ff0b", "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": "5f9c9d1e-1c17-4c65-9e0e-1a4a1a2b3c4d", "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": "b1a9e0d7-2f4c-4d31-9f82-7c1b0e3d5a12", "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/1a349417-5f01-45b1-8b49-977af564ff0b", "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": "522cc99e-6ae3-45d2-9cc3-a8ebc4e8cbc3" } ``` ## 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`. 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": "1a349417-5f01-45b1-8b49-977af564ff0b", "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": "5f9c9d1e-1c17-4c65-9e0e-1a4a1a2b3c4d", "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": "b1a9e0d7-2f4c-4d31-9f82-7c1b0e3d5a12", "name": "Caneca \"Code & Coffee\"", "description": "Caneca de cerâmica para café, com estampa personalizada.", "unitPrice": 4500, "quantity": 1, "tangible": false, "categoryId": null }, { "id": "c8d3e0a1-9b6f-4a25-8e73-42d1f6b2c9e0", "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/1a349417-5f01-45b1-8b49-977af564ff0b", "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": "522cc99e-6ae3-45d2-9cc3-a8ebc4e8cbc3" } ``` 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). 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 Saiba como é simples e rápido criar links através do nosso dashboard Tela de criação de link com o controle de limite de pagamentos habilitado Tela de criação de link com o controle de limite de pagamentos habilitado 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.mdx) a lista de tipos aceitos. 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 Campos opcionais da criação de link: descrição, ID do pedido, validade e quantidade de pagamentos ### 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.mdx). * **Tipo de divisão:** indica se será definido em % ou R\$. * [**Recebedor:**](/documentations/split/seller.mdx) 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. 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 Detalhes de um Link 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 informada. 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á mostrado todos os dados da requisição feitas pelo cliente, seguidos da data e hora. 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 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 | | 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. Saiba como criar um Link de Pagamento via API. Saiba como criar um Link de Pagamento via Dashboard. Saiba como configurar o tema personalizado para o Link de Pagamento. Saiba como configurar o 3DS2 Agnóstico para o Link de Pagamento. 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 Detalhes da personalização ## 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": "df601922-e024-6394-8f12-af21ec4218b1" } ``` 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' ``` 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 entre 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. * 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 | | - | - | - | - | - | | Zoop | | | | | | Pagarme V5 | | | | | | PagSeguro | | | | | | Braspag | | | | | | 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$`. **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. 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": "1a349417-5f01-45b1-8b49-977af564ff0b", "paymentLink": "https://link.malga.io/1a349417-5f01-45b1-8b49-977af564ff0b", "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 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 2. Selecione a opção "Merchant IDs":Apple Developer Account 3. Preencha os campos "Description" e "Identifier":Apple Developer Account 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 3. Selecione o identifier criado anteriormente:Apple Developer Account 4. Na seção "Apple Pay Payment Processing Certificate", clique no botão "Create Certificate":Apple Developer Account 5. Escolha a opção "No" em "Edit or Configure Merchant ID":Apple Developer Account 6. Em "Choose File", faça upload do certificado ".CSR" gerado anteriormente:Apple Developer Account 7. Clique em "Continue" e depois em "Download" para baixar o certificado de pagamento: Apple Developer Account ## 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 2. Selecione o identificador do seu merchant:Apple Developer Account 3. Em "Merchant Domains", clique em "Add Domain":Apple Developer Account 4. Preencha o domínio e clique em "Save":Apple Developer Account 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 ## 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 2. Selecione o identificador do seu merchant:Apple Developer Account 3. Em "Apple Pay Merchant Identity Certificate", clique em "Create Certificate":Apple Developer Account 4. Em "Choose File", faça upload do certificado ".CSR" gerado e clique em "Continue":Apple Developer Account 5. Baixe o certificado de identificação do merchant gerado em "Download":Apple Developer Account # 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). ```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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "10ad53ec-76bb-41d2-a0fe-7513f8f50a8f", "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "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": "148d5db0-f1c3-439f-902d-f1f268086e1d" }, "transactionRequests": [{ "id": "5e506984-318a-4390-b87a-a3bd9b91d357", "updatedAt": "2021-03-23T15:12:42.799Z", "createdAt": "2021-03-23T15:12:38.392Z", "idempotencyKey": "4271e96e-8c2f-4857-a122-279613bc4747", "requestId": null, "providerId": "72cc1ff1-5f6e-4eb2-9cc5-6a3a85525e4b", "providerType": "CIELO", "amount": 150, "authorizationCode": "", "authorizationNsu": "1616512362092", "responseCode": "20000", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": null }] } ``` 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 é pre-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 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ário 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), 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. 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. Comece agora mesmo a usar Apple Pay na Malga Confira a lista de provedores que suportam cobranças Apple Pay Configure o fluxo inteligente para cobranças com Apple Pay # Boleto Source: https://docs.malga.io/documentations/payment-methods/boleto 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. **A Malga não cancela boleto automaticamente no vencimento.** Um boleto vencido permanece com status `pending` até que o provedor nos notifique. Alguns provedores enviam essa notificação e outros não, então o comportamento varia conforme o provedor configurado no seu fluxo. Isso é intencional: boleto é pago com frequência depois da data de vencimento, e cancelar no vencimento descartaria pagamentos legítimos. Use a data que você enviou em `expiresDate` como referência na sua conciliação, em vez de esperar uma mudança de status. Quando o cancelamento acontece, o status da cobrança passa a ser `canceled`, nunca `failed`. O status `failed` indica que a cobrança foi negada no momento da criação, antes de existir um boleto pagável. Não é possível realizar estorno para pagamentos do tipo Boleto, também não existe pré-autorização ou captura de cobranças deste tipo. ## Notificação de alteração de status | objeto | evento | descrição | | - | - | - | | *transaction* | *pending* | Evento enviado quando a cobrança é registrada e os dados para pagamento estão disponíveis | | *transaction* | *authorized* | Evento enviado quando é reconhecida a confirmação do pagamento da cobrança | | *transaction* | *failed* | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro | É possível que o valor de pagamento de um boleto com status *authorized* seja diferente do valor original de emissão do mesmo, como em caso de juros ou multa sendo aplicados. Sempre verifique o campo `amount` informado nas atualizações de transações para confirmar o valor pago. ## Testando recebimento de notificação de boleto pago Para testar sua integração com os webhooks da Malga, você pode desenvolver direto o seu sistema ou utilizar algum serviço como [request.bin](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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "148d5db0-f1c3-439f-902d-f1f268086e1d", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "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": "1cdcf0c9-eb04-4e43-b9b2-b7a4acdead1f" } } ``` # 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": "223efa95-a0bc-43d6-aea9-715281b6b062", "correlationId": "34f4a04b.a54a46e6-dc2d-4ec3-8b2f-babc2280720b", "flowId": "34f4a04b.a54a46e6-dc2d-4ec3-8b2f-babc2280720b.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 Crie sessões (links) de pagamento que oferecem Click to Pay automaticamente Use Click to Pay diretamente pela API de cobranças 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. 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 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 ## 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="223efa95-a0bc-43d6-aea9-715281b6b062"' ``` ### 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="223efa95-a0bc-43d6-aea9-715281b6b062"' ``` 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": "223efa95-a0bc-43d6-aea9-715281b6b062" }' ``` > **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. 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. 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. # Cartão de crédito Source: https://docs.malga.io/documentations/payment-methods/credit-card 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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "10ad53ec-76bb-41d2-a0fe-7513f8f50a8f", "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "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": "148d5db0-f1c3-439f-902d-f1f268086e1d" }, "transactionRequests": [{ "id": "5e506984-318a-4390-b87a-a3bd9b91d357", "updatedAt": "2021-03-23T15:12:42.799Z", "createdAt": "2021-03-23T15:12:38.392Z", "idempotencyKey": "4271e96e-8c2f-4857-a122-279613bc4747", "requestId": null, "providerId": "72cc1ff1-5f6e-4eb2-9cc5-6a3a85525e4b", "providerType": "STRIPE", "amount": 150, "authorizationCode": "", "authorizationNsu": "1616512362092", "responseCode": "20000", "requestStatus": "success", "requestType": "pre_authorization", "responseTs": null }] } ``` ## Pré-autorização e captura 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. 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). 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. 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-notificacao-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 que a operação foi realizada com sucesso.** 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, com todas as letras em maiúsculo. 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 Fluxo Drip com Checkout Você pode consultar mais informações sobre a integração com checkout [neste link](/sdks/intro-sdk). 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). 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": "d749c775-5c61-448e-9ed4-36b67d085301", "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": "074c1ee676ed4998ab66491013c565e2" }, "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": "c1248092-1769-4b93-9b1d-fabcec356c6c", "clientId": "", "merchantId": "d749c775-5c61-448e-9ed4-36b67d085301", "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/0f6aa94e-8593-4662-bddd-7bfce2d4c935", "items": [ { "id": "123", "quantity": 1, "title": "item title", "unitPrice": 100 } ], "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "074c1ee676ed4998ab66491013c565e2" }, "successRedirectUrl": "http://your-service.com/success", "cancelRedirectUrl": "http://your-service.com/cancel" }, "paymentSource": { "sourceType": "customer", "customerId": "4362a975-9cc7-418f-918b-8ee9585f604e" }, "transactionRequests": [ { "id": "449043d9-dc7c-4456-bf58-d8d9a53f15bf", "createdAt": "2023-07-18T23:03:53.048Z", "updatedAt": "2023-07-18T23:03:55.501Z", "idempotencyKey": "9baef27a-9897-4541-9d84-d61b65ffe6fe", "providerId": "769bce00-678e-4d64-9617-9ce82f4dfcbf", "providerType": "DRIP", "transactionId": "9baef27a-9897-4541-9d84-d61b65ffe6fe", "amount": 100, "authorizationCode": "f03a3928-460e-42b3-8ece-76cdfdcb5924", "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "2436ms", "drip": { "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/0f6aa94e-8593-4662-bddd-7bfce2d4c935", "items": [ { "id": "123", "quantity": 1, "title": "item title", "unitPrice": 100 } ], "browser": { "ipAddress": "127.0.0.1", "browserFingerprint": "074c1ee676ed4998ab66491013c565e2" }, "successRedirectUrl": "http://your-service.com/success", "cancelRedirectUrl": "http://your-service.com/cancel" } } ] } ``` 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": "7e4930f0-b23c-4378-a3ab-4db684434ded", "clientId": "", "merchantId": "d749c775-5c61-448e-9ed4-36b67d085301", "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/61cad747-7bc3-41b0-a3c5-6a127eacd790", "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": "17491cfe-9952-40a9-a56f-c087be2ea693" }, "transactionRequests": [ { "id": "3a93edd9-473c-48dd-9b04-62c04d7a3d62", "createdAt": "2023-07-26T12:40:32.489Z", "updatedAt": "2023-07-26T12:40:32.489Z", "idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e", "providerType": "DRIP", "transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "amount": 1200, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "responseTs": "460ms" }, { "id": "06e955f6-b648-4fdd-b9a8-84c1c75d0f26", "createdAt": "2023-07-26T12:26:53.557Z", "updatedAt": "2023-07-26T12:26:53.557Z", "idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e", "providerType": "DRIP", "transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "amount": 1200, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null }, { "id": "72abedb9-ed78-49d3-98c9-2a83ab59f827", "createdAt": "2023-07-26T12:26:03.998Z", "updatedAt": "2023-07-26T12:26:04.717Z", "idempotencyKey": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "providerId": "07fc7b49-6f27-42c4-b610-ba69af41403e", "providerType": "DRIP", "transactionId": "d9160c55-000d-41b4-a6cd-0e2a4dd6439f", "amount": 1200, "authorizationCode": "cd3a3d65-d096-4c4c-aef0-abd71b70b49b", "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "627ms", "drip": { "paymentUrl": "https://sandbox-portal.dripapp.com.br/checkouts/61cad747-7bc3-41b0-a3c5-6a127eacd790", "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-notificacao-de-cobranca-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 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 QRCode 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 parcelando 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. 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. 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. | 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. 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": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "orderId": "pedido-1001", "payments": [ { "amount": 10000, "paymentMethod": { "paymentType": "credit", "installments": 1 }, "paymentSource": { "sourceType": "card", "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "cardCvv": "123" } }, { "amount": 5000, "paymentMethod": { "paymentType": "credit", "installments": 3 }, "paymentSource": { "sourceType": "token", "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09" } } ] }' ``` A resposta `202` traz a Venda com `status: pending` e a operação `authorize` em andamento: ```json Resposta 202 theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "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": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, { "slotIndex": 1, "amount": 5000, "paymentMethod": { "paymentType": "credit", "installments": 3 }, "status": "pending", "refundedAmount": 0, "paymentSource": { "sourceType": "token", "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09" } } ], "operation": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "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. 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 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": "d5b792ba-4d76-46b4-a94d-c7ddae75cf9e", "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": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1", "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d", "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176", "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": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f" }, "transactionRequests": [ { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "NUPAY", "transactionId": "2c57caad-136d-4bc4-a265-c72d408d5ef8", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "pending", "responseTs": "1084ms", "nupay": { "expiresIn": 200 } } ] } ``` 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: `"550e8400-e29b-41d4-a716-446655440000"`. #### `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": "d5b792ba-4d76-46b4-a94d-c7ddae75cf9e", "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": "550e8400-e29b-41d4-a716-446655440000", "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 ## 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": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1", "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d", "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176", "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": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f" }, "transactionRequests": [ { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "NUPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "1123ms", "nupay": { "refundId": "72cecc64-2079-4128-8cb0-c5a4ed8fa444" } }, { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "NUPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null, "nupay": { "installmentsNumber": 1, "paymentType": "spintest-link" } }, { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "NUPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "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 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": "d5b792ba-4d76-46b4-a94d-c7ddae75cf9e", "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": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1", "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d", "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176", "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": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f" }, "transactionRequests": [ { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2024-08-10T21:33:42.969Z", "updatedAt": "2024-08-10T21:33:44.105Z", "idempotencyKey": "2c57caad-136d-4bc4-a265-c72d408d5ef8", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "43a107b3", "transactionId": "2c57caad-136d-4bc4-a265-c72d408d5ef8", "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 ## 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": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1", "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d", "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176", "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": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f" }, "transactionRequests": [ { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "PICPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "1123ms" }, { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "PICPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "amount": 100, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": null }, { "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7", "createdAt": "2022-09-30T21:33:42.969Z", "updatedAt": "2022-09-30T21:33:44.105Z", "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b", "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "providerType": "PICPAY", "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995", "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 sessã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" }' ``` # Pix 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). 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 | É 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. 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`. 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 ## Provedores suportados para estorno de Pix | Provedor | Estorno total | Estorno parcial | | - | :-: | :-: | | Mercado Pago | | | | Pagar.me v5 | | | | BS2 | | | | Banco do Brasil | | | | Zoop | | | | PagSeguro | | | | Adyen | | | | 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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "148d5db0-f1c3-439f-902d-f1f268086e1d", "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": "1cdcf0c9-eb04-4e43-b9b2-b7a4acdead1f" } } ``` ## 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": "1484a29e-4208-42cb-ba03-f9839b98690e", "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "52a20b27-caae-4875-b455-a66f0fddcfc1" }, "transactionRequests": [ { "id": "4c379644-50b2-44e4-af03-62fbfaebc94a", "createdAt": "2022-09-08T15:29:26.950Z", "updatedAt": "2022-09-08T15:29:26.950Z", "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "MERCADO_PAGO", "transactionId": null, "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "713ms" }, { "id": "8742b17c-47d6-464a-968e-e3f2a99eaffd", "createdAt": "2022-09-08T15:28:48.199Z", "updatedAt": "2022-09-08T15:28:48.199Z", "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "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": "21fa762b-8634-4129-a25d-e8c8bdb64cb1", "createdAt": "2022-09-08T15:27:45.893Z", "updatedAt": "2022-09-08T15:27:52.406Z", "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "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":"1484a29e-4208-42cb-ba03-f9839b98690e", "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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "capture":true, "isProcessing":false, "customerId":null, "description":null, "fee":null, "feeAmount":null, "transactionRequests":[ { "id":"21fa762b-8634-4129-a25d-e8c8bdb64cb1", "updatedAt":"2022-09-08T15:27:52.406Z", "createdAt":"2022-09-08T15:27:45.893Z", "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6", "requestId":null, "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd", "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": "4c379644-50b2-44e4-af03-62fbfaebc94a", "createdAt": "2022-09-08T15:29:26.950Z", "updatedAt": "2022-09-08T15:29:26.950Z", "idempotencyKey": "261fccac24c1412f9d23d5eab73418c6", "providerId": "5de239ec-b724-453a-96e1-229fe29cdedd", "providerType": "MERCADO_PAGO", "transactionId": null, "amount": 150, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "processing", "requestType": "void", "responseTs": "713ms" }, { "id":"8742b17c-47d6-464a-968e-e3f2a99eaffd", "updatedAt":"2022-09-08T15:28:48.199Z", "createdAt":"2022-09-08T15:28:48.199Z", "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6", "requestId":null, "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd", "providerType":null, "networkTransactionId":null, "amount":150, "authorizationCode":null, "authorizationNsu":null, "requestStatus":"success", "requestType":"authorization", "responseTs":null, "pix":{ "id":"71808df4-327f-493e-a046-48489b71e356", "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":"88f28d71-a64b-42f3-ac57-1cecbbaf1bb4", "updatedAt":"2022-09-08T15:31:13.488Z", "createdAt":"2022-09-08T15:31:13.488Z", "idempotencyKey":"261fccac24c1412f9d23d5eab73418c6", "requestId":null, "providerId":"5de239ec-b724-453a-96e1-229fe29cdedd", "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`. Não é possível realizar o *estorno parcial* no provedor VR. ## Exemplo de transação do voucher realizada com sucesso 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": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "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": "97443bea-fb76-43c2-afb1-2cb45abbe673", "clientId": "", "merchantId": "", "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "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": "e18cf62e-aa43-4db5-abfe-0f63e2749fef", "createdAt": "2023-07-17T19:46:08.627Z", "updatedAt": "2023-07-17T19:46:10.861Z", "idempotencyKey": "5b011a93-2eaf-4b9c-9f22-f3676c7cba74", "providerId": "56a83eaf-f9b2-4d2e-97f3-53933331b0e5", "providerType": "SANDBOX", "transactionId": "f4ae4d32-350d-4135-9b50-b259e937ca03", "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": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "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": "ef19739f-953b-488e-b653-623b80a88392", "clientId": "", "merchantId": "", "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "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": "e6cad844-ae11-44ab-a83d-e1abfe10ac5c", "createdAt": "2023-07-17T22:09:53.542Z", "updatedAt": "2023-07-17T22:09:55.048Z", "idempotencyKey": "8ef45126-2faa-487c-9367-e8722f5d0d6c", "providerId": "56a83eaf-f9b2-4d2e-97f3-53933331b0e5", "providerType": "SANDBOX", "transactionId": "d00eb5d6-e99f-4c56-a42d-a3d557c27a52", "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/97443bea-fb76-43c2-afb1-2cb45abbe673/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": "a1321f1a-be77-4639-85c8-d0257b2d93af", "clientId": "", "merchantId": "", "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7", "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": "692598f6-410b-4f12-b2df-5b3e653c7b9f" }, "transactionRequests": [ { "id": "c6d3cd78-d562-42d8-83b7-4bc6ea362dac", "createdAt": "2023-07-18T12:53:16.692Z", "updatedAt": "2023-07-18T12:53:16.692Z", "idempotencyKey": null, "providerId": "bce85756-9016-4483-81b8-b1a2a37c3ac4", "providerType": "VR", "transactionId": "128898e2ab7d41df99960859", "amount": 100, "authorizationCode": "011043", "authorizationNsu": "128898e2ab7d41df99960859", "requestStatus": "success", "requestType": "void", "responseTs": "2157ms", "providerAuthorization": { "networkAuthorizationCode": "011043", "networkResponseCode": "00" } }, { "id": "9e01d010-dbb6-497a-bf3c-7c64ff823605", "createdAt": "2023-07-18T12:52:48.579Z", "updatedAt": "2023-07-18T12:52:52.857Z", "idempotencyKey": "205c60c4-c4dc-40c7-8ad5-4339aa61f31a", "providerId": "bce85756-9016-4483-81b8-b1a2a37c3ac4", "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/4b26b3cf-a9a9-45d7-9629-5a97c1f02b88/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 | | - | :-: | :-: | | 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).
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 = dde85eb7-2dd9-4d8b-b924-8c6444d94801; // 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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "amount": 150, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "32c68ff7-902c-408b-b464-cf487c7cda97", "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": "074c1ee676ed4998ab66491013c565e2", "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 | | - | :-: | :-: | | Clearsale Realtime Decision | | | | Clearsale Tickets | | | | 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).
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 Provedor de antifraude 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 | | - | :-: | :-: | | 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).
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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "amount": 15000, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "32c68ff7-902c-408b-b464-cf487c7cda97", "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 | | - | :-: | :-: | | 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).
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`) 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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "amount": 15000, "currency": "BRL", "statementDescriptor": "LOJA JOAO", "description": "Descrição longa da cobrança", "capture": false, "orderId": "32c68ff7-902c-408b-b464-cf487c7cda97", "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": "074c1ee676ed4998ab66491013c565e2", // 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 Provedor de pagamento 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).
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 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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Método de pagamento 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).
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 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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Serviço que divide recebíveis de maneira automática, entre duas ou mais partes envolvidas em uma transação 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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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).
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 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 Provedor de pagamento 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. 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).
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 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 Provedor de pagamento 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).
Não se aplica

## Veja mais 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 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 Provedor de pagamento 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).
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 Provedor de pagamento 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).
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 Provedor de pagamento 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. 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).
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 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 Provedor de pagamento 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).
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 Serviço que divide recebíveis de maneira automática, entre duas ou mais partes envolvidas em uma transação 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 | | - | - | - | - | | Braspag | | | | | Pagarme v5 | | | | | PagSeguro | | | | | Zoop | | | | | 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). 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 Source: https://docs.malga.io/documentations/split/platform-fee 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. 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 no 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 } ] } ``` 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. 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. 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. 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 aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa, payment method credit and installment 18."], "context": { "sellerId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "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. 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. * 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": "9ba4c5bc-a0fe-46b9-8950-c6fdba1b3c67", "rules": [ { "id": "3a249406-b494-49f5-867c-86dd47ace95a", "percentage": 0, "fixedAmount": 0, "paymentMethod": "pix", "createdAt": "2026-09-29T14:49:54.612Z", "updatedAt": "2026-09-29T14:49:54.612Z" }, { "id": "f18bcd0a-be5d-486e-883f-455ea501dcce", "percentage": 1.99, "fixedAmount": 0, "paymentMethod": "credit", "installment": 1, "createdAt": "2026-09-29T14:49:54.612Z", "updatedAt": "2026-09-29T14:49:54.612Z" }, { "id": "9e143ffb-5de0-4298-aa3c-f5686b8f4391", "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": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "percentage": 50, "amount": 4961 }, { "sellerId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "percentage": 30, "amount": 2950 }, { "sellerId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc", "percentage": 20, "amount": 1967 } ], "platformFee": { "ruleId": "1f879b65-ea91-449f-8d28-29a6c5c1cb6a", "percentage": 1.09, "fixedAmount": 30, "paymentMethod": "pix", "installment": null, "amount": 122, "appliedAt": "2026-09-29T18:44:22.627Z", "lines": [ { "sellerId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "scope": "seller", "ruleId": "007c3d89-c1dc-4542-8bf3-595a064a24c8", "percentage": 0, "fixedAmount": 39, "grossAmount": 5000, "feeAmount": 39, "netAmount": 4961 }, { "sellerId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "scope": "merchant", "ruleId": "1f879b65-ea91-449f-8d28-29a6c5c1cb6a", "percentage": 1.09, "fixedAmount": 30, "grossAmount": 3000, "feeAmount": 50, "netAmount": 2950 }, { "sellerId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc", "scope": "merchant", "ruleId": "1f879b65-ea91-449f-8d28-29a6c5c1cb6a", "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": "36d74a1a-a0db-45f1-bf43-d7f4ea2251e1", "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 2f8410be-e7aa-45eb-b63c-d67c4b573c21 has 2 active sellers (aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa, bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb). Send splitRules to choose who receives."], "context": { "reason": "multiple_active_sellers", "paymentMethod": "pix", "sellerIds": ["aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"] }, "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. | | `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 aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa would receive 0 cents: split amount 39 cents, platform fee 39 cents. Each seller must receive at least 1 cent."], "context": { "sellerId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "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. 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. 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 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. 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. Monte o formulário a partir dessa lista e apresente ao recebedor. Registre o momento e a jornada da coleta. 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. 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": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sellerId": "ea115e44-7048-11ed-a1eb-0242ac120002", "provider": "ZOOP", "providerId": "8f14e45f-ceea-467a-9e6f-6c1a5b3a1f2d", "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/ea115e44-7048-11ed-a1eb-0242ac120002/registration-reviews/3fa85f64-5717-4562-b3fc-2c963f66afa6/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). Criação, edição e status dos recebedores usados no Split. 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. 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). **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. ## 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": "b1612460-0fef-447d-9590-97825cf60cf6", "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": "19d05a45-0e92-478e-8366-955231bcf3d6", "providers": [], "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "metadata": null, "owner": { "id": "1ae4bc8a-f8b2-4050-bc32-a90534a803c1", "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": "ecccaa6c-63ac-4edf-8f5e-897f4cd56f76", "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": "afcb459f-168c-4b74-a2cc-85b1756cb97f", "updatedAt": "2022-12-21T23:10:13.334Z", "createdAt": "2022-12-21T23:10:13.334Z", "type": "cpf", "number": "36243319067" } }, "business": null, "bankAccount": { "id": "924ab8c7-df93-465b-97e3-c211c75a3e6e", "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": "6d76b361-a9a8-4e26-865e-d1c790ad5c72", "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": "b1612460-0fef-447d-9590-97825cf60cf6", "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/19d05a45-0e92-478e-8366-955231bcf3d6' \ --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": "b1612460-0fef-447d-9590-97825cf60cf6", "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": "19d05a45-0e92-478e-8366-955231bcf3d6", "providers": [] "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6", "clientid": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "metadata": null, "owner": { "id": "8231ba21-3758-4bd7-b664-5b5fdeda37a0", "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": "883631f0-fea0-4682-ae1a-f4ac6349e0d9", "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": "32543bbe-42c1-4000-9b68-d01a2735708e", "updatedAt": "2023-07-11T23:02:51.588Z", "createdAt": "2023-07-11T23:02:51.588Z", "type": "cpf", "number": "36243319067" }, }, "business": { "id": "607bb56a-974a-4d1d-9f56-cda865dfafbd", "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": "b681dd2e-ebdb-4fad-8c8b-e703a17825ce", "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": "b9380f2c-a657-4f47-a7da-21f3bf08182c", "updatedAt": "2023-07-11T23:02:51.578Z", "createdAt": "2023-07-11T23:02:51.578Z", "type": "cnpj", "number": "94938591000196" } }, "bankAccount": { "id": "f7ac3221-8f69-4276-b88b-34ddbe5ec24a", "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": "a04bca24-f7d1-4cb5-acce-41f12680e5bf", "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/19d05a45-0e92-478e-8366-955231bcf3d6' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' < HTTP/2 201 { "id": "19d05a45-0e92-478e-8366-955231bcf3d6", "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": "b1612460-0fef-447d-9590-97825cf60cf6", "clientid": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "metadata": null, "owner": { "id": "4fece86f-dd81-4115-ac55-efe6a6825a35", "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": "547a525b-cf08-4345-b4a5-4fca0f831a62", "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": "babc1412-24c2-4c74-9791-3cd8b6926bcb", "updatedAt": "2023-07-11T23:16:10.105Z", "createdAt": "2023-07-11T23:16:10.105Z", "type": "cpf", "number": "36243319067" }, "businessCategory": "OTHER_SERVICES" }, "business": { "id": "cdbeb363-0729-4271-b116-f4aee5282227", "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": "ee658a16-1b54-43ba-8ee1-1b84e3df5bd0", "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": "f5ca5122-4479-44c1-9cad-08216df8c61e", "updatedAt": "2023-07-11T23:16:10.099Z", "createdAt": "2023-07-11T23:16:10.099Z", "type": "cnpj", "number": "94938591000196" } }, "bankAccount": { "id": "a147a4fe-0e07-44e8-a58e-52806d5b72b3", "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": "eb896600-df76-4655-ab3f-8be651659e68", "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/b1612460-0fef-447d-9590-97825cf60cf6' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6", "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/6fa25050-4813-4209-9faa-4170a75dd8d7' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955" }' ``` # 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 * **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 - 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. **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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "5323ece6-816d-11ed-a1eb-0242ac120002", "percentage": 10, "processingFee": true, "liable": true }, { "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "percentage": 10, "processingFee": false, "liable": false, }] }' < HTTP/2 201 { "id": "3768a9bf-68fd-43e8-b7f6-e7d12ee22139", "clientId": "", "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955", "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": "5afcdeb3-9e56-4dd9-bfee-e6b70c75b200" }, "splitRules": [ { "id": "214f1995-35f0-411f-9694-0cd56ef31db9", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "5323ece6-816d-11ed-a1eb-0242ac120002", "percentage": 10, "amount": null, "processingFee": true, "liable": true, "fareMdr": null, "fareFee": null }, { "id": "e8444bb9-ba89-4cd7-808c-9c9a8dd8af4c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "percentage": 10, "amount": null, "processingFee": false, "liable": false, "fareMdr": null, "fareFee": null } ], "transactionRequests": [ { "id": "7adfc4c6-567a-4ce0-a9a3-a08a21beff7f", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "40efd5a0-1010-5c8d-9f75-0cd455553388", "providerId": "c6686322-f27b-90b2-a61b-106e7a564087", "providerType": "SANDBOX", "transactionId": "eb80f69e-de28-5060-8daf-da0fecc3b18f", "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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "5323ece6-816d-11ed-a1eb-0242ac120002", "amount": 50, "processingFee": true, "liable": true }, { "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "amount": 50, "processingFee": false, "liable": false, }] }' < HTTP/2 201 { "id": "3768a9bf-68fd-43e8-b7f6-e7d12ee22139", "clientId": "", "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955", "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": "5afcdeb3-9e56-4dd9-bfee-e6b70c75b200" }, "splitRules": [ { "id": "214f1995-35f0-411f-9694-0cd56ef31db9", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "5323ece6-816d-11ed-a1eb-0242ac120002", "percentage": null, "amount": 50, "processingFee": true, "liable": true, "fareMdr": null, "fareFee": null }, { "id": "e8444bb9-ba89-4cd7-808c-9c9a8dd8af4c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "percentage": null, "amount": 50, "processingFee": false, "liable": false, "fareMdr": null, "fareFee": null } ], "transactionRequests": [ { "id": "7adfc4c6-567a-4ce0-a9a3-a08a21beff7f", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "40efd5a0-1010-5c8d-9f75-0cd455553388", "providerId": "c6686322-f27b-90b2-a61b-106e7a564087", "providerType": "SANDBOX", "transactionId": "eb80f69e-de28-5060-8daf-da0fecc3b18f", "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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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": "5323ece6-816d-11ed-a1eb-0242ac120002", "amount": 50, "processingFee": true, "liable": true, "fares": { "mdr": 2, "fee": 100 } }, { "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "amount": 50, "processingFee": false, "liable": false, "fares": { "mdr": 2, "fee": 100 } }] }' < HTTP/2 201 { "id": "3768a9bf-68fd-43e8-b7f6-e7d12ee22139", "clientId": "", "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955", "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": "5afcdeb3-9e56-4dd9-bfee-e6b70c75b200" }, "splitRules": [ { "id": "214f1995-35f0-411f-9694-0cd56ef31db9", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "5323ece6-816d-11ed-a1eb-0242ac120002", "percentage": null, "amount": 50, "processingFee": true, "liable": true, "fareMdr": "2.00", "fareFee": 100 }, { "id": "e8444bb9-ba89-4cd7-808c-9c9a8dd8af4c", "updatedAt": "2023-10-04T19:02:36.814Z", "createdAt": "2023-10-04T19:02:36.814Z", "sellerId": "616605b2-816f-11ed-a1eb-0242ac120002", "percentage": null, "amount": 50, "processingFee": false, "liable": false, "fareMdr": "2.00", "fareFee": 100 } ], "transactionRequests": [ { "id": "7adfc4c6-567a-4ce0-a9a3-a08a21beff7f", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "40efd5a0-1010-5c8d-9f75-0cd455553388", "providerId": "c6686322-f27b-90b2-a61b-106e7a564087", "providerType": "SANDBOX", "transactionId": "eb80f69e-de28-5060-8daf-da0fecc3b18f", "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. 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 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/482b24a0-2165-4c67-a4c6-e2b74853e982/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/1feb14f6-9979-437b-8678-2989bf2cafc6/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": "b39d5e4c-f588-4106-9f62-52bced204c1d", "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": "ba771baa-653c-4071-a1db-19592d694b94" }, "splitRules": [ { "sellerId": "sellerId", "amount": 500, "processingFee": true, "liable": true }, { "sellerId": "sellerId-2", "amount": 500, "processingFee": false, "liable": false, } ], "transactionRequests": [ { "id": "bac6b914-36a7-4722-829e-f60481688ddb", "createdAt": "2024-06-18T18:33:47.096Z", "updatedAt": "2024-06-18T18:33:47.250Z", "idempotencyKey": "53daf149-8ea7-41d7-ad23-c148830f3392", "providerId": "5ce68ed3-2213-423b-8eaf-9d8c4b40df2b", "providerType": "SANDBOX", "transactionId": "35cbc6d2-f506-4aab-8c0d-097479079297", "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": "91c50b2f-c3b4-41c6-ac2b-fe36f1f5ed0d", "createdAt": "2024-06-17T14:20:15.689Z", "updatedAt": "2024-06-17T14:20:18.854Z", "idempotencyKey": "37049fab-7347-4d0d-8265-c8fbd0e11309", "providerId": "d2fc00be-c028-457f-a098-89547687922f", "providerType": "SANDBOX", "transactionId": "35cbc6d2-f506-4aab-8c0d-097479079297", "amount": 1000, "authorizationCode": "133937", "authorizationNsu": "35cbc6d2-f506-4aab-8c0d-097479079297", "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/692cc57b-fd3c-42e4-a7b6-867102ce2113/void' \ --header 'X-Client-Id: 0ce285e0-177d-432a-ad3e-350ca9f31050' \ --header 'X-Api-Key: 0fb5fcad-36c4-49a9-bcb1-a10a54e312dd' \ --header 'Content-Type: application/json' \ --data '{ "amount": 140 }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "692cc57b-fd3c-42e4-a7b6-867102ce2113", "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": "23ef5c24-cc87-43af-9979-cd70b19faa1d" }, "transactionRequests": [ { "id": "4b7aa05f-1e00-4096-abbc-c54b62dcd183", "createdAt": "2024-06-21T15:00:41.973Z", "updatedAt": "2024-06-21T15:00:41.973Z", "idempotencyKey": "8a9109fb-99d6-45df-b9f1-1eb377681c54", "providerId": "1403b164-bef0-4d73-b741-9b877ff6884b", "providerType": "BRASPAG", "transactionId": "a6db2350-6ae6-42da-9271-a8f6b22c92a7", "amount": 140, "authorizationCode": "", "authorizationNsu": null, "requestStatus": "success", "requestType": "void", "requestStatusReason": null, "responseTs": "3400ms", "providerAuthorization": { "networkAuthorizationCode": null, "networkResponseCode": 0 } }, { "id": "dd481160-9305-43ed-bcef-7b2b209c4906", "createdAt": "2024-06-21T14:58:00.663Z", "updatedAt": "2024-06-21T14:58:04.512Z", "idempotencyKey": "03b1b78f-21c0-4292-b0d0-31dbf9df83a3", "providerId": "1403b164-bef0-4d73-b741-9b877ff6884b", "providerType": "BRASPAG", "transactionId": "a6db2350-6ae6-42da-9271-a8f6b22c92a7", "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). 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 8c0d3c9a-ca87-4bd3-af0d-4eee47cc5a8a;cus_abc123;526607******1234;10/2030;NOME DE TESTE;526607;1234 ``` Somente cartões com status `active` são incluídos na exportação. 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. 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 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. 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)). 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. 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. | É 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 | | - | - | - | - | - | | | Amex | | | | | | Dinners | | | | | | Discover | | | | | | Elo | | | | | | JCB | | | | | | Maestro | | | | | | Mastercard | | | | | | MIR | | | | | | Sodexo | | | | | | Ticket | | | | | | Union Pay | | | | | | Visa | | | | | | VR | | | | **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. 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 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. 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. 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": "2d930a61-67d5-45bb-8b90-24a993b292e3" } ``` ## 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": "39a10bed-6ee1-46ea-94ce-565c1f52e2e6", "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": "8d930a61-67d5-45bb-8b90-24a993b292e3", "tokenCvv": "2d930a61-67d5-45bb-8b90-24a993b292e3" } }' < HTTP/2 201 < content-type: application/json; charset=utf-8 { "id": "55d8b213-f3c9-4ef9-9476-4d874edb8ac1", "clientId": "523afbe7-36dc-4654-9dba-e7167d0e5e2d", "merchantId": "ba5cefe2-bf93-4fe3-bd4f-d87af60b21f8", "description": "d9965173-5543-41d1-9709-5d8347a36e53", "orderId": "ca0011e3-ff94-4fc3-a254-f72c8b86fe6e", "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": "e98ea785-aa5e-4ce4-8cc7-812f1b55ba3d" }, "transactionRequests": [ { "id": "0559f1f2-ef81-46b7-8f7c-516428fd8a72", "createdAt": "2023-08-04T14:02:05.166Z", "updatedAt": "2023-08-04T14:02:05.271Z", "idempotencyKey": "d24296b2-dd60-49b5-bc28-0034fb04d293", "providerId": "cd5f2a7c-5fc2-48d3-87bd-ae6573184fb7", "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" } } ] } ``` Para saber mais sobre a Tokenização confira em [nossa documentação](/documentations/tokenization). # Validação de Cartões Source: https://docs.malga.io/documentations/tokenization/zero-dollar 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. 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": "3fb1884c-f442-4044-be6f-5afe2e0629b5", "name": "zero dollar validator", "mcc": "4040", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "status": false, "createdAt": "2023-05-30T13:16:06.979Z", "updatedAt": "2023-05-30T13:16:06.979Z", "providers": [ { "id": "ead031bb-cd67-40e7-a5b2-aa3e5b08f934", "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. É 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": "d3202b89-1ccd-4dea-95f2-05b3561bc055" } ``` 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": "59085c6d-4d21-4fc0-a6da-dda38b51c2aa", "status": "active", "statusReason": null, "createdAt": "2023-05-30T16:18:11.045Z", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "brand": "Visa", "cardHolderName": "JOAO DA SILVA", "cvvChecked": true, "fingerprint": "p5hgkYxaw5EXgim3GbJ7KzDUhdtxo1O2+qkLFj/Qyoo=", "first6digits": "492956", "last4digits": "7814", "expirationMonth": "12", "expirationYear": "2026", "transactionRequests": [ { "id": "edd0d86a-76d0-4c2c-b924-1528510a5a32", "createdAt": "2023-09-25T18:09:59.001Z", "providerId": "5ce68ed3-2213-423b-8eaf-9d8c4b40df2b", "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 | — | # Introdução Source: https://docs.malga.io/documentations/type-tables/antifraude-providers Aqui você encontra uma visão geral dos produtos de antifraude disponíveis para integração: | Provedor | Realtime | Assíncrono | | - | :-: | :-: | | Clearsale Realtime Decision | | | | Clearsale Tickets | | | | Clearsale Total | | | | B2E group | | | | Konduto | | | | 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) | # Tabela tipos de países e documentos de cadastro de Customer Source: https://docs.malga.io/documentations/type-tables/customer-document-by-country | 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 | Swisserland | Swiss social security number ("Sozialversicherungsnummer") | | *CH* | *UID* | Company | Swisserland | Unternehmens-Identifikationsnummer, Swiss business identifier | | *CH* | *VAT* | Company | Swisserland | 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 | Columbia | 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 Personcal 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 Brittan | UTR (United Kingdom Unique Taxpayer Reference) | | *GB* | *VAT* | Company | Great Brittan | 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 | Portugual | 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* | Vatl | 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 | ForeignersI 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). 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. | 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 CRUZEROS (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 ANTIQUIDADES (ANT.REPROD. STORES) | | *5940* | LOJA DE BICICLETAS - VENDAS E SERVIÇOS | | *5941* | SERVIÇOS GERAIS PARA ESPORTES | | *5942* | LIVRARIAS | | *5943* | PAPELARIAS | | *5944* | JOALHERIA (JEWERLY 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) | # Introdução Source: https://docs.malga.io/documentations/type-tables/payment-methods-by-providers 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 | | - | :-: | :-: | :-: | :-: | :-: | :- | | Sandbox | | | | | |
3DS2 Malga
| | Adyen | | | | | |
3DS2 Malga
| | Banrisul | | | | | | | | Barte | | | | | |
3DS2 Malga
| | Banco do Brasil | | | | | | | | Bolt | | | | | | | | Braintree | | | | | |
3DS2 Malga
| | Braspag | | | | | |
Split
| | BS2 | | | | | | | | Cielo | | | | | |
3DS2 Malga
| | Drip | | | | | |
Pix Parcelado
| | Getnet SEP | | | | | |
3DS2 Malga
| | Itaú | | | | | | | | Klap | | | | | | | | Malga | | | | | |
Split
| | MapInvest | | | | | | | | Mercado Pago | | | | | |
3DS2 Malga
| | NuPay | | | | | |
Wallet
| | Pagar.me v5 | | | | | |
Split
3DS2 Malga
| | PagSeguro | | | | | |
3DS2 Malga
| | PicPay | | | | | |
Wallet
| | PayPal | | | | | | | | Rede | | | | | |
3DS2 Malga
| | SafraPay | | | | | |
3DS2 Malga
| | Stripe | | | | | | | | VR | | | | | | | | WorldPay | | | | | |
3DS2 Malga
| | Zoop | | | | | |
Split
3DS2 Malga
|
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).
Não se aplica
# Começando em Vendors Source: https://docs.malga.io/documentations/vendors/intro O serviço de [**Vendedores**](/api-reference/vendors/criacao-de-um-novo-vendedor) permite que facilitadores de pagamento identifiquem os beneficiários finais de suas transações durante sua execução. Este serviço deve ser utilizado por marketplaces, franquias, aplicativos de delivery, entre outros tipos de negócios que possuem exigência regulatória prevista na circular [Bacen N° 3978 de 23 Janeiro de 2020](https://normativos.bcb.gov.br/Lists/Normativos/Attachments/50905/Circ_3978_v3_P.pdf). ## Facilitador de pagamentos São entidades que habilitam estabelecimentos comerciais a aceitarem pagamentos eletrônicos em nome de um adquirente. ## Fluxo de transação com vendedor Para identificar um vendedor/fornecedor em uma transação você deve: * Possuir o código de facilitador de pagamentos (`paymentFacilitatorId`) fornecido por cada bandeira. Obrigatório em alguns provedores, para mais detalhes [verifique a lista de provedores suportados](/documentations/vendors/provedores) * Criar um vendedor, **[veja mais sobre a criação do vendor](/api-reference/vendors/criacao-de-um-novo-vendedor)**. * Criar uma nova transação (**[charge](/api-reference/charges/realizar-nova-cobranca)**), informando o atributo `vendor`, informando o `id` do vendedor criado previamente, e o `paymentFacilitatorId` disponibilizado por sua respectiva bandeira. ## Informações sobre o vendedor | Atributo | Tipo | Tamanho | Obrigatório | Descrição | | - | - | - | - | - | | referenceId | string | `<= 15` | Sim | Identificador do vendedor no seu sistema. (Número máximo de caracteres 15) | | identityType | string | `enum` | Sim | Tipo de documento `CPF` ou `CNPJ` | | identity | string | `<= 14` | Sim | Número do documento formato conforme tipo selecionado | | mcc | string | `<= 10` | Sim | Código de segmento do lojista no adquirente | | name | string | `<= 100` | Sim | Nome Completo ou Razão Social | | email | string | `<= 100` | Não | Email do vendedor | | phoneNumber | string | `13` | Não | Telefone de contato do vendedor | | website | string | `<= 100` | Não | identificação do merchant id a ser utilizado | | address.country | string | `2` | Sim | País onde se localiza o endereço - Padrão ISO 3166-1 alpha-2 | | address.state | string | `2` | Sim | Estado | | address.city | string | `<= 20` | Sim | Cidade | | address.district | string | `<= 20` | Sim | Bairro | | address.zipCode | string | `<= 10` | Sim | Código postal CEP | | address.street | string | `<= 100` | Sim | Nome da rua/avenida/travessa | | address.streetNumber | string | `<= 5` | Sim | Número da rua | | address.complement | string | `<= 20` | Não | Complemento caso exista | ## Exemplo de criação de um vendedor ```bash theme={null} curl --location --request POST \ --url https://api.malga.io/v1/vendors \ --header 'Content-Type: application/json' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' \ --data '{ "referenceId": "12345", "identityType": "CNPJ", "identity": "12345678000199", "mcc": "1234", "name": "Empresa Exemplo Ltda", "email": "contato@empresaexemplo.com", "phoneNumber": "5511999999999", "website": "https://www.empresaexemplo.com", "address": { "country": "BR", "state": "SP", "city": "São Paulo", "district": "Centro", "zipCode": "01001-000", "street": "Avenida Paulista", "number": "1000", "complement": "Apto 101" } }' ``` ```bash theme={null} < HTTP/2 201 { "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1", "referenceId": "12345", "identityType": "CNPJ", "identity": "12345678000199", "mcc": "1234", "name": "Empresa Exemplo Ltda", "email": "contato@empresaexemplo.com", "phoneNumber": "5511999999999", "website": "https://www.empresaexemplo.com", "address": { "country": "BR", "state": "SP", "city": "São Paulo", "district": "Centro", "zipCode": "01001-000", "street": "Avenida Paulista", "number": "1000", "complement": "Apto 101" }, "updatedAt": "2024-06-26T12:34:56Z", "createdAt": "2024-06-01T08:00:00Z" } ``` ### Exemplo de cobrança com vendedor ```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": "7f8870a2-71c9-4ef0-a531-82000e00b7e1", "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" } }, "vendor": { "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1", "paymentFacilitatorId": "123456" } }' ``` ```bash theme={null} < HTTP/2 201 { "id": "3768a9bf-68fd-43e8-b7f6-e7d12ee22139", "clientId": "", "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955", "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": "5afcdeb3-9e56-4dd9-bfee-e6b70c75b200" }, "vendor": { "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1", "paymentFacilitatorId": "123456" }, "transactionRequests": [ { "id": "7adfc4c6-567a-4ce0-a9a3-a08a21beff7f", "createdAt": "2023-10-04T19:02:37.106Z", "updatedAt": "2023-10-04T19:02:37.205Z", "idempotencyKey": "40efd5a0-1010-5c8d-9f75-0cd455553388", "providerId": "c6686322-f27b-90b2-a61b-106e7a564087", "providerType": "SANDBOX", "transactionId": "eb80f69e-de28-5060-8daf-da0fecc3b18f", "amount": 150, "authorizationCode": "9301661", "authorizationNsu": "4244270", "requestStatus": "success", "requestType": "authorization", "responseTs": "62ms", "providerAuthorization": { "networkAuthorizationCode": "7909027", "networkResponseCode": "8168918" } } ], "appInfo": null } } ``` # Provedores suportados no serviço de Vendors Source: https://docs.malga.io/documentations/vendors/provedores Lista dos provedores de pagamento suportados pelo serviço de Vendors na Malga, indicando quais exigem o envio do paymentFacilitatorId. Os provedores de pagamento suportados pelo serviço são: | Provedor | Precisa enviar o `paymentFacilitatorId`? | | - | :-: | | Adyen | | | Cielo | | | Rede | | | SafraPay | | | Sandbox | | Para maiores informações sobre o `paymentFacilitatorId` consulte sua bandeira. * [Visa](https://www.visa.com.br/parceiros-visa/informacoes-para-parceiros/facilitadores-de-pagamento.html#O_que_%C3%A9_arranjo_de_pagamento_da_Visa_-1356886403) * [MasterCard](https://www.mastercard.com.br/pt-br/visao/quem-somos/participantes-arranjo-mastercard.html) # Recebendo webhooks com filas de mensagens Source: https://docs.malga.io/documentations/webhooks/webhook-receiver-aws-sqs Implemente um receiver de webhooks da Malga resiliente usando filas de mensagens AWS SQS para evitar timeouts e garantir processamento assíncrono. Um erro comum ao integrar webhooks é colocar regras de negócio diretamente no endpoint que recebe os eventos. Isso aumenta o risco de timeouts e falhas de processamento, fazendo com que a Malga interprete a entrega como malsucedida e inicie reentregas desnecessárias. A abordagem recomendada é separar o **recebimento** do **processamento**: o endpoint apenas valida e enfileira o evento, e um worker separado consome a fila e executa a lógica de negócio. ## Arquitetura ```text theme={null} Malga → seu endpoint (receiver) → fila → worker → sua lógica de negócio ↓ (em caso de falha) DLQ ``` O receiver deve: 1. Receber o `POST` da Malga 2. Verificar a assinatura do evento (veja [Segurança Webhook](/documentations/webhooks/webhook1-1#segurança-webhook)) 3. Enfileirar o payload 4. Retornar `HTTP 200` imediatamente O worker consome as mensagens da fila e executa as regras de negócio. Se o processamento falhar, a mensagem é retentada automaticamente pela fila e, após o número máximo de tentativas, encaminhada para a **DLQ (Dead Letter Queue)**, garantindo que nenhum evento seja perdido silenciosamente. ## Opções de fila | Serviço | Tipo | Observações | | - | - | - | | **AWS SQS** | Gerenciado (cloud) | DLQ nativa, fácil integração com outros serviços AWS | | **Google Cloud Pub/Sub** | Gerenciado (cloud) | Suporte a múltiplos subscribers, retenção configurável | | **Azure Service Bus** | Gerenciado (cloud) | Suporte a filas e tópicos, DLQ nativa | | **RabbitMQ** | Self-hosted / gerenciado | Flexível, amplamente adotado, suporte a DLQ via dead-letter exchange | | **Redis (BullMQ / Sidekiq)** | Self-hosted / gerenciado | Simples de operar, ideal para quem já usa Redis na stack | # Webhooks v1.0 (obsoleto) Source: https://docs.malga.io/documentations/webhooks/webhook1-0 Acesse a versão 1.1 [clicando aqui](/documentations/webhooks/webhook1-1) A Malga utiliza o Serviço de Webhooks para notificar o seu sistema sobre os eventos ocorridos na nossa plataforma. Através de webhooks você consegue atualizar seu sistema sempre que um evento importante acontece, como a atualização de status de uma cobrança para confirmar ou cancelar um determinado pagamento. ## 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 feitas pela Malga. * 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](/api-reference/webhooks/listagem-de-webhooks-cadastrados). ```bash 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": "transaction.authorized", "endpoint": "https://enuqkxq2lu8be0y.m.pipedream.net", "version": 1, "status": true }' < HTTP/2 201 { "id": "31c142ad-4c30-4964-ba24-2df0f2bbb745", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "event": "transaction.authorized", "endpoint": "https://enuqkxq2lu8be0y.m.pipedream.net", "version": 1, "status": true, "createdAt": "2021-07-06T21:03:36.590Z", "updatedAt": "2021-07-06T21:03:36.590Z" } ``` ## Evento de notificação enviado Muitos dos eventos que ocorrem na sua integração com a Malga são síncronos e você recebe um retorno direto como resposta da sua requisição, como nos casos de criar um cliente, criar um cartão, etc. Porém, em determinados casos, a resposta que você recebe após realizar uma requisição não contempla o status final daquele objeto, sendo necessário registrar um webhook para receber respostas assíncronas da API da Malga, mantendo seu sistema atualizado, isso ocorre principalmente nos casos de cobrança através de PIX e Boleto, notificação de suspeita de fraude, liquidação financeira de transações, entre outros. Quando um determinado evento ocorre a Malga então 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 enviada pela Malga para seu endpoint:** ```bash theme={null} > POST HTTP/2 > Host: > User-Agent: axios/0.21.1 > Accept: application/json, text/plain, */* > Content-Type: application/json > x-idempotency-key: 5616b19e-4d99-4bd3-b415-4990e5cab4f4 > HTTP/2 { "id": "421b0e9d-ab3f-4d29-b626-d832e89f3a3b", "apiVersion": "1", "object": "transaction", "event": "authorized", "data": { "status": "authorized", "id": "ca18308b-6846-43c4-aa92-bc7685e1f979", "updatedAt": "2022-08-01T21:27:54.759Z", "createdAt": "2022-08-01T21:27:52.088Z", "idempotencyKey": null, "requestId": null, "orderId": "17", "amount": 200, "originalAmount": 200, "currency": "BRL", "installments": 1, "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "statementDescriptor": "W✔️C-", "merchantId": "5002bdcd-e816-4741-871c-6de4f31ea965", "capture": false, "isDispute": false, "isProcessing": false, "customerId": null, "description": null, "fee": null, "feeAmount": null, "transactionRequests": [ { "id": "50c7da2f-6283-4e4d-93f9-3f5df50808ca", "updatedAt": "2022-08-01T21:27:53.719Z", "createdAt": "2022-08-01T21:27:53.317Z", "idempotencyKey": "d108207f-3189-4166-b774-34e2c535ece5", "requestId": null, "providerId": "e78f2c8a-2c13-4e2b-ba67-efe528452c61", "providerType": "STRIPE", "networkTransactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob", "amount": 200, "authorizationCode": null, "authorizationNsu": null, "requestStatus": "success", "requestType": "authorization", "responseTs": "395ms", "pix": null, "boleto": null, "providerError": null, "providerAuthorization": null } ], "transactionError": null }, "createdAt": "2022-08-31T11:41:51.583Z" } ``` ## Boas práticas para receber notificações **Tentativas e Retentativas de envio de notificações** A Malga fará a tentativa de envio de uma determinada notificação para seu webhook, em caso de problemas no processamento do serviço passamos a realizar novas tentativas de entrega das notificações com um escalonamento de tempo entre as tentativas. Para concluir o processamento da notificação o seu serviço deve retornar um HTTP STATUS 200 (OK) ou 201 (CREATED) dentro do tempo máximo de espera, caso contrário, será entendido que o endpoint não o recebeu corretamente e o evento será marcado para retentativa. | Evento | Prazo de intervalo do disparo | Tempo de espera para resposta | | - | - | - | | Criado | Imediatamente | 30 segundos | | Primeira tentativa | 5 minutos | 5 segundos | | Segunda tentativa | 45 minutos | 5 segundos | | Terceira tentativa | 6 horas | 5 segundos | | Quarta tentativa | 1 dia | 5 segundos | | Quinta tentativa | 2 dias | 5 segundos | | Sexta tentativa | 4 dias | 5 segundos | A Malga mantém o registro de todas as notificações enviadas, incluindo os dados da requisição (Request) e da resposta do servidor externo (Response), pelo período de 45 dias. Quando uma notificação ultrapassa o número máximo de tentativas de entrega, a mensagem é marcada como perdida e permanece armazenada para reprocessamento futuro mediante solicitação. A URL do seu webhook deve estar exposta (pública) para a internet, de forma que a plataforma da Malga a alcance e consiga enviar os eventos. **Processando eventos, ordem e duplicidade** Quando um determinado evento ocorre, a Malga então cria um objeto do tipo `event` que registra o objeto e o tipo do evento de atualização, bem como a data da ocorrência. Cada evento possui um identificador único que deve ser utilizado do lado do cliente para evitar duplicidade de processamento. O identificador é enviado no objeto `event` no corpo da requisição e também no header `x-idempotency-key` do request, sendo o mesmo valor. Os eventos são enviados através de uma requisição HTTP para o seu endpoint exatamente na ordem em que eles ocorreram no sistema da Malga, porém recomendamos que seja utilizada a data de criação do evento, também enviada no objeto `event`, para garantir uma ordem cronológica no processamento dos eventos do lado do cliente. Caso você receba um evento com data de criação inferior à data de criação de um outro evento já processado pelo seu sistema, os dados do objeto enviado no evento estarão desatualizados, ficando a seu critério tomar ou não alguma ação com esse evento. ## Testando notificação via webhooks 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 transação em sandbox** ```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 '{ "status": "charged_back" }' ``` ## Eventos suportados para notificação via webhooks | 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 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.revert\_void** | Evento enviado quando precisamos fazer a reversão de um estorno bem-sucedido. [Veja mais](/documentations/payment-methods/credit-card#reversao-automatica-de-um-estorno-revert-void) | # Webhooks v1.1 Source: https://docs.malga.io/documentations/webhooks/webhook1-1 A Malga utiliza o serviço de webhooks para notificar o seu sistema sobre os eventos ocorridos na nossa plataforma. Através de webhooks, você consegue atualizar seu sistema sempre que um evento importante acontece, como a atualização de status de uma cobrança para confirmar ou cancelar um determinado pagamento. Procurando pela doc da versão 1.0? [Acesse aqui](/documentations/webhooks/webhook1-0). ## 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 feitos pela Malga. * 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](/api-reference/webhooks/listagem-de-webhooks-cadastrados). ```bash 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": "transaction.authorized", "endpoint": "https://enuqkxq2lu8be0y.m.pipedream.net", "version": 1.1, "status": true }' < HTTP/2 201 { "id": "31c142ad-4c30-4964-ba24-2df0f2bbb745", "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "event": "transaction.authorized", "endpoint": "https://enuqkxq2lu8be0y.m.pipedream.net", "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 Muitos dos eventos que ocorrem na sua integração com a Malga são síncronos e você recebe um retorno direto como resposta da sua requisição, como nos casos de criar um cliente, criar um cartão, etc. Porém, em determinados casos, a resposta que você recebe após realizar uma requisição não contempla o status final daquele objeto, sendo necessário registrar um webhook para receber respostas assíncronas da API da Malga para manter seu sistema atualizado, isso ocorre principalmente nos casos de cobrança através de PIX e Boleto, notificação de suspeita de fraude, liquidação financeira de transações, entre outros. Quando um determinado evento ocorre, a Malga então 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. ## transaction **Exemplo de requisição de notificação de evento de uma transação enviada pela Malga para seu endpoint:** ```bash theme={null} > POST HTTP/2 > Host: > User-Agent: axios/0.21.1 > Accept: application/json, text/plain, */* > Content-Type: application/json > X-Idempotency-Key: 5616b19e-4d99-4bd3-b415-4990e5cab4f4 > X-Plug-Date: 1660053072711 > X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75 > HTTP/2 { "id": "5616b19e-4d99-4bd3-b415-4990e5cab4f4", "apiVersion": "1.1", "object": "transaction", "event": "authorized", "createdAt": "2021-07-05T18:56:08.672Z" "data": { "id": "242b9be8-cd60-461d-af27-f31e3d6e3fb7", "updatedAt": "2021-07-05T18:56:08.247Z", "createdAt": "2021-07-05T18:56:08.247Z", "idempotencyKey": null, "requestId": null, "amount": 1500, "originalAmount": 1500, "installments": 1, "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00", "description": null, "statementDescriptor": "Pedido #231 loja joão", "status": "authorized", "capture": true, "isDispute": false, "fee": null, "feeAmount": null, "transactionRequests": [{ "id": "87c3973c-6a8d-40a5-8b3b-f6e89a8393ab", "updatedAt": "2021-07-05T18:56:08.648Z", "createdAt": "2021-07-05T18:56:08.255Z", "idempotencyKey": "fdd134fa-f79e-4164-b635-a6510908e1a2", "requestId": null, "providerId": "367b118f-a9be-421b-bb61-5df4261df634", "providerType": "STRIPE", "transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob", "amount": 1500, "authorizationCode": "486677", "authorizationNsu": "d8d230ce-7222-4ca6-b08f-135289588bc8", "responseCode": "1", "requestStatus": "success", "requestType": "authorization", "responseTs": "377ms", }], "paymentFlow": { "id": "0b4e9c3e-2f1a-4b6c-8d9e-1f2a3b4c5d6e", "metadata": { "stringProperty": "value for property 1", "numericProperty": 10 } } } } ``` Quando a cobrança é processada por um [Fluxo Inteligente](/documentations/flow-guide/introduction#uso-de-metadados-de-transacao), o objeto `data` inclui a propriedade `paymentFlow`: * **`paymentFlow.id`** — identificador do fluxo que processou a cobrança. * **`paymentFlow.metadata`** — o mesmo objeto de `metadata` que você enviou em `paymentFlow.metadata` na criação da cobrança, usado nas regras condicionais do fluxo. A propriedade `paymentFlow` só é enviada quando a cobrança passa por um Fluxo Inteligente. Cobranças que não acionam um fluxo não trazem esse campo, mesmo que `metadata` tenha sido informado apenas para o roteamento. ## seller Na propriedade data, você terá acesso a dois objetos aninhados: origin e seller. Dentro do objeto seller, você poderá visualizar o estado atual do vendedor com informações de todos os provedores. Já na propriedade origin, você receberá o nome do provedor que originou a emissão do evento. Por exemplo, se o valor de origin for SANDBOX, significa que somente o provedor SANDBOX sofreu modificação de status. Confira o exemplo abaixo para entender melhor como funciona: Dentro de `seller.bankAccount`, os identificadores `bank` (COMPE) e `ispb` podem estar ambos preenchidos ou apenas um deles, conforme o cadastro do recebedor. Consulte a [seção sobre `bank` e `ispb`](/documentations/split/seller#identificador-do-banco-bank-e-ispb) para detalhes. ```json theme={null} { "id": "f2406fde-0c6b-4084-a23f-cec980ab72cc", "apiVersion": "1.1", "object": "seller", "event": "active", "data": { "origin": { "provider": "SANDBOX", "providerId": "af1f0562-150b-45df-93d3-ced36c6967f0", "status": "active" }, "seller": { "bankAccount": { "accountCheckDigit": "22", "accountNumber": "3850", "bank": "077", "ispb": "60746948", "branchCheckDigit": "1", "branchNumber": "492", "createdAt": "2023-03-24T19:53:38.780Z", "holderDocument": "603933950", "holderName": "Vitória Julia Agatha Aparício", "id": "9c1adcfa-a4c2-41cf-b717-30af7807342a", "type": "conta_corrente", "updatedAt": "2023-03-24T19:53:38.780Z" }, "business": { "address": { "city": "Maracan", "complement": null, "country": "BR", "createdAt": "2023-03-24T19:53:38.826Z", "district": "AB", "id": "59b67976-5d66-4870-921d-7eac4cf6d45a", "state": "CE", "street": "Rua Nova Lua", "streetNumber": "30", "updatedAt": "2023-03-24T19:53:38.826Z", "zipCode": "61000-320" }, "createdAt": "2023-03-24T19:53:38.815Z", "description": "business description", "document": { "country": "BR", "createdAt": "2023-03-24T19:53:38.838Z", "id": "364d26de-98d3-4c44-b99c-4f7eec069350", "number": "88.627.023/0001-71", "type": "cnpj", "updatedAt": "2023-03-24T19:53:38.838Z" }, "email": "email@email.com", "facebook": null, "id": "d4cfef03-fd11-4ce7-8240-5b197143795b", "name": "Business 1", "openingDate": "2022-01-10", "phoneNumber": "12345667", "twitter": null, "updatedAt": "2023-03-24T19:53:38.815Z", "website": null }, "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "id": "1705bde2-6707-49bb-8f72-63b7f91e9f38", "mcc": 4040, "merchantId": "37a9aed8-b1a9-4069-befa-71479f54e0b1", "metadata": null, "owner": null, "providers": [ { "createdAt": "2023-03-24T19:53:38.939Z", "externalId": "4039535", "externalStatus": "active", "externalStatusReason": "ok", "providerType": "SANDBOX", "status": "pending", "updatedAt": "2023-03-24T19:58:00.452Z" } ], "transferPolicy": { "anticipatableVolumePercentage": null, "automaticAnticipation1025Delay": null, "automaticAnticipationDays": null, "automaticAnticipationEnabled": null, "automaticAnticipationType": null, "createdAt": "2023-03-24T19:53:38.800Z", "id": "837ea08e-f6f8-4148-bd22-48783751d7fb", "transferDay": "5", "transferEnabled": true, "transferInterval": "monthly", "updatedAt": "2023-03-24T19:53:38.800Z" } } }, "createdAt": "2023-03-24T19:58:03.663Z" } ``` ## subscription **Exemplo de requisição de notificação de evento de uma assinatura enviada pela Malga para seu endpoint:** ```bash theme={null} > POST HTTP/2 > Host: > User-Agent: axios/0.21.1 > Accept: application/json, text/plain, */* > Content-Type: application/json > X-Idempotency-Key: 5616b19e-4d99-4bd3-b415-4990e5cab4f4 > X-Plug-Date: 1660053072711 > X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75 > HTTP/2 { "id": "019a362f-f69c-7789-b535-7051a0031bbe", "apiVersion": "1.1", "object": "subscription", "event": "created", "data": { "subscription": { "id": "019a362f-f69c-7789-b535-7051a0031bbe", "name": "Test Subscription for Events", "clientId": "e0d26950-541b-4b28-b4ec-a95fb61f1a0d", "merchantId": "3e452afd-4b0f-4d11-87bb-6ad3345709d7", "customerId": "a3994087-d867-4c30-8b07-fe0a2f3db77b", "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": "5e334112-6f22-4c31-8e24-2f89ff77e21c" } }, "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" } ``` **Exemplo de evento subscription.activated com cycle:** ```json theme={null} { "id": "019a353e-bae2-7e5f-96e3-c0eab8681652", "apiVersion": "1.1", "object": "subscription", "event": "activated", "data": { "subscription": { "id": "019a353e-bae2-7e5f-96e3-c0eab8681652", "name": "Assinatura Premium com Eventos", "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd", "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0", "customerId": "2a8b64ce-904c-4256-b79a-49525808609c", "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": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5" }, "installments": 1 }, "status": "active", "amount": 29900, "liveMode": false, "createdAt": "2025-10-30T13:11:34.882942Z", "updatedAt": "2025-10-30T13:11:35.921247966Z" }, "cycle": { "id": "019a353e-bafa-774b-9664-8217b3d19da6", "customerId": "2a8b64ce-904c-4256-b79a-49525808609c", "merchantId": "225d39bc-1fbb-480a-90bd-f0caad05d2d0", "cycle": 1, "status": "authorized", "amount": 29900, "scheduledAt": "2025-10-30", "paymentHistory": [ { "id": "d6738023-a45c-4d58-a303-456da757cca6", "createdAt": "2025-10-30T13:11:34.917233965Z", "executedAt": "2025-10-30T13:11:34.905674924Z", "chargeId": "fe703f43-8f77-4780-80d1-b1c4ad44db6c", "attemptNumber": 1, "paymentMethod": { "type": "credit", "card": { "cardId": "ebef4e7e-b5d3-49d8-ac8f-b973faaa3ac5" }, "installments": 1 }, "error": null } ], "createdAt": "2025-10-30T13:11:34.906418Z" } }, "createdAt": "2025-10-30T14:38:59.398Z" } ``` ## purchase Os eventos `purchase.*` notificam o andamento de uma [Venda com múltiplos cartões](/documentations/payment-methods/multiple-cards). São sete eventos, listados em [Eventos Purchase](#eventos-purchase), e todos existem somente na versão 1.1 do webhook. Um webhook em `"version": 1.0` não recebe nenhum evento `purchase.*`, nem com `"event": "*"`. Cadastrar um evento `purchase.*` com versão abaixo de 1.1 devolve `400` com `webhook_purchase_event_requires_version_1_1`. ### Cadastro do webhook Cadastre um evento específico ou use `"event": "*"` para receber todos os eventos da conta na versão 1.1. Com o curinga, o seu endpoint também recebe `transaction.*`, `seller.*` e `subscription.*`: filtre pelo campo `object` e responda `200` aos objetos que você não processa. ```bash 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": "purchase.paid", "endpoint": "https://seu-dominio.com/webhooks/malga", "version": 1.1, "status": true }' ``` ### Como a notificação chega O corpo tem sempre a mesma estrutura, para qualquer evento de Venda. O nome do evento chega dividido em dois campos: `purchase.paid` é entregue como `"object": "purchase"` e `"event": "paid"`. Concatene `object` e `event` para montar o nome. O campo `apiVersion` é uma string (`"1.1"`). O campo `id` identifica a notificação, não a Venda, e é igual ao header `X-Idempotency-Key`. O `data` traz o conteúdo do evento e varia conforme o evento, como mostram os exemplos a seguir. **Exemplo de requisição de notificação do evento `purchase.created` enviada pela Malga para seu endpoint:** ```bash theme={null} > POST HTTP/2 > Host: > Content-Type: application/json; charset=utf-8 > X-Idempotency-Key: 5616b19e-4d99-4bd3-b415-4990e5cab4f4 > X-Plug-Date: 1660053072711 > X-Plug-Signature: 1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75 > HTTP/2 { "id": "5616b19e-4d99-4bd3-b415-4990e5cab4f4", "apiVersion": "1.1", "object": "purchase", "event": "created", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "amount": 15000, "currency": "BRL", "capture": true, "status": "pending", "orderId": "pedido-1001", "sessionId": null, "payments": [ { "id": "16167219-c4a5-4866-939e-afd42be1d2b4", "slotIndex": 0, "amount": 10000, "installments": 1, "status": "pending", "paymentMethodSnapshot": { "sourceType": "card", "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "last4": "4242" } }, { "id": "67aef675-5aab-4e66-a647-6252e0989695", "slotIndex": 1, "amount": 5000, "installments": 3, "status": "pending", "paymentMethodSnapshot": { "sourceType": "token", "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09", "last4": "4444" } } ], "createdAt": "2026-07-27T18:00:00Z", "updatedAt": "2026-07-27T18:00:00Z" }, "createdAt": "2026-07-27T18:00:00.412Z" } ``` `orderId` e `sessionId` chegam como `null` quando você não os informa na criação. O `id` de cada item de `payments` é o identificador do cartão dentro da Venda, e não o `chargeId` da cobrança, que só existe depois da autorização. O `paymentMethodSnapshot` traz a referência do cartão (`cardId` ou `tokenId`) e, quando conhecidos, `brand` e `last4`. Ele nunca traz o número do cartão. ### purchase.charge\_authorized Refere-se a um único cartão da Venda. Neste evento, o identificador da Venda vem em `purchaseId`, e não em `id`. O `status` é o do cartão e pode ser `pre_authorized` ou `authorized`, inclusive em Vendas com `capture: true`. Uma Venda pode gerar mais de um evento deste tipo, portanto não trate o primeiro como o desfecho. ```json theme={null} { "id": "0f7a3c52-9d1e-4b86-a5c4-3e2d1f0a9b8c", "apiVersion": "1.1", "object": "purchase", "event": "charge_authorized", "data": { "purchaseId": "550e8400-e29b-41d4-a716-446655440000", "slotIndex": 1, "status": "pre_authorized", "chargeId": "82650b96-70ea-45b9-aea8-c83c4afb3361", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "amount": 5000, "currency": "BRL", "capture": true }, "createdAt": "2026-07-27T18:00:21.237Z" } ``` ### Desfechos da Venda Os eventos `purchase.pre_authorized`, `purchase.paid`, `purchase.failed`, `purchase.cancelled` e `purchase.void_failed` trazem o mesmo resumo da Venda, sem a lista de cartões. Só o `status` muda. | Evento | `data.status` | | - | - | | **purchase.pre\_authorized** | `pre_authorized`. A Venda continua `pending`, porque esse não é um status de Venda | | **purchase.paid** | `paid` | | **purchase.failed** | `failed` | | **purchase.cancelled** | `cancelled`, com dois "L" | | **purchase.void\_failed** | Status da Venda naquele instante: `failed`, quando a compensação vem de uma recusa, ou `paid`, quando um estorno não conclui | **`purchase.pre_authorized`** — todos os cartões ficaram pré-autorizados em uma Venda criada com `capture: false`: ```json theme={null} { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "apiVersion": "1.1", "object": "purchase", "event": "pre_authorized", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "status": "pre_authorized", "amount": 15000, "currency": "BRL", "capture": false }, "createdAt": "2026-07-27T18:00:22.518Z" } ``` **`purchase.paid`** — todos os cartões foram capturados: ```json theme={null} { "id": "2b9d4f60-7c3a-4e15-b8a2-6d5c4b3a2f10", "apiVersion": "1.1", "object": "purchase", "event": "paid", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "status": "paid", "amount": 15000, "currency": "BRL", "capture": true }, "createdAt": "2026-07-27T18:00:41.093Z" } ``` **`purchase.failed`** — a Venda foi recusada de forma definitiva. O evento não traz o motivo da recusa: consulte `payments[].declineReason` em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda). A Malga compensa automaticamente os cartões que já tinham sido cobrados, cancelando a pré-autorização ou estornando a captura. ```json theme={null} { "id": "8e7d6c5b-4a39-4281-9706-5e4d3c2b1a09", "apiVersion": "1.1", "object": "purchase", "event": "failed", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "status": "failed", "amount": 15000, "currency": "BRL", "capture": true }, "createdAt": "2026-07-27T18:00:19.774Z" } ``` **`purchase.cancelled`** — o cancelamento das pré-autorizações foi concluído. O estorno de uma Venda `paid` não gera este evento: ```json theme={null} { "id": "a4b5c6d7-e8f9-4a0b-9c1d-2e3f4a5b6c7d", "apiVersion": "1.1", "object": "purchase", "event": "cancelled", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "status": "cancelled", "amount": 15000, "currency": "BRL", "capture": false }, "createdAt": "2026-07-27T18:06:03.660Z" } ``` **`purchase.void_failed`** — a liberação ou o estorno de um cartão não concluiu depois das tentativas automáticas. Trate este evento como alerta operacional: há valor retido sem desfecho automático. Consulte a Venda em `GET /v1/purchases/{id}` para identificar o cartão afetado, que permanece `pre_authorized` ou `authorized`, e acione o suporte da Malga com o `id` da Venda. ```json theme={null} { "id": "d9e8f7a6-b5c4-4d3e-a2f1-0b9c8d7e6f5a", "apiVersion": "1.1", "object": "purchase", "event": "void_failed", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8", "status": "failed", "amount": 15000, "currency": "BRL", "capture": true }, "createdAt": "2026-07-27T18:10:44.301Z" } ``` Em casos de abandono da Venda ou de esgotamento das tentativas, os eventos `purchase.failed` e `purchase.void_failed` podem trazer apenas `id` e `status` no `data`. Modele o seu parser de forma tolerante: campos ausentes são esperados. ### Corpo reduzido Em parte dos cenários, os eventos `purchase.paid`, `purchase.cancelled` e `purchase.charge_authorized` são entregues com o `data` reduzido: ```json theme={null} { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "apiVersion": "1.1", "object": "purchase", "event": "paid", "data": { "source": "transaction" }, "createdAt": "2026-07-27T18:00:41.093Z" } ``` Esse corpo não traz o identificador da Venda. Responda `200` e use a notificação como sinal de que algo mudou: consulte as Vendas que você ainda tem como não terminais. Nunca descarte a notificação nem a trate como erro. ### Como processar os eventos de Venda * Use o evento como gatilho e leia o estado em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda). O `data` pode ser um retrato antigo, no caso de uma retentativa, ou reduzido. Nunca grave o estado da Venda a partir do `data`. * Extraia o identificador da Venda de `data.id` e, na falta dele, de `data.purchaseId`. Se nenhum dos dois existir, faça a reconciliação por varredura. * Libere o pedido pelo status da Venda, nunca pelo status de um cartão isolado. Enquanto houver cartão pendente, a Venda continua `pending`. * Não presuma ordem entre os eventos de uma mesma Venda. O `purchase.paid` pode chegar antes de um `purchase.charge_authorized`. * Deduplique pelo campo `id` da notificação, igual ao header `X-Idempotency-Key`. * Se a Venda trouxer o campo `pendingReview` na consulta, interrompa a consulta automática e acione o suporte da Malga. * O estorno de uma Venda `paid` não gera evento `purchase.*` e a Venda permanece `paid`. Acompanhe o valor estornado em `payments[].refundedAmount`, na consulta da Venda. ## Boas práticas para receber notificações Recomendamos que seu endpoint de webhook seja responsável **apenas por receber e enfileirar o evento**, sem executar nenhuma regra de negócio diretamente. Isso evita erros de timeout, falhas de processamento e reentregas desnecessárias. Veja como implementar esse padrão em [Recebendo webhooks com filas de mensagens](/documentations/webhooks/webhook-receiver-aws-sqs). **Tentativas e Retentativas de envio de notificações** A Malga fará a tentativa de envio de uma determinada notificação para seu webhook, em caso de problemas no processamento do serviço, passamos a realizar novas tentativas de entrega das notificações com um escalonamento de tempo entre as tentativas. Para concluir o processamento da notificação, o seu serviço deve retornar um HTTP STATUS 200 (OK) ou 201 (CREATED) dentro do tempo máximo de espera, caso contrário, será entendido que o endpoint não o recebeu corretamente e o evento será marcado para retentativa. | Evento | Prazo de intervalo do disparo | Tempo de espera para resposta | | - | - | - | | Criado | Imediatamente | 30 segundos | | Primeira tentativa | 5 minutos | 5 segundos | | Segunda tentativa | 45 minutos | 5 segundos | | Terceira tentativa | 6 horas | 5 segundos | | Quarta tentativa | 1 dia | 5 segundos | | Quinta tentativa | 2 dias | 5 segundos | | Sexta tentativa | 4 dias | 5 segundos | A Malga mantém o registro de todas as notificações enviadas, incluindo os dados da requisição (Request) e da resposta do servidor externo (Response), pelo período de 45 dias. Quando uma notificação ultrapassa o número máximo de tentativas de entrega, a mensagem é marcada como perdida e permanece armazenada para reprocessamento futuro mediante solicitação. Se o seu webhook apresentar 50 ou mais falhas de entrega em um período de 24 horas, a Malga envia um e-mail de resumo para o contato com papel de proprietário cadastrado na sua conta. A URL do seu webhook deve estar exposta (pública) para a internet, de forma que a plataforma da Malga a alcance e consiga enviar os eventos. **Processando eventos, ordem e duplicidade** Quando um determinado evento ocorre, a Malga então cria um objeto do tipo `event` que registra o objeto e o tipo do evento de atualização, bem como a data da ocorrência. Cada evento possui um identificador único que deve ser utilizado do lado do cliente para evitar duplicidade de processamento. O identificador é enviado no objeto `event` no corpo da requisição e também no header `x-idempotency-key` do request, sendo o mesmo valor. Os eventos são enviados através de uma requisição HTTP para o seu endpoint exatamente na ordem em que eles ocorreram no sistema da Malga, porém recomendamos que seja utilizada a data de criação do evento, também enviada no objeto `event`, para garantir uma ordem cronológica no processamento dos eventos do lado do cliente. Caso você receba um evento com data de criação inferior à data de criação de um outro evento já processado pelo seu sistema, os dados do objeto enviado no evento estarão desatualizados, ficando a seu critério tomar ou não alguma ação com esse evento. ## Testando notificação via webhooks 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 transação em sandbox** ```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 '{ "status": "charged_back" }' ``` ## Segurança Webhook A partir da versão 1.1 do webhook a Malga passou a assinar todos os eventos para garantir a segurança do recebimento do evento. Utilizamos uma chave privada do tipo [Ed25519](https://ed25519.cr.yp.to/) para assinar os eventos. No momento do cadastro do webhook, você recebe a chave pública de mesmo tipo para verificar se a assinatura enviada bate com o payload recebido. Todo evento recebido deve ser verificado e caso a assinatura não seja reconhecida, por medidas de segurança, você deve descartar o evento. ### Como verificar a assinatura do evento? Enviamos 2 headers: * **X-Plug-Date** contendo a data que o evento foi gerado. O formato segue o padrão UTC Unix Timestamp. * **X-Plug-Signature** contendo um hash em hexadecimal de 64 bits. Para prevenir um [ataque de replay](https://en.wikipedia.org/wiki/Replay_attack), verifique se a data do evento (X-Plug-Date) está dentro de seu critério de aceite. Recomendamos não aceitar eventos com mais de 5 minutos. Agora você deve validar a assinatura (X-Plug-Signature). Para isso você precisará utilizar 4 dados, **X-Plug-Date**, **X-Plug-Signature**, **payload** e a **chave pública (pubKey)** (que é retornada na criação do webhook). Primeiro você deve concatenar o date com o body encodado para utf8, criptografar com a chave pública do webhook criado, e validar o criptograma recebido no header signature com o criptograma gerado para verificar integridade. O algoritmo para verificar a assinatura se parece com o declarado abaixo: ```bash theme={null} date = header['X-Plug-Date'] msg = "{date}\n{payload}" sig_raw = header['X-Plug-Signature'] sig_byte = hex_to_bin(sig_raw) EdDSA_signature_verify(msg, pubKey, sig_byte) --> 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: ```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); }, }; ``` ```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 } ``` ```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!') ``` ```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); } } ``` ```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); } } ``` ```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!'; } ``` ```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#reversao-automatica-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": "a3f1c9d2-1b47-4e80-9c3a-2f5d6e7b8a91", "apiVersion": "1.1", "object": "seller", "event": "registration_review.required", "data": { "processId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "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": "ea115e44-7048-11ed-a1eb-0242ac120002", "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6" }, "origin": { "provider": "ZOOP", "providerId": "8f14e45f-ceea-467a-9e6f-6c1a5b3a1f2d" } } } ``` 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 Faça a integração via back-end direto com a nossa [API](/api-reference) ou use algum dos nossos [SDKs](/sdks). Use nosso plugin [VTEX](/sdks/plugins/vtex-connector) 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 Painel Inicial no Dashboard ### 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 Provedores Ilustrados **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 Painel de Merchants ### 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 Painel do Flow ### 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. Faça a integração via back-end direto com a nossa [API](/api-reference) ou use algum dos nossos [SDKs](/sdks). Use nosso plugin [VTEX](/sdks/plugins/vtex-connector) 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.** 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 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. É 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. ```bash theme={null} curl --location --request GET 'https://api.malga.io/v1/' \ --header 'X-Client-Id: ' \ --header 'X-Api-Key: ' ``` ## 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 A Malga disponibiliza uma lista de códigos de erro bem definida para facilitar a identificação dos diferentes tipos de problema que podem acontecer na integração. Através desta especificação de erros é possível identificar os erros que acontecem quando uma requisição é processada com falha na autorização, ou quando ela é rejeitada por erro funcional. As categorias de erro HTTP possíveis são: * (2xx) não autorizado; * (4xx) problema no conteúdo da requisição; * (5xx) erro interno; * falha na comunicação ou timeout. ## Código de retorno Para transações não autorizadas que são recusadas pelo emissor, a Malga fornece uma padronização dos códigos de retorno e uma recomendação de como você deve proceder com as principais falhas. ### Tabela de erros possíveis `error.type` | 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* | *200* | Transação não aprovada pelo provedor | 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 com os códigos de erro](/documentations/type-tables/declined-code) para o `error.declinedCode` # 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 Malga Dark ### Começando Desenvolvedor, este é o seu guia para testar e realizar as configurações necessárias para integrar com a Malga. Entenda como uma única integração pode evoluir a experiência de pagamentos do seu negócio 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. npx skills add [https://docs.malga.io](https://docs.malga.io) ## Consulte também Sua última integração de pagamentos agora mais simples e fácil de integrar Explore nossa documentação detalhada da API para integrar facilmente e aproveitar ao máximo nossos serviços Tenha todos os seus dados de pagamentos para análises e insights em um só lugar 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. 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 Tela de login da Dashboard 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 Interface de chaves na Dashboard A Malga conta com diversos tipos de integração, escolha a ideal para o seu negócio. Integre direto com a nossa API de Cobranças para criar transações para o seu negócio Crie Links de Pagamento utilizando a nossa API de Sessions Utilize nosso SDK para acelerar a sua integração Conheça as nossas soluções para integração rápida no front-end Vtex Crie Links de Pagamento sem nenhuma 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 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 Interface de ativação de conta na Dashboard **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. 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 | 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. 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.** ## 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 | Nulo | | Final 1 | SIM | Aprovado | Nulo | | Final 2 | NÃO | Falha | Aleatório `timeout` ou `processing_error` | | Qualquer outro final | NÃO | Reprovado | Nulo | ## 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. 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. # 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 É 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 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 **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#reversao-automatica-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 🔢 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 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: Data de criação (refere-se ao `created_at` da cobrança); ID da cobrança (charge ID); Valor original; Valor atual. Imagem da Listagem de Cobranças Imagem da Detalhe de Cobrança MELHORIAS **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; Correção na exibição das **informações da Transaction Request** no Histórico de Operações dentro do detalhe da cobrança; 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 🤩 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: Pesquisa de cobranças por NSU; Informações de cobranças recusadas no Painel de Dados; 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 *** Imagem da Busca pelo NSU aplicada *** Imagem da Listagem de Cobranças com opções de Busca, Filtros e Exportação 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 ### 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: **Valor atual da cobrança** (no momento da requisição); **Valor revertido;** **Valor da cobrança após a reversão do estorno pelo provedor.** 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 *** Imagem do Histórico de Operações com reversão de estorno 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#reversao-automatica-de-um-estorno-revert-void); MELHORIAS NO DASHBOARD Implementação de **nova tela de erro** por motivo inesperado; 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 🙌 ### 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 Imagem da Listagem de Cobranças na Dashboard 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 MELHORIAS NO DASHBOARD 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 🚀 **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: **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 🔗 **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) 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) Melhorias no Dashboard Adição da informação de NSU no detalhe da cobrança, junto às informações básicas da transação; 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 ### 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). **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; **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 **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 #### Eventos de **disputa** e **reversão de estorno** sinalizados nos detalhes de uma cobrança Disputa e reversão de estorno **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 **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 ### **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 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 ### **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 **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). **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 **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. 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 ### **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 Simples 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 **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**. 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 **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 Adyen Cielo Getnet Rede 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 ### **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 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 | 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
**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

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 ## 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 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 **PicPay agora possui suporte a PIX na Malga!🎉** Estamos felizes em anunciar que adicionamos o [método de pagamento PIX](/documentations/payment-methods/pix#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

### 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 🔗 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 **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) 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
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 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; 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
É 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 ## 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 ## 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 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 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. É 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
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. 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. 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 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. 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
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 3DS2 Agnóstico na Malga 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 **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` 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
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 Apple Pay na Malga 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 ### **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 Simples 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 **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). 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 **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": "469ed9e8-97d1-433a-a586-2fd282b7d9a4", "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" } } } ``` 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 - Tokenization V2 Source: https://docs.malga.io/release-notes/2025-03-25-Release-Notes **SDK Tokenization: mais segurança com Hosted Fields!** 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
Convida usuário **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 É 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 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! 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 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). 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. 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! 👨‍🍳 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 É 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
Estamos muito felizes em anunciar que lançamos a versão beta do motor de assinaturas da Malga. 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 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 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 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
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 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.
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
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
![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
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
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 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! 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
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
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 ## 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. Crie sessões (links) de pagamento que oferecem Click to Pay automaticamente Use Click to Pay diretamente pela API de cobranças 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
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! Veja como funciona o cancelamento agendado na documentação. 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
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! 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
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 🤓🎉 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). 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). 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.
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
## Nova experiência da Dashboard Novidade fresquinha na [dashboard da Malga](https://dashboard.malga.io/) 🎨✨ Nova tela de login da Malga 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
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). 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.
## 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. 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.
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 Tela do Dashboard com o controle de limite de pagamentos habilitado na criação de link 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. 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.
## 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). 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. 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). 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). 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. 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 **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). 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
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). 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.
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). 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. 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.
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. 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..
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). 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 Apple Pay na WorldPay e notificação de abertura de disputa na SafraPay, ambos em Beta.
## Apple Pay na WorldPay (Beta) O **Apple Pay** passa a ser suportado pela API da Malga em cobranças roteadas pela **WorldPay**. 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`. 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 Novo provedor antifraude
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 Novas queries cards e card no grupo Cards da Analytics API, consultando o novo índice card com tokens e transaction requests aninhados. A query allCards foi depreciada e será descontinuada em 2027.
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`. A query `allCards` será descontinuada em **2027**. Planeje a migração para `cards` (índice `card`), lembrando que o argumento `cardId` foi renomeado para `id`. 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.
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": "01964c5a-0001-7000-8000-000000000001", "status": "pending", "grossAmount": 20000, "netAmount": 19323 } ], "meta": { "totalItems": 32, "itemCount": 10, "itemsPerPage": 10, "totalPages": 4, "currentPage": 1 } } ``` 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": "b1612460-0fef-447d-9590-97825cf60cf6", "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. 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 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.
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 Bloco Composição financeira no detalhe da cobrança, com valor bruto, taxa e valor líquido 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). 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.
 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.
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. 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). 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.
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 Tela de Relatórios no Dashboard, com o Relatório de parcelas na listagem e o botão Exportar ## 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. 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. 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.
 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.
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 Detalhe de uma cobrança com estornos confirmados no Dashboard, com o download da carta de cancelamento e do comprovante de estorno ## 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). 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. 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.
 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 Quem usa o provedor Malga agora pode ter prazos de recebimento diferentes entre os recebedores.
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. 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 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.
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 sub-adquirê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. 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.
 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.
## 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). # Set 30, 2026 - Múltiplos cartões no Link de Pagamento Source: https://docs.malga.io/release-notes/2026-09-30-Release-Notes Crie links de pagamento com o valor da venda dividido entre 2 ou 3 cartões de crédito.
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 Checkout com a opção Combinar cartões de crédito 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 Checkout com o preenchimento de cada cartão 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 | 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). 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.
 Ficou com dúvida? Fale com a gente pelo e-mail [suporte@malga.io](mailto:suporte@malga.io). # Nov 03, 2026 - Taxa da plataforma por seller Source: https://docs.malga.io/release-notes/2026-11-03-Release-Notes Taxa da plataforma própria para cada seller da subconta, com a conta feita seller a seller e o detalhe por seller na resposta da cobrança.
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 **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. **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. 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.
 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.
  1. [Taxa da plataforma por seller](/release-notes/2026-11-03-Release-Notes)
  2. [Múltiplos cartões no Link de Pagamento](/release-notes/2026-09-30-Release-Notes)
  3. [Dashboard: seletor de empresa e subcontas no menu lateral](/release-notes/2026-09-24-Release-Notes)
  4. [Descrição na fatura em cobranças Rede](/release-notes/2026-09-23-Release-Notes)
  5. [Planos de venda no provedor Malga](/release-notes/2026-09-22-Release-Notes)
  6. [Relatório de parcelas](/release-notes/2026-09-09-Release-Notes)
  7. [Revisão cadastral de recebedores](/release-notes/2026-09-08-Release-Notes)
  8. [Composição financeira no detalhe da cobrança](/release-notes/2026-09-01-Release-Notes)
  9. [Listagem de antecipações e notifyOnPayout em recebedores](/release-notes/2026-08-31-Release-Notes)
  10. [Melhoria em Cards no Analytics API](/release-notes/2026-08-26-Release-Notes)
  11. [Koin](/release-notes/2026-08-10-Release-Notes)
  12. [Apple Pay WorldPay e disputa SafraPay (Beta)](/release-notes/2026-08-04-Release-Notes)
  13. [Simulação de status de recebedor no Sandbox](/release-notes/2026-07-20-Release-Notes)
  14. [Antifraude no link de pagamento](/release-notes/2026-07-13-Release-Notes)
  15. [Instruções de boleto em sessões](/release-notes/2026-06-30-Release-Notes)
  16. [Platform Fee](/release-notes/2026-06-18-Release-Notes)
  17. [Descontinuação de split agnóstico e payout eligible](/release-notes/2026-06-12-Release-Notes)
  18. [Beneficiário final NuPay e Antecipação avulsa](/release-notes/2026-05-29-Release-Notes)
  19. [Link de Pagamento 1:N](/release-notes/2026-05-08-Release-Notes)
  20. [Payouts API, salesPlanId em Sellers e Query Charges](/release-notes/2026-04-30-Release-Notes)
  21. [Split no Link de Pagamento](/release-notes/2026-04-29-Release-Notes)
  22. [Nova experiência da Dashboard](/release-notes/2026-04-23-Release-Notes)
  23. [Konduto](/release-notes/2026-04-15-Release-Notes)
  24. [Upload de documentos para Sellers](/release-notes/2026-04-08-Release-Notes)
  25. [Recorrência Barte](/release-notes/2026-03-09-Release-Notes)
  26. [Banrisul](/release-notes/2026-01-15-Release-Notes)
  27. [PayPal](/release-notes/2026-01-06-Release-Notes)
  1. [Zero dollar Safra Pay](/release-notes/2025-12-19-Release-Notes)
  2. [3DS2 Malga no Link](/release-notes/2025-11-25-Release-Notes)
  3. [Getnet Sep Pix Boleto](/release-notes/2025-11-24-Release-Notes)
  4. [Novo Link de Pagamento](/release-notes/2025-11-19-Release-Notes)
  5. [ApplePay Pagseguro](/release-notes/2025-11-12-Release-Notes)
  6. [B2E](/release-notes/2025-11-11-Release-Notes)
  7. [Assinaturas](/release-notes/2025-09-16-Release-Notes)
  8. [Split PagSeguro](/release-notes/2025-09-15-Release-Notes)
  9. [Bolt](/release-notes/2025-09-12-Release-Notes)
  10. [MapInvest](/release-notes/2025-09-08-Release-Notes)
  11. [GETNET SEP](/release-notes/2025-07-29-Release-Notes)
  12. [Split Pagarme](/release-notes/2025-05-16-Release-Notes)
  13. [Convite de Usuários](/release-notes/2025-05-07-Release-Notes)
  14. [Tokenization V2](/release-notes/2025-03-25-Release-Notes)
  15. [Nova funcionalidade 3DS DataOnly](/release-notes/2025-01-30-Release-Notes)
  16. [Novos campos de 3DSecure2](/release-notes/2025-01-03-Release-Notes)
  17. [Estorno parcial](/release-notes/2025-01-03-Release-Notes2)
  18. [Apple Pay](/release-notes/2025-01-02-Release-Notes)
  1. [3DS Malga](/release-notes/2024-10-22-Release-Notes)
  2. [Novos filtros no painel de dados](/release-notes/2024-10-07-Release-Notes)
  3. [Nova busca de cobranças](/release-notes/2024-07-05-Release-Notes)
  4. [Facilitadores de pagamentos](/release-notes/2024-07-03-Release-Notes)
  5. [Estorno Parcial de Split](/release-notes/2024-06-28-Release-Notes)
  6. [Exportação de cobranças](/release-notes/2024-06-24-Release-Notes)
  7. [Barte](/release-notes/2024-05-28-Release-Notes-2)
  8. [Tokens de Bandeira](/release-notes/2024-05-28-Release-Notes)
  9. [Correções Dash](/release-notes/2024-05-23-Release-Notes)
  10. [Export V2](/release-notes/2024-04-18-Release-Notes)
  11. [Filtro por provedor](/release-notes/2024-04-02-Release-Notes)
  12. [Pesquisa por NSU](/release-notes/2024-03-11-Release-Notes)
  13. [Cobrança por status](/release-notes/2024-03-06-Release-Notes)
  14. [Reversão de estorno](/release-notes/2024-03-05-Release-Notes)
  15. [Safrapay](/release-notes/2024-02-28-Release-Notes)
  16. [Parcelas pela Drip](/release-notes/2024-02-21-Release-Notes)
  17. [Detalhes de estorno](/release-notes/2024-02-09-Release-Notes)
  18. [Novos campos no export](/release-notes/2024-01-31-Release-Notes)
  19. [Novos SDKs](/release-notes/2024-01-26-Release-Notes)
  20. [Filtro por subconta](/release-notes/2024-01-19-Release-Notes)
  21. [Novos campos de antifraude](/release-notes/2024-01-17-Release-Notes)
  22. [Novidades Pagarme V5](/release-notes/2024-01-16-Release-Notes)
  23. [Listagem de cartões](/release-notes/2024-01-05-Release-Notes)
  1. [Pix com a Adyen](/release-notes/2023-01-09-Release-Notes)
  2. [Melhorias no filtro e cadastro no Dashboard](/release-notes/2023-01-10-Release-Notes)
  3. [Plug agora é Malga!](/release-notes/2023-01-11-Release-Notes)
  4. [Abertura de Disputa](/release-notes/2023-01-17-Release-Notes)
  5. [Pix na PagSeguro](/release-notes/2023-01-24-Release-Notes)
  6. [Melhorias nos filtros e mais](/release-notes/2023-01-25-Release-Notes)
  7. [Melhorias com a Zoop](/release-notes/2023-01-27-Release-Notes)
  8. [Suporte a antifraude e customers no Malga Checkout](/release-notes/2023-02-03-Release-Notes)
  9. [Notificação de Disputas na Adyen](/release-notes/2023-02-07-Release-Notes)
  10. [Novo Provedor Klap](/release-notes/2023-02-10-Release-Notes)
  11. [Mais flexibilidade no Checkout Malga](/release-notes/2023-03-01-Release-Notes)
  12. [Novo campo de transactionConfig no checkout](/release-notes/2023-03-16-Release-Notes)
  13. [Melhorias Checkout Full e link de pagamento](/release-notes/2023-03-31-Release-Notes)
  14. [Exportação de cobranças](/release-notes/2023-04-04-Release-Notes)
  15. [Split no Pix e Boleto da Pagarme](/release-notes/2023-04-14-Release-Notes)
  16. [Listagem e detalhes de subcontas](/release-notes/2023-04-17-Release-Notes)
  17. [Nomes personalizáveis às subcontas](/release-notes/2023-05-15-Release-Notes)
  18. [Gestão de Split através do Dashboard](/release-notes/2023-05-30-Release-Notes)
  19. [Validação de cartões](/release-notes/2023-06-01-Release-Notes)
  20. [Novo nome do ambiente de testes da Malga](/release-notes/2023-06-06-Release-Notes)
  21. [Propriedades opcionais de cvvCheck e cvvCheckMerchantId](/release-notes/2023-06-16-Release-Notes)
  22. [Mudanças no contrato de customer no Malga Checkout](/release-notes/2023-06-20-Release-Notes)
  23. [Fluxos Inteligentes no Dashboard](/release-notes/2023-06-27-Release-Notes)
  24. [Clearsale Tickets](/release-notes/2023-07-10-Release-Notes)
  25. [Área de Recebedores no Dashboard](/release-notes/2023-07-11-Release-Notes)
  26. [Pix Nupay](/release-notes/2023-07-13-Release-Notes)
  27. [Voucher](/release-notes/2023-07-28-Release-Notes)
  28. [Drip e Worldpay](/release-notes/2023-08-03-Release-Notes)
  29. [Suporte a Zero Dollar na Rede](/release-notes/2023-08-06-Release-Notes)
  30. [Idempotency Key](/release-notes/2023-08-07-2-Release-Notes)
  31. [Nupay e Drip no Malga Checkout](/release-notes/2023-08-07-Release-Notes)
  32. [Tokenização do CVV nas transações](/release-notes/2023-08-08-Release-Notes)
  33. [Analytics API](/release-notes/2023-08-09-Release-Notes)
  34. [Tokenização do cartão voucher nas transações](/release-notes/2023-08-10-Release-Notes)
  35. [Voucher com provedor Pagarme](/release-notes/2023-08-25-Release-Notes)
  36. [Novos filtros na Analytics API](/release-notes/2023-08-30-Release-Notes)
  37. [Novo menu de usuários & Melhorias](/release-notes/2023-08-31-Release-Notes)
  38. [Novo step notificação no webhooks](/release-notes/2023-09-18-Release-Notes)
  39. [Informação de rastreabilidade de cobranças](/release-notes/2023-09-19-Release-Notes)
  40. [Novos dados no relatório de cobranças](/release-notes/2023-09-20-Release-Notes)
  41. [Melhorias validação de cartão](/release-notes/2023-09-26-Release-Notes)
  42. [Novas queries na Analytics API](/release-notes/2023-10-06-Release-Notes)
  43. [Painel de Dados no Dashboard Malga](/release-notes/2023-10-16-Release-Notes)
  44. [Suporte a Zero Dollar na Pagseguro](/release-notes/2023-10-23-Release-Notes)
  45. [Malga e VTEX](/release-notes/2023-10-27-Release-Notes)
  46. [Teste de Performance (Black Friday 2023\)](/release-notes/2023-11-01-Release-Notes)
  47. [Preparativos para Black Friday 2023](/release-notes/2023-11-07-Release-Notes)
  48. [PIX v2 no Banco do Brasil](/release-notes/2023-11-09-Release-Notes)
  49. [Módulo para Magento 2](/release-notes/2023-11-22-Release-Notes)
  50. [Adição de Campos à Charges API e Sessions API](/release-notes/2023-12-11-Release-Notes)
  51. [Crédito na Pagarme V5](/release-notes/2023-12-19-Release-Notes)
  52. [Novo tipo de documento em Customers](/release-notes/2023-12-20-Release-Notes)
  1. [Suporte ao provedor Mercado Pago](/release-notes/2022-01-17-Release-Notes)
  2. [Boleto no retorno de transactionRequest e mais](/release-notes/2022-02-10-Release-Notes)
  3. [Major release](/release-notes/2022-03-25-Release-Notes)
  4. [Suporte a boleto por BS2](/release-notes/2022-05-30-Release-Notes)
  5. [New Dashboard](/release-notes/2022-06-07-Release-Notes)
  6. [Novos meios de pagamento com Mercado Pago e mais](/release-notes/2022-06-22-Release-Notes)
  7. [Chaves de sandbox no Dashboard](/release-notes/2022-08-01-Release-Notes)
  8. [Listagem de Customers no Dash e mais](/release-notes/2022-08-17-Release-Notes)
  9. [Análise de risco utilizando provedores antifraude](/release-notes/2022-09-05-Release-Notes)
  10. [Nupay e Braintree](/release-notes/2022-10-10-Release-Notes)
  11. [Busca por id e suporte a estorno no Dashboard](/release-notes/2022-11-11-Release-Notes)
  12. [Link de Pagamento](/release-notes/2022-11-16-Release-Notes)
  13. [Eventos assíncronos com webhook](/release-notes/2022-11-24-Release-Notes)
  14. [Fluxo Inteligente](/release-notes/2022-11-29-Release-Notes)
  15. [Split de Pagamentos](/release-notes/2022-12-20-Release-Notes)
  16. [runBeforeCharge option no Antifraude](/release-notes/2022-12-22-Release-Notes)
  1. [Pix atrelado a customer](/release-notes/2021-07-28-Release-Notes)
  2. [Features pagarme, fingerprint, fluxo de estorno e mais](/release-notes/2021-10-20-Release-Notes)
  3. [Novidades no Checkout](/release-notes/2021-11-08-Release-Notes)
  4. [Crédito pela REDE](/release-notes/2021-11-29-Release-Notes)
  5. [Novidades em tokenização de cartões](/release-notes/2021-12-23-Release-Notes)
 # 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.auth.createPublicKey({ scope: ["tokens"], expires: 60, }); ``` ```typescript theme={null} { publicKey: 'd6452548-70f3-4721-9090-5320a7e19776', createdAt: '2023-12-31T14:12:37.735Z', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', expires: 60, scope: ['tokens'], } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Escopos suportados da chave. Os valores suportados são: * `customers` * `cards` * `tokens` * `charges` * `webhooks` * `sessions` * `auth` * `reports` * `flows` * `sellers` * `providers` * `subscriptions` * `graphql` (Analytics API) 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.cards.create({ tokenId: 'a666822c-a31c-43ba-aa5d-96daa9d91b6b', zeroDollar: { cvvCheck: true, merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', }, }) ``` ```typescript theme={null} { id: '290d6f2e-7860-4722-b461-fcc9c27a7ca6', status: 'active', createdAt: '2023-12-31T03:00:00.000Z', clientId: '9c80a722-30dd-4bc1-9270-20d505671d1a', 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. ID do cartão tokenizado Dados da validação de cartão com Zero Dollar ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.cards.find('290d6f2e-7860-4722-b461-fcc9c27a7ca6') ``` ```typescript theme={null} { id: '290d6f2e-7860-4722-b461-fcc9c27a7ca6', status: 'active', createdAt: '2023-12-31T03:00:00.000Z', clientId: '9c80a722-30dd-4bc1-9270-20d505671d1a', 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.cards.list() ``` ```typescript theme={null} { items: [ { id: '290d6f2e-7860-4722-b461-fcc9c27a7ca6', status: 'active', createdAt: '2023-12-31T03:00:00.000Z', clientId: '9c80a722-30dd-4bc1-9270-20d505671d1a', 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. Número da página que deverá ser listada 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.cards.tokenization({ holderName: 'João da Silva', number: '5453881028277600', cvv: '170', expirationDate: '10/2030', }) ``` ```typescript theme={null} { tokenId: 'a666822c-a31c-43ba-aa5d-96daa9d91b6b' } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Nome do portador do cartão Número do cartão Código de segurança do cartão 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.cards.tokenization({ cvv: '170', }) ``` ```typescript theme={null} { tokenId: 'a666822c-a31c-43ba-aa5d-96daa9d91b6b' } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.capture( 'e09ef791-1aaa-4b11-8173-698f2689a04d', { amount: 100 } ) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: '5da7d8d4-55e9-4268-bfff-a5992a0b1d43', createdAt: '2023-12-31T19:19:45.013Z', updatedAt: '2023-12-31T19:19:45.044Z', idempotencyKey: '4bd7cd89-ef1d-44aa-a35d-b1eabafc86a6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: '123123', authorizationNsu: '123123', requestStatus: 'success', requestType: 'capture', responseTs: '11ms', providerAuthorization: { networkAuthorizationCode: '123123', networkResponseCode: '123123', } }, { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 da cobrança Segundo parâmetro 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', amount: 100, paymentMethod: { type: 'boleto' }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '2c48166b-51fe-4d8d-a450-1385df8a95b9', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. ID do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com boleto Método de pagamento que será utilizado na cobrança
Com boleto sempre será boleto Data de vencimento do boleto Instruções do boleto Dados opcionais da condição de juros para pagamento em atraso Dias após a expiração do boleto que ocorrerá a cobrança dos juros Valor em centavos da taxa de juros que será cobrado ao dia Valor em porcentagem da taxa de juros que será cobrado ao mês Dados opcionais da condição de multa para pagamento em atraso Dias após a expiração do boleto que ocorrerá a cobrança da multa Valor em centavos da multa Valor em porcentagem da multa Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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. 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', amount: 100, paymentMethod: { type: 'credit', installments: 1, card: { holderName: 'João da Silva', number: '5453881028277600', cvv: '170', expirationDate: '10/2030', }, }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. Dados do pagamento com cartão Método de pagamento que será utilizado na cobrança
Com cartão de crédito sempre será credit Dados do cartão de crédito Nome do portador do cartão Número do cartão Código de segurança do cartão Data de validade do cartão Dados da validação de cartão com Zero Dollar ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar Valide o CVV do cartão no momento da criação Número de parcelas Vincula o cartão automaticamente com o customer Define se a cobrança deve ser capturada automaticamente Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Descrição da cobrança que irá aparecer na fatura do cartão Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização das funcionalidades de antifraude Valor em minutos de SLA máximo de análise do pedido Dados do cliente Nome do cliente E-mail do cliente Telefone do cliente Número do documento do cliente Tipo do documento do cliente Data de registro do cliente Dados do endereço de entrega do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do endereço de cobrança do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do navegador do cliente Fingerprint gerado dos dados do navegador Indica se os cookies foram aceitados E-mail logado no navegador Nome do host do usuário Endereço de IP do usuário User-Agent do navegador Dados dos itens do carrinho Nome do produto Quantidade do produto Identificador único do item na loja Preço de cada produto Definição do índice de risco do produto

Os tipos suportados são: Low ou High Descrição do produto Categoria do produto Localidade onde ocorrerá o evento Data do evento Tipo do evento Definição do gênero do evento Dados do ingresso Quantidade total de ingressos à venda Quantidade de vezes que o evento será realizado na casa Taxa de conveniência Quantidade de ingressos com valor integral Quantidade de ingresso com desconto (meia entrada) Lote do ingresso Dados do endereço do evento Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do aparelho do cliente Nome do modelo do aparelho Capacidade da memória RAM do aparelho Capacidade de armazenamento do aparelho Quantidade de armazenamento livre do aparelho Resolução do aparelho Dados do sistema operacional do aparelho Tipo do sistema operacional Versão do sistema operacional Dados dos atributos do aparelho Aparelho possui flash na câmera Aparelho pode realizar chamadas Aparelho pode enviar SMS Aparelho possui câmera de vídeo Quantidade de CPUs do aparelho Aparelho possui simulador Linguagem do aparelho Idioma do aparelho Plataforma do sistema operacional Nome do aparelho Família do aparelho Aparelho possui display de retina Aparelho possui câmera Modelo do aparelho Aparelho possui câmera frontal Dados adicionais do aparelho Nome do atributo do fornecedor Valor do atributo do fornecedor Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados para utilização da funcionalidade de 3DS URL para redirecionamento da autenticação URL de origem da requisição Dados do navegador do cliente O Accept do cabeçalho de requisição HTTP A profundidade de cores da tela Indica se o Java está habilitado Indica se o JavaScript está habilitado A linguagem utilizada pelo sistema do usuário Altura da tela Largura da tela Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual O User-Agent do cabeçalho de requisição HTTP Endereço de IP do usuário Dados do endereço de cobrança Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do endereço de envio Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do titular do cartão E-mail do titular do cartão Telefone do titular do cartão Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', amount: 100, paymentMethod: { type: 'drip', }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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/e09ef791-1aaa-4b11-8173-698f2689a04d', successRedirectUrl: null, cancelRedirectUrl: null, }, paymentSource: { sourceType: 'customer', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: null, authorizationNsu: null, requestStatus: 'success', requestType: 'pending', responseTs: '11ms', drip: { paymentUrl: 'https://sdb-drip-checkout-url.com.br/e09ef791-1aaa-4b11-8173-698f2689a04d', } } ], appInfo: null } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. ID do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com Drip Método de pagamento que será utilizado na cobrança
Com Drip sempre será drip Link de redirecionamento em caso de aprovação do pagamento no ambiente de checkout da Drip Link de redirecionamento em caso de cancelamento do pagamento no ambiente de checkout da Drip Dados do navegador do cliente Endereço IP do cliente Fingerprint do navegador utilizado pelo cliente Dados dos produtos do pedido Identificador único do produto Nome do produto Preço do produto Quantidade do produto Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', orderId: '3c066bcb-0fe6-4ec3-be2e-9158b12ea2e2', amount: 100, paymentMethod: { type: 'nupay', items: [ { sku: '123', name: 'Produto 1', quantity: 1, unitPrice: 100, risk: 'Low', } ] }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', description: null, orderId: '3c066bcb-0fe6-4ec3-be2e-9158b12ea2e2', 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: '2c48166b-51fe-4d8d-a450-1385df8a95b9', }, 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: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. ID do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com NuPay Método de pagamento que será utilizado na cobrança
Com NuPay sempre será nupay Dados dos produtos do pedido Nome do produto Quantidade do produto Identificador único do item na loja Preço de cada produto Definição do índice de risco do produto

Os tipos suportados são: Low ou High URL de origem da cobrança URL para a qual o cliente será redirecionado após finalizar o pagamento URL para onde o cliente será direcionado caso escolha não finalizar o pagamento e cancele o pedido Total de taxas aplicadas em centavos Tempo em minutos para a expiração de uma cobrança criada que não tenha sido paga Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', amount: 100, paymentMethod: { type: 'pix', expiresIn: 3600 }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '2c48166b-51fe-4d8d-a450-1385df8a95b9', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. ID do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com PIX Método de pagamento que será utilizado na cobrança
Com PIX sempre será pix Tempo de expiração do PIX em segundos Dados adicionais para o pagamento Nome do dado adicional Valor do dado adicional Dados dos produtos do pedido Identificador único do produto Nome do produto Preço do produto Quantidade do produto Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', amount: 100, paymentMethod: { type: 'credit', installments: 1, cardId: '584e5835-d81f-4dad-b9ca-0d58e7a4734e' }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '584e5835-d81f-4dad-b9ca-0d58e7a4734e', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com cartão Método de pagamento que será utilizado na cobrança
Com cartão de crédito sempre será credit ID do cartão já armazenado CVV do cartão sem ser tokenizado para verificação do cartão CVV tokenizado para verificação do cartão Número de parcelas Vincula o cartão automaticamente com o customer Define se a cobrança deve ser capturada automaticamente Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Descrição da cobrança que irá aparecer na fatura do cartão Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização das funcionalidades de antifraude Valor em minutos de SLA máximo de análise do pedido Dados do cliente Nome do cliente E-mail do cliente Telefone do cliente Número do documento do cliente Tipo do documento do cliente Data de registro do cliente Dados do endereço de entrega do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do endereço de cobrança do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do navegador do cliente Fingerprint gerado dos dados do navegador Indica se os cookies foram aceitados E-mail logado no navegador Nome do host do usuário Endereço de IP do usuário User-Agent do navegador Dados dos itens do carrinho Nome do produto Quantidade do produto Identificador único do item na loja Preço de cada produto Definição do índice de risco do produto

Os tipos suportados são: Low ou High Descrição do produto Categoria do produto Localidade onde ocorrerá o evento Data do evento Tipo do evento Definição do gênero do evento Dados do ingresso Quantidade total de ingressos à venda Quantidade de vezes que o evento será realizado na casa Taxa de conveniência Quantidade de ingressos com valor integral Quantidade de ingresso com desconto (meia entrada) Lote do ingresso Dados do endereço do evento Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do aparelho do cliente Nome do modelo do aparelho Capacidade da memória RAM do aparelho Capacidade de armazenamento do aparelho Quantidade de armazenamento livre do aparelho Resolução do aparelho Dados do sistema operacional do aparelho Tipo do sistema operacional Versão do sistema operacional Dados dos atributos do aparelho Aparelho possui flash na câmera Aparelho pode realizar chamadas Aparelho pode enviar SMS Aparelho possui câmera de vídeo Quantidade de CPUs do aparelho Aparelho possui simulador Linguagem do aparelho Idioma do aparelho Plataforma do sistema operacional Nome do aparelho Família do aparelho Aparelho possui display de retina Aparelho possui câmera Modelo do aparelho Aparelho possui câmera frontal Dados adicionais do aparelho Nome do atributo do fornecedor Valor do atributo do fornecedor Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados para utilização da funcionalidade de 3DS URL para redirecionamento da autenticação URL de origem da requisição Dados do navegador do cliente O Accept do cabeçalho de requisição HTTP A profundidade de cores da tela Indica se o Java está habilitado Indica se o JavaScript está habilitado A linguagem utilizada pelo sistema do usuário Altura da tela Largura da tela Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual O User-Agent do cabeçalho de requisição HTTP Endereço de IP do usuário Dados do endereço de cobrança Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do endereço de envio Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do titular do cartão E-mail do titular do cartão Telefone do titular do cartão Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ publicKey: 'd04cecd3-3d16-4942-a169-1f08af3c8b32', sessionId: '4693cc46-5e28-4996-a964-f7212499323f', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', paymentMethod: { type: 'pix', }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', sessionId: '4693cc46-5e28-4996-a964-f7212499323f' 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: '2c48166b-51fe-4d8d-a450-1385df8a95b9', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. Chave pública gerada unicamente para o pagamento da session ID da session que será usada para a cobrança Dados do pagamento conforme método de pagamento usado ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização das funcionalidades de antifraude Valor em minutos de SLA máximo de análise do pedido Dados do cliente Nome do cliente E-mail do cliente Telefone do cliente Número do documento do cliente Tipo do documento do cliente Data de registro do cliente Dados do endereço de entrega do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do endereço de cobrança do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do navegador do cliente Fingerprint gerado dos dados do navegador Indica se os cookies foram aceitados E-mail logado no navegador Nome do host do usuário Endereço de IP do usuário User-Agent do navegador Dados dos itens do carrinho Nome do produto Quantidade do produto Identificador único do item na loja Preço de cada produto Definição do índice de risco do produto

Os tipos suportados são: Low ou High Descrição do produto Categoria do produto Localidade onde ocorrerá o evento Data do evento Tipo do evento Definição do gênero do evento Dados do ingresso Quantidade total de ingressos à venda Quantidade de vezes que o evento será realizado na casa Taxa de conveniência Quantidade de ingressos com valor integral Quantidade de ingresso com desconto (meia entrada) Lote do ingresso Dados do endereço do evento Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do aparelho do cliente Nome do modelo do aparelho Capacidade da memória RAM do aparelho Capacidade de armazenamento do aparelho Quantidade de armazenamento livre do aparelho Resolução do aparelho Dados do sistema operacional do aparelho Tipo do sistema operacional Versão do sistema operacional Dados dos atributos do aparelho Aparelho possui flash na câmera Aparelho pode realizar chamadas Aparelho pode enviar SMS Aparelho possui câmera de vídeo Quantidade de CPUs do aparelho Aparelho possui simulador Linguagem do aparelho Idioma do aparelho Plataforma do sistema operacional Nome do aparelho Família do aparelho Aparelho possui display de retina Aparelho possui câmera Modelo do aparelho Aparelho possui câmera frontal Dados adicionais do aparelho Nome do atributo do fornecedor Valor do atributo do fornecedor Dados para utilização da funcionalidade de 3DS URL para redirecionamento da autenticação URL de origem da requisição Dados do navegador do cliente O Accept do cabeçalho de requisição HTTP A profundidade de cores da tela Indica se o Java está habilitado Indica se o JavaScript está habilitado A linguagem utilizada pelo sistema do usuário Altura da tela Largura da tela Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual O User-Agent do cabeçalho de requisição HTTP Endereço de IP do usuário Dados do endereço de cobrança Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do endereço de envio Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do titular do cartão E-mail do titular do cartão Telefone do titular do cartão Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.charges.create({ merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1", amount: 100, paymentMethod: { type: "credit", installments: 1, tokenId: "b7288045-80bd-4d17-8280-4d96d7a44e47", }, }); ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', tokenId: 'b7288045-80bd-4d17-8280-4d96d7a44e47', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com cartão Método de pagamento que será utilizado na cobrança
Com cartão de crédito sempre será credit ID do cartão tokenizado Número de parcelas Vincula o cartão automaticamente com o customer Define se a cobrança deve ser capturada automaticamente Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Descrição da cobrança que irá aparecer na fatura do cartão Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização das funcionalidades de antifraude Valor em minutos de SLA máximo de análise do pedido Dados do cliente Nome do cliente E-mail do cliente Telefone do cliente Número do documento do cliente Tipo do documento do cliente Data de registro do cliente Dados do endereço de entrega do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do endereço de cobrança do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do navegador do cliente Fingerprint gerado dos dados do navegador Indica se os cookies foram aceitados E-mail logado no navegador Nome do host do usuário Endereço de IP do usuário User-Agent do navegador Dados dos itens do carrinho Nome do produto Quantidade do produto Identificador único do item na loja Preço de cada produto Definição do índice de risco do produto

Os tipos suportados são: Low ou High Descrição do produto Categoria do produto Localidade onde ocorrerá o evento Data do evento Tipo do evento Definição do gênero do evento Dados do ingresso Quantidade total de ingressos à venda Quantidade de vezes que o evento será realizado na casa Taxa de conveniência Quantidade de ingressos com valor integral Quantidade de ingresso com desconto (meia entrada) Lote do ingresso Dados do endereço do evento Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do aparelho do cliente Nome do modelo do aparelho Capacidade da memória RAM do aparelho Capacidade de armazenamento do aparelho Quantidade de armazenamento livre do aparelho Resolução do aparelho Dados do sistema operacional do aparelho Tipo do sistema operacional Versão do sistema operacional Dados dos atributos do aparelho Aparelho possui flash na câmera Aparelho pode realizar chamadas Aparelho pode enviar SMS Aparelho possui câmera de vídeo Quantidade de CPUs do aparelho Aparelho possui simulador Linguagem do aparelho Idioma do aparelho Plataforma do sistema operacional Nome do aparelho Família do aparelho Aparelho possui display de retina Aparelho possui câmera Modelo do aparelho Aparelho possui câmera frontal Dados adicionais do aparelho Nome do atributo do fornecedor Valor do atributo do fornecedor Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados para utilização da funcionalidade de 3DS URL para redirecionamento da autenticação URL de origem da requisição Dados do navegador do cliente O Accept do cabeçalho de requisição HTTP A profundidade de cores da tela Indica se o Java está habilitado Indica se o JavaScript está habilitado A linguagem utilizada pelo sistema do usuário Altura da tela Largura da tela Diferença em minutos do deslocamento de fuso horário entre o UTC e a localidade atual O User-Agent do cabeçalho de requisição HTTP Endereço de IP do usuário Dados do endereço de cobrança Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do endereço de envio Cidade País Estado Nome da rua, avenida ou travessa Número da rua Código postal Dados do titular do cartão E-mail do titular do cartão Telefone do titular do cartão Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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. 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', amount: 100, paymentMethod: { type: 'voucher', card: { holderName: 'João da Silva', number: '5453881028277600', cvv: '170', expirationDate: '10/2030', }, }, }) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 do Merchant que será usado na cobrança Valor da cobrança em centavos Dados do pagamento com voucher Método de pagamento que será utilizado na cobrança
Com voucher sempre será voucher Dados do cartão Nome do portador do cartão Número do cartão Código de segurança do cartão Data de validade do cartão Dados da validação de cartão com Zero Dollar ID do Merchant com pelo menos um provedor com suporte ao Zero Dollar Valide o CVV do cartão no momento da criação Dados dos produtos do pedido Identificador único do produto Nome do produto Preço do produto Quantidade do produto Vincula o cartão automaticamente com o customer Identificador único da cobrança do lado do cliente para conciliação futura Identificador único da cobrança do lado do cliente utilizado para referenciar a cobrança do lado do provedor Descrição da cobrança Descrição da cobrança que irá aparecer na fatura do cartão Moeda que será usada para a cobrança ID do Customer que será usado na cobrança Dados do cliente para criação e vinculação automática à cobrança Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados do endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados para utilização da funcionalidade de Split ID do Recebedor Indica se o recebedor vinculado à regra será cobrado pelas taxas da transação Indica se o recebedor atrelado assumirá os riscos de chargeback da transação Porcentagem do valor da transação que será enviada ao recebedor Valor que será enviado ao recebedor Informações sobre as taxas que serão cobradas do recebedor, apenas para sellers com provedor Braspag 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 Indica valor em centavos a ser cobrado por transação capturada. É descontado no momento da “montagem” da agenda financeira Dados adicionais para uso em condicionais dos Fluxos Inteligentes Dados adicionais da cobrança enviados na criação da mesma Dados para a rastreabilidade da cobrança Dados sobre o dispositivo Nome do sistema operacional Versão do sistema operacional Dados sobre o sistema proprietário de captura do merchant Nome da empresa e/ou plataforma 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.find('e09ef791-1aaa-4b11-8173-698f2689a04d') ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.list() ``` ```typescript theme={null} { items: [ { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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. Número da página que deverá ser listada Limite de itens por página Ordenação da listagem, padrão é ASC

Os valores suportados são: ASC ou DESC Data inicial do período filtrado Data final do período filtrado ID do Merchant Valor da cobrança Identificador único da cobrança do lado do cliente para conciliação futura Cobranças que foram feitas com Split de pagamentos Cobrança vinculada à Sessão Status atual da cobrança Método de pagamento da cobrança 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.charges.refund( 'e09ef791-1aaa-4b11-8173-698f2689a04d', { amount: 100 } ) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: '5da7d8d4-55e9-4268-bfff-a5992a0b1d43', createdAt: '2023-12-31T19:19:45.013Z', updatedAt: '2023-12-31T19:19:45.044Z', idempotencyKey: '4bd7cd89-ef1d-44aa-a35d-b1eabafc86a6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: '123123', authorizationNsu: '123123', requestStatus: 'success', requestType: 'void', responseTs: '11ms', providerAuthorization: { networkAuthorizationCode: '123123', networkResponseCode: '123123', } }, { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 da cobrança Segundo parâmetro Valor da cobrança a ser estornado 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) 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' } }) ``` ```typescript theme={null} { id: '2c48166b-51fe-4d8d-a450-1385df8a95b9', name: 'João da Silva', email: 'joao.silva@test.com', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', 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. Nome do cliente E-mail do cliente Telefone do cliente Dados do documento do cliente Tipo do documento Número do documento País do documento Dados de endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.find('2c48166b-51fe-4d8d-a450-1385df8a95b9') ``` ```typescript theme={null} { id: '2c48166b-51fe-4d8d-a450-1385df8a95b9', name: 'João da Silva', email: 'joao.silva@test.com', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.linkCard( '2c48166b-51fe-4d8d-a450-1385df8a95b9', { cardId: '290d6f2e-7860-4722-b461-fcc9c27a7ca6' } ) ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. ID do cliente Segundo parâmetro 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.cards('2c48166b-51fe-4d8d-a450-1385df8a95b9') ``` ```typescript theme={null} [ { id: '290d6f2e-7860-4722-b461-fcc9c27a7ca6', status: 'active', createdAt: '2023-12-31T03:00:00.000Z', clientId: '9c80a722-30dd-4bc1-9270-20d505671d1a', customerId: '2c48166b-51fe-4d8d-a450-1385df8a95b9', 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.list() ``` ```typescript theme={null} { items: [ { id: '2c48166b-51fe-4d8d-a450-1385df8a95b9', name: 'João da Silva', email: 'joao.silva@test.com', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', 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. Número da página que deverá ser listada Limite de itens por página Ordenação da listagem, padrão é ASC

Os valores suportados são: ASC ou DESC Tipo do documento 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.remove('2c48166b-51fe-4d8d-a450-1385df8a95b9') ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.update( '2c48166b-51fe-4d8d-a450-1385df8a95b9', { 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' } } ) ``` ```typescript theme={null} { id: '2c48166b-51fe-4d8d-a450-1385df8a95b9', updatedAt: '2023-12-31T20:36:30.741Z', createdAt: '2023-12-31T19:36:30.741Z', idempotencyKey: null, requestId: null, clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', cardId: null, name: 'João da Silva', email: 'joao.silva@test.com', phoneNumber: '99999999999', documentNumber: '99999999999', documentType: 'cpf', documentCountry: 'BR', address: { country: 'BR', id: '5818e483-5914-46ee-a409-af4dd915a533', 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 do cliente Segundo parâmetro Nome do cliente Telefone do cliente Dados de endereço do cliente Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista # Entendendo Malga API SDK Source: https://docs.malga.io/sdks/api-sdks/docs/intro 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: ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", options: { sandbox: true, http: { retries: 3, retryDelay: 10000, }, }, }); ``` Abaixo está a lista detalhada com todos os parâmetros de configuração disponíveis. Chave de acesso à API Identificador único da sua conta na Malga Configurações adicionais Define se integração está rodando no ambiente de teste ou produção Configurações das requisições http Número de retentativa de uma requisição em caso de falha para evitar condições de corrida 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: ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.charges.create( { merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1", amount: 100, paymentMethod: { type: "credit", installments: 1, card: { holderName: "João da Silva", number: "5453881028277600", cvv: "170", expirationDate: "10/2030", }, }, }, { idempotencyKey: "518eb962-cccd-4bc3-a497-4e48335dc8c4" } ); ``` 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. Objeto com os detalhes do erro Tipo do erro Status code da requisição Mensagem resumida do erro Mensagem detalhada do erro contendo os campos 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', options: { sandbox: true } }) await malga.sandbox.changeAntifraudStatus( 'e09ef791-1aaa-4b11-8173-698f2689a04d', { status: 'reproved' } ) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: '5da7d8d4-55e9-4268-bfff-a5992a0b1d43', createdAt: '2023-12-31T19:19:45.013Z', updatedAt: '2023-12-31T19:19:45.044Z', idempotencyKey: '4bd7cd89-ef1d-44aa-a35d-b1eabafc86a6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: '123123', authorizationNsu: '123123', requestStatus: 'success', requestType: 'void', responseTs: '11ms', providerAuthorization: { networkAuthorizationCode: '123123', networkResponseCode: '123123', } }, { id: '5da7d8d4-55e9-4268-bfff-a5992a0b1d43', createdAt: '2023-12-31T19:19:45.013Z', updatedAt: '2023-12-31T19:19:45.044Z', idempotencyKey: '4bd7cd89-ef1d-44aa-a35d-b1eabafc86a6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'ANTIFRAUD_SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: '123123', authorizationNsu: '123123', requestStatus: 'success', requestType: 'anti_fraud', responseTs: '19ms', fraudAnalysis: { score: 85, status: 'reproved', } }, { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 da Cobrança Segundo parâmetro 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', options: { sandbox: true } }) await malga.sandbox.changeChargeStatus( 'e09ef791-1aaa-4b11-8173-698f2689a04d', { status: 'authorized' } ) ``` ```typescript theme={null} { id: 'e09ef791-1aaa-4b11-8173-698f2689a04d', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: '3db399d3-44c1-49fe-ab26-6fb00c161337', }, transactionRequests: [ { id: '5da7d8d4-55e9-4268-bfff-a5992a0b1d43', createdAt: '2023-12-31T19:19:45.013Z', updatedAt: '2023-12-31T19:19:45.044Z', idempotencyKey: '4bd7cd89-ef1d-44aa-a35d-b1eabafc86a6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', amount: 100, authorizationCode: '123123', authorizationNsu: '123123', requestStatus: 'success', requestType: 'authorization', responseTs: '11ms', providerAuthorization: { networkAuthorizationCode: '123123', networkResponseCode: '123123', } }, { id: 'a6cc6bda-3f6d-4277-8ea2-e4bbd9166f16', createdAt: '2023-12-31T18:19:45.013Z', updatedAt: '2023-12-31T18:19:45.044Z', idempotencyKey: '3b42ede3-15a8-4d81-b6e9-54c5762776c6', providerId: '694f7eee-2966-4825-a847-65d070cbdece', providerType: 'SANDBOX', transactionId: '18242a4d-dd35-475f-b79b-5cbe8f9d1fea', 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 da Cobrança Segundo parâmetro 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', options: { sandbox: true } }) await malga.sandbox.generateCard({ brand: 'Mastercard', status: 'expired_card' }) ``` ```typescript theme={null} { number: '5462320441541663', cvv: '830', expirationDate: '03/2025', } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Bandeira do cartão

Os tipos suportados são: Mastercard, Visa, Amex, HiperCard ou DinersClub 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.sellers.create({ merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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' } }) ``` ```typescript theme={null} { id: 'c1015d17-f123-499f-aaad-32e7f7812132', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', status: 'pending', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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 do Merchant que será vinculado o recebedor Código de segmento do lojista no adquirente Dados do recebedor Nome do recebedor E-mail do recebedor Telefone do recebedor Data de nascimento do recebedor Dados do documento do recebedor Tipo do documento Número do documento País do documento Dados de endereço do recebedor Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do estabelecimento do recebedor Nome do estabelecimento do recebedor E-mail do estabelecimento do recebedor Telefone do estabelecimento do recebedor Data de abertura do estabelecimento do recebedor Descrição do estabelecimento do recebedor Site do estabelecimento do recebedor Twitter do estabelecimento do recebedor Facebook do estabelecimento do recebedor Dados do documento do estabelecimento do recebedor Tipo do documento Número do documento País do documento Dados de endereço do estabelecimento do recebedor Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados da conta bancária Nome do portador da conta bancária Identificador de pessoa física ou jurídica

Os tipos aceitos são: individual ou company Documento do portador da conta bancária Código do banco Número da agência bancária Código verificador da agência bancária Número da conta bancária Número verificador da conta bancária Tipo da conta

Os tipos aceitos são: conta\_corrente, conta\_poupanca, conta\_corrente\_conjunta ou conta\_poupanca\_conjunta Dados da política de transferência Dia em que o parceiro será pago Determina se as transferências estão autorizadas a acontecer Intervalo entre as transferências

Os tipos aceitos são: daily, weekly ou monthly Determina se o recebedor receberá antecipações automaticamente Indica a porcentagem do volume passível de ser antecipado para o recebedor Indica o tipo de antecipação automática que será configurado para a conta do recebedor Indica a quantidade de dias de antecipação automática 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.sellers.find('c1015d17-f123-499f-aaad-32e7f7812132') ``` ```typescript theme={null} { id: 'c1015d17-f123-499f-aaad-32e7f7812132', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', status: 'pending', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.customers.list() ``` ```typescript theme={null} { items: [ { id: 'c1015d17-f123-499f-aaad-32e7f7812132', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', status: 'pending', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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. Número da página que deverá ser listada Limite de itens por página Ordenação da listagem, padrão é ASC

Os valores suportados são: ASC ou DESC E-mail do recebedor 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.sellers.remove('c1015d17-f123-499f-aaad-32e7f7812132') ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Nome do portador do cartão Número do cartão Código de segurança do cartão 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.sellers.update( 'c1015d17-f123-499f-aaad-32e7f7812132', { merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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' } } ) ``` ```typescript theme={null} { id: 'c1015d17-f123-499f-aaad-32e7f7812132', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', status: 'pending', merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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 do Recebedor Segundo parâmetro ID do Merchant que será vinculado o recebedor Código de segmento do lojista no adquirente Dados do recebedor Nome do recebedor E-mail do recebedor Telefone do recebedor Data de nascimento do recebedor Dados do documento do recebedor Tipo do documento Número do documento País do documento Dados de endereço do recebedor Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados do estabelecimento do recebedor Nome do estabelecimento do recebedor E-mail do estabelecimento do recebedor Telefone do estabelecimento do recebedor Data de abertura do estabelecimento do recebedor Descrição do estabelecimento do recebedor Site do estabelecimento do recebedor Twitter do estabelecimento do recebedor Facebook do estabelecimento do recebedor Dados do documento do estabelecimento do recebedor Tipo do documento Número do documento País do documento Dados de endereço do estabelecimento do recebedor Cidade País Bairro Estado Nome da rua, avenida ou travessa Número da rua Código postal Complemento onde se localiza o endereço, caso exista Dados da conta bancária Nome do portador da conta bancária Identificador de pessoa física ou jurídica

Os tipos aceitos são: individual ou company Documento do portador da conta bancária Código do banco Número da agência bancária Código verificador da agência bancária Número da conta bancária Número verificador da conta bancária Tipo da conta

Os tipos aceitos são: conta\_corrente, conta\_poupanca, conta\_corrente\_conjunta ou conta\_poupanca\_conjunta Dados da política de transferência Dia em que o parceiro será pago Determina se as transferências estão autorizadas a acontecer Intervalo entre as transferências

Os tipos aceitos são: daily, weekly ou monthly Determina se o recebedor receberá antecipações automaticamente Indica a porcentagem do volume passível de ser antecipado para o recebedor Indica o tipo de antecipação automática que será configurado para a conta do recebedor Indica a quantidade de dias de antecipação automática 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.sessions.cancel('bbc9d986-b65e-48fe-b879-2e1df10aea87') ``` ```typescript theme={null} { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', status: 'canceled' } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.sessions.create({ merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1", 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, }, ], }); ``` ```typescript theme={null} { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', name: 'Link de Pagamento', status: 'created', isActive: true, clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', orderId: null, amount: 100, currency: 'BRL', capture: null, merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: 'b8d59a73-fd16-4d6b-9e0f-9d7b2a8a7e6d', multiplePayments: { allow: true, maxPayments: 5, paymentCount: 0, pendingCount: 0, status: 'active' }, } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. ID do Merchant que será usado na sessão Valor da sessão em centavos Data de expiração da sessão Nome de identificação da sessão Dados dos métodos de pagamento disponíveis na sessão Identificador do tipo de pagamento, com cartão de crédito sempre será credit Número de parcelas possíveis na venda Identificador do tipo de pagamento, com PIX sempre será pix Tempo de expiração do PIX em segundos Identificador do tipo de pagamento, com boleto sempre será boleto Data de vencimento do boleto Instruções do boleto Dados opcionais da condição de juros para pagamento em atraso Dias após a expiração do boleto que ocorrerá a cobrança dos juros Valor em centavos da taxa de juros que será cobrado ao dia Valor em porcentagem da taxa de juros que será cobrado ao mês Dados opcionais da condição de multa para pagamento em atraso Dias após a expiração do boleto que ocorrerá a cobrança da multa Valor em centavos da multa Valor em porcentagem da multa Identificador do tipo de pagamento, com Drip sempre será drip Link de redirecionamento em caso de aprovação do pagamento no ambiente de checkout da Drip Link de redirecionamento em caso de cancelamento do pagamento no ambiente de checkout da Drip Identificador do tipo de pagamento, com NuPay sempre será nupay URL de origem da cobrança URL para a qual o cliente será redirecionado após finalizar o pagamento URL para onde o cliente será direcionado caso escolha não finalizar o pagamento e cancele o pedido Total de taxas aplicadas em centavos Tempo em minutos para a expiração de uma cobrança criada que não tenha sido paga Dados dos produtos da sessão Nome do produto Preço do produto Quantidade do produto Descrição do produto Define se é um produto tangível Descrição da sessão Descrição da cobrança que irá aparecer na fatura do cartão Define se deve criar um link para pagamento com a funcionalidade de Link de Pagamento 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. Identificador único da sessão do lado do cliente para conciliação futura Moeda que será usada para a sessão Define se a sessão está ativa 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.sessions.disable("bbc9d986-b65e-48fe-b879-2e1df10aea87"); ``` ```typescript theme={null} { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', isActive: false } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.sessions.enable("bbc9d986-b65e-48fe-b879-2e1df10aea87"); ``` ```typescript theme={null} { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', isActive: true } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); await malga.sessions.find("bbc9d986-b65e-48fe-b879-2e1df10aea87"); ``` ```typescript theme={null} { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', name: 'Link de Pagamento', status: 'created', isActive: true, clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', orderId: null, amount: 100, currency: 'BRL', capture: null, merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: 'b8d59a73-fd16-4d6b-9e0f-9d7b2a8a7e6d', multiplePayments: { allow: true, maxPayments: 5, paymentCount: 0, pendingCount: 0, status: 'active' }, } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) 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', }) ``` ```typescript theme={null} { items: [ { id: 'bbc9d986-b65e-48fe-b879-2e1df10aea87', name: 'Link de Pagamento', status: 'created', isActive: true, clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', orderId: null, amount: 100, currency: 'BRL', capture: null, merchantId: '8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1', 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: 'b8d59a73-fd16-4d6b-9e0f-9d7b2a8a7e6d', } ], meta: { totalItems: 1 itemCount: 1 itemsPerPage: 15 totalPages: 1 currentPage: 1 } } ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Número da página que deverá ser listada Limite de itens por página 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 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 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 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 ```typescript theme={null} import { Malga } from 'malga' const malga = new Malga({ apiKey: '17a64c8f-a387-4682-bdd8-d280493715e0', clientId: 'd1d2b51a-0446-432a-b055-034518c2660e', }) await malga.webhooks.verify({ payload: '{"event":"ping","payload":{"object":{}}}', publicKey: '-----BEGIN PUBLIC KEY-----\nMCwBQYDK2VwAyEASdad=\n-----END PUBLIC KEY-----\n', signature: '5b20c43cfd55f0c1884196' signatureTime: 1661795163719, }) ``` ```typescript theme={null} true // or false ``` ### Parâmetros Lista de todos os parâmetros suportados pelo método. Chave pública retornada no momento da criação do webhook Dados enviados no corpo do evento Assinatura enviada pelo evento no header X-Plug-Signature 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. ### Documentação Veja detalhadamente como cada um dos métodos funciona e entenda como usá-los no seu projeto. Comece a transacionar Gerencie cartões com segurança Crie sessões de pagamento ### Exemplos Confira os exemplos de projetos integrados com a Malga: Veja o código completo 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. ```bash theme={null} npm install malga ``` ```bash theme={null} yarn add malga ``` ```bash theme={null} pnpm add malga ``` ### 2. Fazendo sua primeira cobrança Crie uma cobrança de forma simplificada. ```typescript theme={null} import express, { Request, Response } from "express"; import { Malga } from "malga"; const app = express(); const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", options: { sandbox: true }, }); app.post("/", (request: Request, response: Response) => { try { const data = await malga.charges.create({ merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1", 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 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. ```bash theme={null} npm install malga ``` ```bash theme={null} yarn add malga ``` ```bash theme={null} pnpm add malga ``` ### 2. Fazendo sua primeira cobrança Crie uma cobrança de forma simplificada. ```typescript theme={null} import { Malga } from "malga"; const malga = new Malga({ apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", options: { sandbox: true }, })(async function () { try { const data = await malga.charges.create({ merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1", 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 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. Não é possível finalizar um pagamento no preview do Malga Checkout Malga Checkout ## Live preview do Malga Checkout Full Você pode acessar uma demo do Malga Checkout Full neste link. Não é possível finalizar um pagamento no preview do Malga Checkout Full. Malga Checkout Full ## 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" } ``` 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", }` | 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). 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). 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` | `""` | 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", }` | 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). 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). 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` | `""` | 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", }` | 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). 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). 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` | `""` | 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", }` | 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). 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). 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` | `""` | 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", }` | 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). 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` | `""` | 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", }` | 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). 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` | `""` | 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). # SDK React.js Source: https://docs.malga.io/sdks/malga-checkout/react ## 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", }` | 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). 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` | `""` | 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", }` | 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). 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` | `""` | 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 VTEX Source: https://docs.malga.io/sdks/plugins/vtex-connector Através do **conector Malga**, é possível processar pagamentos de crédito, pix e boleto na sua loja VTEX utilizando todos os recursos e provedores do Fluxo Inteligente Malga . 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 , sem precisar desenvolver integrações, e também fazer o acompanhamento das cobranças através das soluções de Painel de Dados , Analytics API e Exportação de cobranças . 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 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
Configurações de pagamentos no painel VTEX > Afiliações de gateways > Outros > Malga
Vtex Gateway Configuration
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) , 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. **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) , 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
Configurações de pagamentos no painel VTEX > Afiliações de gateways
Captura automática de pagamentos
Painel VTEX > Afiliações de gateways > Captura automática de pagamentos
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
Condições de pagamento > Método Boleto Bancário
Condições de pagamento > Método Boleto Bancário
Condições de pagamento > Método Boleto Bancário
Condições de pagamento > Método Boleto Bancário > Padrão
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
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
Condições de pagamento > Método Pix
Condições de pagamento > Método Pix > Malga
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
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
Fluxo inteligente de Pagamento Malga > Condicional de Balanceador
Vtex Detalhes da Charge DashboardVtex
Condições de pagamento > Cartão de Crédito > Bandeira American Express > Malga como Padrão
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
Fluxo inteligente de Pagamento Malga > Condicional de Balanceador
**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
Loja VTEX > Todos os pedidos > ID do pedido
Vtex Detalhes da Charge DashboardVtex
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
Dashboard Malga > Cobranças > Detalhe de cobrança
Vtex Detalhes da Charge DashboardVtex
Detalhe de cobranças na loja VTEX > ID da transação
Vtex Detalhes da Charge DashboardVtex
Cobranças na loja VTEX
**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 Vtex Painel de Dados **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). 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: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", 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. Chave de acesso à API Identificador único da sua conta na Malga Configurações Adicionais Identificador da tag form
Identificador do campo de portador do cartão
Identificador do campo de CVV
Identificador do campo de data de expiração
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. A forma mais simples de tokenizar cartões ### Exemplos Confira os exemplos de projetos integrados com a Malga: Veja o código completo 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. ```bash theme={null} npm install @malga/tokenization ``` ```bash theme={null} yarn add @malga/tokenization ``` ```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. ```jsx theme={null}
``` ```html theme={null}
``` ### 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: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); 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: "17a64c8f-a387-4682-bdd8-d280493715e0", clientId: "d1d2b51a-0446-432a-b055-034518c2660e", }); malgaTokenization.init(); ``` Pronto, agora seus cartões já estão sendo tokenizados com segurança! :rocket: ### 4. Teste você mesmo Veja o código completo 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}
``` É importante que o id da tag div seja uma das opções válidas, conforme o exemplo ## 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 da 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. | `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` | A configuração do container deve seguir rigorosamente a nomenclatura: `card-number`, `card-holder-name`, `card-cvv`, `card-expiration-date`. Da mesma forma, os campos devem ser configurados utilizando as versões em camelCase: `cardNumber`, `cardHolderName`, `cardCvv`, `cardExpirationDate`, conforme demonstrado no exemplo acima. ##### `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 | 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. Aprenda a estilizar os campos. # Utilizando os eventos Source: https://docs.malga.io/sdks/tokenization/v2/events A aplicação possui dois métodos principais: on e tokenize. ### on(eventType, function) O método on permite escutar eventos e executar um callback quando um determinado evento ocorre. #### Eventos disponíveis ##### `cardTypeChange` Disparado quando o valor do campo card-number é alterado. Objeto de retorno: ```typescript theme={null} { field: '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('cardTypeChange', () => console.log('cardTypeChange')) ``` ##### `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: 'card-number'| 'card-cvv'| 'card-holder-name'| 'card-expiration-date' valid: boolean error: { field: 'card-number'| 'card-cvv'| 'card-holder-name'| 'card-expiration-date' 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: 'card-number'| 'card-cvv'| 'card-holder-name'| 'card-expiration-date' parentNode: Element } ``` Exemplo de uso ```typescript theme={null} malgaTokenization.on('blur', () => console.log('blur')) malgaTokenization.on('focus', () => console.log('focus')) ``` ### tokenize() Método responsável por enviar os dados do cartão para tokenização. 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} const { tokenId, error } = await malgaTokenization.tokenize() if (error) { console.error('Error', error.message) } return console.log('TokenId:', tokenId) ``` Método responsável por criptografar os dados do cartão, enviá-los para tokenização e retornar o tokenID em caso de sucesso. 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 Source: https://docs.malga.io/sdks/tokenization/v2/intro 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 SDK de Tokenização com Hosted Fields 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. Aprenda a tokenizar cartões de forma segura usando o Malga Tokenization SDK. # 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 Suas chaves de integração no Dashboard ### Instalando o SDK Instale nosso SDK com o seu gerenciador de pacotes favorito. ```bash theme={null} npm install @malga/tokenization ``` ```bash theme={null} yarn add @malga/tokenization ``` ```bash theme={null} pnpm add @malga/tokenization ``` Com as chaves em mãos e o SDK instalado, vamos à configuração. 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 cor do text apenas do input de 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", }, } ``` 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 } ``` Aprenda a utilizar os eventos disponíveis