Cobrança com Split

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.

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.

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

curl -X POST 'https://api.malga.io/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_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": "<YOUR_CLIENT_ID>",
    "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

curl -X POST 'https://api.malga.io/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_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": "<YOUR_CLIENT_ID>",
    "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

curl -X POST 'https://api.malga.io/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_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": "<YOUR_CLIENT_ID>",
    "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. 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, 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

curl -X POST 'https://api.malga.io/v1/charges/482b24a0-2165-4c67-a4c6-e2b74853e982/void' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_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

curl -X POST 'https://api.malga.io/v1/charges/1feb14f6-9979-437b-8678-2989bf2cafc6/void' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_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": "<YOUR_CLIENT_ID>",
    "merchantId": "<YOUR_MERCHANT_ID>",
    "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

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": "<YOUR_CLIENT_ID>",
    "merchantId": "<YOUR_MERCHANT_ID>",
    "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
}

Comece na Malga

Conexões

Guias

Serviços adicionais

Cobrança com Split

Criando uma cobrança com Split

Regras de split

Exemplo de cobrança com Split aprovado usando o campo percentage

Exemplo de cobrança com Split aprovado usando o campo amount

Exemplo de cobrança com Split aprovado usando o campo de tarifa

Estorno Total ou Parcial

Exemplo de requisição com falha na especificação do amount

Exemplo de requisição de estorno parcial com Split

Exemplo de requisição de estorno total de transação com split

​Criando uma cobrança com Split

​Regras de split

​Exemplo de cobrança com Split aprovado usando o campo percentage

​Exemplo de cobrança com Split aprovado usando o campo amount

​Exemplo de cobrança com Split aprovado usando o campo de tarifa

​Estorno Total ou Parcial

​Exemplo de requisição com falha na especificação do amount

​Exemplo de requisição de estorno parcial com Split

​Exemplo de requisição de estorno total de transação com split

Criando uma cobrança com Split

Regras de split

Exemplo de cobrança com Split aprovado usando o campo percentage

Exemplo de cobrança com Split aprovado usando o campo amount

Exemplo de cobrança com Split aprovado usando o campo de tarifa

Estorno Total ou Parcial

Exemplo de requisição com falha na especificação do amount

Exemplo de requisição de estorno parcial com Split

Exemplo de requisição de estorno total de transação com split