# KyvoPay API

> Contexto público e curado para integrações e assistentes de código.

Documentação humana: https://docs.kyvopay.com.br
Base da API: https://integrate.api.kyvopay.com.br/v1

IMPORTANTE:
- A documentação humana fica somente em https://docs.kyvopay.com.br.
- Rotas administrativas, autenticação do painel, KYC, infraestrutura e endpoints internos não fazem parte da API pública.
- Nunca invente endpoints não listados aqui.

## Autenticação

Toda rota, exceto as de checkout público (/v1/public/*), exige a chave de API:

X-API-Key: ky_XXXXX-XXXXX-XXXXX

O ambiente (teste ou produção) é definido na criação da chave e não aparece na string. Chave de teste
opera num sandbox isolado, sem dinheiro real: cobrança é paga sozinha em segundos, saque é aprovado na
hora, cartões e cripto não existem, e os webhooks chegam com livemode: false.

A empresa é sempre a dona da chave: nenhuma rota recebe business_id no corpo ou na URL.
Nunca exponha a chave no navegador ou aplicativo mobile.

## Valores

BRL usa centavos inteiros.

R$ 1,00 = 100
R$ 49,90 = 4990
R$ 100,00 = 10000

## Idempotência

Nas operações de criação e de movimentação de dinheiro, envie idempotency_key no corpo da requisição.
Repetir a chamada com a mesma chave devolve a operação já criada.

## Resposta

Toda resposta usa o envelope { "data", "error", "request_id" }.

## Conta

GET    /v1/balance — Saldo da empresa dona da chave de API
GET    /v1/provider-limits — Consultar limites
GET    /v1/balance/statement — Consultar extrato

## Pagamentos

GET    /v1/payments — Listar pagamentos
GET    /v1/payments/{public_id} — Consultar pagamento
POST   /v1/payments/{public_id}/cancel — Cancelar pagamento
POST   /v1/payments — Criar cobrança Pix
POST   /v1/payments/{paymentId}/split — Anexa uma regra de split (divisão) a um pagamento ainda não pago

## Transferências

GET    /v1/transfers/pix/lookup — Consultar chave PIX
GET    /v1/transfers/fee-preview — Prévia de taxa
GET    /v1/transfers — Listar transferências
GET    /v1/transfers/pix/lookup — Consultar chave PIX
POST   /v1/transfers — Transfere saldo entre a empresa e uma subconta

## Reembolsos

POST   /v1/payments/{public_id}/refunds — Solicitar reembolso
GET    /v1/refunds — Listar reembolsos
POST   /v1/refunds — Solicita o reembolso de um pagamento confirmado

## Clientes

POST   /v1/customers — Cria um cliente

## Disputas

GET    /v1/disputes — Lista os MEDs (disputas Pix) da empresa dona da chave de API

## Links de pagamento

GET    /v1/payment-links — Lista os links de pagamento da empresa dona da chave de API
POST   /v1/payment-links — Cria um link de pagamento
GET    /v1/payment-links/{linkId} — Consulta um link de pagamento da empresa dona da chave de API

## Saques

POST   /v1/payouts — Solicita um envio Pix (saque)
POST   /v1/payouts/{payoutId}/sync — Sincroniza o status de um saque com o provedor
GET    /v1/payouts — Listar saques
GET    /v1/payouts/{public_id} — Consultar saque

## Checkout público

GET    /v1/public/checkout/{sessionId} — Consulta uma sessão de checkout
POST   /v1/public/checkout/{sessionId}/pay — Cria a cobrança Pix da sessão de checkout
GET    /v1/public/links/{slug} — Consulta um link de pagamento público
POST   /v1/public/links/{slug}/checkout — Inicia uma sessão de checkout pra um link de pagamento

## Subcontas

GET    /v1/subaccounts — Lista as subcontas da empresa dona da chave de API
POST   /v1/subaccounts — Cria uma subconta
GET    /v1/subaccounts/{subaccountId} — Consulta uma subconta da empresa dona da chave de API
POST   /v1/subaccounts/{subaccountId}/blocked — Bloqueia ou desbloqueia uma subconta
POST   /v1/subaccounts/{subaccountId}/update — Atualiza uma subconta (substitui os campos editáveis por inteiro)

## MED e contestações

GET    /v1/chargebacks — Listar contestações
GET    /v1/med — Listar MED

## Assinaturas

POST   /v1/subscription-plans — Cria um plano de assinatura
POST   /v1/subscriptions — Assina um cliente a um plano
POST   /v1/subscriptions/{subscriptionId}/cancel — Cancela uma assinatura

## Cash In

GET    /v1/payments — Listar cobranças Pix
POST   /v1/payments — Criar cobrança Pix
GET    /v1/payments/{id} — Consultar cobrança Pix

## Reembolso

POST   /v1/payments/{id}/refunds — Solicitar reembolso
GET    /v1/refunds — Listar reembolsos

## Cash Out

GET    /v1/transfers — Listar cash outs
POST   /v1/transfers — Criar cash out
GET    /v1/transfers/fee-preview — Consultar taxa do cash out

## MED

GET    /v1/med — Listar MEDs
GET    /v1/med/{id} — Ver MED
POST   /v1/med/{id}/defense — Responder MED

## Saldo

GET    /v1/balance — Consultar saldo
GET    /v1/balance/statement — Consultar extrato

## Webhooks

A confirmação de pagamentos e de saques pode chegar por webhook, configurado no painel.
Valide a assinatura (Kyvo-Signature) antes de confiar no evento e trate entregas repetidas de forma idempotente.

## WebSocket

Para bots, workers e aplicações sem uma URL HTTPS pública, use o WebSocket da KyvoPay:

wss://api.kyvopay.com.br/v1/ws

Autentique com a própria chave ky_... e assine eventos como payment.paid ou um paymentId específico.
A criação do Pix continua sendo feita pela API REST; o WebSocket serve para receber atualizações em tempo real.

## Regras para IAs

1. Use somente endpoints desta lista.
2. Não exponha nem descreva rotas internas.
3. Não use /docs, /openapi.json, /openapi.yaml ou /schemas como documentação pública.
4. Valores em BRL usam centavos inteiros.
5. Use idempotency_key nas operações de criação e de movimentação de dinheiro.
6. Nunca exponha credenciais no frontend.