Criar uma cobrança Pix
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
| Campo | Obrigatório | Descrição |
|---|---|---|
amount | sim | Valor em centavos, a partir de 100. Os limites mínimo e máximo da sua conta também valem. |
externalId | sim | Identificador do pedido no seu sistema, com até 45 caracteres. |
paymentType | sim | pix. |
customer.name | sim | Nome do comprador, só com letras e espaços, até 120 caracteres. |
customer.identity | não | CPF ou CNPJ do comprador, só números. Envie junto com o identityType. |
customer.identityType | não | CPF ou CNPJ. |
customer.email | não | E-mail do comprador. |
postbackUrl | não | URL que recebe os postbacks desta cobrança. |
pixPayment.expiresIn | não | Validade do QR Code em segundos, de 60 a 7200. O padrão é 3600, uma hora. |
cart | não | Itens do pedido, cada um com name, quantity, sku e unitPrice (em centavos). |
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 }
}'{
"id": "0b9c4e2a-6f1d-4c8e-9a37-2d5e8f1a4b6c",
"externalId": "pedido-1235",
"postbackUrl": "https://seusite.com.br/webhooks/payzu",
"amount": 10000,
"paymentType": "pix",
"customer": {
"name": "Maria Souza",
"identity": "11144477735",
"identityType": "CPF",
"email": null,
"birthdate": null,
"phone": null,
"address": null
},
"cart": [],
"creditCardPayment": null,
"pixPayment": {
"status": "pending",
"qrCode": "00020101021226800014br.gov.bcb.pix2558pix.example.com/qr/v2/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865802BR5912LOJA EXEMPLO6009SAO PAULO62070503***6304D233",
"expiresAt": "2026-06-12T17:02:10.000Z",
"paidAt": null,
"canceledAt": null,
"endToEndId": null,
"refunds": []
},
"recurrence": null,
"recurrenceCycle": null,
"createdAt": "2026-06-12T16:02:10.000Z",
"updatedAt": "2026-06-12T16:02:10.000Z"
}// npm i undici
import { readFileSync } from 'node:fs'
import { Agent, fetch } from 'undici'
const agent = new Agent({
connect: {
cert: readFileSync(process.env.PAYZU_CLIENT_CERT),
key: readFileSync(process.env.PAYZU_CLIENT_KEY)
}
})
const response = await fetch('https://api.sandbox.payzu.dev/v1/charges', {
method: 'POST',
dispatcher: agent,
headers: {
authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'content-type': 'application/json'
},
body: JSON.stringify({
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 }
})
})
const charge = await response.json()
if (!response.ok) throw new Error(`${charge.statusCode}: ${charge.message}`)
console.log(charge.id, charge.pixPayment.status, charge.pixPayment.qrCode)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ódigo | HTTP | Mensagem |
|---|---|---|
PZ010 | 403 | Produto não habilitado |
PZ101 | 422 | Valor mínimo por cobrança não atingido |
PZ102 | 422 | Valor máximo por cobrança excedido |
PZ103 | 422 | Conta sem limites de cobrança configurados |
PZ105 | 422 | Provedor de pagamento desabilitado |
PZ108 | 422 | Configuração de pagamento da conta incompleta |
PZ300 | 422 | Pix não disponível para esta conta |
PZ301 | 422 | Recorrência não disponível para Pix |
PZ700 | 422 | Conta sem configuração de taxas definidas para este meio de pagamento |
PZ900 | 422 | O provedor de pagamento recusou a operação |
PZ109 | 502 | Nã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. |
PZ901 | 503 | Nã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.