WebSocket

Use o WebSocket quando sua integração precisa receber a confirmação do Pix em tempo real, mas não possui uma URL HTTPS pública para webhooks. A criação da cobrança continua sendo feita pela API REST; o WebSocket entrega apenas os eventos.

Endpoint

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

Autenticação

A conexão usa a mesma chave criada em Integrações → Chaves de API.

Em clientes que aceitam headers customizados, envie:

Authorization: Bearer ky_XXXXX-XXXXX-XXXXX

ou:

X-API-Key: ky_XXXXX-XXXXX-XXXXX

Para Node.js e runtimes cuja API WebSocket não permite headers customizados, use os subprotocolos kyvopay e sua chave:

const ws = new WebSocket(
  "wss://api.kyvopay.com.br/v1/ws",
  ["kyvopay", process.env.KYVO_API_KEY]
);

Conexão estabelecida

Depois da autenticação, o servidor envia:

{
  "type": "connected",
  "connection_id": "ws_...",
  "livemode": true,
  "heartbeat_seconds": 25
}

Chaves live recebem apenas eventos de produção. Chaves test recebem apenas eventos do ambiente de testes.

Assinar eventos

Para receber todos os eventos de pagamento:

{
  "action": "subscribe",
  "pattern": "payment.*"
}

Também é possível assinar somente um evento:

{
  "action": "subscribe",
  "pattern": "payment.paid"
}

Eventos disponíveis:

Para eventos de pagamento, a chave precisa do escopo payments:read. Para eventos de saque, precisa de transfers:read.

Acompanhar somente um Pix

Depois de criar uma cobrança em POST /v1/payments, assine o public_id retornado:

{
  "action": "subscribe",
  "paymentId": "pay_..."
}

A KyvoPay confirma a inscrição:

{
  "type": "subscribed",
  "payment_id": "pay_..."
}

Se o pagamento já estiver em estado final quando a assinatura acontecer, o estado atual é enviado imediatamente. Assim, uma confirmação que ocorra entre a criação do Pix e a abertura do WebSocket não é perdida.

A inscrição por paymentId é encerrada automaticamente em payment.paid, payment.failed ou payment.canceled.

Evento recebido

{
  "id": "payment.paid:pay_...",
  "type": "payment.paid",
  "created_at": "2026-09-25T06:00:00.000Z",
  "livemode": true,
  "data": {
    "id": "pay_...",
    "status": "paid",
    "amount_centavos": 1000,
    "fee_centavos": 40,
    "net_centavos": 960,
    "method": "pix"
  }
}

Exemplo completo para bot

const apiKey = process.env.KYVO_API_KEY;
const ws = new WebSocket(
  "wss://api.kyvopay.com.br/v1/ws",
  ["kyvopay", apiKey]
);
 
ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    pattern: "payment.paid"
  }));
});
 
ws.addEventListener("message", (message) => {
  const event = JSON.parse(String(message.data));
 
  if (event.type !== "payment.paid") return;
 
  console.log("Pix pago:", event.data.id);
  // Entregue o produto, cargo ou serviço aqui.
});
 
ws.addEventListener("close", () => {
  // Em produção, reconecte usando backoff exponencial.
});

Cancelar uma assinatura

{
  "action": "unsubscribe",
  "pattern": "payment.paid"
}

ou:

{
  "action": "unsubscribe",
  "paymentId": "pay_..."
}

Ping e limites

Você pode testar a conexão com:

{
  "action": "ping"
}

Resposta:

{
  "type": "pong",
  "at": "2026-09-25T06:00:00.000Z"
}

A conexão aceita até 64 inscrições simultâneas e até 20 conexões por empresa. O servidor mantém heartbeat periódico e encerra conexões que deixam de responder.