接口端点
PIX 转账
概述
POST /dict/pix 接口端点向指定密钥发起 PIX 转账。密钥可以是 CPF、CNPJ、邮箱、手机号或 EVP（随机密钥）。
此端点遵循中央银行关于通过 DICT（交易账户标识目录）进行 PIX 转账的规范。
接口端点
POST /dict/pix身份认证
通过 /oauth/token 获取的 Bearer 令牌。
用于幂等性支持的唯一请求标识符。必须为 UUID v4。
示例：550e8400-e29b-41d4-a716-446655440000
请求体
目标 PIX 密钥。可以是：
- CPF：11 位数字
- CNPJ：14 位数字
- 邮箱：有效的邮箱地址
- 手机号：+55区号号码（例如 +5511999999999）
- EVP：随机密钥（UUID）
收款人证件号（CPF 或 CNPJ）。当 priority = HIGH 时必填，用于即时验证。
处理优先级：
HIGH：即时处理（需要creditorDocument）NORM：标准队列处理
PIX 转账附带的消息。将显示给收款人。
付款流程（可选）。用于内部分类。
操作在队列中等待的最长时间（秒），超时将被取消。
- 最小值：1 秒
- 最大值：10800 秒（3 小时）
- 默认值：600 秒（10 分钟）
付款数据。
不允许付款的 ISPB 代码列表。用于阻止向特定机构的转账。
示例：["12345678", "87654321"]
请求
curl -X POST https://api.safirapay.com/dict/pix \
-H "Authorization: Bearer <token>" \
-H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"pixKey": "12345678909",
"creditorDocument": "12345678909",
"priority": "NORM",
"description": "Pagamento referente a NF 12345",
"expiration": 600,
"payment": {
"currency": "BRL",
"amount": 100.50
}
}'const response = await fetch('https://api.safirapay.com/dict/pix', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'x-idempotency-key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
pixKey: '12345678909',
creditorDocument: '12345678909',
priority: 'NORM',
description: 'Pagamento referente a NF 12345',
expiration: 600,
payment: {
currency: 'BRL',
amount: 100.50,
},
}),
});
const transfer = await response.json();import requests
import uuid
response = requests.post(
'https://api.safirapay.com/dict/pix',
headers={
'Authorization': f'Bearer {token}',
'x-idempotency-key': str(uuid.uuid4()),
'Content-Type': 'application/json',
},
json={
'pixKey': '12345678909',
'creditorDocument': '12345678909',
'priority': 'NORM',
'description': 'Pagamento referente a NF 12345',
'expiration': 600,
'payment': {
'currency': 'BRL',
'amount': 100.50,
},
}
)
transfer = response.json()响应
{
"endToEndId": "550e8400-e29b-41d4-a716-446655440000",
"eventDate": "2024-01-15T10:30:00.000Z",
"id": 12345,
"payment": {
"amount": 100.50
},
"type": "PENDING"
}{
"statusCode": 400,
"message": "Chave PIX inválida",
"error": "Bad Request"
}{
"statusCode": 422,
"message": "Chave PIX não encontrada no DICT",
"error": "Unprocessable Entity"
}响应字段
endToEndIdstringPIX 交易的唯一标识符。交易结算时，实际的 E2E 值将在 Webhook 中发送。
eventDatestring事件日期和时间（ISO 8601）。
idnumber交易的唯一标识符。
paymentobjecttypestring交易类型/状态：
PENDING：转账正在处理中COMPLETED：转账完成ERROR：转账失败
幂等性
x-idempotency-key 请求头确保相同的请求不会被重复处理：
// 相同的幂等键 = 相同的响应
const key = '550e8400-e29b-41d4-a716-446655440000';
// 第一次调用 - 创建转账
const res1 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' }
// 使用相同键的第二次调用 - 返回相同的转账
const res2 = await createTransfer(key, { amount: 100 });
// { id: 123, type: 'PENDING' }（不会创建新的）x-idempotency-key 是必填的。不包含此请求头的请求将被拒绝。
转账 Webhook
当转账处理完成时，您将收到一个类型为 TRANSFER 的 V2 Webhook：
{
"type": "TRANSFER",
"data": {
"id": 12345,
"txId": null,
"pixKey": "12345678909",
"status": "LIQUIDATED",
"payment": {
"amount": "100.50",
"currency": "BRL"
},
"endToEndId": "E12345678901234567890123456789012",
"creditDebitType": "DEBIT",
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"creditorAccount": {
"name": "João Silva",
"document": "123.xxx.xxx-xx",
"ispb": "18236120"
},
"remittanceInformation": "Pagamento referente a NF 12345"
}
}TRANSFER Webhooks
查看完整的 TRANSFER Webhook 文档
PIX 密钥类型
| 类型 | 格式 | 示例 |
|---|---|---|
| CPF | 11 位数字 | 12345678909 |
| CNPJ | 14 位数字 | 12345678000195 |
| 邮箱 | 有效邮箱 | joao@email.com |
| 手机号 | +55区号号码 | +5511999999999 |
| EVP | UUID | 7d9f0335-8dcc-4054-9bf9-0dbd61d36906 |
处理优先级
ISPB 黑名单
使用 ispbDeny 阻止向特定机构的转账：
{
"pixKey": "joao@email.com",
"payment": { "amount": 100.00 },
"ispbDeny": [
"12345678",
"87654321"
]
}如果 PIX 密钥属于被屏蔽的机构，转账将被拒绝。
常见错误
| 状态码 | 错误 | 解决方案 |
|---|---|---|
| 400 | PIX 密钥无效 | 检查密钥格式 |
| 400 | 金额无效 | 使用最多 2 位小数的数值 |
| 400 | 缺少幂等键 | 包含 x-idempotency-key 请求头 |
| 401 | 令牌无效 | 续期访问令牌 |
| 422 | 未找到密钥 | 该密钥在 DICT 中不存在 |
| 422 | 余额不足 | 检查可用余额 |
| 422 | ISPB 被屏蔽 | 该机构在 ispbDeny 列表中 |