Webhooks

由于转账以异步方式进行，正确映射和处理发送的 webhooks 至关重要。

注意！

QI Tech 的 webhooks 不应以限制性方式映射。 我们 API 返回的 webhook 载荷中可能会添加额外字段。

待处理交易的 Webhook

此 Webhook 用于更新在 Pix 发送请求中处于待处理状态（状态 202）的转账状态。

Webhook Request Body

Request Body: 已发送交易

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}

Request Body: 已拒绝交易

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "rejected",
    "created_at": "2021-10-22T20:30:23.459Z",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}

Webhook Body Param

字段	类型	描述	最大字符数
webhook_type	string	定义报告事件类型的枚举值	23
webhook_datetime	string	Webhook 发送日期和时间	20
request_control_key	string	用于查询已发起请求的 UUID4。	36
pix_transfer_key	string	QI 系统中 Pix 转账的标识键	36
pix_transfer_status	string	交易状态。	200
created_at	string	交易创建日期和时间。	20
error_code	string	交易发生的错误代码	20
error_description	string	英文错误描述	200
error_translation	string	翻译为葡萄牙语的错误描述	200
error_short_description	string	错误简短描述	100

入账 Pix 的 Webhook

此 Webhook 用于通知账户收到的 Pix 交易。

Webhook Request Body

Request Body: 已收到 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}

Request Body: 人工审核中的 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "in_manual_analysis",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}

Request Body: 被审核拒绝的 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "rejected_by_analysis",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message",
    "error_code": "PXT000194",
    "error_description": "Incoming pix transfer rejected by manual analysis",
    "error_translation": "Transferência de Pix de entrada rejeitada pela análise manual",
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}

预防性冻结

收到 Pix 时，可能会被预防性冻结。在这种情况下，目标账户不会有任何资金入账，并向客户发送状态为 in_manual_analysis 的 webhook。Pix 将在最多 72 小时内经过人工审核。审核完成后，入账将被接受或拒绝，入账 Pix 将分别进入 received 状态（此时资金将记入客户账户）或 rejected_by_analysis 状态。

Webhook Body Param

字段	类型	描述	最大字符数
webhook_type	string	定义报告事件类型的枚举值	23
webhook_datetime	string	Webhook 发送日期和时间	20
pix_transfer_type	enumerator	执行的 Pix 类型	Enumerador pix_transfer_type
target_pix_key	string	接收交易的账户 Pix 键	100
source_account	Object	来源账户 - 仅在"manual"类型的交易中发送	Objeto source_account
transfer_amount	number	转账金额	10
receiver_conciliation_id	string	接收方对账标识	35
end_to_end_id	string	Pix 交易的幂等键 - 仅当转账类型为 "key" 时发送	32
pix_message	string	随 Pix 转账一起发送的消息	140
fee_amount	number	转账金额	10
pix_transfer_status	string	Pix 交易状态	10
account_key	string	QI 账户的唯一标识键	36
pix_transfer_key	string	Pix 转账的唯一标识键	36
error_code	string	交易发生的错误代码	20
error_description	string	英文错误描述	200
error_translation	string	翻译为葡萄牙语的错误描述	200
error_short_description	string	错误简短描述	100

Enumerador pix_transfer_type

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 键的 Pix
static_qr_code	使用静态 QR 码的 Pix
dynamic_qr_code	使用动态 QR 码的 Pix
reversal	Pix 退款

Objeto source_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

Enumerador account_type

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

Pix 退款的 Webhook

此 Webhook 用于通知账户收到的 Pix 退款。

Webhook Request Body

Request Body: 已收到 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "D18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494",
    "original_end_to_end_id": "E18236120202308111235s14fddf2801"
  }
}

Webhook Body Param

字段	类型	描述	最大字符数
webhook_type	string	定义报告事件类型的枚举值	23
webhook_datetime	string	Webhook 发送日期和时间	20
pix_transfer_type	enumerator	执行的 Pix 类型	Enumerador pix_transfer_type
target_pix_key	string	接收交易的账户 Pix 键	100
source_account	Object	来源账户 - 仅在"manual"类型的交易中发送	Objeto source_account
transfer_amount	number	转账金额	10
receiver_conciliation_id	string	接收方对账标识	35
end_to_end_id	string	Pix 交易的幂等键 - 仅当转账类型为 "key" 时发送	32
pix_message	string	随 Pix 转账一起发送的消息	140
fee_amount	number	转账金额	10
pix_transfer_status	string	Pix 交易状态	10
account_key	string	QI 账户的唯一标识键	36
pix_transfer_key	string	Pix 转账的唯一标识键	36
original_outgoing_pix_transfer	string	原始出账 Pix 转账的唯一标识键	36
original_end_to_end_id	string	原始出账 Pix 转账的 end to end ID	36
error_code	string	交易发生的错误代码	20
error_description	string	英文错误描述	200
error_translation	string	翻译为葡萄牙语的错误描述	200
error_short_description	string	错误简短描述	100

Enumerador pix_transfer_type

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 键的 Pix
static_qr_code	使用静态 QR 码的 Pix
dynamic_qr_code	使用动态 QR 码的 Pix
reversal	Pix 退款

Objeto source_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

Enumerador account_type

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