Primeiros passos
Criar conta
Abra sua conta em abrirconta.saq.com.br. Após aprovação você recebe:
- Bearer token, usado em todas as requisições. Ver Autenticação.
- Base URL,
https://api.saq.processamento.com/v1.
Guarde o token em vault (Google Secret Manager, AWS Secrets, etc). Nunca commite em repositório nem exponha no front-end.
Testar autenticação
Para confirmar que o token funciona, consulte o saldo da conta usando o endpoint GET /user/balance.
curl https://api.saq.processamento.com/v1/user/balance \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json"const res = await fetch('https://api.saq.processamento.com/v1/user/balance', {
headers: {
Authorization: `Bearer ${process.env.SAQ_TOKEN}`,
'Content-Type': 'application/json',
},
});
const balance = await res.json();Se voltar o JSON com o saldo, está autenticado. Se retornar 401, revise o token (espaço, encoding) ou contate o suporte. Ver códigos HTTP no glossário.
Criar a primeira cobrança Pix
Crie uma cobrança via POST /pix. Schema completo na referência.
curl -X POST https://api.saq.processamento.com/v1/pix \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/saq",
"clientReference": "pedido-2025-001"
}'const res = await fetch('https://api.saq.processamento.com/v1/pix', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SAQ_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 10.90,
generatedName: 'João da Silva',
generatedDocument: '12345678909',
callbackUrl: 'https://seusite.com.br/webhooks/saq',
clientReference: 'pedido-2025-001',
}),
});
const charge = await res.json();A resposta traz qrCodeText (copia-e-cola), qrCodeUrl e o id da transação. Cada campo está explicado no glossário.
Valores estão sempre em reais (BRL), não em centavos. 10.90 é R$ 10,90.
Receber o callback
Quando o pagador concluir o Pix, a Saq envia um POST para a callbackUrl informada com o objeto da transação atualizado (status: "COMPLETED"). Responda com 2xx em até 5 segundos.
POST /webhooks/saq
Content-Type: application/json
{
"id": "SAQ20251123104518DF75D20A8F",
"status": "COMPLETED",
"amount": 10.90,
"clientReference": "pedido-2025-001",
"endToEndId": "E18236120202511231046s1235ee7",
"paidAt": "2025-11-23T10:46:26.986Z"
}Detalhes de retry, payload completo e segurança em Webhooks. Se quiser inspecionar ou reenviar manualmente, use GET /user/callbacks.
Conceitos
Antes de fazer a primeira chamada, vale entender o que a API cobre, como os endpoints são agrupados e o que representa uma transação na Saq. Esta página é o mapa mental que você vai usar em todas as outras.
Autenticação
Toda chamada à Saq usa Bearer token. Esta página mostra como enviar, onde guardar com segurança e o que fazer quando aparecer um 401 ou 403. Token é como senha, trata como tal.