Balance API

The Balance API in Getnet Split Payments lets you query the consolidated balance of a marketplace or a specific partner, summed across three views: overdue, current, and future. Unlike the Statement API, which details each item, commission, and adjustment individually, the Balance API returns only the already-summed totals for each view.

Important: The Balance API accesses a static database, updated every day at 1 a.m. with a snapshot of the schedules after settlement processing. Sales, cancellations, chargebacks, and adjustments made the same day only appear in the query starting the next day. To track same-day movements, use the Statement API.

Query the Balance of a Marketplace or Partner

Send a GET request to /v1/mgm/balances/balance/summary to query the balance of a marketplace or a specific partner.

Set the Authorization header with the access token, in the format Bearer <token>.
Build the query string with the parameters from the table below.
Send the request and check the response code in the Check the Most Common Errors table, further down.

Query Parameters

Field	Type	Rules
`seller_id`	string	Required. Identifier of the marketplace.
`subseller_id`	integer	Required if the period between `balance_start_date` and `balance_end_date` is longer than two days. Even when provided, the maximum search period is 30 days. Identifier of the partner.
`balance_start_date`	string (date)	Required. Start date of the search, in `YYYY-MM-DD` format.
`balance_end_date`	string (date)	Required. End date of the search, in `YYYY-MM-DD` format.
`blocks_codes`	string	Optional. Codes of the blocks to display, comma-separated and in uppercase letters: `E` (overdue), `C` (current), or `F` (future). For example, `E,C,F`.

The response groups the values into up to three blocks, according to the requested blocks_codes: expired_balance, current_balances, and future_balances.

Understand the Overdue Balance Block

The expired_balance block shows the overdue balance accumulated up to the query date: the sum of items and commissions not yet released, plus the balance of blocked schedules. Even if the query specifies a future date, this block only returns information up to the current date.

Field	Description
`unreleased_amount`	Sum of orders and commissions not yet released whose settlement date has already passed.
`blocked_amount`	Accumulated balance of the blocked schedule, not yet sent for payment. This hold doesn't prevent the marketplace or the partner from transacting, canceling schedules, or recording adjustments.
`balance_date`	Reference date of the balance, in full date-time format (`YYYY-MM-DDT00:00:00`).

Example: unreleased balance

JSON

{
  "status": {
    "status_code": "0000",
    "message": "Processamento concluído com sucesso!"
  },
  "balances": {
    "expired_balance": [
      {
        "balances": [
          {
            "merchant_id": "54868901",
            "subseller_id": 700110805,
            "unreleased_amount": 2541.72,
            "blocked_amount": 0.0,
            "balance_date": "2024-11-20T00:00:00"
          }
        ]
      }
    ]
  }
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "status": {
    "status_code": "0000",
    "message": "Processamento concluído com sucesso!"
  },
  "balances": {
    "expired_balance": [
      {
        "balances": [
          {
            "merchant_id": "54868901",
            "subseller_id": 700110805,
            "unreleased_amount": 2541.72,
            "blocked_amount": 0.0,
            "balance_date": "2024-11-20T00:00:00"
          }
        ]
      }
    ]
  }
}

Understand the Current Balance Block

The current_balances block shows the balance already sent for payment, with settlement confirmed, including the breakdown in the released_balances sub-block.

