Visão geral da API
Uma API REST para cobrar por PIX, boleto e cartão, acompanhar saldo e liquidações, sacar e receber cada evento por webhook assinado.
A API Kodano conecta a sua plataforma à operação de pagamentos da Kodano. Com ela você cria cobranças, consulta o que entrou e o que já foi liquidado, faz saques para contas cadastradas e recebe uma notificação assinada a cada mudança de status.
Acesso por convite
A API v1 está em piloto. O acesso é liberado por convite, a começar pelo sandbox. A produção abre para cada parceiro depois da homologação.
O que dá para fazer
Pagamentos
Cobranças por PIX, boleto e cartão, captura, estorno e cancelamento.
Clientes e cartões
Cadastro de pagadores e cofre de cartões para cobranças recorrentes.
Links de pagamento
Um link pronto para enviar ao cliente, sem montar checkout.
Saldo, extrato e liquidações
O que está disponível, o que entrou e o que foi liquidado em cada dia.
Saques
Transferência do saldo para contas bancárias e chaves PIX verificadas.
Webhooks
Eventos de pagamento, estorno, saque e liquidação, assinados e com retentativa.
Como a API funciona
- REST sobre HTTPS. Corpo em JSON, campos em camelCase e enums em MAIÚSCULAS. Toda rota começa com
/v1. - Um endpoint por método de pagamento. Para cobrar por PIX você chama
POST /v1/payments/pix; boleto e cartão têm rotas próprias. Consultas, estornos e cancelamentos são comuns aos três em/v1/payments/{id}. - Valores em centavos.
amounté sempre um inteiro em centavos, acompanhado decurrency(BRL). R$ 159,90 é15990. - Credencial de máquina, não API Key. A autenticação é OAuth 2.0: você troca a credencial por um token de acesso e envia
Authorization: Bearer <token>em cada chamada. Veja Credenciais e autenticação. - Acesso por produto. Cada produto contratado (PIX, boleto, cartão, saques…) libera um conjunto de escopos. Uma rota fora dos seus produtos responde
403 AUTH.ENTITLEMENT_MISSING. Veja Produtos e escopos. - Merchant explícito. Credenciais de organização indicam em qual loja (merchant) a operação acontece com o header
X-Merchant-Id. Veja Merchant e X-Merchant-Id. - Idempotência obrigatória onde há dinheiro. Todo
POSTque cria recurso ou move dinheiro exigeIdempotency-Key. Repetir a chamada com a mesma chave devolve a resposta original, sem cobrar duas vezes. Veja Idempotência. - Erros padronizados. Toda falha volta em
application/problem+jsoncom umcodeestável para o seu código tratar. Veja Erros.
Ambientes
| Ambiente | Base da API | Para quê |
|---|---|---|
| Sandbox | https://api.sandbox.kodano.com.br/v1 | Integrar e testar, sem dinheiro de verdade |
| Produção | https://api.kodano.com.br/v1 | Operação real, liberada após a homologação |
Os dois ambientes são isolados: credencial, cobranças, webhooks e eventos de um nunca aparecem no outro. Os exemplos desta documentação usam o sandbox; o seletor no topo da página troca o host dos exemplos de código. Mais detalhes em Ambientes.
Anatomia de uma chamada
curl -X POST https://api.sandbox.kodano.com.br/v1/payments/pix \
-H "Authorization: Bearer $KODANO_ACCESS_TOKEN" \
-H "X-Merchant-Id: mrc_dbd3bd9cd2ae463997022ee37a888b7a" \
-H "Idempotency-Key: b2eab92e-2dbf-4cb5-b4da-02e025095a53" \
-H "Content-Type: application/json" \
-d '{
"amount": 15990,
"currency": "BRL",
"description": "Pedido 123",
"customer": {
"name": "Ana Souza",
"document": "12345678909",
"email": "ana@exemplo.com.br"
}
}'| Header | Obrigatório | Para quê |
|---|---|---|
Authorization | sempre | Bearer + token de acesso obtido no servidor de autorização |
X-Merchant-Id | com credencial de organização | Loja em que a operação acontece (mrc_ + 32 caracteres hexadecimais) |
Idempotency-Key | em POST que cria recurso ou move dinheiro | UUID único por operação, válido por 24 horas |
X-Correlation-Id | não | Identificador seu para rastrear a chamada; volta na resposta e nos erros |
Content-Type | com corpo | application/json |