Token
Troque o client_id e o client_secret da conta por um token em POST /token e envie esse token em toda chamada.
Peça o token
Mande client_id:client_secret em Authorization: Basic, em base64, e grant_type igual a client_credentials no corpo. Nenhum outro valor de grant_type é aceito.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/v1/token' \
--user "$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET" \
--cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY" \
--header 'Content-Type: application/json' \
--data '{ "grant_type": "client_credentials" }'{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}// npm i undici
import { readFileSync } from 'node:fs'
import { Agent, fetch } from 'undici'
// O certificado entra pelo Agent; use o fetch do mesmo pacote.
const agent = new Agent({
connect: {
cert: readFileSync(process.env.PAYZU_CLIENT_CERT),
key: readFileSync(process.env.PAYZU_CLIENT_KEY)
}
})
const basic = Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64')
const response = await fetch('https://api.sandbox.payzu.dev/v1/token', {
method: 'POST',
dispatcher: agent,
headers: { authorization: `Basic ${basic}`, 'content-type': 'application/json' },
body: JSON.stringify({ grant_type: 'client_credentials' })
})
const token = await response.json()
if (!response.ok) throw new Error(`${token.statusCode}: ${token.message}`)
console.log(token.access_token, token.expires_in)Referência: Gerar um token de acesso
Nas rotas de cobrança, envie Authorization: Bearer com o access_token e mantenha o mesmo certificado na conexão.
O exemplo em Node.js usa o pacote undici.
O fetch global do Node.js não recebe certificado de cliente. Com a exigência do certificado desligada na credencial, tire o --cert/--key do cURL e, no Node.js, o Agent, com a leitura dos arquivos PEM, e o dispatcher.
Validade e renovação
A validade vem em expires_in, em segundos. Programe a renovação pelo valor recebido, não por um número fixo: peça um token por processo, reutilize-o e peça outro pouco antes de vencer.
Certificado e credencial
- Padrão: a credencial exige o certificado de cliente na conexão, já no
POST /token. - Exigência desligada: a PayZu pode desligar a exigência na sua credencial, e aí o
POST /tokene as rotas aceitam a chamada sem certificado. - Dono do certificado: o certificado é emitido para a sua credencial, e o nome (CN) dele é o próprio
client_id. Se a chamada apresenta um certificado, com a exigência ligada ou desligada, oclient_iddo Basic ou do token precisa ser o mesmo dele. - Validade: 365 dias a partir da emissão.
- IP de origem: o PayZu Payments não confere. Quem identifica a sua aplicação é o token e, quando a credencial exige, o certificado.
Como enviar o certificado no cURL, no Node.js e em outras linguagens está em Certificado mTLS.
Erros de autenticação
Os erros de autenticação ainda saem sem code; decida pelo status e pela mensagem.
| Código | HTTP | Mensagem |
|---|---|---|
| - | 400 | Basic token não definido. |
| - | 400 | grant_type não informado |
| - | 400 | grant type não suportado |
| - | 401 | Unauthorized |
| - | 401 | Não foi possível verificar o certificado. |
| - | 401 | Certificado não pertence ao usuário autenticado. |
| - | 401 | Token inválido ou expirado. |
| - | 403 | Não foi possível concluir sua solicitação |
Todos os códigos do PayZu Payments estão no Catálogo de erros.