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 | 支付账户 |