Cobranças Pix
Gere um Pix para o cliente pagar e acompanhe até a confirmação.
Uma cobrança Pix é o que o cliente paga: um QR Code e um código copia e cola com o valor certo. Você cria pela API e mostra na sua tela.
Criar
| Campo | Obrigatório | O que é |
|---|---|---|
amountCents | Sim | Valor em centavos. Mínimo 500 (R$ 5,00). |
description | Sim | O que está sendo cobrado (3 a 180 caracteres). Aparece para o pagador. |
customer | Sim | Quem paga: name, email, phone (com DDD), documentType (CPF ou CNPJ) e document. |
customer.address | Não | Endereço, salvo no cadastro do cliente. |
expiresAt | Não | Até quando o Pix aceita pagamento (ISO 8601). |
metadata | Não | Dados seus, como o id do pedido. Voltam iguais na consulta e nos webhooks. |
O CPF ou CNPJ é validado pelos dígitos. Um documento inválido responde 400 e a cobrança não é criada.
Use sempre o header idempotency-key (ex.: o id do pedido). Se a chamada for repetida por uma falha de rede, a mesma cobrança volta, sem duplicar. Veja Idempotência.
Mostrar ao cliente
A resposta traz em pix:
copyPaste: o código copia e cola. Mostre com um botão de copiar.qrCode: o mesmo código, para você gerar a imagem do QR Code com qualquer biblioteca de QR.
Mostre também o prazo: expiresAt diz até quando o Pix pode ser pago.
Saber que foi pago
Use o webhook transaction.paid: ele chega em segundos, com a cobrança inteira, incluindo o seu metadata. Libere o pedido quando ele chegar.
Se precisar conferir, consulte GET /api/v1/transactions/{id}. Evite consultar em loop: o webhook é mais rápido e não gasta o seu limite de requisições.
Situações (status)
| Status | Quer dizer |
|---|---|
WAITING_PAYMENT | Pix gerado, aguardando o pagamento. |
PAID | Pago e confirmado. Pode liberar o pedido. |
EXPIRED | Passou do expiresAt sem pagamento. Gere uma cobrança nova se o cliente ainda quiser pagar. |
CANCELLED, FAILED | Não pode mais ser paga. |
Outros status aparecem em situações raras (como PENDING ou PROCESSING, enquanto o Pix é gerado). Trate tudo que não é PAID como "não pago".
Valores
amountCents: o que o cliente paga.feeCents: a taxa da WysePay, definida pelo seu plano no momento em que a cobrança é criada.netAmountCents: o que entra no seu saldo (amountCents − feeCents).
Se depois de pago o cliente contestar pelo banco (MED), a cobrança ganha o campo dispute. Veja MED.