跳到主要内容

执行双因素认证批量 Pix 交易

QI Tech 提供通过单次调用执行多笔 Pix 交易的功能。在该系统中，交易以异步方式执行。如果初始调用返回 http status 4xx，则所有交易均不会执行。提交申请后，集成合作伙伴将收到每笔交易的 webhook，告知尝试的最终状态，可能为 rejected 或 sent。

此类交易需要通过发送给贷方账户交易审批人的令牌来确认付款。

配置为使用双因素认证的集成合作伙伴的 Pix 交易申请方式与执行批量 Pix 交易中描述的类似。区别在于添加了 tfa_info 对象（包含账户审批人信息和联系方式），以及成功申请的状态将始终为 pending_2fa_approval。

向审批人发送 token 的通知事件为 baas.token_validation.pix_transfer.batch。可以自定义发送的消息。

请求​

ENDPOINT
/account/ACCOUNT_KEY/pix_transfer_batch
方法
POST
Request Body
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_transfers": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
      "pix_transfer_type": "manual",
      "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"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbrb",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}

Path Params​

字段类型描述字符数
account_keyuuidv4账户的唯一标识键。36

Body Params​

字段类型描述字符数
request_control_key *uuidv4客户端使用的 uuid v4 格式请求唯一标识键。36
pix_transfers *array与批次关联的 pix_transfer 对象列表。列表，见 Objeto pix_transfer
tfa_info*Object包含账户审批人文件和联系方式的对象。Objeto tfa_info

Objeto tfa_info​

字段类型描述
approver_document_number*string账户审批人的文件编号。
contact_type*string与账户审批人的联系方式，可以是 sms 或 email

Objeto pix_transfer​

字段类型描述字符数
request_control_key *uuidv4客户端使用的 uuid v4 格式请求唯一标识键。36
pix_transfer_type *enumerator要执行的 Pix 类型。Enumerador pix_transfer_type
target_pix_keystring接收交易的账户 Pix 键。100
target_accountObject目标账户 - 仅在 pix_transfer_type 为 manual 的转账中发送。Objeto target_account
receiver_conciliation_idstring接收方对账标识。35
transaction_amount *number转账金额。10
end_to_end_idstringSPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 pix_transfer_type 为 key、static_qr_code 或 dynamic_qr_code 时发送。32
pix_messagestring随 Pix 转账一起发送的消息。140

Objeto target_account​

字段类型描述字符数
account_branch *string账户支行。4
account_digit *string账户校验位。1
account_number *string账户号码。20
owner_document_number *string账户持有人的 CPF 或 CNPJ（仅数字）。14
owner_name *string账户持有人姓名。150
account_type*enumerator账户类型。Enumerador account_type
ispb *string基于金融机构 CNPJ 的代码（8位数字）。8

Enumerador account_type​

枚举值描述
checking_account支票账户
salary_account工资账户
saving_account储蓄账户
payment_account支付账户

Enumerador pix_transfer_type​

枚举值描述
manual使用目标账户数据进行 Pix 转账。必须发送 target_account
key使用 Pix 键进行 Pix 转账。必须发送 target_pix_key。如果已执行 Pix 键查询，建议发送 end_to_end_id
static_qr_code使用静态 QR 码进行 Pix 转账。必须发送QR 码解码返回的 end_to_end_id
dynamic_qr_code使用动态 QR 码进行 Pix 转账。必须发送QR 码解码返回的 end_to_end_id

响应​

STATUS
201
Response Body: 批量转账已申请
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "pending_2fa_approval"
}

Enumerador pix_transfer_batch_status​

枚举值描述
approved批量转账已批准，交易正在执行中。
rejected批量转账已拒绝
pending_2fa_approval批量预约待双因素认证审批
STATUS
4xx
Response Body: 转账被拒绝
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "rejected"
    }
  }
}
STATUS
4xx
Response Body: Error
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
信息

之前为 Pix 转账列出的错误以及以下错误也可能由此端点返回。

HTTP 状态码
status		QI 代码
code		标题
title		描述（英文）
description		描述（葡文）
translation
400PXT000168No approver permissionGiven document number does not belong to an approver for this accountNúmero de documento enviado não pertence a um aprovador da conta
400PXT000169tfa_info is requiredClient must send object tfa_infoCliente deve enviar objeto tfa_info
400PXT000170Error occurred while sending tokenAn unexpected error occurred while sending tokenUm erro inexperado ocorreu ao tentar enviar token