Skip to main content

Get Balance

Use this route to get the financial balance of your account or a specific partner. The response returns the available balance for withdrawal and, optionally, the future balance and the related transactions list.

Important

This route requires prior enablement by Marlim. Contact our support team for more information.

GETv3/financial/balance

Request Query Params​

AttributeTypeDescription
sub_seller_idstringPartner ID whose balance will be retrieved. When omitted, the query returns the seller account balance.
with_transactionsbooleanWhen true, includes the list of transactions linked to each balance in the response. Default: false.
with_future_balancebooleanWhen true, includes the future object with the balance that has not yet been settled. Default: false.
Tip

Monetary values returned by this route are always in cents. For example, 15000 represents R$ 150.00.

Refunds and balance impact

When a transaction is refunded, the amount is deducted from the balance according to the settlement stage:

Transaction situationImpacted balance
Still not settled (awaiting settlement)Deducted from the future balance (balance.future)
Already settled, withdrawal requested or completedDeducted from the available balance (balance.available)

Response Object​

The response returns an object with the balance property.

AttributeTypeDescription
balanceobjectObject containing the retrieved balances.
balance[available]objectBalance available for withdrawal.
balance[available][amount]int32Available amount in cents.
balance[available][transactions]arrayList of already settled transactions. Returns an empty array when with_transactions is false.
balance[available][residual_balance]object | nullResidual balance generated when a withdrawal does not withdraw the full available balance. Returns null when there is no residual (for example, after withdrawing the full balance or when no partial withdrawal has been made).
balance[available][residual_balance][amount]int32 | nullResidual amount of the available balance at the time of the referenced withdrawal, in cents.
balance[available][residual_balance][referenced_withdrawal_id]string | nullID of the withdrawal that originated the residual balance.
balance[available][residual_balance][date_created]dateTime | nullResidual balance creation date in ISODateTime format.
balance[available][residual_balance][date_updated]dateTime | nullResidual balance update date in ISODateTime format.
balance[future]objectFuture balance, still awaiting settlement. Present only when with_future_balance is true.
balance[future][amount]int32Future amount in cents.
balance[future][transactions]arrayList of transactions awaiting settlement. Returns an empty array when with_transactions is false.
Residual balance

The residual_balance field records the amount that remained in the available balance after a partial withdrawal, that is, when the withdrawn amount was less than the available balance at that moment.

  • With residual: returns the object with the remaining amount (amount), the ID of the withdrawal that originated it (referenced_withdrawal_id), and the creation/update dates.
  • Without residual: returns null, for example, after a full balance withdrawal or when no partial withdrawal has occurred yet.

The value in balance.available.amount already includes the residual balance. Do not add the two fields together.

Transaction object (transactions)​

When with_transactions=true, each item in the transactions array contains:

AttributeTypeDescription
transaction_idstringMarlim transaction ID.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction update date in ISODateTime format.
paid_amountint32Paid amount in cents.
net_valueint32Net transaction amount in cents.
amount_to_receiveint32Amount to receive in cents. The calculation depends on the account type (see note below).
installmentsstringNumber of installments.
authorization_codestringTransaction authorization code.
nsustringUnique Sequential Number of the transaction.
item_idstringTransaction identifier in your platform.
customer_namestringCustomer name.
customer_document_numberstringCustomer document.
customer_emailstringCustomer email.
customer_phone_numberstringCustomer phone number.
card_brandstringCard brand.
card_first_digitsstringFirst digits of the card.
card_last_digitsstringLast digits of the card.
card_expiration_datestringCard expiration date.
statusstringTransaction status.
Important

The meaning of amount_to_receive changes depending on who is querying the balance:

  • Partner: amount from the split allocated to them in the transaction, in cents.
  • Seller: net transaction amount after deducting fees and splits, in cents.
Example Response (available balance)
{
  "balance": {
    "available": {
      "amount": 15000,
      "transactions": [],
      "residual_balance": null
    }
  }
}
Example Response (with residual balance)
{
  "balance": {
    "available": {
      "amount": 5000,
      "transactions": [],
      "residual_balance": {
        "amount": 5000,
        "referenced_withdrawal_id": "wd_k4m6Rw5rlQszEY7fiuRe",
        "date_created": "2026-07-22T11:00:00.000Z",
        "date_updated": "2026-07-22T11:00:00.000Z"
      }
    }
  }
}
Example Response (with future balance and transactions)
{
  "balance": {
    "available": {
      "amount": 15000,
      "transactions": [
        {
          "transaction_id": "HcDscltTIVK3VMAAOj7J",
          "date_created": "2026-07-20T14:30:00.000Z",
          "date_updated": "2026-07-21T10:00:00.000Z",
          "paid_amount": 10000,
          "net_value": 9700,
          "amount_to_receive": 9700,
          "installments": "1",
          "authorization_code": "112233",
          "nsu": "98765432",
          "item_id": "ABC123456789",
          "customer_name": "Luke Skywalker",
          "customer_document_number": "12345678900",
          "customer_email": "luke@jedi.com",
          "customer_phone_number": "11999999999",
          "card_brand": "visa",
          "card_first_digits": "555544",
          "card_last_digits": "2222",
          "card_expiration_date": "1228",
          "status": "paid"
        }
      ],
      "residual_balance": null
    },
    "future": {
      "amount": 5000,
      "transactions": [
        {
          "transaction_id": "XyZabcDefGhiJklMnOp",
          "date_created": "2026-07-25T18:00:00.000Z",
          "date_updated": "2026-07-25T18:00:00.000Z",
          "paid_amount": 5200,
          "net_value": 5000,
          "amount_to_receive": 5000,
          "installments": "2",
          "authorization_code": "445566",
          "nsu": "11223344",
          "item_id": "PEDIDO-987",
          "customer_name": "Leia Organa",
          "customer_document_number": "98765432100",
          "customer_email": "leia@rebel.com",
          "customer_phone_number": "11988888888",
          "card_brand": "mastercard",
          "card_first_digits": "544433",
          "card_last_digits": "1111",
          "card_expiration_date": "1129",
          "status": "paid"
        }
      ]
    }
  }
}

Error Object​

AttributeTypeDescription
errorsarrayArray with all errors found while processing the request.
errors[][type]stringType of error that occurred.
errors[][message]stringDetailed message of the error that occurred.
Example error
{
  "errors": [
    {
      "type": "not_found",
      "message": "Sub Seller with id [sub_123456789] was not found"
    }
  ]
}

Examples​

ATTENTION

The values used in the examples below are for illustration only and must not be used to make requests to Marlim APIs.

Request
curl -X GET "https://api.marlim.co/v3/financial/balance" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
Response200
{
  "balance": {
    "available": {
      "amount": 15000,
      "transactions": [],
      "residual_balance": null
    }
  }
}