Pagar com o saldo da carteira
Pague as cobranças das suas linhas na hora, sem esperar o Pix, enviando BALANCE no campo channel do corpo.
Rotas que aceitam o saldo
Sem o campo channel, a rota segue com PIX.
| Rota | Quando o saldo paga |
|---|---|
| Pedir uma linha nova | Na compra da linha. |
| Renovar ou reativar uma linha | Na cobrança do próximo ciclo. |
| Trocar o plano de uma linha | Na troca com timing igual a NOW. |
| Gerar o pagamento de uma cobrança | Em qualquer cobrança aberta das suas linhas. |
Pague a renovação com o saldo
curl -X POST https://api.payzucell.com.br/v1/lines/cm3x2b7k90004q8f2m1n6p8rs/renew \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 0b9e4c71-5d2a-4f8e-a1c3-7e6d5f4a3b2c" \
-H "Content-Type: application/json" \
-d '{"channel": "BALANCE"}'{
"charge": {
"id": "cm4a6r2e80007q8f2v3b5n9kd",
"lineId": "cm3x2b7k90004q8f2m1n6p8rs",
"kind": "RENEWAL",
"status": "PAID",
"amount": 29.9,
"dueOn": "2026-11-25",
"paidAt": "2026-11-20T15:10:02.000Z"
},
"payment": {
"id": "cm4a6s1f30008q8f2p7c2m4hu",
"chargeIds": ["cm4a6r2e80007q8f2v3b5n9kd"],
"method": "BALANCE",
"status": "PAID",
"amount": 29.9,
"pixCopyPaste": null,
"pixQrCode": null,
"paidAt": "2026-11-20T15:10:02.000Z"
}
}A resposta traz também a line. Com o débito confirmado antes do vencimento, renewedUntil mostra o fim do ciclo seguinte, e a recarga na operadora roda no dia do vencimento. Nas outras três rotas, o corpo leva o mesmo channel.
Referência: Renovar ou reativar uma linha
Como o débito acontece
| Situação | O que acontece |
|---|---|
| Saldo suficiente | O valor sai da carteira do ambiente da chave, e a resposta traz o pagamento BALANCE já pago. Na compra, na renovação e na troca de plano, ela traz também a cobrança PAID. |
| Débito em confirmação | O payment vem null, e a cobrança é paga sozinha quando o débito confirmar. Acompanhe pela cobrança. |
| Saldo insuficiente | A resposta é 422, e a cobrança segue aberta para o Pix. Na compra, a recusa vem antes de criar a linha e a cobrança. |
| Saldo que muda durante a compra | A compra volta aguardando pagamento, com payment nulo. Pague pela cobrança. |
| Carteira bloqueada | O pagamento é recusado até o atendimento do PayZu Cell liberar a carteira. |
| Cobrança que fecha antes da baixa | O valor volta inteiro ao saldo, com o lançamento PAYMENT_REVERSAL no extrato. |
Mesma Idempotency-Key e mesmo corpo | Depois de um sucesso, a resposta é a mesma, sem debitar de novo. Para trocar o meio de pagamento, use outra chave. |
A chave de testes paga com o saldo da carteira de testes.
O atendimento do PayZu Cell credita essa carteira. Com BALANCE, a compra, a renovação e a troca de plano funcionam nos testes como na produção, sem dinheiro real.
Erros
| Código | HTTP | Mensagem |
|---|---|---|
PZC200 | 409 | O estado atual da linha não permite esta operação. |
PZC201 | 409 | Outra operação na mesma linha está em andamento. |
PZC300 | 422 | O provedor de pagamento recusou a operação. |
PZC304 | 422 | O provedor de pagamento não atende este meio de pagamento. |
PZC305 | 422 | Saldo insuficiente na carteira para pagar as faturas. |
Com BALANCE, o PZC200 também indica a carteira bloqueada por uma recarga estornada.
Os outros códigos estão no Catálogo de erros.