Visão geral

O recurso de Finanças reúne os endpoints de leitura que mostram a posição financeira da sua conta na Selectwin: quanto você tem disponível e o que está retido (saldo), o seu indicador de risco perante as bandeiras e adquirentes (saúde de risco) e a lista detalhada do que entra na conta a cada venda (recebíveis). Use estes endpoints para reconciliar a contabilidade, planejar fluxo de caixa e decidir quando solicitar um saque.

O que é o módulo de Finanças

Toda venda aprovada gera um ou mais recebíveis (o valor líquido que você tem direito a receber, já descontadas as taxas). Conforme cada recebível é liquidado, ele alimenta o seu saldo disponível, de onde você pode sacar. Em paralelo, a plataforma acompanha a saúde de risco do seu negócio (proporção de chargebacks, disputas e reembolsos) — um indicador que influencia limites e retenções.

O módulo é somente leitura: aqui você consulta a situação financeira. As ações de saída de dinheiro vivem no recurso de Saques (/v1/withdrawals), descrito em outra seção.

Os três endpoints cobertos por esta visão geral:

Existe ainda um endpoint complementar de agregados de recebíveis (GET /v1/receivables/analytics), útil para dashboards — explicado em Listar recebíveis.

Como o dinheiro flui

O caminho de uma venda até o seu saldo disponível e, por fim, até a sua conta bancária:

• Recebível: a "promessa" de um valor, com uma data prevista (expectedOn). Enquanto não liquida, conta como pendente.
• Saldo: o consolidado de tudo. O campo available é o que está livre para saque; pending ainda não liquidou; blocked/warranty estão retidos por garantia ou risco.
• Saúde de risco: avaliada continuamente em uma janela móvel; não move dinheiro, mas pode justificar retenções (blocked/warranty).

O objeto Saldo

GET /v1/finance/balance — exige o parâmetro de query companyId (o ID da empresa, ex.: bus_1234567890). Retorna um único objeto com os saldos agregados, o plano de taxas vigente, dados do merchant e links HATEOAS.

{
  "id": "bal_01hqzvabc",
  "available": 150000,
  "pending": 25000,
  "blocked": 0,
  "debit": 0,
  "refunded": 12000,
  "warranty": 5000,
  "feePlan": {
    "id": "fee_01hqzvabc",
    "cashoutFee": 367,
    "transactionFixedFee": 49,
    "antecipationFee": 0,
    "antecipationDays": 30,
    "transactionAmountLimit": 5000000,
    "minCashoutAmount": 1000,
    "availabilityDays": 30,
    "warrantyPercentage": 0,
    "warrantyEnabled": false,
    "pixFee": 99,
    "nupayFee": 199,
    "billetFee": 349,
    "creditFee": 399,
    "chargeMonthlyFee": 0,
    "premium": true,
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-01-26T20:18:05.000Z"
  },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/finance/balance",
      "method": "GET"
    }
  }
}

Campos do saldo

Campos de feePlan

O objeto Saúde de risco

GET /v1/finance/risk-health — não recebe parâmetros e retorna um objeto direto (sem merchant nem _links). Mostra, para uma janela móvel (ex.: rolling30d), as proporções de chargeback, disputa e reembolso, além dos limiares (thresholds) que definem o tier de risco.

{
  "object": "merchant_risk_health",
  "window": "rolling30d",
  "periodStart": "2026-03-13T00:00:00.000Z",
  "periodEnd": "2026-04-12T00:00:00.000Z",
  "tier": "ok",
  "chargebackRatio": 0.008,
  "chargebackCount": 2,
  "disputeRatio": 0.012,
  "refundRatio": 0.025,
  "thresholds": {
    "chargebackWarnRatio": 0.009,
    "chargebackExcessiveRatio": 0.018,
    "mastercardEcmRatio": 0.015,
    "disputeWarnRatio": 0.009,
    "refundWatchRatio": 0.15
  },
  "lastEvaluatedAt": "2026-04-12T17:56:33.000Z"
}

