Visão geral
Nesta página
Como funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasPróximos passosCobre 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
Cobrança à vista ou em até 12 parcelas, consulta por id ou por período, estorno total e resposta a chargeback.
Cobrança PixPix copia e cola na resposta, confirmação do pagamento pelo aviso e devolução do valor total.
Recorrência no cartãoContrato aberto pela API, sem plano no painel, que cobra o mesmo cartão todo mês ou todo ano.
WebhooksAviso assinado a cada mudança de status depois da criação, na URL de cada cobrança.
3D SecureA cobrança aceita o resultado da autenticação do portador.
AntifraudeA cobrança aceita os dados da análise antifraude.
Cobrança internacionalA cobrança em moeda estrangeira usa a mesma rota POST /charges.
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 /tokenem diante; a PayZu pode desligar essa exigência na sua credencial. Veja Certificado mTLS. - Credencial: o
client_ide oclient_secretda conta, trocados por um token emPOST /token. A validade do token vem emexpires_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
| Regra | Como funciona |
|---|---|
| Valores | Inteiros 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 identificador | externalId, obrigatório, com até 45 caracteres. A rota não deduplica por ele: cada chamada cria uma cobrança. |
| Identificador da PayZu | id da cobrança, um UUID. É ele que vai em GET /charges/{chargeId} e em PUT /charges/{chargeId}/reverse. |
| Paginação | page e limit em GET /charges; limit vai de 1 a 100, padrão 10. |
| Datas | Nas 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. |
| Erros | JSON 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. |