申请批量 Pix 交易预约（双因素认证）

QI Tech 提供通过单次调用执行多个 Pix 定期交易的功能。在此系统中，预约以异步方式进行。如果初始调用返回 http status 4xx，则不会执行任何预约。申请后，集成合作伙伴将针对创建时被拒绝的每个 pix_schedule 收到一个 webhook。

此类预约需要通过向贷方账户中具有交易审批权限的人员发送令牌来确认付款计划。

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

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

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_schedule_batch

MÉTODO

POST

通过邮件和短信进行身份验证

Request Body: 通过短信或邮件进行 TFA 的批量预约

{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_schedules": [
    {
      "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",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "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",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}

通过设备进行身份验证

除了现有的 sms 和 email 身份验证方式外，还可以使用预先注册的设备对交易进行身份验证。在这种情况下，需要从 Device Scan 中获取 session_id 并在 tfa_info 中发送。

Request Body: 通过设备进行 TFA 的批量预约

{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "pix_schedules": [
    {
      "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",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "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",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}

Path Params

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

Body Params

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

Objeto tfa_info

字段	类型	描述	字符数
`approver_document_number` *	string	账户审批人的文件编号。	11
`session_id`	string	设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。	36
`contact_type` *	string	与账户审批人的联系方式，可以是 sms、email 或 device

Objeto pix_schedule

字段	类型	描述	字符数
`request_control_key`*	uuidv4	客户使用的请求唯一标识键，uuid v4 格式。	36
`pix_transfer_type`*	enumerator	Pix 转账类型。	Enumerador pix_transfer_type
`target_pix_key`	string	目标账户的 Pix 密钥。	100
`receiver_conciliation_id`	string	收款方对账标识。	35
`target_account` *	Object	目标账户 - 仅在 `pix_transfer_type` 为 manual 时发送。	Objeto target_account
`transaction_amount`*	number	转账金额。	10
`end_to_end_id`	string	SPI（即时支付系统）内 Pix 交易的幂等键。此键在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 key、static_qr_code 或 static_qr_code 时发送。	32
`pix_message`	string	随 Pix 转账发送的消息。	140

Objeto target_account

字段	类型	描述	字符数
`account_branch` *	string	账户机构编号。	6
`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	金融机构 8 位识别码（ISPB）。	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 Code 的 Pix。必须发送 QR code 解码返回的 `end_to_end_id`
dynamic_qr_code	使用动态 QR Code 的 Pix。必须发送 QR code 解码返回的 `end_to_end_id`

Response

STATUS

202

Response Body: 批量预约已批准

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
} 

Enumerador schedule_batch_status

枚举值	描述
created	批量预约已创建
approved	批量预约已批准
rejected	批量预约已拒绝
pending_2fa_approval	批量预约待双因素认证批准

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP 代码 `status`	QI 代码 `code`	标题 `title`	描述（英文） `description`	描述（葡文） `translation`
400	QIT000001	Bad Request	schema error description	Schema Inválido
404	PSC000001	Account not Found	Account was not found	Conta não encontrada
406	PSC000002	Invalid Uuid	key was not accepted for not being a valid uuid v4 string	key não foi aceito por não ser uma palavra uuid v4 válida
400	PSC000003	Bad Request	pix_message can not be longer than 140 characters	pix_message não pode ser maior que 140 caracteres
400	PSC000004	Bad Request	Emoji not allowed in pix message	Emoji não é permitido na mensagem pix
406	PSC000005	Invalid Transaction Amount	Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places	O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais
406	PSC000006	Invalid end_to_end_id	The end_to_end_id sent end_to_end_id is not valid	O end_to_end_id enviado end_to_end_id não é válido
400	PSC000007	Invalid date format	Dates must be sent using format YYYY-MM-DD	Datas devem ser enviadas no formato YYYY-MM-DD
400	PSC000008	Invalid Schedule Date	Schedule date must be after current date for UTC-3	Data de agendamento deve ser após a data atual em UTC-3
400	PSC000009	Account is Closed	Account is closed	Conta está fechada
400	PSC000010	Account is Blocked	Account is blocked	Conta está bloqueada
422	PSC000011	Invalid Account Type	Pix is not yet implemented for non-checking or non-escrow account types	Transações Pix não estão implementadas para conta que não sejam escrow ou livres
403	PSC000012	User is not allowed to do this transaction	User is not allowed to do this transaction	Usuário não tem autorização para fazer essa transação
400	PSC000013	Bad Request	For Manual Pix Transfer Type a target account must be provided	Para transação pix do tipo manual, uma conta destino deve ser fornecida
404	PSC000014	Inquiry Not Found	Pix key inquiry was not found	Pesquisa de chave pix não encontrada
400	PSC000015	Bad Request	Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct	Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto
404	PSC000016	Account not found	Nonexistent account in destination financial institution	Conta inexistente na instituição financeira de destino
400	PSC000017	Target Account and Source Account must be different	Target Account must not be the same as Source Account	A conta de destino não pode ser a mesma da conta de origem
409	PSC000018	Bad Request	request_control_key request_control_key already in use	request_control_key request_control_key já utilizada
400	PSC000019	Invalid Target	Account does not have permission to transfer to the given target account	A conta não possui permissão para realizar transferências para a conta enviada
404	PSC000020	Decode Inquiry Not Found	QR Code decode inquiry not found	Pesquisa e decodificação de QR code não encontrada
400	PSC000021	Bad Request	Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct	Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto
400	PSC000022	Bad Request	Dynamic Instant QR codes cannot be scheduled for payment	Pagamentos de vencimento instantâneo não podem ter pagamento agendado
400	PSC000023	Bad Request	Schedule Date sent is after max payment date for target qr code	Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado
400	PSC000024	Bad Request	Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct	Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto
400	PSC000040	Empty pix-schedule list received	A list of pix schedules must be provided	Uma lista de agendamentos pix deve ser fornecida
409	PSC000041	Bad Request	One or more request_control_key already in use	Uma ou mais request_control_key já está sendo utilizada
403	PSC000045	Requester not allowed to access this endpoint	Requester has no permission to perform pix transfers on this endpoint	Requester não possui permissão de realizar transações pix através deste endpoint

Request​

通过邮件和短信进行身份验证​

通过设备进行身份验证​

Path Params​

Body Params​

Objeto tfa_info​

Objeto pix_schedule​

Objeto target_account​

Enumerador account_type​

Enumerador pix_transfer_type​

Response​

Enumerador schedule_batch_status​