PayZu Conta HubApoio

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 mudaValorPor quê
RotaA de devolução de depósitoÉ separada da devolução de cobrança.
amount1000Sem amount, a devolução é do que resta. Outro campo no corpo é recusado.
Idempotency-KeyUm UUID por devoluçãoCom a mesma chave e o mesmo amount, a repetição retorna a devolução já pedida, sem enviar outro Pix.
Tarifarefund.feeFixed e refund.feePercentage de Limites e tarifasÉ somada por cima, e totalDebited mostra o total que sai.
LimiteMáximo por operaçãodetails.max traz o teto aplicado. Não há mínimo conferido.
Antes de pedirrefundableAmount em Consultar um depósitoÉ quanto ainda pode ser devolvido. Vem 0 com devolução em andamento ou infração aberta.
bash
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.

DesfechoAvisoStatus da tentativa
Devolvido ao pagadorREFUND_COMPLETED, com depositId e refundIdSETTLED
Recusado, com o valor de volta ao saldoREFUND_FAILEDRELEASED

Depois do desfecho, refundableAmount volta a mostrar o que resta, e você pode pedir a próxima parcela.

CódigoHTTPMensagem
REFUND_ABOVE_REMAINING422O valor do estorno é maior do que o que resta a devolver deste pagamento.
REFUND_ABOVE_TICKET_MAX422O valor do estorno está acima do limite por operação desta conta.
REFUND_INFRACTION_OPEN422Esta cobrança tem uma contestação MED em andamento; o estorno fica indisponível até o desfecho.
REFUND_IN_FLIGHT422Já 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 mudaValorPor quê
Leitura préviaLer um Pix copia e cola com o brCodeNão gasta cota nem consulta o banco. Com isDynamic: false e isAmountFixed: false, o valor é aberto.
amountO valor escolhido, em centavosSó quando o código não fixa valor. Se fixar, amount tem de ser igual ao do código ou pode ficar de fora.
brCodeO código completo, como foi lidoA API resolve o código; não envie trechos.
commentPedido 4821Texto enviado ao recebedor.
Idempotency-KeyUm UUID por pagamentoA chave também compara o código pago; repetir com outro valor ou código responde 409.
Tarifa e limitesexternalPayment em Limites e tarifasValem os limites, o teto diário e a cota do saque, com tarifa própria.
bash
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ódigoHTTPMensagem
QR_AMOUNT_DISAGREES422O valor impresso no QR code é diferente do que o banco do recebedor informa. Confirme o valor com quem cobrou.
QR_AMOUNT_MISMATCH422O 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_REQUIRED422Este 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.