PayZu Gateway

Novidades


Nesta página20 nov 202618 nov 202616 nov 202608 nov 202628 out 202617 out 2026

20 nov 2026

Novidades

  • Toda cobrança do PayZu Gateway é uma fatura. POST /v1/invoices cria a fatura com url de pagamento fixa, que vale como comprovante depois de paga, e com payment cobra no cartão ou no Pix na mesma chamada. A fatura pode nascer sem cliente, para quem paga informar os dados na página, e aceita discount, items, billing, payment_settings e checkout. Saem POST /v1/payments, GET /v1/payments e GET /v1/payments/{paymentId}: cada tentativa de pagamento vem em payments[] da fatura, e receiptUrl deixa de existir. Criar uma fatura
  • POST /v1/invoices/:invoice_id/payments faz uma nova tentativa na fatura em aberto, POST /v1/invoices/:invoice_id/cancel cancela a fatura e POST /v1/invoices/:invoice_id/refunds estorna, com 201, no lugar de POST /v1/payments/{paymentId}/refund. Cartão recusado responde 201, com a tentativa failed e o motivo em failure.code, e não mais 402; sem resposta da adquirente, a tentativa fica processing, e não sai mais 202. Pagar uma fatura
  • POST /v1/subscriptions responde com a fatura de adesão em invoice, também quando o cartão é recusado, e exige Idempotency-Key. Cancelar a assinatura passa a POST /v1/subscriptions/:subscription_id/cancel, que fecha as faturas em aberto dela. A carência vai até o billing.expires_at da fatura do ciclo, e entram os eventos subscription.renewed e subscription.grace_started. Criar uma assinatura
  • O link de pagamento sai da /v1 e é criado só no painel, sem link de assinatura nem cliente fixo. Cada compra pelo link cria uma fatura sem cliente, paga na página da fatura. Saem as rotas /v1/payment-links. Comprar pelo link
  • O endereço vai em address, dentro do cliente, e o PATCH mescla o bloco campo a campo. Saem as rotas /v1/customers/{customerId}/addresses. Alterar um cliente
  • O token de cartão passa a POST /v1/card-tokens, com o cartão em card, e vai em credit_card.card_token na fatura e na assinatura. Os códigos do script de tokenização passam a PZ210 a PZ219. Tokenização no app
  • Só a página da fatura tem formulário de pagamento: GET e POST /v1/checkout/invoices/:invoice_id e …/payments. A assinatura pela página nasce sem cartão e leva à fatura de adesão, e a compra pelo link é POST /v1/checkout/payment-links/:payment_link_id/invoices, sem corpo. Saem as rotas da página por token e por pagamento. Pagar a fatura pela página
  • Os eventos passam a 19, com data numa chave só, invoice, subscription ou chargeback, igual à consulta do recurso. Saem payment.*, payment_link.* e invoice.failed: esses nomes respondem 400 ao cadastrar o webhook e no filtro de entregas. As entregas criadas antes da mudança seguem legíveis em /v1/webhook-deliveries e podem ser reenviadas à mão, com o corpo gravado. As entregas passam a /v1/webhook-deliveries e a troca do segredo a POST /v1/webhooks/:webhook_id/rotate-secret. Webhooks
  • O erro passa a {status_code, error, message, code, request_id}, com error em minúsculas, code com PZ e três dígitos, request_id em todo erro e fields na validação. Os códigos de cada operação estão na página dela e no Catálogo de erros. Erros
  • A API passa a snake_case no corpo, na query, nos parâmetros de caminho, como :invoice_id, e nas respostas, com valores em minúsculas e datas em _at. As listas trazem next_cursor, aceitam created_from e created_to e ignoram parâmetro que não têm. Paginação

18 nov 2026

Correções

  • Na referência, os exemplos de 503 com código (CARD_VAULT_UNAVAILABLE, SUBSCRIPTION_AMOUNT_UPDATE_UNAVAILABLE e SUBSCRIPTION_REACTIVATION_UNAVAILABLE) trazem requestId, como a API responde em todo 5xx. Erros

