PayZu PaymentsCobranças

Criar uma cobrança Pix


Nesta páginaCrie a cobrançaMostre o QR CodeErros desta operação

Crie a cobrança com paymentType igual a pix e mostre ao comprador o Pix copia e cola que vem na resposta.

Crie a cobrança

CampoObrigatórioDescrição
amountsimValor em centavos, a partir de 100. Os limites mínimo e máximo da sua conta também valem.
externalIdsimIdentificador do pedido no seu sistema, com até 45 caracteres.
paymentTypesimpix.
customer.namesimNome do comprador, só com letras e espaços, até 120 caracteres.
customer.identitynãoCPF ou CNPJ do comprador, só números. Envie junto com o identityType.
customer.identityTypenãoCPF ou CNPJ.
customer.emailnãoE-mail do comprador.
postbackUrlnãoURL que recebe os postbacks desta cobrança.
pixPayment.expiresInnãoValidade do QR Code em segundos, de 60 a 7200. O padrão é 3600, uma hora.
cartnãoItens do pedido, cada um com name, quantity, sku e unitPrice (em centavos).
bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/v1/charges' \
  --header "Authorization: Bearer $PAYZU_TOKEN" \
  --cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10000,
    "paymentType": "pix",
    "externalId": "pedido-1235",
    "postbackUrl": "https://seusite.com.br/webhooks/payzu",
    "customer": {
      "name": "Maria Souza",
      "identity": "11144477735",
      "identityType": "CPF"
    },
    "pixPayment": { "expiresIn": 3600 }
  }'

Referência: Criar uma cobrança com Pix

Guarde o id, que identifica a cobrança nas consultas, nos postbacks e na devolução. A cobrança Pix não aceita creditCardPayment nem recurrence.

A rota não deduplica por externalId.

Num timeout, procure o seu externalId em Listar as cobranças antes de repetir.

Mostre o QR Code

O qrCode é o Pix copia e cola. Mostre esse texto para o comprador copiar e gere a imagem do QR Code a partir dele, com qualquer biblioteca de QR Code. O QR Code aceita pagamento até o expiresAt.

Com pixPayment.status igual a failed na criação, o Pix não foi gerado.

qrCode e expiresAt vêm nulos, nenhum postback é enviado e é preciso criar outra cobrança. Os status estão em Status do Pix.

Erros desta operação

CódigoHTTPMensagem
PZ010403Produto não habilitado
PZ101422Valor mínimo por cobrança não atingido
PZ102422Valor máximo por cobrança excedido
PZ103422Conta sem limites de cobrança configurados
PZ105422Provedor de pagamento desabilitado
PZ108422Configuração de pagamento da conta incompleta
PZ300422Pix não disponível para esta conta
PZ301422Recorrência não disponível para Pix
PZ700422Conta sem configuração de taxas definidas para este meio de pagamento
PZ900422O provedor de pagamento recusou a operação
PZ109502Não foi possível confirmar a criação da cobrança com o provedor de pagamento. Verifique com o suporte antes de repetir o pedido.
PZ901503Não foi possível estabelecer comunicação com o provedor de pagamento. Tente novamente em instantes.

Toda resposta traz o cabeçalho request-id. Informe esse valor ao suporte quando precisar que uma chamada seja investigada. Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.