WebSocket

Use WebSocket when your integration needs real-time Pix confirmation but cannot expose a public HTTPS webhook endpoint. Charge creation still happens through the REST API; WebSocket only delivers events.

Endpoint

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

Authentication

Use the same API key created under Integrations → API Keys. Clients that support custom headers can send Authorization: Bearer ky_... or X-API-Key: ky_....

For Node.js and runtimes without custom WebSocket headers:

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

Subscribe to payment events

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

You can also subscribe to one exact event such as payment.paid, or track one charge by its public_id:

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

A payment-specific subscription is automatically removed after payment.paid, payment.failed or payment.canceled. If the payment is already final when you subscribe, KyvoPay immediately sends its current final state.

Event payload

{
  "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"
  }
}

Limits

Each connection supports up to 64 subscriptions, and each company can keep up to 20 WebSocket connections open. Payment events require payments:read; payout events require transfers:read.