WebSocket na prática

Tutorial focado em implementar o cliente WebSocket. Referência completa do protocolo: guia de WebSocket. Ideal para bots Discord/Telegram, workers em VPS ou qualquer processo que não expõe porta 443.

1. Pré-requisitos

Chave de API wp_live_... (a mesma que você usa na REST API)
Node 18+ ou Python 3.10+
Processo rodando no servidor — nunca no browser

Não coloque wp_live_... em frontend, app mobile ou repositório público. Use variável de ambiente (WovePay_API_KEY).

2. Conectar e autenticar

Endpoint:

wss://ws.wovepay.com/v1

Três formas de autenticar (escolha uma):

Modo	Exemplo
Query string	`wss://ws.wovepay.com/v1?token=wp_live_...`
Header	`Authorization: Bearer wp_live_...`
Mensagem	`{ "action": "authenticate", "apiKey": "wp_live_..." }`

Você deve receber:

{ "event": "authenticated", "version": "1" }

3. Inscrever-se em eventos

Após autenticar, envie:

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

Resposta:

{ "event": "subscribed", "pattern": "payment.*" }

Patterns úteis: payment.*, transfer.*, refund.*, payment_link.paid (via payment.*), *. Para um pagamento específico:

{ "action": "subscribe", "paymentId": "clx_transacao" }

4. Node.js

npm install ws

import WebSocket from "ws";

const API_KEY = process.env.WovePay_API_KEY;
const seen = new Set();

const ws = new WebSocket(`wss://ws.wovepay.com/v1?token=${API_KEY}`);

ws.on("open", () => {
  console.log("conectado");
  ws.send(JSON.stringify({ action: "subscribe", pattern: "payment.*" }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(String(raw));

  // Obrigatório: responder ao heartbeat do servidor
  if (msg.event === "ping") {
    ws.send(JSON.stringify({ action: "ping" }));
    return;
  }

  if (msg.event === "error") {
    console.error("erro:", msg.code);
    return;
  }

  if (!msg.id || seen.has(msg.id)) return;
  seen.add(msg.id);

  if (msg.event === "payment.paid") {
    console.log("PIX pago:", msg.data.id, msg.data.amount);
  }

  ws.send(JSON.stringify({ action: "ack", id: msg.id }));
});

ws.on("close", () => {
  console.log("desconectado — reconecte com backoff (1s → 30s)");
});

5. Python

pip install websockets

import asyncio
import json
import os
import websockets

API_KEY = os.environ["WovePay_API_KEY"]
seen = set()

async def main():
    uri = f"wss://ws.wovepay.com/v1?token={API_KEY}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({"action": "subscribe", "pattern": "payment.*"}))

        async for raw in ws:
            msg = json.loads(raw)
            event = msg.get("event")

            if event == "ping":
                await ws.send(json.dumps({"action": "ping"}))
                continue

            if event == "error":
                print("erro:", msg.get("code"))
                continue

            delivery_id = msg.get("id")
            if not delivery_id or delivery_id in seen:
                continue
            seen.add(delivery_id)

            if event == "payment.paid":
                print("PIX pago:", msg["data"])

            await ws.send(json.dumps({"action": "ack", "id": delivery_id}))

asyncio.run(main())

6. Testar ponta a ponta

Exportar a API key

export WovePay_API_KEY=wp_live_SUA_CHAVE

Rodar o script

node bot.js ou python bot.py — aguarde authenticated / subscribed.

Criar um PIX de teste

Use a mesma API key:

curl -X POST https://api.wovepay.com/v1/payment-pix/create \
  -H "X-API-Key: $WovePay_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "externalReference": "ws-test"}'

Validar eventos

Você deve receber payment.created. Após pagar o QR, payment.paid.

7. Eventos que você provavelmente precisa

Evento	Quando usar
`payment.paid`	PIX recebido — liberar pedido
`payment.created`	Cobrança registrada (opcional)
`payment.pix.expired`	QR expirou — cancelar checkout
`transfer.completed`	Saque PIX concluído
`payment_link.paid`	Link de pagamento pago
`refund.completed`	Reembolso confirmado
`med.created`	Disputa MED aberta

Lista completa: guia de WebSocket — eventos.

8. Escopo por API key

Conexões com wp_live_... recebem eventos das transações criadas pela mesma API key. Se o evento não chega, confira se a cobrança foi criada com a chave usada na conexão.

Checklist

WovePay_API_KEY em variável de ambiente
Handler de ping → { "action": "ping" }
Idempotência pelo id da entrega
ack após processar (opcional, recomendado)
Reconexão com backoff após close
REST API como fallback após downtime (GET /payment-pix/get/:id)

Próximo passo

Guia completo WebSocket · Criar cobrança PIX · Webhooks HTTP se tiver URL pública

Começar

Integração

Tutoriais

Ajuda

WebSocket na prática

1. Pré-requisitos

2. Conectar e autenticar

3. Inscrever-se em eventos

4. Node.js

5. Python

6. Testar ponta a ponta

7. Eventos que você provavelmente precisa

8. Escopo por API key

Checklist

Próximo passo

​1. Pré-requisitos

​2. Conectar e autenticar

​3. Inscrever-se em eventos

​4. Node.js

​5. Python

​6. Testar ponta a ponta

​7. Eventos que você provavelmente precisa

​8. Escopo por API key

​Checklist

​Próximo passo

1. Pré-requisitos

2. Conectar e autenticar

3. Inscrever-se em eventos

4. Node.js

5. Python

6. Testar ponta a ponta

7. Eventos que você provavelmente precisa

8. Escopo por API key

Checklist

Próximo passo