Autenticação

Chaves de API, escopos, ambientes e boas práticas.

Chave de API#

Toda requisição servidor-a-servidor é autenticada pelo header X-API-Key. Não usamos OAuth nem Basic Auth para integração.

A chave completa é exibida apenas no momento da criação. Depois disso o painel mostra só os últimos caracteres — se você perder a chave, rotacione-a e atualize seu ambiente.

Escopos#

Cada chave carrega um conjunto de escopos. Uma chave sem payments:create, por exemplo, consegue consultar cobranças mas não criar. Use isso para separar sistemas que só leem de sistemas que movimentam dinheiro.

Escopo	Permite
`payments:create`	Criar cobranças
`payments:read`	Consultar cobranças e sincronizar status
`payments:cancel`	Cancelar cobranças pendentes
`write`	Escrita geral em recursos da conta

header de autenticação

POST /v1/payments HTTP/1.1
Host: api.kyvopay.com.br
X-API-Key: kyvo_live_9f3c...
Content-Type: application/json

401chave inválida

{
  "data": null,
  "error": {
    "code": "unauthorized",
    "message": "Chave de API inválida ou revogada.",
    "details": {}
  },
  "request_id": "req_0a91cc42"
}

Idempotência#

Em qualquer POST que movimente dinheiro — cobrança, reembolso, saque, transferência — envie o header Idempotency-Key com um valor único do seu lado, normalmente o id do pedido.

Se a mesma chave chegar de novo, devolvemos o recurso original em vez de criar outro. É a proteção contra timeout de rede, retentativa do seu job e duplo clique do usuário.

Limite de requisições#

A API tem limite por minuto e por IP. Ao estourar, você recebe 429 com o código rate_limited. Espere e repita — com a mesma Idempotency-Key, se for uma operação financeira.

Cabeçalhos úteis#

Headers

X-API-Keystringobrigatório

Sua chave de API. Prefixo kyvo_test_ ou kyvo_live_.

Idempotency-Keystringopcional

Torna o POST seguro para repetição. Recomendado em toda operação financeira.

Content-Typestringopcional

Sempre application/json quando houver corpo.

idempotência

curl https://api.kyvopay.com.br/v1/payments \
  -H "X-API-Key: $KYVO_API_KEY" \
  -H "Idempotency-Key: pedido-8291" \
  -H "Content-Type: application/json" \
  -d '{"method":"pix","amount_centavos":12990}'

# repetir a mesma chave devolve a MESMA cobrança