Arquitetura da integração
Nesta página
Chamadas do seu servidorCartão no aparelho do compradorPágina de pagamento da PayZuAvisos para o seu sistemaConsultaO seu servidor chama a API para criar e consultar cada fatura, e a PayZu avisa o seu sistema sempre que uma fatura, uma assinatura ou uma contestação muda.
Chamadas do seu servidor
Toda chamada vai por HTTPS, com a chave de API, que fica só no seu servidor e nunca vai ao navegador nem ao app do comprador.
| Item | Regra |
|---|---|
| Servidor de produção | https://api.gateway.payzu.com.br |
| Credencial | Chave de API no cabeçalho Authorization: Bearer. |
Idempotency-Key | Nas escritas que aceitam o cabeçalho, impede que a mesma chamada rode duas vezes. É obrigatório ao criar, pagar e estornar uma fatura e ao criar uma assinatura. |
Veja Autenticação e Idempotência.
Cartão no aparelho do comprador
O número do cartão não precisa passar pelo seu servidor, que recebe só o token e o envia no lugar do cartão: em payment.credit_card.card_token na fatura e em credit_card.card_token na assinatura.
| Onde o comprador paga | Como o token é gerado |
|---|---|
| Página web | O script de tokenização cifra o cartão com a chave de tokenização do painel. |
| App | O aparelho do comprador gera o token na API com a chave de checkout. |
O token vale 15 minutos e serve para uma operação só. Quem já recebe o cartão no próprio servidor pode mandar os dados dele direto na cobrança. Veja Tokenização de cartão.
Página de pagamento da PayZu
A PayZu hospeda a página em que o cliente paga uma fatura.
| Campo | Onde vem | O que traz |
|---|---|---|
url | Em toda fatura, já na resposta da criação. | A página para o cliente pagar a fatura, no cartão ou no Pix. Depois de paga, a mesma página é o comprovante. |
url | No link de pagamento criado no painel. | A página do link: cada compra cria uma fatura e leva o cliente à página dela. |
Veja Criar uma fatura e Comprar pelo link.
Para vender um plano ou cobrar um link numa tela sua, use as rotas do Checkout: as do plano e da assinatura levam a chave de checkout, e as do link levam o id do link no caminho.
Avisos para o seu sistema
Quando uma fatura, uma assinatura ou uma contestação muda, a PayZu envia um POST ao endereço de cada webhook ativo que escolheu aquele evento. O seu sistema responde 2xx em até 5 segundos e confere a assinatura do aviso, feita com o segredo do webhook.
Veja Webhooks e Assinatura dos webhooks.
Consulta
A consulta serve de apoio aos avisos, por exemplo para checar um pedido cujo aviso não chegou.
| Você tem | Como achar a fatura |
|---|---|
O id que veio no aviso | Consulte a fatura pelo id. |
| O identificador do pedido no seu sistema | Liste as faturas por external_reference. |
| O id do link de pagamento | Liste as faturas por payment_link_id. |
Veja Consultar faturas.