Novidades

  • O script de tokenização do navegador saiu da API: carregue https://static.gateway.payzu.com.br/scripts/gateway.min.js no lugar de https://api.gateway.payzu.com.br/v1/scripts, que responde 404. Na página com Content-Security-Policy, inclua https://static.gateway.payzu.com.br em script-src. window.PayZuGateway, init(pk) e encrypt(card) não mudam. Tokenização no navegador
  • POST /v1/subscriptions/{subscriptionId}/reactivate reativa também a assinatura no cartão: a recorrência volta a valer na adquirente, e billing.nextAt passa a ser a próxima cobrança que ela devolve. Se a adquirente não reativar a recorrência, ou se outra alteração da mesma assinatura estiver em curso, a resposta é 503 SUBSCRIPTION_REACTIVATION_UNAVAILABLE, no lugar do 422, e a assinatura segue cancelada. Cancelar uma assinatura
  • A assinatura traz previousCancellations, os cancelamentos desfeitos do mais antigo para o mais novo, cada um com at, reason, note e reactivatedAt, em toda resposta e no data.subscription dos webhooks. Na volta a ACTIVE, pela reativação ou por um pagamento confirmado depois do cancelamento, cancellation volta a null e o cancelamento vai para a lista. Um cancelamento desfeito antes desta mudança não aparece na lista. Ciclo da assinatura
  • GET /v1/settings e PATCH /v1/settings consultam e alteram a carência da conta, graceDays, de 0 a 30 dias, com 7 quando não foi alterada; a carência acima de 30 dias, que o painel aceitava, passou a 30. No cartão, a carência passa a seguir graceDays: começa na primeira renovação recusada e termina graceDays dias depois, quando a assinatura é cancelada com RENEWAL_FAILURE, e com 0 a primeira recusa já cancela. A carência que já tinha começado mantém o grace.endsAt gravado. A renovação recusada que a adquirente aprova numa nova tentativa passa a PAID, com payment.paid e invoice.paid, e tira a assinatura da carência. Carência

16 nov 2026

Correções

  • O guia não cita mais o 422 da segunda assinatura do mesmo plano, que deixou de existir, e o exemplo do cartão aprovado traz returnCode 0 e returnMessage Successful, como a API responde. Assinar um plano pelo checkout
  • O script de tokenização precisa do Chrome 93, do Firefox 95 ou do Safari 15.4, e não do Chrome 92. Fora disso, o script não registra window.PayZuGateway ou init responde TOKENIZER_UNAVAILABLE. Tokenização no navegador

