Comece aqui

Introdução


Nesta páginaComo funcionaO que você consegue fazerO que você precisaRegras que valem para todas as chamadasOnde encontrar cada coisaPróximos passos

Use 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

O que você precisa

RequisitoOnde valePágina
Credencial do produtoTodos os produtosAutenticação
Acesso ao sandboxCada produto tem o próprio, menos o PayZu Câmbio, que só tem produçãoAmbientes
IP cadastrado em produçãoPayZu Pix, na lista da conta, e PayZu Conta Hub, na lista da credencialIP cadastrado
Certificado mTLSPayZu Payments e recorrência no cartão, por padrãoCertificado mTLS

Regras que valem para todas as chamadas

ProdutoAutenticaçãoUnidade de valorCódigo do erro
PayZu PixToken Bearer da contaReais: 10.9 é R$ 10,90errorCode
PayZu Conta HubCredencial trocada por token de 15 minutosCentavos: 1500 é R$ 15,00code
PayZu PaymentsCertificado mTLS com tokenCentavosNão há: decida pelo statusCode
PayZu GatewayChave de API no seu servidor; chave de checkout no token de cartão e nas rotas de plano e de assinatura do checkoutCentavoscode; sem ele, status_code
PayZu CâmbioChave de APITexto com um inteiro: centavos de real e unidades de 1e-8 de USDTerror.code
PayZu OnboardingConta de serviço com troca de tokenSem valor monetáriocode; 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 requestId do 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 nome request_id, em todo erro.

Onde encontrar cada coisa

OndeO que tem
DocumentaçãoOs guias deste menu, agrupados por produto.
APIA referência de cada rota, com o Try It! apontado para o sandbox, como em Criar uma cobrança Pix com QR Code.
TutoriaisProgramas completos em Node.js, comentados passo a passo.
Catálogo de errosCódigo, status HTTP, mensagem e rotas de cada erro.
SDKs e Coleção do PostmanAbas de cada produto, com os SDKs do PayZu Pix e uma coleção pronta para importar por produto.
FerramentasServidor MCP e Para IA.
SuporteO link no topo da página.

Próximos passos