Primeiros passos
Crie a sua primeira cobrança Pix no sandbox com um token da sua credencial.
Obtenha a credencial
A chamada do token usa o client_id e o client_secret de uma credencial da sua conta no PayZu Conta Hub. Guarde o client_secret fora do código, numa variável de ambiente ou num cofre de segredos. Quando a credencial tem lista de IPs, chame de um IP dela, inclusive na troca do token.
Sandbox e produção têm os mesmos caminhos.
Teste em https://api.sandbox.payzu.dev/api/v1. Em produção, o servidor é https://api.hub.payzu.com.br/api/v1.
Peça o token
Envie client_id:client_secret em Authorization: Basic, em base64, e grant_type=client_credentials no corpo. O token vem em access_token e vale 15 minutos.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/oauth/token' \
--user 'SEU_CLIENT_ID:SEU_CLIENT_SECRET' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials'{
"access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl",
"token_type": "Bearer",
"expires_in": 900
}Referência: Gerar um token de acesso
Nas rotas de /transactions, mande o token no cabeçalho Authorization: Bearer SEU_TOKEN. Reutilize o mesmo token até perto de vencer e só então peça outro: a rota limita as trocas por client_id e por IP.
Crie a primeira cobrança
| Campo | Regra |
|---|---|
amount | Valor em centavos. |
method | PIX. |
customer | Nome e CPF ou CNPJ. E-mail e telefone são opcionais. |
externalRef | O seu identificador. Repetir a mesma chamada retorna a cobrança já criada. |
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"
}
}'{
"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
pix.qrCodeText: o copia e cola, de onde você desenha o QR Code.status: a cobrança nascePENDING.serviceFee: a tarifa que será descontada quando a cobrança for paga.netAmount: o que vai entrar no saldo.id: guarde para consultar a cobrança e baixar o comprovante.
Para testar sem escrever código, abra a rota na referência, cole o token e use o Try It!: a resposta aparece ao lado da requisição.