Tarifas

A tarifa da Koku é a do seu contrato. Ela pode ter uma parte percentual, uma parte fixa por transação ou as duas, e é a única tarifa sobre a venda: o que você vê na API é o que sai da venda.

#Onde a tarifa aparece

Na criação, a cobrança já mostra a tarifa vigente: fee_percent_bps (percentual em pontos-base: 200 = 2,00%) e fee_fixed_cents (fixa, em centavos). Quando a venda é paga, a cobrança passa a trazer o cálculo:

{
  "id": "8d3f6a12-4b9e-4c71-a2d5-6e0f1b3c9a47",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "order_reference": "PEDIDO-1001",
  "amount_cents": "15990",
  "currency": "BRL",
  "description": "Pedido 1001 - Loja Exemplo",
  "status": "paid",
  "fee_percent_bps": 200,
  "fee_fixed_cents": "0",
  "fee_cents": "320",
  "net_cents": "15670",
  "reserve_cents": "0",
  "refunded_cents": "0",
  "expires_at": "2026-10-07T16:00:00.000Z",
  "paid_at": "2026-10-07T15:32:10.000Z",
  "late_payment": false,
  "is_simulated": false,
  "created_at": "2026-10-07T15:30:00.000Z",
  "updated_at": "2026-10-07T15:32:11.000Z",
  "pix": {
    "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qr.exemplo.com.br/pix/v2/8d3f6a124b9e4c71a2d56e0f1b3c9a475204000053039865406159.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
    "txid": "8d3f6a124b9e4c71a2d56e0f1b3c9a47",
    "expires_at": "2026-10-07T16:00:00.000Z"
  },
  "end_to_end_id": "E12345678202610071532a1B2c3D4e5F",
  "payments_count": 1,
  "failure_message": null
}

Os mesmos valores aparecem no evento charge.paid e no extrato, em sale.

#Como o cálculo é feito

• Tarifa = bruto × percentual + parte fixa, sempre em centavos inteiros, com o arredondamento previsto no contrato. No exemplo: 2% de R$ 159,90 = R$ 3,198, que vira R$ 3,20.
• O contrato pode ter tarifa mínima e tarifa máxima por venda. Elas são aplicadas depois do cálculo acima: se o resultado ficar abaixo do mínimo, vale o mínimo; acima do máximo, vale o máximo. Em vendas de valor baixo, a tarifa mínima costuma ser a que vale.
• fee_cents já vem com tudo isso aplicado. Para conciliar, use sempre fee_cents e net_cents da cobrança (ou de sale no extrato), em vez de recalcular a partir de fee_percent_bps e fee_fixed_cents. Os valores de mínimo e máximo do seu contrato ficam no painel, em Configurações.
• A tarifa usada é a vigente quando a cobrança foi criada (gravada na cobrança), mesmo que o contrato mude antes do pagamento.
• Na devolução, a tarifa da venda não é devolvida, salvo disposição diferente no contrato.

#Mudança de tarifa

Mudanças de condição comercial nunca são silenciosas: a Koku publica a nova tarifa com vigência e você é avisado pelo evento pricing.policy_published (e reserve.policy_published para reserva contratual). As condições vigentes ficam no painel, em Configurações.

#Valores de exemplo

Os valores desta documentação são fictícios. A sua tarifa está no seu contrato e no painel.