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:

{ "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).