跳到主要内容

发起临时 Pix 转账

发起一笔 Pix 转账，消耗该账户已获批临时 Pix 限额，而不触及标准 Pix 限额。该接口会自行解析账户当前有效的临时限额 —— 无需提供 pix_request_key。

请求​

ENDPOINT
/account/ACCOUNT_KEY/exceptional_pix_transfer
方法
POST
警告

仅在 06:00 至 20:00（巴西利亚时间）之间可用。在该窗口之外，即使仍有可用额度，响应也为 PXT000204。

Path Params​

字段类型描述字符数
account_keyuuidv4付款账户的唯一标识键，该账户须拥有已获批的临时 Pix 限额。36
Request Body
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "transaction_amount": 300000.00,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_message": "Pagamento de folha"
}

Body Params​

字段类型描述字符数
pix_transfer_type *enumerator需要发起的 Pix 类型。本接口仅接受 manual。"manual"
transaction_amount *number转账金额。与已交易金额相加后，不得超过已获批的 total_amount。—
target_account *object目标账户数据。参见 对象 target_account。—
request_control_keyuuidv4由合作伙伴定义的请求幂等键。参见 幂等性。36
pix_messagestring随 Pix 转账一并发送的消息。140
信息

本接口不支持通过 Pix 键、静态 QR 码或动态 QR 码转账。对于这些类型，请使用 执行 Pix 交易，它消耗标准 Pix 限额。

对象 target_account​

字段类型描述字符数
account_branch *string目标账户的分行号。4
account_digit *string目标账户的校验位。1
account_number *string目标账户的账号。20
owner_document_number *string目标账户持有人的 CPF 或 CNPJ，仅数字。11 或 14
owner_name *string目标账户持有人的姓名。100
account_type *enumerator目标账户的类型。—
ispb *string目标账户所属机构的 ISPB。8

幂等性​

request_control_key 是请求的幂等键。

重复使用会被拒绝，而不是重放

重复发送已使用过的 request_control_key 时，请求将被拒绝 —— 原转账不会被返回，也不会被重新执行，并且不会消耗任何临时 Pix 额度。请为每笔转账使用新的 key。

响应​

响应状态码取决于为该请求方配置的执行模式，与普通 Pix 转账完全一致：

HTTP 状态码pix_transfer_status含义
201sent转账已同步发送
202pending转账已受理，正在异步处理
202pending_2fa_approval转账等待双因素认证批准
Response Body: 201 Created
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "4f1c8b7a-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
  "transaction_key": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "end_to_end_id": "E32402502202608141530abcdefghijk",
  "pix_transfer_status": "sent",
  "created_at": "2026-08-14 15:30:00"
}

Response Body Params​

字段类型描述
request_control_keyuuidv4请求中提供的幂等键。
pix_transfer_keyuuidv4该 Pix 转账在 QI 系统中的唯一标识键。
transaction_keyuuidv4该交易的唯一标识键。
end_to_end_idstring该 Pix 交易在 SPI 内的幂等键。
pix_transfer_statusenumerator转账状态。
created_atstring转账创建的日期与时间。
信息

临时 Pix 限额在本次调用时、执行之前即被预留，若转账被拒绝则会释放。在异步与 2FA 模式下，预留会贯穿整个处理过程 —— 转账处于待处理状态期间，额度保持预留。

错误​

临时 Pix 的专属错误列于 Temporary Pix 错误表。本操作可能返回 PXT000201、PXT000203 和 PXT000204。

除此之外，普通 Pix 转账的所有错误同样适用 —— 参见 执行 Pix 交易。