Comece aqui
Novidades
Nesta página
20 nov 202618 nov 202616 nov 202608 nov 202606 nov 202603 nov 202602 nov 202628 out 202627 out 202624 out 202623 out 202622 out 202621 out 202620 out 202619 out 202617 out 202613 out 202612 out 202607 out 202603 out 202619 ago 202620 nov 2026
Novidades
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
- 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
- PayZu Gateway: 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
- PayZu Gateway: 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
06 nov 2026
Correções
- PayZu Payments: PUT /charges/{chargeId}/reverse responde 503 PZ901, 422 PZ900 ou 500 PZ999 quando a chamada de cancelamento do cartão à adquirente falha ou é recusada com erro HTTP. Antes o estorno era registrado mesmo assim, com 200. Estornar ou devolver uma cobrança
Novidades
- PayZu Payments: Os erros do PayZu Payments, da recorrência no cartão e do PayZu Câmbio trazem code, um código PZ com três dígitos que não muda de sentido. Validação responde 400 PZ001 com details, e erro interno responde 500 PZ999 com requestId. Conta sem limites de cobrança passa de 500 a 422 PZ103. Na criação, a falha de comunicação com a adquirente deixa de ser 500: sem resposta, 502 PZ109; falha temporária, 503 PZ901; recusa, 422 PZ900. Os erros de autenticação e o Cannot get currency rate seguem sem code. Erros da API
- PayZu Payments: Na criação e na consulta por id, o pagamento negado traz creditCardPayment.retryAllowed e creditCardPayment.retryAfter, nulos no pagamento que não foi negado. Depois de uma recusa definitiva do emissor, a nova tentativa com o mesmo cartão na mesma conta responde 422 PZ202 por 30 dias, sem criar cobrança; antes do prazo de uma recusa com prazo, responde 422 PZ203. Os dois códigos trazem em details a recusa original. Programa de retentativa das bandeiras
03 nov 2026
Correções
- PayZu Payments: PUT /charges/{chargeId}/reverse responde 409 quando já há um estorno em andamento para a cobrança. Antes a resposta era 500. Estornar ou devolver uma cobrança
Novidades
- PayZu Payments: POST /charges aceita paymentType pix, com pixPayment.expiresIn de 60 a 7200 segundos, e retorna o Pix copia e cola em pixPayment.qrCode. PUT /charges/{chargeId}/reverse pede a devolução do valor total de um Pix pago, e cada devolução aparece em pixPayment.refunds, com o status do pedido. A cobrança de cartão passa a trazer pixPayment nulo. Criar uma cobrança com cartão
- PayZu Conta Hub: POST /transactions/payment/{paymentId}/refund e POST /transactions/deposit/{depositId}/refund aceitam o header Idempotency-Key, de 1 a 255 caracteres visíveis. Repetir com a mesma chave e o mesmo
amountretorna a devolução já pedida, sem outro Pix ao pagador. A mesma chave com outroamountou em outra operação responde 409 REFUND_IDEMPOTENCY_KEY_REUSED, e chave fora do formato responde 400 REFUND_INVALID_IDEMPOTENCY_KEY. Solicitar a devolução de uma cobrança - PayZu Conta Hub: Na devolução de cobrança e na devolução de depósito, só o corpo vazio ou {} devolve o que resta. Corpo que não é JSON responde 400 SCHEMA_MALFORMED_BODY, e campo diferente de
amountresponde 400 SCHEMA_INVALID. Nos dois casos nada é devolvido; antes, esses corpos devolviam o valor inteiro. Solicitar a devolução de um depósito
02 nov 2026
Correções
- PayZu Pix: Quando a instituição do recebedor recusa um saque já aceito, cancellationReason traz a mensagem do PZS102 ou o motivo do catálogo para o caso, como conta do beneficiário inválida. Antes essas recusas chegavam como indisponibilidade ou erro de comunicação da instituição financeira. Consultar o status de um saque
28 out 2026
Novidades
- PayZu Gateway: 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
- PayZu Gateway: 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
- PayZu Gateway: 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
27 out 2026
Novidades
- PayZu Onboarding: Na proposta de empresa, depois da etapa FACE concluída ou do envio para análise, o CPF de quem preenche não muda mais na etapa PERSONAL_DATA, e a tentativa responde 422 field_locked. Quem preenche a empresa passa por verificação de pessoa, e a análise da proposta espera também essa decisão. Empresas e sócios
24 out 2026
Novidades
- PayZu Pix: POST /pix recusa
amountcom mais de 2 casas decimais com 400 PZV001. Antes o valor era arredondado. Criar uma cobrança Pix com QR Code
23 out 2026
Novidades
- PayZu Conta Hub: Saque e pagamento de QR Code passam a ter só PROCESSING, CONFIRMED e FAILED: PROCESSING substitui REQUESTED, CREATED e APPROVED. Vale também para o filtro status de GET /transactions/withdraw e para os webhooks WITHDRAW_*. Na devolução, PROCESSING substitui RESERVED e SENT. Consultar o status de um saque
- PayZu Conta Hub: No saque e na transferência entre contas, providerRejectedReason passa a se chamar failureReason, e sentAt e approvedAt saem do saque. A listagem de saques traz operation e leva bank e pixKey para destination, como o detalhe; failureReason e callbackUrl ficam só em GET /transactions/withdraw/{withdrawId}. Listar os saques e pagamentos
- PayZu Conta Hub: paymentId, withdrawId e transferId dos webhooks passam a ser o mesmo id no formato PAAAAMMDDhhmmss que a API retorna, nos dois lados da transferência. O PAYMENT_REFUNDED deixa de trazer serviceFeeReturned, e ACCOUNT_BLOCKED e ACCOUNT_UNBLOCKED deixam de trazer blockings e seguem com blockedOperations. Webhooks e callbacks
- PayZu Conta Hub: Saem qrCodeUrl e qrCodeBase64 da cobrança, que vinham sempre nulos, o status da chave Pix, o id e o origin.id da contestação MED e o trilho de cartão das métricas, com o campo available. No extrato saem entryId, originId, trigger e statusDetail, e os filtros trigger e originId. Listar os lançamentos do extrato
- PayZu Conta Hub: Com o recebimento de depósitos desabilitado na conta, o Pix entra, mas o líquido fica retido até a liberação pela PayZu. O detalhe do depósito traz blockedAmount, blockedAt e releasedAt, refundableAmount fica em 0 e a devolução responde 422 DEPOSIT_BLOCKED enquanto durar a retenção. Consultar um depósito
22 out 2026
Correções
- PayZu Payments: GET /charges/{chargeId} responde 404 quando a cobrança não existe ou é de outra conta. Antes a resposta era 500. Consultar uma cobrança
Novidades
- PayZu Pix: A devolução parcial concluída dispara TRANSACTION_REFUNDED. A transação segue COMPLETED, e refundAmount traz o total já devolvido. Antes o webhook só saía na devolução total. Solicitar a devolução de um Pix recebido
21 out 2026
Novidades
- PayZu Pix: A consulta de chave da v1 fica só em GET /pix/key, que traz o titular, a instituição e a conta mascarada. GET /user/dict deixou de existir. Consultar o titular e a conta de uma chave Pix
20 out 2026
Novidades
- PayZu Onboarding: O analista pode aprovar uma proposta que a análise automática reprovou. Nesse caso chega um segundo proposal.decided, com APPROVED. Envio e análise
19 out 2026
Novidades
- PayZu Pix: A devolução responde 424 com PZC500 quando a instituição financeira da transação não faz devolução. Solicitar a devolução de um Pix recebido
17 out 2026
Novidades
- PayZu Gateway: 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
13 out 2026
Novidades
- PayZu Pix: expiresIn passa a aceitar de 60 a 172.000 segundos. GET /user deixa de trazer role. Criar uma cobrança Pix com QR Code
12 out 2026
Novidades
- PayZu Onboarding: Proposta enviada para análise não pode mais ser cancelada pela API: a resposta é proposal_in_analysis. Duas gravações da mesma proposta ao mesmo tempo respondem write_conflict. Cancelar uma proposta
07 out 2026
Correções
- PayZu Payments: A rota de estorno não aceita
amount. A documentação prometia estorno parcial e foi corrigida. Estornar ou devolver uma cobrança
Novidades
- PayZu Conta Hub: Nova API da conta de cada loja: cobranças Pix, saques, pagamento de copia e cola, transferências entre contas, extrato e infrações MED. Sobre o PayZu Conta Hub
03 out 2026
Novidades
- PayZu Pix: Conta com IP cadastrado só chama a v1 desses IPs, inclusive nos depósitos; de outro IP, recebe PZA203. Conta que envia Pix pela API precisa ter IP cadastrado; sem ele, recebe
PZA205em qualquer rota. IP cadastrado
19 ago 2026
Correções
- PayZu Pix: O header correto é
X-Callback-Signature, no formatot=<segundos>,v1=<HMAC-SHA256 de t.corpo>. O exemplo anterior usava o esquema do PayZu Payments. Assinatura dos callbacks