Skip to main content
A API Korbit é REST/JSON com contratos versionados via OpenAPI. Tudo que está nesta referência é o que a API faz — a especificação é gerada automaticamente do nosso OpenAPI 3.1.

​
Bases por ambiente

O ambiente é derivado da chave — não existe parâmetro de ambiente na requisição. Detalhes em Autenticação e Ambientes e sandbox.

​
Autenticação

Todas as rotas desta referência exigem chave de API de merchant no header Authorization:
Cada chave tem escopos (payments:write, payouts:write, refunds:write…) que limitam o que ela pode fazer. Rota sem escopo retorna 403 INSUFFICIENT_SCOPE.

​
Convenções que valem para todos os endpoints

Idempotência

Toda mutação aceita Idempotency-Key: retries são seguros — mesma chave + mesmo payload retorna a resposta original.

Erros RFC 7807

Erros em application/problem+json com code estável. Decida sua lógica pelo code, nunca pelo texto.

Rate limits

Limites por rota (ex.: 60/min para criar payment intent) com headers Rate-Limit-* e 429 + Retry-After.

Moeda

Todos os valores são inteiros em centavos (BRL): 14990 = R$ 149,90.

​
Dev mode (sandbox)

Com uma chave kbt_test_ você desenvolve o fluxo completo sem tocar em dinheiro: providers fake, código PIX de teste e endpoints de simulação para controlar aprovações, recusas e expirações — inclusive a entrega de webhooks assinados. Veja Sandbox.

​
Webhooks

O estado muda na Korbit, o seu sistema fica sabendo por webhooks assinados (padrão Svix) — pagamentos, refunds, payouts, disputas e atualizações de conta. A entrega é at-least-once com agenda de retries. Veja a tab de Webhooks.

​
Como ler esta referência

Cada categoria começa com uma página de referência que explica o modelo de objetos, os estados e o contexto de uso — depois vêm os endpoints gerados da spec, com descrição de cada campo e exemplos prontos para o playground. Recomendação de leitura para começar: Pagamentos → Checkout → Webhook Subscriptions.