Saldo e extrato · Documentação Wavewhite

Saldo

GET /v1/balance mostra a sua posição na Wavewhite. Escopo: balance:read. Referência: Consultar saldo.

GET/v1/balance

curl -X GET 'https://api.wavewhite.com/v1/balance' \
  -H "Authorization: Bearer $API_KEY"

const response = await fetch('https://api.wavewhite.com/v1/balance', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.wavewhite.com/v1/balance",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.wavewhite.com/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "currency": "BRL",
  "pending_cents": "0",
  "available_cents": "15670",
  "contract_reserve_cents": "0",
  "blocked_cents": "0",
  "payout_reserved_cents": "0",
  "total_cents": "15670",
  "owed_to_koku_cents": "0",
  "payouts_suspended": false,
  "suspension_reasons": [],
  "payouts_by_koku": true,
  "payouts_by_koku_message": "Os repasses são feitos pela Wavewhite: peça o saque pelo painel ou pela API, a qualquer hora",
  "available_for_payout_cents": "15670",
  "to_receive_cents": "15670",
  "as_of": "2026-10-08T09:00:00.000Z"
}

Campo	Significado
`pending_cents`	Líquido de vendas pagas que ainda não foi liberado: vendas processadas por adquirente que libera só depois de liquidar e conciliar.
`available_cents`	Liberado para saque: na hora, para adquirente que libera na confirmação do pagamento, ou depois da liquidação conciliada, para as demais.
`contract_reserve_cents`	Reserva contratual. Continua sendo seu e é liberada conforme o contrato.
`blocked_cents`	Bloqueado por devolução em andamento, contestação (MED) ou pagamento retido.
`payout_reserved_cents`	Reservado para saques pedidos e ainda não pagos.
`available_for_payout_cents`	Quanto você pode pedir de saque agora (o disponível).
`to_receive_cents`	A receber da Wavewhite: pendente + disponível + reserva contratual (sem o bloqueado).
`owed_to_koku_cents`	Valor devido à Wavewhite (por exemplo, uma contestação maior que o saldo). É abatido do que ficar disponível em seguida.
`payouts_by_koku`	`true` quando os repasses são feitos pela Wavewhite conforme o contrato: você pede o saque (pelo painel ou pela API) e a Wavewhite aprova e transfere.
`payouts_suspended`	`true` quando os repasses estão suspensos; o motivo vem em `suspension_reasons`.

Os valores vêm em centavos (string). Quando o líquido passa de pendente a disponível depende da regra da adquirente que processou a venda (na hora ou depois da liquidação conciliada): veja Como funciona. O evento balance.available avisa quando um valor passa a disponível.

Extrato

GET /v1/statement lista os lançamentos que movimentaram o seu saldo, do mais recente para o mais antigo. Escopo: statement:read. Referência: Consultar extrato.

GET/v1/statement

curl -X GET 'https://api.wavewhite.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100' \
  -H "Authorization: Bearer $API_KEY"

