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

# Convenções

> Centavos, datas, identificadores, idempotência, paginação por cursor e cabeçalhos.

## Valores em centavos

Todo valor é um inteiro em centavos. R\$ 1,00 = `100`; R\$ 1.234,56 = `123456`. Nunca mande decimais.

## Datas

ISO 8601 em UTC, com milissegundos: `2026-10-08T15:04:12.318Z`. Converta para o fuso de quem vê.

## Identificadores

| Prefixo | O que é |
| - | - |
| `BKY-` + 12 caracteres | cobrança (Pix, cartão ou cripto) |
| `LNK-` + 12 | link de pagamento |
| `SAQ-` + 12 · `SAQ-API-` + 12 | saque (pelo painel · pela API) |
| `ENV-` + 12 | Pix enviado |
| `EST-` + 12 | estorno |
| `MED-` + 12 | pedido de devolução (MED) |
| `TRF-` + 12 | transferência entre contas WyzeCash |
| `TAR-` + 12 | tarifa |
| `SUB-` + 12 | movimento de subconta |
| `sacc_` + 32 hex | subconta |
| UUID | cliente |
| `evt_...` | evento de webhook |

Os caracteres são letras maiúsculas e números, sem I, L, O e U (para não confundir com 1 e 0). Guarde o identificador inteiro, com o prefixo.

## Idempotência

Cobrança e saque exigem o cabeçalho `Idempotency-Key` (8 a 128 caracteres; um UUID ou o número do seu pedido). Ele garante que repetir a chamada (timeout, rede caiu) não cria duas cobranças nem dois saques:

| Situação | Resposta |
| - | - |
| Mesma chave, mesmos dados | o mesmo resultado da primeira chamada (`200`, não `201`) |
| Mesma chave, dados diferentes | `422 IDEMPOTENCY_KEY_REUSED` |
| Mesma chave, primeira chamada ainda em andamento | `409 IDEMPOTENCY_IN_PROGRESS`: espere e repita |
| Sem a chave | `400 IDEMPOTENCY_KEY_REQUIRED` |

A chave vale por conta e por tipo de operação.

## Paginação por cursor

Listas longas (`/v1/transactions`, `/v1/payments`, `/v1/withdrawals`, `/v1/meds`, `/v1/subaccounts`) aceitam `?limit=` (1 a 100, padrão 50) e `?cursor=`. A resposta traz `items` e `nextCursor`:

```json theme={null}
{ "items": [ ... ], "nextCursor": "WyIyMDI2LTEwLTA4VDE1OjA0OjEyLjMxOFoiLCIuLi4iXQ" }
```

Para a próxima página, mande `?cursor=<nextCursor>`. `nextCursor: null` = acabou. Os itens vêm do mais novo para o mais antigo. Cursor inválido: `400 INVALID_CURSOR`.

## Cabeçalhos

| Cabeçalho | Uso |
| - | - |
| `Authorization: Bearer bk_live_...` | obrigatório em toda chamada |
| `Content-Type: application/json` | em todo `POST`, `PATCH` e `PUT` com corpo |
| `Idempotency-Key` | cobrança e saque |
| `x-request-id` | volta em toda resposta; cite ao falar com o suporte |

## Corpo das requisições

Só os campos documentados: campo desconhecido responde `422 VALIDATION` com `details.fields`. Corpo de até 256 KB. Campo com `null` limpa o valor (onde a documentação diz que aceita).

## Situações

| Recurso | `status` | Título no painel |
| - | - | - |
| Cobrança | `pending` · `paid` · `expired` · `refunded` | Entrada pendente · Pix recebido / Cartão aprovado / Cripto recebida (conforme `method`) · Entrada expirada · Estornada |
| Saque | `processing` · `completed` · `failed` · `rejected` | Em processamento · Concluído · Não realizado · Não realizado |
| Movimentação do extrato | `pending` · `processing` · `completed` · `failed` · `canceled` | Pendente · Em processamento · Aprovado (entrada) ou Concluído (saída) · Não realizado · Cancelado |
| Link de pagamento | `active` · `paused` · `expired` · `sold_out` | Ativo · Pausado · Vencido · Esgotado |
| MED | `open` · `analysis` · `refunded` · `rejected` | Aberto · Em análise · Devolvido · Contestado |

Cada resposta também traz `statusTitle`, o texto em português pronto para mostrar.

## Tarifas

A tarifa de cada operação vem da sua conta (padrão: R\$ 0,50 por cobrança paga e por Pix enviado ou saque; transferência entre contas WyzeCash grátis) e aparece em `fee` nas respostas. Antes de uma operação, `GET /v1/fees/preview` mostra quanto será cobrado. O valor mínimo do saque da sua conta vem em `GET /v1/balance` (`withdrawal.minPerTransaction`).


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