Novidade

A BukioPay agora é WyzeCash. Sua conta, seu saldo e suas chaves de API continuam iguais.

Entrar no Discord
Desenvolvedores

Um POST cobra.
Webhook avisa.

API REST em /v1, chaves com permissões e webhooks assinados. Valores sempre em centavos, IDs com prefixo (BKY-, SAQ-…).

criar-cobranca.sh
POST /v1/payments · 200 OK · BKY-8K2M4QZ7XN3P

SDKs oficiais. Instale e cobre.

Os mesmos campos da API, com tipos e a descrição em português. O que tira dinheiro nunca é repetido sozinho.

Node.js e TypeScript

Node 20+, Bun e Deno
npm install wyzecash
  • Tipos prontos, sem @types
  • Plugin de webhook para o Fastify
  • Eventos ao vivo pelo WebSocket
Documentação do SDK

Python

Python 3.10+
pip install wyzecash
  • Sem dependências: só a biblioteca padrão
  • Respostas com tipos para o editor
  • Webhook no Flask, FastAPI ou Django
Documentação do SDK

PHP

PHP 8.1+ e Laravel
composer require wyzecash/wyzecash
  • Só precisa do cURL e do JSON
  • Provider e middleware do Laravel
  • Campos nos comentários para o PhpStorm
Documentação do SDK
verificar-webhook.js
import { createHmac, timingSafeEqual } from "node:crypto";

export function wyzecash(req, res) {
  const corpo = req.rawBody; // o corpo cru, antes do JSON.parse
  const { t, v1 } = Object.fromEntries(
    req.headers["x-bukio-signature"].split(",").map((p) => p.split("=")));
  const esperado = createHmac("sha256", process.env.WYZECASH_WEBHOOK_SECRET)
    .update(`${t}.${corpo}`).digest("hex");
  const velho = Math.abs(Date.now() / 1000 - Number(t)) > 300;
  if (velho || !timingSafeEqual(Buffer.from(esperado), Buffer.from(v1)))
    return res.status(401).end();

  const evento = JSON.parse(corpo);
  if (jaProcessado(evento.id)) return res.status(200).end(); // evt_ repetido
  switch (evento.type) {
    case "payment.paid":        marcarPago(evento.data.id); break;
    case "payment.expired":     liberarPedido(evento.data.id); break;
    case "withdrawal.completed": avisarSaque(evento.data.id); break;
  }
  res.status(200).end();
}
HMAC-SHA256 de "<t>.<corpo>"

Verifique a assinatura.
Recuse o que não bater.

Cada aviso chega com X-Bukio-Signature: t=…,v1=…. Calcule o HMAC-SHA256 do timestamp e do corpo cru com o seu segredo whsec_… e compare em tempo constante. Com o SDK, é uma linha: verifyWebhook(corpo, assinatura, segredo).

  • Evento no cabeçalhoX-Bukio-Event diz o tipo antes de abrir o corpo.
  • Pelo menos uma vezO mesmo evt_ vale em todo reenvio: guarde e ignore repetido. X-Bukio-Delivery identifica cada envio.
  • 5 minutos de tolerânciaRecuse timestamp mais velho que isso: barra quem tenta repetir um aviso antigo.
  • Reenvio automáticoSem 2xx em 10 s, tentamos de novo 7 vezes em cerca de 22 horas. E dá para reenviar pelo painel.

Cada evento, um ID.
Tudo em centavos.

Todas as URLs (até 5) recebem todos os eventos. Corpo: { id, type, created_at, data }, com o ID com prefixo em data.id.

Entradasdata.id
payment.createdCobrança criadaBKY-
payment.paidPago: com fee, paidAt e endToEndIdBKY-
payment.expiredPassou da validade sem pagamento (Pix: 30 min)BKY-
payment.refundedEstorno concluído (refundId EST-)BKY-
transfer.receivedTransferência de outra conta WyzeCashTRF-
Saídasdata.id
withdrawal.requestedSaque pedidoSAQ-
withdrawal.completedSaque concluído (chave mascarada)SAQ-
withdrawal.failedNão realizado ou recusado pela equipeSAQ-
pix.sentPix enviado ou Copia e Cola pagoENV-
pix.failedPix que não saiu (com reason)ENV-
transfer.sentTransferência para outra conta WyzeCashTRF-

O botão "Enviar teste" do painel manda webhook.test para todas as URLs. Saque pela API usa o prefixo SAQ-API-.

Configurar webhooks no painel

O contrato da API.
Sem surpresa.

O que vale em toda chamada para /v1.

Autenticação

Authorization: Bearer bk_live_…. A chave aparece uma única vez, na criação, que pede o código do app autenticador. Pode ter validade (30, 90, 180 dias ou 1 ano).

Escopos

Um por rota e ação, no formato recurso:ação: payments:create (Pix), payments:create-card, payments:create-crypto, payments:get, payments:list, e o mesmo para links, clientes, Pix enviado, saques, estornos, MED, conta, comprovantes e subcontas. A chave só faz o que foi marcado.

Idempotência

Idempotency-Key obrigatória ao criar cobrança, saque e Pix: repetir devolve o mesmo resultado; a mesma chave com outros dados dá IDEMPOTENCY_KEY_REUSED.

Erros

{ "error": { "code", "message" }, "requestId" }: código estável para o seu sistema e mensagem em português para mostrar.

Limites

100 pedidos por minuto por conta, somando todas as rotas e chaves. Passou disso: 429 RATE_LIMITED com Retry-After.

Dinheiro saindo

Chave com withdrawals:create, subaccounts:withdraw, pix:create ou refunds:create só é criada ou editada com o 2FA ativo e o código do app autenticador. IP liberado é opcional. Saque pela API vai para a chave enviada no pedido. Concluído, vem com receiptUrl: o comprovante em imagem.

Ciclo da cobrança.
Sem adivinhação.

O caminho principal e os desvios possíveis. Cada passo vira um webhook.

Caminho principal
pendingEntrada pendentepayment.created
paidPix recebidopayment.paid
refundedEstornadapayment.refunded
Sem pagamento
expiredpayment.expired
Depois de pago
MED abertovalor bloqueadodevolvidoMED-contestadovalor liberado

expired pago mesmo assim ainda entra no saldo e dispara payment.paid. Estorno parcial mantém paid e soma em refundedAmount.

Integre do seu jeito. Com ou sem código.

Escreva você, peça para a IA ou só use o painel. A API é a mesma de sempre.

criar-cobranca.sh

API REST com webhooks assinados.

    Abrir a documentação
    Pela API, funciona com cURLNode.jsPythonPHPGoJavaRubyC#

    Sua próxima venda pode cair aqui.

    Crie a conta, gere a chave de API no painel e faça a primeira cobrança.