Novidades

  • Nos webhooks do PayZu Gateway, data traz o recurso como a API devolve na consulta dele: subscription em subscription.*, invoice, com payments, em invoice.*, payment em payment.*, chargeback em chargeback.* e paymentLink em payment_link.*; payment_link.subscription_created traz paymentLink e subscription. O envelope id, type, createdAt e data, a assinatura, as tentativas e o ping não mudam. Saem do corpo method, que passa a paymentMethod; failedAt, que passa a failure.at ou, no Pix vencido ou cancelado, a cancellation.at; refundedAt e refundedAmount, que passam ao bloco refund; chargedbackAt, que passa a chargeback.at; nextBillingAt, canceledAt e canceledBy, que passam aos blocos billing e cancellation; e paidCount, que passa a usage.paid. No pagamento de fatura, a assinatura sai de invoice.subscription e vem em subscription. failure.stage vem em maiúsculas, e customer é o da API, com document e documentType. As entregas criadas antes desta mudança guardam o corpo anterior, também no reenvio. Modelo de evento
  • O mesmo cliente pode ter mais de uma assinatura ativa do mesmo plano: a segunda assinatura no cartão deixa de responder 422 em POST /v1/subscriptions, no checkout e no link de assinatura. Em POST /v1/subscriptions, a assinatura INCOMPLETE de um plano só é usada de novo pela chamada com o mesmo cliente e o mesmo metadata; com outro metadata, a chamada cria outra assinatura. PATCH /v1/subscriptions/{subscriptionId} com metadata responde 409 SUBSCRIPTION_INCOMPLETE enquanto a assinatura está INCOMPLETE. Criar uma assinatura
  • POST /v1/webhooks/deliveries/{deliveryId}/retry reenvia a entrega em qualquer status, e o 422 WEBHOOK_DELIVERY_NOT_FAILED deixa de existir. A entrega DELIVERED é enviada de novo numa tentativa só e passa a FAILED se o seu endpoint não responder 2xx. Na entrega PENDING, a próxima tentativa automática é feita na hora, mesmo com o webhook INACTIVE. Reenviar entregas
  • A URL do webhook não aceita localhost nem domínio que resolve para endereço interno: o cadastro e a alteração respondem 400 WEBHOOK_URL_INVALID. Cadastrar webhooks
  • O corpo que não é JSON válido responde 400 com uma mensagem em português, no lugar de Bad Request, e o corpo JSON acima de 1 MB responde 413 com statusCode, error e message. POST /v1/customers responde 400 para campo que não existe, birthdate não aceita data futura e cvv aceita só 3 ou 4 dígitos. O Pix que a adquirente cancela depois do vencimento sai com cancellation.reason EXPIRED, e não OTHER. Erros

08 nov 2026

