Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.malga.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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 conforme Cobrança com 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).

​
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.

​
Exemplo: criar sessão com split

curl --location 'https://api.malga.io/v1/sessions' \
--header 'X-Client-Id: <SEU_CLIENT_ID>' \
--header 'X-Api-Key: <SUA_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Marketplace - 2 sellers",
  "merchantId": "<SEU_MERCHANT_ID>",
  "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": "<SELLER_ID_1>",
      "percentage": 60,
      "processingFee": true,
      "chargeEntireFee": true,
      "liable": true
    },
    {
      "sellerId": "<SELLER_ID_2>",
      "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.

​
Exemplo: pagar sessão (sem split no corpo)

curl --location 'https://api.malga.io/v1/sessions/<SESSION_ID>/charge' \
--header 'X-Client-Id: <SEU_CLIENT_ID>' \
--header 'X-Api-Key: <SUA_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "paymentMethod": {
    "paymentType": "credit",
    "installments": 1
  },
  "paymentSource": {
    "sourceType": "customer",
    "customerId": "<CUSTOMER_ID>"
  }
}'
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 (mesmo modelo de regra, aplicado na criação da sessão em vez do POST /v1/charges).