const response = await fetch('https://api.wavewhite.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.wavewhite.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.wavewhite.com/v1/statement?from=2026-10-01T03%3A00%3A00.000Z&to=2026-11-01T03%3A00%3A00.000Z&limit=100');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "items": [
    {
      "journal_id": "2b7e4c19-8a3d-4f60-9c15-e7a2d5b8f031",
      "line_no": 1,
      "event_type": "payout.paid",
      "description": "Saque pago (E98765432202610121300Sq4Ke7Mn2Pw)",
      "economic_at": "2026-10-12T13:00:00.000Z",
      "posted_at": "2026-10-12T13:04:00.000Z",
      "position": "payout_reserved",
      "amount_cents": "-5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "6d0a3f58-2c9e-4b17-a4d6-1f8e5b3c7a29",
      "line_no": 2,
      "event_type": "payout.reserved",
      "description": "Reserva para saque solicitado",
      "economic_at": "2026-10-10T17:00:00.000Z",
      "posted_at": "2026-10-10T17:00:00.000Z",
      "position": "payout_reserved",
      "amount_cents": "5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "6d0a3f58-2c9e-4b17-a4d6-1f8e5b3c7a29",
      "line_no": 1,
      "event_type": "payout.reserved",
      "description": "Reserva para saque solicitado",
      "economic_at": "2026-10-10T17:00:00.000Z",
      "posted_at": "2026-10-10T17:00:00.000Z",
      "position": "available",
      "amount_cents": "-5000",
      "source_type": "payout",
      "source_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
      "is_reversal": false,
      "sale": null,
      "payout": {
        "payout_id": "a4c81e5d-7f2b-4d39-9e06-3b5f8c1d2e74",
        "requested_cents": "5000",
        "fee_cents": "500",
        "amount_cents": "4500"
      },
      "financial_case": null
    },
    {
      "journal_id": "5e9b3d71-c2a8-4f06-8d14-b7e0a6c3f952",
      "line_no": 1,
      "event_type": "gateway.external_payout",
      "description": "Repasse feito pela Wavewhite (E98765432202610081000Zx9Yw8Vu7Ts)",
      "economic_at": "2026-10-08T10:00:00.000Z",
      "posted_at": "2026-10-08T10:05:00.000Z",
      "position": "available",
      "amount_cents": "-10670",
      "source_type": "gateway",
      "source_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
      "is_reversal": false,
      "sale": null,
      "payout": null,
      "financial_case": null
    },
    {
      "journal_id": "0c5e8a3f-7b21-4d96-a4e0-3f9b1d7c5e28",
      "line_no": 2,
      "event_type": "gateway.funds_available",
      "description": "Valor liberado para saque (na hora ou depois da liquidação, conforme a adquirente)",
      "economic_at": "2026-10-08T08:00:00.000Z",
      "posted_at": "2026-10-08T08:00:02.000Z",
      "position": "available",
      "amount_cents": "15670",
      "source_type": "charge",
      "source_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "is_reversal": false,
      "sale": {
        "payment_id": "d7b3e9c2-5a14-4f6e-8b20-9c1e4a7d3f56",
        "charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
        "order_reference": "PEDIDO-1001",
        "classification": "primary",
        "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
        "paid_at": "2026-10-07T15:32:10.000Z",
        "gross_cents": "15990",
        "fee_cents": "320",
        "net_cents": "15670",
        "reserve_cents": "0",
        "payable_cents": "15670"
      },
      "payout": null,
      "financial_case": null
    },
    {
      "journal_id": "7a1d4c9e-2f6b-4e83-9b05-c8e3a2f1d746",
      "line_no": 3,
      "event_type": "charge.paid",
      "description": "Pagamento confirmado do pedido PEDIDO-1001",
      "economic_at": "2026-10-07T15:32:10.000Z",
      "posted_at": "2026-10-07T15:32:11.000Z",
      "position": "pending",
      "amount_cents": "15670",
      "source_type": "charge",
      "source_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
      "is_reversal": false,
      "sale": {
        "payment_id": "d7b3e9c2-5a14-4f6e-8b20-9c1e4a7d3f56",
        "charge_id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
        "order_reference": "PEDIDO-1001",
        "classification": "primary",
        "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
        "paid_at": "2026-10-07T15:32:10.000Z",
        "gross_cents": "15990",
        "fee_cents": "320",
        "net_cents": "15670",
        "reserve_cents": "0",
        "payable_cents": "15670"
      },
      "payout": null,
      "financial_case": null
    }
  ],
  "next_cursor": null,
  "as_of": "2026-10-08T10:10:00.000Z"
}

Como ler cada item:

position diz qual parte do saldo mudou (pending, available, contract_reserve, case_hold, payout_reserved ou receivable) e amount_cents o efeito: positivo aumenta, negativo reduz. Uma venda que passa de pendente para disponível gera duas linhas no mesmo lançamento (journal_id): uma negativa em pending e uma positiva em available.
sale liga a linha à venda: pedido, bruto (gross_cents), tarifa (fee_cents), líquido (net_cents), reserva e o que vai para o saldo (payable_cents).
financial_case liga a linha a uma devolução, contestação ou bloqueio, com o pedido a que se refere.
event_type diz o que gerou o lançamento e é o campo para decidir no código. description é um texto fixo da Wavewhite para exibição.
O período usa economic_at (data do fato): from inclusivo, to exclusivo. Padrão: os últimos 30 dias.
Até 500 itens por página; pagine com cursor. Veja Paginação.

Tipos de lançamento