Novidades

  • A API do PayZu Gateway passa a responder em https://api.gateway.payzu.com.br, no checkout, na API do lojista e no script de tokenização. Troque o host de produção: os caminhos das rotas não mudam, e o sandbox segue em https://api.sandbox.payzu.dev. Sobre o PayZu Gateway
  • POST /v1/payments cria uma venda avulsa no cartão ou no Pix, sem plano e sem link: com o cartão digitado, com um cartão salvo em card.id ou com um token gerado pela chave de tokenização em card.token. O cabeçalho Idempotency-Key é obrigatório. Cartão aprovado e Pix emitido respondem 201; a recusa responde 402 PAYMENT_DECLINED, com o pagamento em details.payment; sem resposta a tempo, 202 com o pagamento em ERROR. GET /v1/payments lista os pagamentos de todas as origens, com os filtros status, method, origin, customerId, externalReference, from e to. Vender no cartão
  • POST /v1/payments/{id}/refund estorna o cartão ou pede a devolução do Pix, sempre pelo valor total e com Idempotency-Key obrigatório. No pagamento de fatura, cancelSubscription decide se a assinatura é cancelada; sem ele, vale refundCancelsSubscription, que GET e PATCH /v1/settings passam a mostrar e alterar junto com invoiceDaysBefore e graceDays. A devolução do Pix passa por REFUND_REQUESTED, com os eventos payment.refund_requested e payment.refund_failed. Estornar uma fatura
  • POST /v1/customers cria um cliente, e PATCH /v1/customers/{id} altera só os campos enviados. Documento já cadastrado responde 409 CUSTOMER_ALREADY_EXISTS, e documento diferente na alteração, 409 CUSTOMER_DOCUMENT_IMMUTABLE. GET /v1/customers/{id}/cards lista os cartões do cliente, com chargeable, e DELETE /v1/customers/{id}/cards/{cardId} apaga um cartão salvo. Criar um cliente
  • Os webhooks do lojista entram na API: /v1/webhook-endpoints cadastra até 5 endereços, altera, troca o segredo e testa o envio, e /v1/webhook-deliveries/{id}/retry reenvia uma entrega que falhou. Nos eventos payment.*, o pagamento traz origin, externalReference, metadata e failure, com stage, label e reason. Webhooks
  • As rotas de escrita da API do lojista aceitam o cabeçalho Idempotency-Key. A mesma chave com o mesmo corpo, em até 24 horas, devolve a primeira resposta; com outro corpo, responde 409 IDEMPOTENCY_KEY_REUSED, e enquanto a primeira chamada não terminou, 409 IDEMPOTENCY_IN_PROGRESS. Idempotência
  • GET /v1/payments/{id} traz origin, description, items, externalReference, metadata, failure e a bandeira do cartão, e deixa de trazer providerId e os códigos de retorno e de erro da transação. O status ganha REFUND_REQUESTED. Consultar uma fatura
  • O link de fatura aceita Pix: no /pay, paymentMethod PIX devolve o QR Code, que vale 60 minutos, e sem paymentMethod vale o cartão. No Pix, pixTransaction.status passa a pending, paid, canceled, refunded ou failed, qrCodeUrl vem nulo e pixTransaction.expiresAt traz o prazo do QR Code. Conta sem Pix habilitado responde 403 PIX_NOT_ENABLED. Pagar a fatura pela página
  • POST /v1/payment-links aceita type: ORDER, o link de valor fixo, que segue como padrão, ou SUBSCRIPTION, que assina o plano de planId. No SUBSCRIPTION, o valor, os meios e o desconto vêm do plano, amount e installments voltam nulos e paymentMethods vazio, maxPayments limita as assinaturas e pagar o link cria a assinatura, com o evento payment_link.subscription_created; cartão recusado cancela a adesão na hora. GET /v1/payment-links filtra por type, e GET /v1/payment-links/{id}/payments traz os pagamentos da adesão. Criar uma fatura
  • GET /v1/account troca cardEnabled e pixEnabled por card, com enabled e access (READ ou WRITE), e pix, com enabled, e passa a trazer recurrenceActivatedAt. Sem a Recorrência ativada, as rotas de planos, assinaturas e faturas, o checkout por chave e o link SUBSCRIPTION respondem 404 RECURRENCE_NOT_ACTIVE. Conta só de consulta responde 403 READ_ONLY nas cobranças, nos planos, nos links e no estorno. Sobre o PayZu Gateway
  • O link de fatura muda de POST /v1/subscriptions/payment-links para POST /v1/invoices/payment-links, com o mesmo corpo e a mesma resposta. O caminho antigo deixa de existir. Consultar uma fatura
  • Os 401 da chave de API passam a trazer code: API_KEY_MISSING, sem a chave, e API_KEY_INVALID, com a chave desconhecida, malformada ou revogada. A conta suspensa responde 403 ACCOUNT_SUSPENDED, também nas rotas públicas dos links. Catálogo de erros
  • GET /v1/scripts serve o script de tokenização do navegador. Carregado com uma tag script na página de pagamento, ele registra window.PayZuGateway, com init(pk) e encrypt(card): confere o cartão com as regras da cobrança, cifra com a chave de tokenização e devolve o token para card.token na venda avulsa, sem o cartão passar aberto pelo seu servidor. Tokenização no navegador

28 out 2026

Novidades

  • POST /v1/plans e PATCH /v1/plans/{id} só aceitam installments igual a 1, e outro valor responde 400. Os planos gravados com mais parcelas passaram a 1. Criar um plano
  • GET /v1/plans filtra por recurrence. GET /v1/customers filtra por subscriptionStatus e planId e busca também pelo telefone. Cada cliente traz paymentSummary, com quantidade, total e último pagamento pago, e subscriptionSummary ganha latestPlan e latestNextBillingAt. Listar os clientes
  • POST /v1/payment-links aceita customerId no lugar de customer, só em link de uso único. Os dois juntos, ou customerId em link reutilizável, respondem 400, e cliente de outro lojista responde 404. GET /v1/payment-links filtra por customerId. Criar uma fatura

17 out 2026

Novidades

  • Cartão vencido, bandeira não aceita e CPF ou CNPJ do titular inválido são recusados com 400. As consultas aceitam 60 chamadas por minuto por IP, e a consulta da assinatura mostra e-mail, celular e documento do cliente mascarados. Criar uma assinatura pela página