> ## 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.

# Sua primeira cobrança

> Da chave de API ao primeiro Pix recebido, em quatro passos.

**1. Crie a chave de API**

No painel WyzeCash, abra **Integrações e API › Chaves de API › Nova chave**. Dê um nome, escolha as permissões (para este guia: `payments:write`, `transactions:read` e `balance:read`; para cobrar no cartão ou em cripto, também `card:write` ou `crypto:write`) e, se quiser, uma validade.

A chave completa (`bk_live_...`) aparece **uma única vez**. Guarde num cofre de segredos do seu sistema; nunca no código nem no navegador.

> [!NOTE]
>
> Chaves que sacam ou enviam Pix (`withdrawals:write`, `pix:write`) exigem o 2FA ligado na sua conta e pelo menos um IP liberado. Veja [Autenticação](https://docs.wyzecash.com.br/autenticacao.md).

**2. Faça a primeira chamada**

```bash theme={null}
curl https://api.wyzecash.com.br/v1/balance \
  -H "Authorization: Bearer bk_live_SEU_ID_SEU_SEGREDO"
```

```json theme={null}
{
  "available": 0,
  "pending": 0,
  "blocked": 0,
  "medOwed": 0,
  "subaccounts": 0,
  "free": 0,
  "withdrawal": { "minPerTransaction": 100 },
  "updatedAt": null
}
```

**3. Crie uma cobrança Pix**

Mande um `Idempotency-Key` único por pedido (um UUID serve): se a conexão cair e você repetir, a WyzeCash devolve a mesma cobrança em vez de criar outra.

```bash theme={null}
curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_SEU_ID_SEU_SEGREDO" \
  -H "Idempotency-Key: pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30 }'
```

```json theme={null}
{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "...",
  "copyPaste": "00020126580014br.gov.bcb.pix...",
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": null,
  "payer": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

Mostre o `copyPaste` para quem vai pagar: como texto (Pix Copia e Cola) e como QR Code (qualquer biblioteca de QR Code gera a imagem a partir dessa string).

**4. Saiba quando o Pix cair**

Cadastre a URL do seu servidor em **Integrações e API › Webhooks**. Quando a cobrança for paga, você recebe um `POST` com o evento `payment.paid`:

```json theme={null}
{
  "id": "evt_01JA...",
  "type": "payment.paid",
  "created_at": "2026-10-08T15:04:12.318Z",
  "data": {
    "id": "BKY-7KQ2M9XP4RZT",
    "status": "paid",
    "amount": 15000,
    "fee": 50,
    "description": "Pedido 1842",
    "txid": "...",
    "expiresAt": "2026-10-08T15:30:00.000Z",
    "customerId": null,
    "paidAt": "2026-10-08T15:04:11.000Z",
    "endToEndId": "E12345678202610081504abcdef123456",
    "createdAt": "2026-10-08T15:00:00.000Z"
  }
}
```

Valide a assinatura antes de liberar o pedido ([Validando a assinatura](https://docs.wyzecash.com.br/webhooks/assinatura.md)). Se preferir consultar em vez de esperar o aviso, `GET /v1/payments/BKY-7KQ2M9XP4RZT` devolve o `status` atual.

## Próximos passos

> [card] [Links de pagamento](https://docs.wyzecash.com.br/endpoints/links-de-pagamento.md)
>
> Uma página de pagamento pronta, sem tela para programar.

> [card] [Saques](https://docs.wyzecash.com.br/endpoints/saques.md)
>
> Tire o saldo para a chave Pix que você mandar.

> [card] [Eventos de webhook](https://docs.wyzecash.com.br/webhooks/cobrancas.md)
>
> O corpo de cada evento e o jeito certo de tratar.

> [card] [Erros](https://docs.wyzecash.com.br/erros.md)
>
> Códigos estáveis e mensagens prontas para o usuário.


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