`event_type`	O que é	`position`
`charge.paid`	Venda paga: o líquido entra como pendente.	`pending`
`reserve.held` / `reserve.released`	Reserva contratual da venda retida e, depois, liberada.	`contract_reserve`, `pending` ou `available`
`gateway.funds_available`	Líquido da venda liberado para saque (na hora ou depois da liquidação, conforme a adquirente): sai de pendente e entra em disponível.	`pending` e `available`
`payout.reserved`	Saque pedido (pelo painel ou pela API): o valor pedido sai do disponível e fica reservado até o pagamento. `payout` traz o valor pedido, a taxa de saque e o valor enviado.	`available` (negativo) e `payout_reserved` (positivo)
`payout.paid`	Saque pago: a Wavewhite transferiu o valor enviado (pedido − taxa de saque) para a sua conta. `description` traz a referência da transferência.	`payout_reserved` (negativo)
`payout.released`	Saque recusado pela Wavewhite ou cancelado por você antes da aprovação: o valor pedido volta ao disponível.	`payout_reserved` (negativo) e `available` (positivo)
`gateway.external_payout`	Repasse feito pela Wavewhite sem pedido de saque (`source_type: "gateway"`, `source_id` = id da sua conta). `description` traz a referência da transferência, a mesma de Listar repasses.	`available` (negativo)
`charge.payment_held`	Pagamento duplicado ou sem correspondência, retido para devolução ao pagador.	`case_hold`
`case.hold` / `case.release`	Valor bloqueado por devolução ou contestação e, se for o caso, liberado.	`pending`, `available` e `case_hold`
`refund.completed` / `case.returned`	Devolução concluída: o valor bloqueado saiu para o pagador.	`case_hold`
`gateway.receivable_covered`	Valor devido à Wavewhite compensado com saldo disponível.	`available` e `receivable`
`journal.reversal`	Estorno de um lançamento anterior (`is_reversal: true`).	a do lançamento estornado

Tipos novos podem aparecer: trate um event_type desconhecido pelo sinal de amount_cents e pela position.

Saques

Os repasses do seu saldo para a sua conta bancária são feitos pela Wavewhite, conforme o contrato. Você pede o saque a qualquer hora, pelo painel ou pela API (POST /v1/payouts): o valor pedido sai do disponível e fica reservado (payout_reserved_cents), a Wavewhite analisa, transfere e marca o saque como pago. Taxa, limites, conta de destino, acompanhamento e cancelamento estão em Saques.

Repasses feitos pela Wavewhite sem pedido

A Wavewhite também pode repassar valores sem que você peça (conforme o contrato). Cada repasse sai do seu saldo disponível e aparece no extrato como gateway.external_payout.

GET /v1/payouts/by-koku lista esses repasses, com a referência da transferência. Escopo: payouts:read. Os saques que você pediu (pelo painel ou pela API) não entram nesta lista: eles aparecem em Listar saques, no extrato e nos eventos payout.*. Referência: Listar repasses.

GET/v1/payouts/by-koku

curl -X GET 'https://api.wavewhite.com/v1/payouts/by-koku' \
  -H "Authorization: Bearer $API_KEY"

const response = await fetch('https://api.wavewhite.com/v1/payouts/by-koku', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.wavewhite.com/v1/payouts/by-koku",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.wavewhite.com/v1/payouts/by-koku');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

200Resposta

{
  "items": [
    {
      "id": "4b8f2c6e-1a9d-4e37-8c05-6f3a9d2e7b14",
      "amount_cents": "10670",
      "external_reference": "E98765432202610081000Zx9Yw8Vu7Ts",
      "paid_at": "2026-10-08T10:00:00.000Z"
    }
  ]
}

Prazos e frequência dos repasses seguem o contrato; dúvidas, fale com a Wavewhite (veja Suporte).

Conciliação

Para fechar o seu financeiro:

Some as vendas do período pelo extrato (sale.gross_cents, sale.fee_cents, sale.net_cents) ou pelas cobranças pagas.
Desconte devoluções e contestações (financial_case).
Compare o disponível com os saques e repasses: cada linha payout.paid do extrato é um saque pago (valor pedido, taxa de saque e valor enviado em payout, referência da transferência em description), e cada linha gateway.external_payout corresponde a um item de Listar repasses com a mesma referência de transferência.

Tarifas por venda: veja Tarifas.

#Saldo

#Extrato

#Tipos de lançamento

#Saques

#Repasses feitos pela Wavewhite sem pedido

#Conciliação

Saldo

Extrato

Tipos de lançamento

Saques

Repasses feitos pela Wavewhite sem pedido

Conciliação