Como integrar Pix por API

1. Antes de começar

• Uma conta na WyzeCash e uma chave de API, criada no painel em Integrações e API, com a permissão /payments/create.
• O endereço da API: https://api.wyzecash.com.br.
• Valores sempre em centavos (R$ 189,90 é 18990) e uma Idempotency-Key por pedido, para um pedido repetido nunca gerar duas cobranças.
• A chave fica só no seu servidor, nunca no site ou no app.

2. Crie a cobrança

Um POST /v1/payments com o valor e a descrição:

curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: pedido-1052" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 18990, "description": "Pedido #1052" }'

A resposta traz o código da cobrança (BKY-), o Pix Copia e Cola em copyPaste e até quando ele vale em expiresAt:

{
  "id": "BKY-8K2M4QZ7XN3P",
  "method": "pix",
  "status": "pending",
  "amount": 18990,
  "total": 18990,
  "copyPaste": "00020126580014br.gov.bcb.pix...",
  "expiresAt": "2026-11-13T15:30:00.000Z"
}

3. Mostre o QR Code

Na tela de pagamento do seu site, transforme o copyPaste num QR Code (qualquer biblioteca de QR Code serve) e mostre também o código com um botão Copiar, para quem paga pelo celular. O Pix vale 30 minutos.

4. Receba o aviso de pagamento

Cadastre a URL do seu servidor em Integrações e API › Webhooks. Quando o Pix é pago, a WyzeCash manda o evento payment.paid, assinado no cabeçalho X-Bukio-Signature com o seu segredo whsec_…. Confira a assinatura antes de liberar o pedido:

import { verifyWebhook } from "wyzecash";

const evento = await verifyWebhook(
  corpoCru,
  request.headers["x-bukio-signature"],
  process.env.WYZECASH_WEBHOOK_SECRET,
);
if (evento.type === "payment.paid") {
  // libere o pedido (use evento.id para não processar duas vezes)
}

Responda 2xx em até 10 segundos. Se o seu servidor não responder, a WyzeCash manda de novo depois de 1 min, 5 min, 30 min, 2 h, 8 h e 24 h.

5. Com os SDKs oficiais

Os SDKs de Node.js, Python e PHP já trazem a chave, os valores e a conferência do webhook prontos:

npm install wyzecash
pip install wyzecash
composer require wyzecash/wyzecash

// npm install wyzecash
import WyzeCash from "wyzecash";

const wyzecash = new WyzeCash(process.env.WYZECASH_API_KEY);

const cobranca = await wyzecash.payments.create(
  { amount: 18990, description: "Pedido #1052" },
  { idempotencyKey: "pedido-1052" },
);
cobranca.copyPaste; // Pix Copia e Cola

6. Boas práticas

• Use os webhooks para saber quando foi pago, em vez de consultar a cobrança de tempos em tempos.
• Guarde o id de cada evento e ignore o repetido: o mesmo aviso pode chegar mais de uma vez.
• A API aceita até 100 pedidos por minuto por conta, somando todas as chaves.
• Se o seu servidor tem IP fixo, libere só ele na chave de API.

7. Perguntas frequentes