> ## 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.
# Cobrança com Split
> Guia de split em cobrança direta via POST /v1/charges com splitRules no corpo da requisição.
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 em conjunto divisão **só por percentual** e **só por valor fixo** entre as regras da mesma cobrança (ou da mesma sessão, quando o split é configurado na sessão).
- Por regra, use **somente `percentage` ou somente `amount`** em cada recebedor, sem combinar os dois no mesmo objeto de regra.
- Não mantenha `chargeEntireFee` e `chargeRemainderFee` como `true` ao mesmo tempo.
- A informação de tarifas (mdr e fee) é específica para transações no provedor Braspag
### 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.
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
}
```