Skip to main content
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 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

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