Introdução
Nesta página
Como funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasOnde encontrar cada coisaPróximos passosUse as seis APIs da PayZu para receber e pagar com Pix, operar contas com saldo, cobrar no cartão, vender planos e assinaturas, cobrar em outra moeda e abrir contas para os seus clientes.
Como funciona
Você desenvolve contra o sandbox, que responde nos mesmos caminhos de rota da produção. Para operar de verdade, troque o host e a credencial. Em produção, a operação segue para o banco ou para o emissor do cartão.
Quando o estado muda, a PayZu avisa a sua aplicação por callback.
Isso vale para o PayZu Pix, o PayZu Conta Hub, o PayZu Payments, o PayZu Gateway e o PayZu Onboarding.
O que você consegue fazer
Gere QR Code de cobrança, envie Pix para chave ou QR Code, devolva valores recebidos, responda ao MED e baixe extratos.
PayZu Conta HubOpere uma conta com saldo: cobrança copia e cola, saque para chave, pagamento de copia e cola, transferência, chaves Pix e extrato.
PayZu PaymentsAutorize compras no cartão de crédito em uma ou mais parcelas, com 3D Secure e análise antifraude, programe ciclos de cobrança direto no cartão ou cobre por Pix. O estorno e a devolução são sempre do valor total.
PayZu GatewayCobre no cartão de crédito e no Pix com faturas avulsas, de assinatura ou de link de pagamento, cada uma com a sua página de pagamento.
PayZu CâmbioCompre USDT com o saldo em reais e saque para as suas carteiras.
PayZu OnboardingCrie propostas de abertura de conta, colete dados e documentos pela jornada e acompanhe a análise até a decisão.
O que você precisa
| Requisito | Onde vale | Página |
|---|---|---|
| Credencial do produto | Todos os produtos | Autenticação |
| Acesso ao sandbox | Cada produto tem o próprio, menos o PayZu Câmbio, que só tem produção | Ambientes |
| IP cadastrado em produção | PayZu Pix, na lista da conta, e PayZu Conta Hub, na lista da credencial | IP cadastrado |
| Certificado mTLS | PayZu Payments e recorrência no cartão, por padrão | Certificado mTLS |
Regras que valem para todas as chamadas
| Produto | Autenticação | Unidade de valor | Código do erro |
|---|---|---|---|
| PayZu Pix | Token Bearer da conta | Reais: 10.9 é R$ 10,90 | errorCode |
| PayZu Conta Hub | Credencial trocada por token de 15 minutos | Centavos: 1500 é R$ 15,00 | code |
| PayZu Payments | Certificado mTLS com token | Centavos | Não há: decida pelo statusCode |
| PayZu Gateway | Chave de API no seu servidor; chave de checkout no token de cartão e nas rotas de plano e de assinatura do checkout | Centavos | code; sem ele, status_code |
| PayZu Câmbio | Chave de API | Texto com um inteiro: centavos de real e unidades de 1e-8 de USDT | error.code |
| PayZu Onboarding | Conta de serviço com troca de token | Sem valor monetário | code; na troca de token, error |
Decida pelo código do erro, nunca pela mensagem.
Nas APIs de cartão, dentro do statusCode, decida por details[].field ou pela message, como em Erros do PayZu Payments.
Outras regras:
- Cotações do PayZu Payments. A cotação é um número decimal. A conversão recebe centavos de real e retorna centavos da moeda de destino.
- Chamada repetida. Cada produto deduplica por um identificador diferente, exceto o PayZu Payments e a recorrência no cartão, que não deduplicam. Veja Idempotência.
- Identificador da chamada. Envie ao suporte o
requestIddo erro, com a rota e o código. O PayZu Pix retorna esse campo em todo erro; o PayZu Onboarding, em todo erro fora da troca de token; o PayZu Gateway, com o nomerequest_id, em todo erro.
Onde encontrar cada coisa
| Onde | O que tem |
|---|---|
| Documentação | Os guias deste menu, agrupados por produto. |
| API | A referência de cada rota, com o Try It! apontado para o sandbox, como em Criar uma cobrança Pix com QR Code. |
| Tutoriais | Programas completos em Node.js, comentados passo a passo. |
| Catálogo de erros | Código, status HTTP, mensagem e rotas de cada erro. |
| SDKs e Coleção do Postman | Abas de cada produto, com os SDKs do PayZu Pix e uma coleção pronta para importar por produto. |
| Ferramentas | Servidor MCP e Para IA. |
| Suporte | O link no topo da página. |