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.

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

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
}