Cenários práticos
Devolver parte de um depósito
Um cliente mandou um Pix de R$ 50,00 (5000) direto para a chave da conta, sem cobrança, e você precisa devolver R$ 10,00 (1000). O depósito chegou pelo webhook DEPOSIT_RECEIVED, e o depositId do evento é o que entra na rota.
| O que muda | Valor | Por quê |
|---|---|---|
| Rota | A de devolução de depósito | É separada da devolução de cobrança. |
amount | 1000 | Sem amount, a devolução é do que resta. Outro campo no corpo é recusado. |
Idempotency-Key | Um UUID por devolução | Com a mesma chave e o mesmo amount, a repetição retorna a devolução já pedida, sem enviar outro Pix. |
| Tarifa | refund.feeFixed e refund.feePercentage de Limites e tarifas | É somada por cima, e totalDebited mostra o total que sai. |
| Limite | Máximo por operação | details.max traz o teto aplicado. Não há mínimo conferido. |
| Antes de pedir | refundableAmount em Consultar um depósito | É quanto ainda pode ser devolvido. Vem 0 com devolução em andamento ou infração aberta. |
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/deposit/cmu4a1b2c000001s6xyz98765/refund' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Idempotency-Key: 9b2e4c6a-1d3f-4a5b-8c7d-0e9f1a2b3c4d' \
--header 'Content-Type: application/json' \
--data '{ "amount": 1000 }'Referência: Solicitar a devolução de um depósito
A resposta é o depósito relido, com a tentativa nova em refunds[0] e status PROCESSING. Até o desfecho, refundInProgressAmount fica em 1000 e refundableAmount em 0.
| Desfecho | Aviso | Status da tentativa |
|---|---|---|
| Devolvido ao pagador | REFUND_COMPLETED, com depositId e refundId | SETTLED |
| Recusado, com o valor de volta ao saldo | REFUND_FAILED | RELEASED |
Depois do desfecho, refundableAmount volta a mostrar o que resta, e você pode pedir a próxima parcela.
| Código | HTTP | Mensagem |
|---|---|---|
REFUND_ABOVE_REMAINING | 422 | O valor do estorno é maior do que o que resta a devolver deste pagamento. |
REFUND_ABOVE_TICKET_MAX | 422 | O valor do estorno está acima do limite por operação desta conta. |
REFUND_INFRACTION_OPEN | 422 | Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho. |
REFUND_IN_FLIGHT | 422 | Já existe um estorno em andamento para este pagamento. Aguarde o desfecho antes de pedir outro. |
Depois de um erro de rede, repita com a mesma Idempotency-Key e o mesmo corpo.
Sem a chave, consulte o depósito e veja se a tentativa já está em refunds antes de repetir.
Pagar um copia e cola sem valor fixado
Um fornecedor mandou um Pix copia e cola estático sem valor, e o usuário informa quanto pagar na sua tela. Você precisa descobrir que o código não fixa valor e enviar amount só nesse caso.
| O que muda | Valor | Por quê |
|---|---|---|
| Leitura prévia | Ler um Pix copia e cola com o brCode | Não gasta cota nem consulta o banco. Com isDynamic: false e isAmountFixed: false, o valor é aberto. |
amount | O valor escolhido, em centavos | Só quando o código não fixa valor. Se fixar, amount tem de ser igual ao do código ou pode ficar de fora. |
brCode | O código completo, como foi lido | A API resolve o código; não envie trechos. |
comment | Pedido 4821 | Texto enviado ao recebedor. |
Idempotency-Key | Um UUID por pagamento | A chave também compara o código pago; repetir com outro valor ou código responde 409. |
| Tarifa e limites | externalPayment em Limites e tarifas | Valem os limites, o teto diário e a cota do saque, com tarifa própria. |
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/pix/decode' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "brCode": "COLE_AQUI_O_CODIGO_COMPLETO" }'
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/pix/qr-payments' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Idempotency-Key: 5f0c1d2e-8a7b-4c3d-9e1f-2a3b4c5d6e7f' \
--header 'Content-Type: application/json' \
--data '{ "brCode": "COLE_AQUI_O_CODIGO_COMPLETO", "amount": 2500, "comment": "Pedido 4821" }'Referência: Consultar os dados de um Pix copia e cola e Pagar um Pix copia e cola
O pagamento responde 201 com o registro em PROCESSING, a chave de destino mascarada e totalDebited com a tarifa. Na retentativa, repita a mesma Idempotency-Key com o mesmo corpo.
Acompanhe pelos webhooks WITHDRAW_COMPLETED e WITHDRAW_FAILED, com operation: EXTERNAL_PAYMENT, ou por Consultar um saque ou pagamento com o id da resposta.
| Código | HTTP | Mensagem |
|---|---|---|
QR_AMOUNT_DISAGREES | 422 | O valor impresso no QR code é diferente do que o banco do recebedor informa. Confirme o valor com quem cobrou. |
QR_AMOUNT_MISMATCH | 422 | O valor deste QR code é diferente do que foi informado. Se o código é dinâmico, quem cobrou pode tê-lo alterado depois da leitura — leia o código de novo. |
QR_AMOUNT_REQUIRED | 422 | Este QR code não fixa valor — informe quanto pagar. |
Em código dinâmico, envie em amount o valor que o usuário conferiu na consulta do recebedor.
O decode retorna a url e só preenche amount, com isAmountFixed: true, quando o valor está impresso no código; sem valor impresso, amount vem null e isAmountFixed vem false. Para saber o valor, consulte o recebedor com o mesmo código, como em Consultar o recebedor: ele pode mudar depois da leitura.