Conceitos essenciais
Esta pagina explica os principais termos da documentacao em linguagem direta,
para voce entender rapido o que cada parte faz antes de integrar.
Bem-vindo ao Glossario: ficou em duvida sobre um termo?
Comece por aqui e depois siga para as paginas de endpoint.
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.Status mais comuns
Cobranca PIX
PENDING: aguardando pagamentoPAID: pagamento confirmadoCANCELLED: cobranca canceladaEXPIRED: cobranca expirada
Eventos de webhook de cobranca
charge.createdcharge.paidcharge.expiredcharge.cancelled
Rotas publicas principais
POST /sellers/pixGET /sellers/pix/{id}POST /v1/payouts/batchesGET /v1/payouts/batches/{batchId}GET /v1/payouts/batchesGET /v1/payouts/batches/{batchId}/itemsPOST /v1/payouts/batches/{batchId}/cancel
Proximos passos
- Configure Autenticacao.
- Crie sua primeira cobranca em Criar cobranca PIX.
- Configure callbacks em Webhooks.