接收 Pix 付款
生成收款单
endpoint:POST /pix。仅 amount 为必填项;其他字段用于丰富 QR 和对账信息。
curl -X POST https://api.saq.processamento.com/v1/pix \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 99.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/saq",
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"expiresIn": 600
}'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: 99.90,
generatedName: 'João da Silva',
generatedDocument: '12345678909',
callbackUrl: 'https://seusite.com.br/webhooks/saq',
clientReference: 'pedido-2025-001',
virtualAccount: 'loja-rj-01',
expiresIn: 600,
}),
});
const charge = await res.json();import os, requests
res = requests.post(
'https://api.saq.processamento.com/v1/pix',
headers={
'Authorization': f'Bearer {os.environ["SAQ_TOKEN"]}',
'Content-Type': 'application/json',
},
json={
'amount': 99.90,
'generatedName': 'João da Silva',
'generatedDocument': '12345678909',
'callbackUrl': 'https://seusite.com.br/webhooks/saq',
'clientReference': 'pedido-2025-001',
'virtualAccount': 'loja-rj-01',
'expiresIn': 600,
},
)
charge = res.json()body := strings.NewReader(`{
"amount": 99.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/saq",
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"expiresIn": 600
}`)
req, _ := http.NewRequest("POST", "https://api.saq.processamento.com/v1/pix", body)
req.Header.Set("Authorization", "Bearer " + os.Getenv("SAQ_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)<?php
$ch = curl_init('https://api.saq.processamento.com/v1/pix');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SAQ_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 99.90,
'generatedName' => 'João da Silva',
'generatedDocument' => '12345678909',
'callbackUrl' => 'https://seusite.com.br/webhooks/saq',
'clientReference' => 'pedido-2025-001',
'virtualAccount' => 'loja-rj-01',
'expiresIn' => 600,
]),
]);
$charge = json_decode(curl_exec($ch), true);响应:
{
"id": "SAQ20250817215911F49RDOBJ",
"status": "PENDING",
"amount": 99.90,
"qrCodeText": "00020126870014br.gov.bcb.pix...",
"qrCodeUrl": "https://api.saq.processamento.com/v1/pix/qr-code/SAQ20250817215911F49RDOBJ",
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"expiresAt": "2025-08-17T22:00:00.000Z"
}向客户展示 QR Code
两种方式:
直接图片,在 <img> 中使用 qrCodeUrl:
<img src="https://api.saq.processamento.com/v1/pix/qr-code/SAQ2025..." />复制粘贴,将 qrCodeText 显示在带按钮的 input 中:
<input value="00020126870014br.gov.bcb.pix2565..." readonly />
<button onclick="navigator.clipboard.writeText(qrCodeText)">复制</button>Saq 只生成动态 QR。不支持静态 QR。
在付款时接收 callback
当客户完成 Pix 付款后,Saq 将向您的 callbackUrl 发送 POST:
{
"id": "SAQ20250817215911F49RDOBJ",
"type": "DEPOSIT",
"status": "COMPLETED",
"amount": 99.90,
"clientReference": "pedido-2025-001",
"virtualAccount": "loja-rj-01",
"endToEndId": "E60746948202508172200X7H4K2P9M5",
"paidAt": "2025-08-17T22:00:12.000Z"
}处理器示例:
import express from 'express';
const app = express();
app.post('/webhooks/saq', express.json(), async (req, res) => {
const tx = req.body;
if (await isProcessed(tx.id, tx.status)) return res.status(200).end();
if (tx.type === 'DEPOSIT' && tx.status === 'COMPLETED') {
await markOrderPaid(tx.clientReference, tx);
}
res.status(204).end();
});from flask import Flask, request
app = Flask(__name__)
@app.post('/webhooks/saq')
def saq_webhook():
tx = request.get_json()
if is_processed(tx['id'], tx['status']):
return '', 200
if tx['type'] == 'DEPOSIT' and tx['status'] == 'COMPLETED':
mark_order_paid(tx['clientReference'], tx)
return '', 204http.HandleFunc("/webhooks/saq", func(w http.ResponseWriter, r *http.Request) {
var tx Transaction
if err := json.NewDecoder(r.Body).Decode(&tx); err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if isProcessed(tx.ID, tx.Status) {
w.WriteHeader(http.StatusOK)
return
}
if tx.Type == "DEPOSIT" && tx.Status == "COMPLETED" {
markOrderPaid(tx.ClientReference, tx)
}
w.WriteHeader(http.StatusNoContent)
})<?php
$tx = json_decode(file_get_contents('php://input'), true);
if (isProcessed($tx['id'], $tx['status'])) {
http_response_code(200);
exit;
}
if ($tx['type'] === 'DEPOSIT' && $tx['status'] === 'COMPLETED') {
markOrderPaid($tx['clientReference'], $tx);
}
http_response_code(204);请在 5 秒内以 2xx 响应。否则,Saq 将启动重试(最多 72 次,采用指数退避)。详情请见 Webhooks。
通过 polling 后备查询
如果 callback 未送达,可直接通过 GET /pix 查询。接受 id、clientReference、endToEndId 或 virtualAccount,仅使用其中一个。
curl "https://api.saq.processamento.com/v1/pix?clientReference=pedido-2025-001" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"const res = await fetch(
`https://api.saq.processamento.com/v1/pix?clientReference=pedido-2025-001`,
{
headers: {
Authorization: `Bearer ${process.env.SAQ_TOKEN}`,
'Content-Type': 'application/json',
},
},
);
const charge = await res.json();res = requests.get(
'https://api.saq.processamento.com/v1/pix',
params={'clientReference': 'pedido-2025-001'},
headers={
'Authorization': f'Bearer {os.environ["SAQ_TOKEN"]}',
'Content-Type': 'application/json',
},
)polling 应作为后备方案。请将 callback 配置为主要来源。
凭证
付款完成后,通过 GET /proof/{id} 下载官方凭证:
curl "https://api.saq.processamento.com/v1/proof/SAQ20250817215911F49RDOBJ" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"Tutoriais
Fluxos reais de produção combinando os endpoints da Saq, desde receber um Pix simples até lidar com uma disputa MED. Cada tutorial tem código pronto em curl, Node, Python, Go e PHP.
Enviar Pix
Dois caminhos para enviar Pix da sua conta Saq para um destinatário externo. Saque por chave Pix (com validação DICT) ou pagar QR Code. Inclui acompanhamento de status e download de comprovante.