> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wyzecash.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://docs.wyzecash.com.br/sdk/node) é 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.

```bash theme={null}
npm install wyzecash
```

> [!WARNING]
>
> 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:

```typescript theme={null}
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`:

```typescript theme={null}
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

> [tab] Next.js (App Router)
>
> ```typescript app/api/webhooks/wyzecash/route.ts theme={null}
> 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;
>   }
> }
> ```
>
> ```typescript app/api/cobrar/route.ts theme={null}
> 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 });
> }
> ```

> [tab] NestJS
>
> ```typescript wyzecash.service.ts theme={null}
> 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`.

> [tab] Fastify
>
> ```typescript theme={null}
> 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](https://docs.wyzecash.com.br/sdk/node.md): é o mesmo pacote.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.