PayZu Gateway

Como começar a usar o PayZu Gateway


Nesta páginaCrie a chave de APIFaça a primeira cobrançaReceba os avisosPasse para a produção

Siga estes passos para fazer a primeira cobrança pela API e, depois, levar a integração para a produção.

Crie a chave de API

A conta do PayZu Gateway nasce no primeiro acesso ao painel, e é lá que você cria a chave de API. Veja Autenticação e Ambientes de teste e produção.

A chave aparece uma única vez, na criação.

Guarde a chave no seu servidor, fora do código e do navegador.

Teste a chave listando a fatura mais recente da conta:

bash
curl "https://api.sandbox.payzu.dev/v1/invoices?limit=1" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Com a chave aceita, a resposta é 200, com a fatura em items, ou com items vazio numa conta sem faturas. Na Referência API, o mesmo teste está em Listar as faturas: cole a chave em Credenciais e clique em Try It!.

Faça a primeira cobrança

Crie uma fatura com a descrição e o valor em centavos. Para o cliente escolher o meio na página da PayZu, mande a ele a url da resposta. Para mostrar o Pix no seu sistema, envie também payment e o cliente.

bash
curl -X POST https://api.sandbox.payzu.dev/v1/invoices \
  -H "Authorization: Bearer SUA_CHAVE_DE_API" \
  -H "Idempotency-Key: 3e7a1c5b-8d2f-4a9e-b6c4-0f1d2e3a4b5c" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pedido 1242",
    "amount": 9900
  }'
Trecho da resposta
{
  "id": "in_2QwT6nXcVb4LzYm9KdRh5E",
  "status": "pending",
  "url": "https://invoice.payzu.com.br/pay/in_2QwT6nXcVb4LzYm9KdRh5E",
  "description": "Pedido 1242",
  "amounts": {
    "subtotal": 9900,
    "discount": 0,
    "total": 9900,
    "paid": 0,
    "refunded": 0
  },
  "customer": null,
  "payments": []
}
  • Resposta: 201, com a fatura pending. No Pix, o copia e cola vem em payments[0].pix.qr_code_text.
  • Cliente: com payment, a fatura precisa de cliente. Troque o customer_id do exemplo pelo id de um cliente da sua conta, criado em Cadastrar um cliente, ou envie o cliente inteiro em customer.
  • Idempotency-Key: cabeçalho obrigatório, com um valor novo para cada fatura.
  • Recorrência: a fatura não depende dela.

Os campos estão em Criar uma fatura e Vender no Pix.

Receba os avisos

Cadastre um webhook com o endereço do seu sistema e os eventos que você quer receber. Guarde o segredo que vem na resposta, porque ele só aparece na criação e na troca.

Quando o cliente paga, a fatura passa a paid e sai o evento invoice.paid, com a fatura em data.invoice. Antes de dar baixa no pedido, confira a assinatura de cada aviso. Se o aviso não chegar, consulte a fatura pelo id, como em Consultar faturas.

Passe para a produção

Em produção, chame https://api.gateway.payzu.com.br, com os mesmos caminhos.

RecursoQuem liberaSem a liberação
CartãoSuporte da PayZuAs cobranças no cartão respondem 403.
PixSuporte da PayZuAs cobranças no Pix respondem 403.
RecorrênciaVocê, no painelAs rotas de planos, assinaturas e configurações respondem 404. As faturas funcionam sem ela.

Veja Ambientes de teste e produção e o Checklist de produção.