Boas práticas
Nesta página
Guarde 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 citadosGuarde 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
Authorizationem 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 tentativafailedque saiu deprocessingnão é recusa definitiva: consulte a fatura antes de cobrar de novo. - Se o
409de 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 recebem409.
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
idda fatura e confirme o pagamento pelo eventoinvoice.paidou 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
failedque saiu deprocessing: se a cobrança aparecer depois, aprovada, a tentativa ainda passa apaide saiinvoice.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 liberar | Quando |
|---|---|
| A venda | Com a fatura paid, pelo evento invoice.paid ou pela consulta da fatura. |
| O acesso da assinatura no cartão | Com 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 Pix | Com 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 tentativaprocessingoupending, ou com a assinaturaincomplete. - Dar como devolvido o Pix com o estorno
requestedemrefunds: a fatura só passa arefundedcom 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-Signatureantes de gravar. Veja Assinatura dos webhooks. - Grave o aviso e responda
2xxem até 5 segundos, antes de processar. Sem2xx, a PayZu tenta de novo depois de 1 minuto, 10 minutos, 1 hora, 6 horas e 24 horas. - Descarte o evento cujo
idvocê 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
- Gere o token com POST /v1/card-tokens ou com o script de tokenização. O token vale 15 minutos e serve para uma operação só.
- Para cobrar de novo o mesmo cliente, salve o cartão com
save_card: truena cobrança ou em POST /v1/customers/:customer_id/cards, e cobre depois pelocard_id.
Evite
- Usar o mesmo token duas vezes: a segunda operação responde
400. - Pôr número de cartão em
metadataou, na fatura, emdescription,external_referenceeitems: a PayZu recusa o campo com400.
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_cursoremcursor, como veio, com os mesmos filtros da primeira página. - Pare quando
next_cursorviernull. - Para fechar um período, filtre por dia, no formato
AAAA-MM-DDe 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ódigo | HTTP | Mensagem |
|---|---|---|
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
PZ021 | 401 | Chave de API inválida. |
PZ011 | 409 | Idempotency-Key já usada com outra requisição. |
PZ012 | 409 | Requisição com esta Idempotency-Key ainda está em processamento. |
PZ113 | 409 | Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde. |
PZ500 | 409 | A 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.