> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossario da API TurbofyPay

> Conceitos e termos tecnicos da TurbofyPay explicados de forma simples para acelerar sua integracao.

<div className="turbofy-hero">
  <span className="turbofy-eyebrow">Conceitos essenciais</span>
  Esta pagina explica os principais termos da documentacao em linguagem direta,
  para voce entender rapido o que cada parte faz antes de integrar.
</div>

<div className="turbofy-note">
  <Note>
    <strong>Bem-vindo ao Glossario:</strong> ficou em duvida sobre um termo?
    Comece por aqui e depois siga para as paginas de endpoint.
  </Note>
</div>

O mapa abaixo mostra a relacao entre autenticacao, escrita idempotente,
cobrancas, webhooks, payouts e status. Use como leitura inicial antes de abrir
os endpoints em detalhe.

<img src="https://mintcdn.com/turbofypay/PV8PQGFRC5_DV7l4/images/enterprise/api-glossary-map.png?fit=max&auto=format&n=PV8PQGFRC5_DV7l4&q=85&s=164d34c6d06fddcf6b13f16f43c957c6" alt="Mapa conceitual conectando clientId, secret, timestamp, signature, idempotencyKey, charge, PIX, webhook, payout batch e status." width="1586" height="992" data-path="images/enterprise/api-glossary-map.png" />

*Conceitos de autenticacao protegem quem chama a API. Conceitos de produto representam o ciclo financeiro, da cobranca PIX ao payout em lote.*

## Autenticacao e seguranca

### x-client-id

Identificador publico da sua conta na TurbofyPay.\
Funciona como "quem esta chamando a API".

### x-client-secret

Segredo da sua conta para autenticar chamadas.\
Sempre use no backend. Nunca exponha no frontend.

### x-turbofy-timestamp

Horario da requisicao em milissegundos (UTC).\
Usado para validar janela de tempo e reduzir replay.

### x-turbofy-signature

Assinatura HMAC da requisicao.\
Obrigatoria em rotas de payouts.

### x-idempotency-key

Chave unica para evitar duplicidade em operacoes de escrita.\
Se a mesma chave for reenviada, a API evita criar o mesmo efeito duas vezes.

## Pagamentos e cobrancas

### Gateway de Pagamento

Plataforma intermediária que processa pagamentos entre o cliente e o vendedor. A TurbofyPay é um gateway de pagamento que facilita transações PIX e cartão de crédito.

### Fintech

Empresa que usa tecnologia para oferecer serviços financeiros. A TurbofyPay é uma fintech focada em simplificar pagamentos.

### Cobranca PIX

Registro de cobranca criado para pagamento via PIX.

### Payout

Transferência de dinheiro da sua conta TurbofyPay para outra conta (seja sua ou de terceiros). Também chamado de saque ou transferência externa.

### Lote de payouts

Conjunto de payouts enviados em uma unica solicitacao para processamento.

### Webhook

Notificacao automatica enviada pela TurbofyPay para sua URL quando um evento acontece.

## Estrutura de dados

### externalRef

Codigo do seu sistema para relacionar a transacao internamente.

### amountCents

Valor em centavos.\
Exemplo: `2990` representa `R$ 29,90`.

### metadata

Campo opcional para dados extras de conciliacao.

### bill\_\*

Prefixo do identificador publico de checkout em `/v1/checkouts`.
Exemplo: `bill_session_abc123`.

## Status mais comuns

### Cobranca PIX

* `PENDING`: aguardando pagamento
* `PAID`: pagamento confirmado
* `CANCELLED`: cobranca cancelada
* `EXPIRED`: cobranca expirada

### Checkout P0

* `PENDING`: checkout criado e aguardando pagamento
* `PAID`: pagamento confirmado
* `CANCELLED`: cancelado
* `EXPIRED`: expirado
* `REFUNDED`: estornado

### Eventos de webhook de cobranca

<div className="turbofy-status-row">
  <span className="turbofy-chip turbofy-chip-green">charge.created</span>
  <span className="turbofy-chip turbofy-chip-green">charge.paid</span>
  <span className="turbofy-chip turbofy-chip-yellow">charge.expired</span>
  <span className="turbofy-chip turbofy-chip-red">charge.cancelled</span>
</div>

## Rotas publicas principais

* `POST /sellers/pix`
* `GET /sellers/pix/{id}`
* `POST /v1/checkouts`
* `GET /v1/checkouts/{id}`
* `GET /v1/checkouts`
* `POST /v1/payouts/batches`
* `GET /v1/payouts/batches/{batchId}`
* `GET /v1/payouts/batches`
* `GET /v1/payouts/batches/{batchId}/items`
* `POST /v1/payouts/batches/{batchId}/cancel`
* `GET /v1/receipts/transactions/{id}`
* `GET /v1/receipts/withdrawals/{id}`

## Proximos passos

1. Configure [Autenticacao](/integracao/autenticacao).
2. Crie sua primeira cobranca em [Criar cobranca PIX](/reference/cobranca-pix/criar-cobranca-pix).
3. Configure callbacks em [Webhooks](/integracao/webhooks).