PayZu Conta HubCobrar com Pix

Criar uma cobrança Pix


Nesta páginaCrie a cobrançaMostre o copia e colaConfirme o pagamentoErros desta operação

Gere um código Pix copia e cola com valor definido para o cliente pagar no banco dele e receba o valor na conta, já sem a tarifa, com o aviso PAYMENT_PAID.

Crie a cobrança

CampoRegra
amountValor em centavos.
methodPIX.
customerCom name e document.
externalRefIdentificador do seu pedido, único na conta.
descriptionTexto que o pagador vai ver.
metadataO que você quiser receber de volta nos webhooks PAYMENT_*.
bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/api/v1/transactions/payment' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1500,
    "method": "PIX",
    "description": "Pedido 4821",
    "externalRef": "pedido-4821",
    "customer": {
      "name": "Maria Souza",
      "document": "52998224725",
      "email": "maria.souza@exemplo.com",
      "phone": "+5511999998888"
    },
    "metadata": { "pedido": "4821", "canal": "checkout-web" }
  }'

Referência: Criar uma cobrança Pix com copia e cola

Repetir a chamada com o mesmo `externalRef` e os mesmos dados retorna a cobrança já criada.

A resposta da repetição vem com 200. Se a primeira chamada ainda estiver em processamento, aguarde e repita. A cota é de 60 cobranças por minuto por credencial e 120 por conta.

Mostre o copia e cola

O código está em pix.qrCodeText. Desenhe o QR Code a partir desse texto com a biblioteca que preferir e ofereça também o botão de copiar. A cobrança nasce PENDING, e os outros status estão em Cobrar com Pix.

Confirme o pagamento

Cadastre um webhook com os eventos PAYMENT_* em Cadastrar webhooks. O corpo de cada um está na página dele, como Cobrança paga, com externalRef e metadata como você enviou.

Para ter um endereço só desta cobrança, mande também callbackUrl: os avisos dela chegam lá além dos webhooks cadastrados.

Crie o segredo dos callbacks antes de enviar callbackUrl.

Sem ele, a cobrança é recusada. Veja Segredo dos callbacks.

Use a consulta da cobrança para conciliar ou quando um aviso não chegar.

Erros desta operação

CódigoHTTPMensagem
PAYMENT_DISABLED403Pagamento desabilitado para esta conta.
PAYMENT_EXTERNAL_REF_MISMATCH409Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela.
CALLBACK_SECRET_MISSING412Gere o segredo de callback da conta antes de informar uma callbackUrl.
PAYMENT_CREATION_IN_FLIGHT412Uma cobrança com esta referência está sendo criada agora. Repita em instantes.
PAYMENT_ABOVE_MAXIMUM422O valor excede o máximo permitido.
PAYMENT_AMOUNT_NOT_ABOVE_FEE422O valor da cobrança precisa ser maior que a tarifa de recebimento.
PAYMENT_BELOW_MINIMUM422O valor é inferior ao mínimo permitido.

Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.