PayZu GatewayApoio

Boas práticas


Nesta páginaGuarde a chave no servidorRepita com a mesma Idempotency-KeyEspere o desfecho do cartãoLibere o pedido pelo statusDeduplique os avisosNão guarde o cartão abertoPagine com o cursorCódigos citados

Guarde a chave no servidor

A chave de API vai em Authorization: Bearer nas chamadas do seu servidor e aparece uma única vez, quando você a cria no painel. Veja Autenticação.

Faça

  • Chame a API só do seu servidor e guarde a chave fora do código e do navegador.
  • Para trocar a chave sem parar as vendas, crie a nova no painel, troque no servidor e só então revogue a antiga, que passa a responder 401.
  • No aparelho do comprador, use só as chaves públicas da tokenização. Veja Tokenização de cartão.

Evite

  • Pôr a chave de API no app ou na página de pagamento.
  • Gravar o cabeçalho Authorization em log.

Repita com a mesma Idempotency-Key

A Idempotency-Key aceita até 255 caracteres e é obrigatória em Criar uma fatura, Pagar uma fatura, Estornar uma fatura e Criar uma assinatura. A primeira resposta fica guardada por 24 horas. Veja Idempotência.

Faça

  • Gere a chave antes da chamada e grave-a junto com o pedido.
  • Depois de um timeout, repita com a mesma chave e o mesmo corpo: a resposta guardada volta com Idempotent-Replayed: true, sem cobrar de novo.
  • Para tentar de novo depois de um cartão recusado pela adquirente, use outra chave em POST /v1/invoices/:invoice_id/payments, na mesma fatura, e não crie outra: a recusa também fica guardada, e a mesma chave só repete a resposta anterior. A tentativa failed que saiu de processing não é recusa definitiva: consulte a fatura antes de cobrar de novo.
  • Se o 409 de requisição em processamento persistir, não troque a chave: a primeira chamada ainda pode terminar. Confira o resultado pela consulta da fatura e pelos eventos.

Evite

  • Trocar a chave ao repetir uma chamada que pode ter sido feita: a PayZu trata como operação nova.
  • Reaproveitar a chave com outro corpo: com a primeira resposta guardada, a resposta é 409.
  • Cobrar outro cartão com a mesma chave. O número, o CVV e o token do cartão ficam fora da comparação, e um token novo recebe a resposta da primeira tentativa. Outro card_id, outra validade, outro titular ou a troca entre token e cartão digitado recebem 409.

Espere o desfecho do cartão

Quando a adquirente não responde a tempo, a resposta é 201, com a fatura pending e a tentativa processing em payments[0]. A tentativa se resolve sozinha e passa a paid ou a failed. Veja Vender no cartão.

Não crie outra fatura para o mesmo pedido enquanto a tentativa estiver processing.

Seria uma segunda cobrança no cartão do cliente. Uma nova tentativa na mesma fatura é recusada até o desfecho.

Faça

  • Grave o id da fatura e confirme o pagamento pelo evento invoice.paid ou pela consulta da fatura.
  • Conte com a conciliação: a PayZu procura a cobrança na adquirente a partir de 5 minutos da criação e nunca cobra de novo.

Evite

  • Dar como definitiva a tentativa failed que saiu de processing: se a cobrança aparecer depois, aprovada, a tentativa ainda passa a paid e sai invoice.paid. Se outra tentativa for paga nesse meio-tempo, a cobrança confirmada por último vira pagamento em duplicidade e é devolvida sozinha.
  • Criar de novo, com outra chave, a assinatura cuja adesão no cartão ficou processing: a criação é recusada enquanto a cobrança inicial aguarda confirmação.

Libere o pedido pelo status

O que liberarQuando
A vendaCom a fatura paid, pelo evento invoice.paid ou pela consulta da fatura.
O acesso da assinatura no cartãoCom a assinatura active: na criação pela API, ela já vem na resposta 201 quando o cartão é aprovado; pela página do plano, chega com subscription.activated depois do pagamento da adesão.
O acesso da assinatura no PixCom a assinatura active, que chega com subscription.activated.

No Pix, mostre pix.qr_code_text da tentativa enquanto ela estiver pending, até pix.expires_at. Os status da fatura estão em Cobranças, e os da tentativa, em Consultar faturas.

Evite

  • Liberar com a fatura pending, mesmo com uma tentativa processing ou pending, ou com a assinatura incomplete.
  • Dar como devolvido o Pix com o estorno requested em refunds: a fatura só passa a refunded com a devolução confirmada.

Deduplique os avisos

Cada evento chega com um id próprio, o mesmo em todas as tentativas de entrega. Veja Webhooks.

Faça

  • Confira X-Webhook-Signature antes de gravar. Veja Assinatura dos webhooks.
  • Grave o aviso e responda 2xx em até 5 segundos, antes de processar. Sem 2xx, a PayZu tenta de novo depois de 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas.
  • Descarte o evento cujo id você já processou: ele se repete nas novas tentativas, no reenvio e em cada webhook cadastrado para o mesmo evento.

Evite

  • Confiar na ordem de chegada: uma nova tentativa pode chegar depois de um evento mais novo. Na dúvida, consulte o recurso pelo GET.
  • Esperar aviso de antes do cadastro: a PayZu só gera o aviso para os webhooks ativos que assinam aquele evento.

Não guarde o cartão aberto

Tokenize o cartão no aparelho do comprador e mande ao seu servidor só o token, para enviar em card_token no lugar do cartão. Veja Tokenização de cartão.

Faça

Evite

  • Usar o mesmo token duas vezes: a segunda operação responde 400.
  • Pôr número de cartão em metadata ou, na fatura, em description, external_reference e items: a PayZu recusa o campo com 400.

Pagine com o cursor

As 8 listas da API usam o mesmo cursor e respondem items e next_cursor, sem total. Veja Paginação.

Faça

  • Mande o next_cursor em cursor, como veio, com os mesmos filtros da primeira página.
  • Pare quando next_cursor vier null.
  • Para fechar um período, filtre por dia, no formato AAAA-MM-DD e no fuso de São Paulo.

Evite

  • Montar ou alterar o cursor: um cursor que a API não gerou responde 400.
  • Esperar o total na resposta: conte os itens ao percorrer as páginas.

Códigos citados

CódigoHTTPMensagem
PZ201400Token de cartão inválido ou vencido. Gere o token de novo.
PZ021401Chave de API inválida.
PZ011409Idempotency-Key já usada com outra requisição.
PZ012409Requisição com esta Idempotency-Key ainda está em processamento.
PZ113409Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde.
PZ500409A cobrança inicial desta assinatura ainda aguarda confirmação. Tente novamente mais tarde.

Todos os códigos do PayZu Gateway estão no Catálogo de erros.