Recarregar a carteira por Pix
Nesta página
Crie a recargaPague o PixConfira o créditoLimites da recargaRepita o pedido sem gerar outro PixErrosPonha saldo na carteira de produção com um Pix, para pagar as cobranças das suas linhas na hora.
Crie a recarga
Envie o valor e o e-mail de quem paga, que segue com o Pix para o provedor de pagamento. A empresa aparece como pagadora, com o nome e o documento do cadastro.
curl -X POST https://api.payzucell.com.br/v1/wallet/top-ups \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 6f1c2d9e-8a4b-4c3d-9e7f-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d '{"amount": 500, "email": "financeiro@suaempresa.com.br"}'{
"id": "cm4b1t7q20003q8f2h6k9m4zd",
"amount": 500,
"status": "PENDING",
"paidAt": null,
"environment": "LIVE",
"payment": {
"id": "cm4b1t8r50005q8f2c3n7p1xw",
"orderId": "cm4b1t7p80002q8f2w5j8l3yc",
"chargeIds": [],
"method": "PIX",
"status": "PENDING",
"amount": 500,
"pixCopyPaste": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-4266554400005204000053039865406500.005802BR5905PAYZU6009SAO PAULO62070503***6304898D",
"pixQrCode": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAA...",
"expiresAt": "2026-11-21T14:05:12.000Z",
"paidAt": null,
"createdAt": "2026-11-20T14:05:12.000Z"
},
"createdAt": "2026-11-20T14:05:11.000Z"
}Mostre o pixCopyPaste ou o pixQrCode a quem vai pagar.
Referência: Recarregar a carteira por Pix
Pague o Pix
O saldo sobe quando o provedor de pagamento confirma o Pix. O pagamento entra no saldo uma vez, mesmo que chegue depois de expiresAt.
Limites da recarga
Os limites vêm em topUpLimits, no saldo da carteira.
| Campo | Limite |
|---|---|
minAmount | Menor valor de uma recarga. |
maxAmount | Maior valor de uma recarga. |
balanceCap | Saldo máximo da carteira. Na criação, a recarga que levaria o saldo disponível acima dele é recusada, mas o Pix já pago sempre entra no saldo. |
Repita o pedido sem gerar outro Pix
O cabeçalho Idempotency-Key é obrigatório e vale 24 horas em cada ambiente.
| Ao repetir a chave | Resposta |
|---|---|
| Com o mesmo corpo, depois de um sucesso | A mesma recarga, com o cabeçalho Idempotent-Replayed em true. |
| Com outro corpo | 409 com PZC004. |
| Com o primeiro pedido ainda em andamento | 409 com PZC201. |
A chave de testes não gera Pix.
Por isso, a recarga com a chave de testes é recusada com 422. A carteira de testes recebe o crédito do atendimento do PayZu Cell.
Erros
| Código | HTTP | Mensagem |
|---|---|---|
PZC001 | 400 | Corpo ou parâmetro fora do formato. |
PZC200 | 409 | O estado atual da linha não permite esta operação. |
PZC300 | 422 | O provedor de pagamento recusou a operação. |
PZC301 | 502 | O provedor de pagamento não respondeu; consulte o estado antes de repetir. |
PZC304 | 422 | O provedor de pagamento não atende este meio de pagamento. |
PZC307 | 422 | A recarga passaria do saldo máximo da carteira. |
Na recarga, o PZC001 também recusa o valor fora dos limites, o PZC200 indica a carteira bloqueada por uma recarga estornada e o PZC304 vem da chave de testes. Depois de um 502, a resposta não traz o id da recarga, e a API não tem consulta da recarga. Guarde o requestId do erro antes de tentar de novo.
Os outros códigos estão no Catálogo de erros.