The fields below are reproduced exactly as returned by the API, including negative_shcedule_reversal_value (the API's real spelling, not "schedule") and chargeBack_value/mdr_fee_chargeBack_value (mixed case, unlike the other fields, all in snake_case).

Field	Description
`amount_paid`	Sum of the balance paid.
`rejected_payment_value`	Sum of the payment value rejected in the last settlement.
`liquidation_process_value`	Sum of the value in settlement processing, or the negative value of the last settlement.
`total_amount`	Sum of all fields in the `released_balances` sub-block.
`merchant_id`	Marketplace code (EC, Merchant Establishment).
`subseller_id`	Partner code.
`balance_date`	Reference date of the balance, in date-only format (`YYYY-MM-DD`).
`released_balances.sale_value`	Sum of the sales value.
`released_balances.commission`	Sum of the commission. Populated only for the marketplace's own-store balance.
`released_balances.cancelled_value`	Sum of the value of canceled sales.
`released_balances.chargeBack_value`	Sum of the chargeback value received in the schedule (credit and debit). Populated only for the own-store balance.
`released_balances.mdr_fee_chargeBack_value`	Sum of the fees charged on the transaction, refunded after the chargeback is processed.
`released_balances.if_anticipation_value`	Sum of Financial Institution anticipation contracts distributed in the schedule.
`released_balances.nf_anticipation_value`	Sum of Non-Financial Institution anticipation contracts distributed in the schedule.
`released_balances.subseller_debit_adjustment_boleto_value`	Sum of debit adjustments posted to guarantee the refund of a reversed boleto's value to the buyer.
`released_balances.marketplace_adjustment_entry_value`	Sum of entries posted for the EC. Populated only for the marketplace's own-store balance.
`released_balances.subseller_adjustment_entry_value`	Sum of entries posted for the partner by the EC. Populated only for a partner's balance.
`released_balances.negative_schedule_value`	Sum of the negative schedule value.
`released_balances.negative_shcedule_reversal_value`	Sum of the negative schedule reversal. Populated only for the own-store balance.
`released_balances.other_adjustments_value`	Sum of other adjustments posted via Backoffice, such as a card brand penalty fee.

Example: positive current balance

JSON

{
  "status": { "status_code": "0000", "message": "Processamento concluído com sucesso!" },
  "balances": {
    "current_balances": [
      {
        "balances": [
          {
            "amount_paid": 0.0,
            "rejected_payment_value": 0.0,
            "liquidation_process_value": 677.18,
            "total_amount": 677.18,
            "merchant_id": "54869000",
            "balance_date": "2024-12-26",
            "subseller_id": 700127925,
            "released_balances": {
              "other_adjustments_value": 0.0,
              "commission": 0.0,
              "sale_value": 677.18,
              "cancelled_value": 0.0,
              "chargeBack_value": 0.0,
              "mdr_fee_chargeBack_value": 0.0,
              "if_anticipation_value": 0.0,
              "nf_anticipation_value": 0.0,
              "subseller_debit_adjustment_boleto_value": 0.0,
              "marketplace_adjustment_entry_value": 0.0,
              "subseller_adjustment_entry_value": 0.0,
              "negative_schedule_value": 0.0,
              "negative_shcedule_reversal_value": 0.0
            }
          }
        ]
      }
    ]
  }
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "status": { "status_code": "0000", "message": "Processamento concluído com sucesso!" },
  "balances": {
    "current_balances": [
      {
        "balances": [
          {
            "amount_paid": 0.0,
            "rejected_payment_value": 0.0,
            "liquidation_process_value": 677.18,
            "total_amount": 677.18,
            "merchant_id": "54869000",
            "balance_date": "2024-12-26",
            "subseller_id": 700127925,
            "released_balances": {
              "other_adjustments_value": 0.0,
              "commission": 0.0,
              "sale_value": 677.18,
              "cancelled_value": 0.0,
              "chargeBack_value": 0.0,
              "mdr_fee_chargeBack_value": 0.0,
              "if_anticipation_value": 0.0,
              "nf_anticipation_value": 0.0,
              "subseller_debit_adjustment_boleto_value": 0.0,
              "marketplace_adjustment_entry_value": 0.0,
              "subseller_adjustment_entry_value": 0.0,
              "negative_schedule_value": 0.0,
              "negative_shcedule_reversal_value": 0.0
            }
          }
        ]
      }
    ]
  }
}

Negative values in liquidation_process_value and total_amount indicate that the settlement closed negative, which can also be reflected in released_balances.commission or released_balances.negative_shcedule_reversal_value, depending on the cause. Chargebacks, cancellations, and anticipations in the period appear, respectively, in chargeBack_value, cancelled_value, and if_anticipation_value/nf_anticipation_value, using the same fields described above.

Understand the Future Balance Block

The future_balances block shows the balance not yet sent for payment, referring to schedules beyond D+2. Schedules with a D-1 or D+1 view appear in the current balance block, since they're already in the settlement flow, or in the overdue balance block, if they're overdue or blocked.

Field	Description
`total_amount`	Sum of all fields in the `released_balances` sub-block for that date. Since it's a future balance, it may change in subsequent queries.
`unreleased_value`	Sum of transaction values not yet released.
`balance_date`	Reference date of the balance, in date-only format (`YYYY-MM-DD`).
`total_amount_paid_future_period`	Sum of the `total_amount` values across all dates returned in the future balance.

The released_balances sub-block of the future balance uses the same fields described in Understand the Current Balance Block.

Example: positive future balance

JSON

{
  "status": { "status_code": "0000", "message": "Processamento concluído com sucesso!" },
  "balances": {
    "future_balances": [
      {
        "balances": [
          {
            "total_amount": 677.18,
            "unreleased_value": 0.0,
            "merchant_id": "54869000",
            "balance_date": "2024-12-30",
            "subseller_id": 700127925,
            "released_balances": {
              "other_adjustments_value": 0.0,
              "commission": 0.0,
              "sale_value": 677.18,
              "cancelled_value": 0.0,
              "chargeBack_value": 0.0,
              "mdr_fee_chargeBack_value": 0.0,
              "if_anticipation_value": 0.0,
              "nf_anticipation_value": 0.0,
              "subseller_debit_adjustment_boleto_value": 0.0,
              "marketplace_adjustment_entry_value": 0.0,
              "subseller_adjustment_entry_value": 0.0
            }
          }
        ],
        "total_amount_paid_future_period": 677.18
      }
    ]
  }
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "status": { "status_code": "0000", "message": "Processamento concluído com sucesso!" },
  "balances": {
    "future_balances": [
      {
        "balances": [
          {
            "total_amount": 677.18,
            "unreleased_value": 0.0,
            "merchant_id": "54869000",
            "balance_date": "2024-12-30",
            "subseller_id": 700127925,
            "released_balances": {
              "other_adjustments_value": 0.0,
              "commission": 0.0,
              "sale_value": 677.18,
              "cancelled_value": 0.0,
              "chargeBack_value": 0.0,
              "mdr_fee_chargeBack_value": 0.0,
              "if_anticipation_value": 0.0,
              "nf_anticipation_value": 0.0,
              "subseller_debit_adjustment_boleto_value": 0.0,
              "marketplace_adjustment_entry_value": 0.0,
              "subseller_adjustment_entry_value": 0.0
            }
          }
        ],
        "total_amount_paid_future_period": 677.18
      }
    ]
  }
}

Check the Most Common Errors

The table below lists the most common error scenarios for the query, with the response code and the returned body in each case. The status_code field in the error body varies between a numeric code (for example, "9103") and a descriptive text ("Período Incorreto"), depending on the scenario. Both formats are returned by the API. The error messages below are reproduced exactly as returned by the API, including the typos and grammatical inconsistencies present in the original text.

Scenario	Code	Response Body
`seller_id` not provided	400	`{"seller_id":["Campo 'seller_id' é obrigatório."]}`
`balance_start_date` not provided	400	`{"balance_start_date":["Campo 'Data Inicial' é obrigatório."]}`
`balance_end_date` not provided	400	`{"balance_end_date":["Campo 'Data Final' é obrigatório."]}`
Period longer than 2 days without `subseller_id`	400	`{"status_code":"Período Incorreto","message":"Período máximo de pesquisa entre Data Inicial e Data final é de 2 dias"}`
Period longer than 30 days	400	`{"status_code":"Período Incorreto","message":"Período máximo de pesquisa entre Data Inicial e Data final é de 30 dias"}`
Future balance query more than 18 months from the start date	400	`{"status_code":"Período Incorreto","message":"A data limite para consulta de saldo Futuro é de 18 meses a partir da Data Inicial"}`
Invalid `blocks_codes` (not one of `E`, `C`, `F`, lowercase, or improperly separated)	400	`{"blocks_codes":["Os seguintes códigos de blocos informados são inválidos.: [valor] - Códigos permitidos: E, C ou F (letras maiúsculas e separados por vírgula)"]}`
`seller_id` not found in the database	400	`{"status_code":"9103","message":"Seller_id informado, inexiste na base."}`
`subseller_id` not found in the database	400	`{"status_code":"9104","message":"SubSeller_id informado, inexiste na base."}`
`subseller_id` not associated with the provided `seller_id`	400	`{"status_code":"9105","message":"SubSeller_id não associada ao Marketplace informado."}`

A query with a valid period and no results returns status_code: "0000" with the requested block empty, for example "future_balances": [].

Use the three blocks, Overdue Balance, Current Balance, and Future Balance, to quickly identify what stage each value of a marketplace or partner is in: what has already come due and wasn't released, what's already in settlement, and what's still to come.

Next Steps

Backoffice API — Adjustments: post a manual credit or debit adjustment to a partner's balance.
Balance Management: see the overview of releases, adjustments, and refunds.

On this page

Balance API

Seller Onboarding (PF and PJ)

Balance and Adjustments

Payouts

Reconciliation and Statement

Balance API

Query the Balance of a Marketplace or Partner

Query Parameters

Understand the Overdue Balance Block

Understand the Current Balance Block

Understand the Future Balance Block

Check the Most Common Errors

Next Steps