TypeScript

O SDK wyzecash já é TypeScript: tipos de cada pedido, resposta e evento, com a descrição em português no editor.

O SDK wyzecash é escrito em TypeScript e traz os tipos junto: não precisa de @types. O mesmo pacote serve para Node.js, Bun e Deno, com ou sem TypeScript.

npm install wyzecash

Use só no servidor (rota de API, servidor, worker). Nunca em componente que roda no navegador: a chave de API iria junto.

​

Tipos de pedido e resposta

Cada método tem o tipo do que você manda (...Params) e do que volta (...Response), com o nome do recurso e da ação:

import WyzeCash, { type PaymentsCreateParams, type PaymentsCreateResponse } from "wyzecash";

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

const pedido: PaymentsCreateParams = {
  amount: 15000,      // centavos
  method: "pix",      // "pix" | "card" | "crypto": o editor completa
  description: "Pedido 1052",
};

const cobranca: PaymentsCreateResponse = await wyzecash.payments.create(pedido, { idempotencyKey: "pedido-1052" });
cobranca.copyPaste; // string | null

Passe o mouse em qualquer campo: a descrição em português vem da própria API (o que é, limites, quando aparece).

Exemplo	Tipo
wyzecash.payments.create	PaymentsCreateParams, PaymentsCreateResponse
wyzecash.withdrawals.create	WithdrawalsCreateParams, WithdrawalsCreateResponse
wyzecash.refunds.create	RefundsCreateParams, RefundsCreateResponse
wyzecash.balance.retrieve	BalanceRetrieveResponse
wyzecash.payments.list	PaymentsListParams, PaymentsListResponse
Webhook	WebhookEvent, WebhookEventType
WebSocket	RealtimeEvent, RealtimeOptions
Erros	WyzeCashError, WyzeCashConnectionError, WyzeCashWebhookError

​

Eventos tipados

WebhookEventType é a lista dos tipos de evento, e verifyWebhook aceita o tipo do data:

import { verifyWebhook, type WebhookEvent } from "wyzecash";

type CobrancaPaga = { id: string; amount: number; fee: number; method: "pix" | "card" | "crypto"; paidAt: string };

const evento: WebhookEvent<CobrancaPaga> = await verifyWebhook<CobrancaPaga>(corpoCru, assinatura, process.env.WYZECASH_WEBHOOK_SECRET!);

if (evento.type === "payment.paid") {
  evento.data.amount; // number
}

​

Frameworks

Next.js (App Router)

app/api/webhooks/wyzecash/route.ts

import { verifyWebhook, WyzeCashWebhookError } from "wyzecash";

export async function POST(request: Request) {
  const corpo = await request.text(); // corpo cru, antes de qualquer JSON.parse
  try {
    const evento = await verifyWebhook(corpo, request.headers.get("x-bukio-signature"), process.env.WYZECASH_WEBHOOK_SECRET!);
    if (evento.type === "payment.paid") await liberarPedido(evento.data.id as string);
    return new Response("ok");
  } catch (erro) {
    if (erro instanceof WyzeCashWebhookError) return new Response("assinatura inválida", { status: 400 });
    throw erro;
  }
}

app/api/cobrar/route.ts

import WyzeCash from "wyzecash";

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

export async function POST(request: Request) {
  const { pedidoId, valor } = (await request.json()) as { pedidoId: string; valor: number };
  const cobranca = await wyzecash.payments.create({ amount: valor, description: `Pedido ${pedidoId}` }, { idempotencyKey: pedidoId });
  return Response.json({ id: cobranca.id, copyPaste: cobranca.copyPaste, expiresAt: cobranca.expiresAt });
}

NestJS

wyzecash.service.ts

import { Injectable } from "@nestjs/common";
import WyzeCash from "wyzecash";

@Injectable()
export class WyzeCashService {
  readonly client = new WyzeCash(process.env.WYZECASH_API_KEY);

  cobrar(pedidoId: string, valor: number) {
    return this.client.payments.create({ amount: valor, description: `Pedido ${pedidoId}` }, { idempotencyKey: pedidoId });
  }
}

No controller do webhook, ligue o rawBody: true no NestFactory.create e passe req.rawBody para o verifyWebhook.

Fastify

import Fastify from "fastify";
import { wyzecashWebhooks } from "wyzecash/fastify";

const app = Fastify();
await app.register(wyzecashWebhooks, {
  secret: process.env.WYZECASH_WEBHOOK_SECRET,
  async onEvent(evento) {
    if (evento.type === "payment.paid") await liberarPedido(evento.data.id);
  },
});

​

O resto

Tudo o mais (recursos, listas, Idempotency-Key, erros, novas tentativas, tempo real) está em SDK Node.js: é o mesmo pacote.