PayZu Payments

Visão geral


Nesta páginaComo funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasPróximos passos

Cobre no cartão de crédito a partir do seu próprio checkout, à vista ou em até 12 parcelas, e receba o resultado da autorização na mesma resposta.

Como funciona

Sua aplicação coleta os dados do cartão no seu checkout e chama a API com o token da conta. A PayZu autoriza e captura a cobrança na mesma chamada e retorna a cobrança com id, creditCardPayment.status e os códigos de retorno.

Quando o status muda depois disso, como num estorno ou num chargeback, a PayZu avisa a URL informada em postbackUrl. A consulta pelas rotas GET continua disponível para conferência.

O que você consegue fazer

A recorrência usa o mesmo POST /charges, com o nó recurrence.

O que você precisa

  • Certificado de cliente: emitido pela PayZu, com a chave privada. Por padrão, toda chamada à API exige o certificado, do POST /token em diante; a PayZu pode desligar essa exigência na sua credencial. Veja Certificado mTLS.
  • Credencial: o client_id e o client_secret da conta, trocados por um token em POST /token. A validade do token vem em expires_in. Veja Autenticação.
  • Segredo de assinatura: faz parte da credencial da conta. Sem ele, a PayZu não envia os avisos.
  • Habilitação: para as bandeiras que você vai aceitar (Visa, Master, Elo, Diners e Hipercard) e, quando usar, para 3D Secure, antifraude, moeda estrangeira e Pix.
  • Ambiente: sandbox para testar e produção para cobrar. Veja Ambientes e URLs.

Sem a habilitação, a cobrança é recusada.

A resposta é 403 com Produto não habilitado.

Regras que valem para todas as chamadas

RegraComo funciona
ValoresInteiros em centavos: 10000 é R$ 100,00. O mínimo por cobrança é 100, e a conta tem um menor e um maior valor próprios. Em moeda estrangeira, amount vai na menor unidade daquela moeda.
Seu identificadorexternalId, obrigatório, com até 45 caracteres. A rota não deduplica por ele: cada chamada cria uma cobrança.
Identificador da PayZuid da cobrança, um UUID. É ele que vai em GET /charges/{chargeId} e em PUT /charges/{chargeId}/reverse.
Paginaçãopage e limit em GET /charges; limit vai de 1 a 100, padrão 10.
DatasNas respostas, ISO 8601 em UTC com o sufixo Z, como 2026-06-12T14:35:22.000Z. customer.birthdate vai em AAAA-MM-DD. Os filtros startDate e endDate aceitam data ou instante ISO 8601. Validade do cartão em MM/AAAA.
ErrosJSON com statusCode, error e message; erros de validação trazem details com o campo. Não há código próprio além do status HTTP. Veja Erros.

Próximos passos