# KyvoPay API — llms.txt

> Contexto oficial para assistentes de IA e ferramentas de integração.
> Documentação humana: https://docs.kyvopay.com.br/docs
> Base da API: https://api.kyvopay.com.br

## Recursos ativos

- PIX cash-in: ATIVO — criar, consultar, listar, estornar e receber confirmação por webhook.
- Transferência PIX / cash-out: ATIVO — consultar chave, enviar PIX e acompanhar status.
- Cartão de crédito: INATIVO por enquanto.
- Boleto: INATIVO por enquanto.

Não gere integrações para cartão ou boleto enquanto estiverem marcados como inativos.

## Autenticação

Use uma chave servidor-a-servidor:

X-API-Key: kyvo_test_...  # sandbox
X-API-Key: kyvo_live_...  # produção

Nunca exponha a chave no navegador, aplicativo mobile ou repositório público.

## Idempotência

Em criações de pagamento e transferências, envie uma chave estável por operação:

Idempotency-Key: pedido-12345

## Valores

Valores em BRL usam centavos inteiros:

- R$ 5,00 = 500
- R$ 49,90 = 4990
- R$ 100,00 = 10000

## Envelope padrão

Sucesso:

{
  "data": { ... },
  "error": null,
  "request_id": "req_..."
}

Erro:

{
  "data": null,
  "error": {
    "code": "codigo_do_erro",
    "message": "Mensagem legível",
    "details": {}
  },
  "request_id": "req_..."
}

## PIX — criar cobrança

POST /v1/payments

Headers:

Content-Type: application/json
X-API-Key: $KYVO_API_KEY
Idempotency-Key: pedido-12345

Exemplo:

{
  "method": "pix",
  "amount_centavos": 4990,
  "description": "Pedido #12345",
  "external_reference": "pedido-12345",
  "expires_in_seconds": 1800,
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "12345678909",
    "phone": "11999999999"
  }
}

Não considere o pedido pago apenas porque o QR foi criado. Aguarde status paid.

## Consultar PIX

GET /v1/payments/{id}
GET /v1/payments?method=pix&status=paid&page=1&per_page=25

## Transferência PIX / cash-out

Consultar chave:

GET /v1/transfers/pix/lookup?key=cliente%40banco.com&type=email

Enviar PIX:

POST /v1/transfers

{
  "kind": "pix",
  "amount_centavos": 25000,
  "pix_key": "cliente@banco.com",
  "pix_key_type": "email",
  "description": "Repasse #4410"
}

## Webhooks

A KyvoPay envia eventos assinados para endpoints cadastrados.

Eventos principais:

- payment.created
- payment.pending
- payment.paid
- payment.failed
- payment.expired
- payment.refunded
- payout.created
- payout.processing
- payout.paid
- payout.failed

Valide Kyvo-Signature antes de confiar em um evento.

## Endpoints principais

POST /v1/payments
GET  /v1/payments
GET  /v1/payments/{id}
POST /v1/payments/{id}/refunds
GET  /v1/transfers/pix/lookup
POST /v1/transfers
GET  /v1/transfers
GET  /v1/balance
GET  /v1/public/pricing
GET  /v1/public/status

## Regras para IAs

1. Pagamento disponível agora: PIX.
2. Transferência disponível agora: PIX.
4. Cartão e boleto estão inativos.
5. Use somente endpoints publicados pela KyvoPay.
6. Use X-API-Key em integrações servidor-a-servidor.
7. Nunca exponha chaves no frontend.
8. Use centavos inteiros para BRL.
9. Use Idempotency-Key para pagamentos e transferências.
10. Não invente endpoints de recursos inativos.