Campos da saúde de risco

Campos de thresholds

As proporções e limiares são decimais (0.012 = 1,2%). Compare chargebackRatio com thresholds.chargebackWarnRatio para saber o quão perto você está de um alerta.

O objeto Recebível

GET /v1/receivables — lista paginada dos valores a receber, com filtros por período, status e ID. Cada item representa uma parcela de uma venda. Em listas, os itens são projeções leves (alguns campos podem vir omitidos); veja a página dedicada para o conjunto completo de parâmetros.

{
  "id": "rec_01hqzvabc",
  "transactionId": "tra_01hqzvabc",
  "recipientId": null,
  "splitId": null,
  "currency": "BRL",
  "amount": 4850,
  "grossAmount": 5000,
  "status": "pending",
  "installmentNumber": 1,
  "anticipationFee": 0,
  "liable": true,
  "chargeProcessingFee": true,
  "description": "Payment successfully completed.",
  "paidAt": null,
  "refundedAt": null,
  "canceledAt": null,
  "expectedOn": "2026-04-20T00:00:00.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Campos do recebível

Ciclo de vida do recebível

O status de um recebível segue valores como scheduled, pending, paid, refunded, canceled, chargeback, dispute e fraud-hold:

Os campos liable e chargeProcessingFee determinam quem arca com chargebacks e taxas — relevantes em cenários de split entre vários recipientes.

Operações

Recursos relacionados (fora desta seção): Saques — GET /v1/withdrawals, GET /v1/withdrawals/{id} e POST /v1/withdrawals — para movimentar o saldo disponível para uma conta bancária.

Conceitos e relações

• Recebível → Saldo. Cada recebível liquidado soma ao available. Antes disso, conta em pending.
• Saldo → Saque. Você só pode sacar o que estiver em available, respeitando feePlan.minCashoutAmount e feePlan.cashoutFee. Saques insuficientes retornam balanceIsInsufficient.
• Risco → Retenções. Uma saúde de risco ruim pode aumentar blocked/warranty, reduzindo o quanto fica disponível.
• Transação → Recebível. O transactionId liga o recebível à venda de origem. Mudanças de estado (reembolso, chargeback) chegam por webhooks, não por polling — veja Proibição de polling.

Erros

Todos os endpoints retornam o envelope padrão de erro; trate sempre pelo error.code, nunca pela message. Códigos específicos de Finanças e os transversais mais comuns:

Catálogo completo em Códigos de Erro; estrutura do envelope em Tratamento de Erros.

Boas práticas

• Sempre informe companyId ao consultar o saldo — é obrigatório e segue o padrão prefixo_valor (ex.: bus_1234567890).
• Confira o saldo antes de sacar. Use available (não pending) e respeite feePlan.minCashoutAmount e feePlan.cashoutFee para evitar balanceIsInsufficient.
• Reconcilie pelo recebível, não pelo saldo. Para auditoria, percorra GET /v1/receivables com filtros de período (daterangegte/daterangelte) e compare grossAmount × amount para enxergar as taxas.
• Monitore o risco de forma proativa. Compare cada *Ratio com seu threshold correspondente e crie alertas internos antes de atingir o tier de risco elevado.
• Trate dinheiro em centavos inteiros em toda a cadeia; divida por 100 só na exibição.
• Não faça polling. Reaja a mudanças de estado por webhooks (ex.: eventos de transação e de saque), e use estes endpoints sob demanda para snapshots.
• Pagine com cautela. Em recebíveis, limit vai de 1 a 50; use offset e os campos page/hasMore da resposta. Veja Paginação.

Veja também

• Consultar saldo — detalhe completo de GET /v1/finance/balance.
• Listar recebíveis — filtros, paginação e o endpoint de analytics.
• Convenções · Autenticação · Códigos de Erro · Paginação · Proibição de polling