Criar uma cobrança Pix
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
| Campo | Regra |
|---|---|
amount | Valor em centavos. |
method | PIX. |
customer | Com name e document. |
externalRef | Identificador do seu pedido, único na conta. |
description | Texto que o pagador vai ver. |
metadata | O que você quiser receber de volta nos webhooks PAYMENT_*. |
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" }
}'{
"id": "P20261005113205K7Q2M9XB4TC127431",
"method": "PIX",
"status": "PENDING",
"amount": 1500,
"description": "Pedido 4821",
"serviceFee": 105,
"netAmount": 1395,
"refundedAmount": 0,
"refundFee": 0,
"refundInProgressAmount": 0,
"refundableAmount": 0,
"openInfractionProtocol": null,
"externalRef": "pedido-4821",
"callbackUrl": null,
"createdAt": "2026-10-05T14:32:05.123Z",
"paidAt": null,
"refundedAt": null,
"pix": {
"qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4",
"endToEndId": null
},
"customer": {
"name": "Maria Souza",
"document": "52998224725",
"email": "maria.souza@exemplo.com",
"phone": "+5511999998888"
},
"payer": null,
"refunds": []
}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ódigo | HTTP | Mensagem |
|---|---|---|
PAYMENT_DISABLED | 403 | Pagamento desabilitado para esta conta. |
PAYMENT_EXTERNAL_REF_MISMATCH | 409 | Já existe uma cobrança com esta referência, e os dados enviados não conferem com os dela. |
CALLBACK_SECRET_MISSING | 412 | Gere o segredo de callback da conta antes de informar uma callbackUrl. |
PAYMENT_CREATION_IN_FLIGHT | 412 | Uma cobrança com esta referência está sendo criada agora. Repita em instantes. |
PAYMENT_ABOVE_MAXIMUM | 422 | O valor excede o máximo permitido. |
PAYMENT_AMOUNT_NOT_ABOVE_FEE | 422 | O valor da cobrança precisa ser maior que a tarifa de recebimento. |
PAYMENT_BELOW_MINIMUM | 422 | O valor é inferior ao mínimo permitido. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.