Pular para o conteúdo principal

Consultar Saldo

Use esta rota para consultar o saldo financeiro da sua conta ou de um parceiro específico. A resposta retorna o saldo disponível para saque e, opcionalmente, o saldo futuro e a lista de transações relacionadas.

Importante

Esta rota depende de habilitação prévia pela Marlim. Entre em contato com o nosso time de suporte para mais informações.

GETv3/financial/balance

Request Query Params​

AtributoTipoDescrição
sub_seller_idstringID do parceiro cujo saldo será consultado. Quando omitido, a consulta retorna o saldo da conta do seller.
with_transactionsbooleanQuando true, inclui no retorno a lista de transações vinculadas a cada saldo. Padrão: false.
with_future_balancebooleanQuando true, inclui no retorno o objeto future com o saldo ainda não liquidado. Padrão: false.
Dica

Os valores monetários retornados por esta rota estão sempre em centavos. Por exemplo, 15000 representa R$ 150,00.

Estornos e impacto no saldo

Quando uma transação é estornada, o valor é descontado do saldo conforme o estágio de liquidação:

Situação da transaçãoSaldo impactado
Ainda não liquidada (aguardando liquidação)Descontado do saldo futuro (balance.future)
Já liquidada, saque solicitado ou efetuadoDescontado do saldo disponível (balance.available)

Response Object​

A resposta retorna um objeto com a propriedade balance.

AtributoTipoDescrição
balanceobjectObjeto contendo os saldos consultados.
balance[available]objectSaldo disponível para saque.
balance[available][amount]int32Valor disponível em centavos.
balance[available][transactions]arrayLista de transações já liquidadas. Retorna array vazio quando with_transactions for false.
balance[available][residual_balance]object | nullSaldo residual gerado quando um saque não retira o saldo disponível por completo. Retorna null quando não há residual (por exemplo, após saque do saldo total ou quando nenhum saque parcial foi realizado).
balance[available][residual_balance][amount]int32 | nullValor residual do saldo disponível no momento do saque referenciado, em centavos.
balance[available][residual_balance][referenced_withdrawal_id]string | nullID do saque que originou o saldo residual.
balance[available][residual_balance][date_created]dateTime | nullData de criação do saldo residual no formato ISODateTime.
balance[available][residual_balance][date_updated]dateTime | nullData de atualização do saldo residual no formato ISODateTime.
balance[future]objectSaldo futuro, ainda aguardando liquidação. Presente apenas quando with_future_balance for true.
balance[future][amount]int32Valor futuro em centavos.
balance[future][transactions]arrayLista de transações aguardando liquidação. Retorna array vazio quando with_transactions for false.
Saldo residual

O campo residual_balance registra o valor que sobrou no saldo disponível após um saque parcial, ou seja, quando o valor sacado foi menor que o saldo disponível naquele momento.

  • Com residual: retorna o objeto com o valor remanescente (amount), o ID do saque que o originou (referenced_withdrawal_id) e as datas de criação/atualização.
  • Sem residual: retorna null, por exemplo, após um saque do saldo total ou quando ainda não houve saque parcial.

O valor em balance.available.amount já inclui o saldo residual. Não some os dois campos.

Objeto de transação (transactions)​

Quando with_transactions=true, cada item do array transactions contém:

AtributoTipoDescrição
transaction_idstringID Marlim da transação.
date_createddateTimeData de criação da transação no formato ISODateTime.
date_updateddateTimeData de atualização da transação no formato ISODateTime.
paid_amountint32Valor pago em centavos.
net_valueint32Valor líquido da transação em centavos.
amount_to_receiveint32Valor a receber em centavos. O cálculo depende do tipo de conta (veja nota abaixo).
installmentsstringNúmero de parcelas.
authorization_codestringCódigo de autorização da transação.
nsustringNúmero Sequencial Único da transação.
item_idstringIdentificador da transação na sua plataforma.
customer_namestringNome do cliente.
customer_document_numberstringDocumento do cliente.
customer_emailstringE-mail do cliente.
customer_phone_numberstringTelefone do cliente.
card_brandstringBandeira do cartão.
card_first_digitsstringPrimeiros dígitos do cartão.
card_last_digitsstringÚltimos dígitos do cartão.
card_expiration_datestringData de validade do cartão.
statusstringStatus da transação.
Importante

O significado de amount_to_receive muda conforme quem consulta o saldo:

  • Parceiro: valor do split destinado a ele na transação, em centavos.
  • Seller: valor líquido da transação após descontar taxas e splits, em centavos.
Exemplo de Response (saldo disponível)
{
  "balance": {
    "available": {
      "amount": 15000,
      "transactions": [],
      "residual_balance": null
    }
  }
}
Exemplo de Response (com saldo residual)
{
  "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"
      }
    }
  }
}
Exemplo de Response (com saldo futuro e transações)
{
  "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​

AtributoTipoDescrição
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.
Exemplo de erro
{
  "errors": [
    {
      "type": "not_found",
      "message": "Sub Seller with id [sub_123456789] was not found"
    }
  ]
}

Exemplos​

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim.

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