# QI Tech — Risk Solutions › 银行反欺诈 Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 13 página(s). Índice: - Boleto (/zh-Hans/documentation/caas/banking/bankslips) - 账单支付 (/zh-Hans/documentation/caas/banking/bill_payments) - 存款 (/zh-Hans/documentation/caas/banking/deposits/introduction) - HTTP 状态码 (/zh-Hans/documentation/caas/banking/http_status) - 简介 (/zh-Hans/documentation/caas/banking/introduction) - 共享对象 (/zh-Hans/documentation/caas/banking/objects) - PIX Dict Operation (/zh-Hans/documentation/caas/banking/pix_dict_operations) - PIX Infraction Report (/zh-Hans/documentation/caas/banking/pix_infraction_reports) - PIX Transaction (/zh-Hans/documentation/caas/banking/pix_transactions) - 标准 (/zh-Hans/documentation/caas/banking/standards) - Webhook (/zh-Hans/documentation/caas/banking/webhook) - 转账 (/zh-Hans/documentation/caas/banking/wire_transfers) - 取款 (/zh-Hans/documentation/caas/banking/withdrawals) --- # Boleto URL: /zh-Hans/documentation/caas/banking/bankslips 当用户执行或接收 Boleto 支付时，支付数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。 ## Boleto 对象定义 Request Body ```json { "id": "082373263", "bankslip_direction": "received", "document_amount": 13725, "discount_amount": 1000, "other_deduction_amount": 0, "interest_amount": 254, "amount": 12979, "bankslip_payment_date": "2020-10-07T15:06:25-03:00", "bankslip_due_date": "2020-10-07", "bankslip_issuing_date": "2020-10-07", "description": "BOLETO PARA PAGAMENTO DA MENSALIDADE DE SETEMBRO", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "payer": { "id": "182373263", "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA.", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "email": "mailto@qitech.com.br", "account": { "participant": "60701190", "branch": "3675", "account_number": "13212", "account_digit": "5", "account_type": "CACC" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "recipient": { "id": "282373263", "type": "legal_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "10552", "account_digit": "6", "account_type": "CACC" } }, "final_recipient": { "id": "382373263", "type": "legal_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "10442", "account_digit": "6", "account_type": "CACC" } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.056.098", "session_id": "7839jdqd9a8wd9" } } ``` Boleto 支付必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 支付状态表示模型对该 Boleto 返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此 Boleto 支付。 automatically_reproved | 建议拒绝此 Boleto 支付。 in_manual_analysis | 建议对此 Boleto 支付进行人工分析。 pending | Boleto 支付正在处理中。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中交易的标识符。 **此编号对每个 Boleto 支付必须唯一** bankslip_direction | 枚举 | Boleto 支付方式。定义客户是支付 Boleto 还是接收 Boleto 支付。 document_amount | 整数 | 文件金额（分）——如"标准"部分所述。 discount_amount | 整数 | 对文件金额应用的折扣或减免金额（分）——如"标准"部分所述。 other_deduction_amount | 整数 | 对文件金额应用的其他扣除额（分）——如"标准"部分所述。 interest_amount | 整数 | 对文件金额应用的罚款、滞纳金或利息金额（分）——如"标准"部分所述。 amount | 整数 | Boleto 最终支付金额——如"标准"部分所述。 bankslip_payment_date | datetime | Boleto 支付的日期和时间，含时区。 bankslip_due_date | date | Boleto 到期日期，符合标准格式 description | string | Boleto 的描述或备注字段。 face_recognition_key | string | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。 validation_key | string | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。 payer | *bankslip_payer* | 表示支付 Boleto 的自然人或法人的对象。 recipient | *bankslip_recipient* | 表示 Boleto 受益的自然人或法人的对象。 final_recipient | *bankslip_recipient* | 表示 Boleto 最终受益的自然人或法人的对象。 source | *source* | Source 类型的对象，描述用于 Boleto 支付的应用程序信息。 *bankslip_direction* 的枚举值为：`payed` 和 `received`。 ## 发送 Boleto 支付 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` 要评估 Boleto 支付，只需将 Boleto 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/bankslip/bankslip` ## 查询 Boleto 支付 Response Body ```json { "id": "082373263", "bankslip_direction": "received", ... } ``` 要检索 Boleto 支付数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}` 其中 *bankslip_id* 是发送 Boleto 时在客户系统中使用的交易标识符。 ## 更新 Boleto 支付 Request Body ```json { "bankslip_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "bankslip_status": "completed" } ``` Boleto 支付创建并分析后，将发送到清算中心进行处理。因此，需要在支付发送时通过以下端点通知支付状态更新： `PUT https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}` 这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的 Boleto 支付。 --- # 账单支付 URL: /zh-Hans/documentation/caas/banking/bill_payments 当用户执行账单支付时，支付数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。 ## 账单支付对象定义 Request Body ```json { "id": "082373263", "amount": 12979, "bill_payment_date": "2020-10-07T15:06:25-03:00", "bill_due_date": "2020-10-07", "bill_issuing_date": "2020-10-07", "service_description": "CONTA DE ELETRICIDADE ENEL", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "company": { "id": "451673263", "provided_service": "eletricity", "name" : "Enel", "legal_name": "Eletropaulo Metropolitana Eletricidade de São Paulo S.A.", "document_number": "61.695.227/0001-93", "address": { "street": "Av. Dr. Marcos Penteado de Ulhôa Rodrigues", "number": "939", "neighbourhood": "Sítio Tamboré", "city": "Barueri", "uf": "SP", "complement": "Loja 1 e 2", "postal_code": "06460-040" } }, "payer": { "id": "182373263", "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA.", "email": "gioconda_pizza@bol.com.br", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "13212", "account_digit": "5", "account_type": "CACC" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.105.098", "session_id": "7839jdqd9a8wd9" } } ``` 账单支付必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 支付状态表示模型对该账单返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此账单支付。 automatically_reproved | 建议拒绝此账单支付。 in_manual_analysis | 建议对此账单支付进行人工分析。 pending | 账单支付正在处理中。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中交易的标识符。 **此编号对每个账单支付必须唯一** document_amount | 整数 | 文件金额（分）——如"标准"部分所述。 other_deduction_amount | 整数 | 对文件金额应用的其他扣除额（分）——如"标准"部分所述。 interest_amount | 整数 | 对文件金额应用的罚款、滞纳金或利息金额（分）——如"标准"部分所述。 amount | 整数 | 账单最终支付金额——如"标准"部分所述。 bill_payment_date | datetime | 账单支付的日期和时间，含时区。 bill_due_date | date | 账单到期日期，符合标准格式 description | string | 账单的描述或备注字段。 face_recognition_key | string | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。 validation_key | string | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。 client | *client* | 表示客户数据的对象，无论是执行 Boleto 支付还是接收支付的客户。 company | *company* | 表示该账单对应的特许经营商或服务提供商的对象。 payer | *bill_payer* | 表示支付账单的自然人或法人的对象。 recipient | *bill_client* | 表示账单发出对象的自然人或法人的对象。 source | *source* | Source 类型的对象，描述用于账单支付的应用程序信息。 ## 发送账单支付 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` 要评估账单支付，只需将 BillPayment 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/bill_payment/bill_payment` ## 查询账单支付 Response Body ```json { "id": "082373263", "amount": 12979, ... } ``` 要检索账单支付数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}` 其中 *bill_payment_id* 是发送账单支付时在客户系统中使用的交易标识符。 ## 更新账单支付 Request Body ```json { "bill_payment_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "bill_payment_status": "completed" } ``` 账单支付创建并分析后，将发送到清算中心进行处理。因此，需要在支付发送时通过以下端点通知支付状态更新： `PUT https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}` 这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的支付。 --- # 存款 URL: /zh-Hans/documentation/caas/banking/deposits/introduction 当用户执行存款时，存款数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的欺诈风险和反洗钱风险进行分析。 ## 存款对象定义 Request Body ```json { "id": "082373263", "amount": 12979, "deposit_date": "2020-10-07T15:06:25-03:00", "client": { "id": "182373263", "type": "natural_person", "document_number": "123.456.789-10", "name": "Benedito Calixto de Jesus", "email": "benedito@test.com", "address": { "street": "Rua José Wasth Rodrigues", "number": "243", "neighbourhood": "Vila Maria", "city": "São Paulo", "uf": "SP", "complement": "Apartamento 14B", "postal_code": "02121-010" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "destination_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "terminal": { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" }, "authentication": { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } } ``` 存款必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 存款状态表示模型对该账户返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此存款。 automatically_reproved | 建议拒绝此存款。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中存款的标识符。 **此编号对每笔存款必须唯一** amount | integer | 存款金额（分）——如"标准"部分所述。 deposit_date | datetime | 存款执行的日期和时间——如"标准"部分所述。 client | *client* | 包含来源账户持有人数据的对象。 destination_account | *account* | 确定待存款资金目标账户的对象。 terminal | *terminal* | 包含执行存款的终端数据的对象。 authentication | *authentication* | 包含认证信息的对象。 ## 存款相关对象 ### Terminal 对象 Request Body ```json { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" } ``` 表示用于存款的终端的对象。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中终端的标识符 latitude | number | 终端位置的纬度（度） longitude | number | 终端位置的经度（度） address | *address* | 终端地址 type | 枚举 | 终端类型，可能值："atm"、"counter" ### Authentication 对象 Request Body ```json { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } ``` 定义存款时使用的认证参数的对象。 名称 | 类型 | 描述 :----: | :----: | ----------- used_password | boolean | 确定用户是否使用了密码 used_card | boolean | 确定用户在认证时是否携带卡片 used_card_chip_and_pin | boolean | 确定用户是否使用了芯片和密码 used_card_magnetic_stripe | boolean | 确定用户是否使用了磁条 used_fingerprint | boolean | 确定用户是否使用了指纹 typed_account_number | boolean | 确定用户是否输入了账户数据 ## 发送存款 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "id": "082373263", "analysis_status": "automatically_approved", "reason": "2019-10-01T10:37:25-03:00" } ``` 要评估存款，只需将 deposit 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/deposit/deposit` ## 查询存款 Response Body ```json { "id": "082373263", "analysis_status": "automatically_approved", "reason": "2019-10-01T10:37:25-03:00" } ``` 要检索存款数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/deposit/deposit/{deposit_id}` 其中 *deposit_id* 是发送存款时在客户系统中使用的交易标识符。 ## 更新存款 Request Body ```json { "deposit_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "id": "082373263", "deposit_status": "completed" } ``` 存款创建并分析后，资金将提供给用户。此流程可能因其他业务规则而中断。因此，需要在取款完成时通过以下端点通知取款状态更新： `PUT https://api.caas.qitech.app/deposit/deposit/{deposit_id}` 这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的存款。 --- # HTTP 状态码 URL: /zh-Hans/documentation/caas/banking/http_status QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ： HTTP 状态码 | 含义 | 描述 ---------- | ------- | --------------------------------- 400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。 401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。 403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。 404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。 405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。 406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。 409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。 500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。 503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。 --- # 简介 URL: /zh-Hans/documentation/caas/banking/introduction 欢迎使用 QI Tech Banking API！此 API 为银行和数字账户操作提供欺诈预防功能，例如转账分析、账单支付和 Boleto 支付。 以下，您可以看到使用 cUrl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。 ## 遇到问题？ 我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！ ### 我们热爱反馈 即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！ ## 环境 我们为客户提供两个环境。API 的基本 URL 为： * 生产环境 - `https://api.caas.qitech.app/` * 沙盒环境 - `https://api.sandbox.caas.qitech.app/` :::danger 重要提示！ 不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。 ::: ## 沙盒环境中的分析 在沙盒环境中，分析不计费，并根据简化的规则进行响应。 对于 *wire_transfers*、*bankslips*、*bill_payments* 和 *pix* 的情况，返回的响应将基于请求中发送的操作金额（*amount*）： 最小值 | 最大值 | 决策 ------ | ------ | ------- 16000 | - | 自动挑战* 10000 | 15999 | 自动批准 6000 | 9999 | 转人工分析 0 | 5999 | 自动拒绝 \* 自动挑战仅适用于 *pix* 服务。 对于 *withdrawal* 和 *deposit* 的情况，返回的响应将基于请求中发送的操作金额（*amount*）： 最小值 | 最大值 | 决策 ------ | ------ | ------- 10000 | - | 自动批准 0 | 9999 | 自动拒绝 对于 DICT 操作，返回的响应将基于请求中发送的 DICT 绑定密钥（*dict_key*）： DICT 中的密钥 | 决策 :----------: | ------- "Approve_dict_key" | 自动批准 任何其他字符串 | 转人工分析 "Reprove_dict_key" | 自动拒绝 ## 仅限 HTTPS 出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。 ## 流程 - 转账 转账分析流程在两种情况下启动： - PSP 用户正在执行转账 - PSP 用户正在接收转账 在这两种情况下，都必须调用 *wire_transfer* 端点，可能的结果状态为： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 in_manual_analysis | 转人工分析 pending | 银行转账对象正在处理中。 如果转账转为人工分析，分析师须批准或拒绝该转账。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪转账进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 流程 - Boletos Boleto 分析流程在两种情况下启动： - PSP 用户正在执行 Boleto 支付 - PSP 用户正在接收 Boleto 支付 在这两种情况下，都必须调用 *bankslip* 端点，可能的结果状态为： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 in_manual_analysis | 转人工分析 pending | Boleto 对象正在处理中。 如果 Boleto 支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 流程 - 账单支付 账单支付分析流程在以下情况下启动： - PSP 用户正在执行账单支付 在这种情况下，必须调用 *bill_payment* 端点，可能的结果状态为： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 in_manual_analysis | 转人工分析 pending | 账单支付对象正在处理中。 如果账单支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 流程 - 取款 取款分析流程在以下情况下启动： - PSP 用户正在执行取款 在这两种情况下，都必须调用 *withdrawal* 端点，可能的结果状态为： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 如果取款转为人工分析，分析师须批准或拒绝该取款。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 流程 - PIX 交易 PIX 支付流程在两种情况下启动： - 集成到 QI Tech 的 PSP 用户正在执行支付 - 从另一个 PSP 接收支付 在这两种情况下，都必须调用支付端点，可能的结果状态为： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 in_manual_analysis | 转人工分析 如果支付转为人工分析，分析师须批准或拒绝该支付。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪支付进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 流程 - DICT 变更 DICT 变更流程在两种情况下启动： - 集成到 QI Tech 的 PSP 用户向集成到 QI Tech 的 PSP 请求注册/变更/可携带性/申领 - 集成到 QI Tech 的 PSP 收到可携带性/申领 对于由 PSP 用户发起的注册，在 DICT 中进行变更之前，必须通过 QI Tech 的验证 API 执行密钥验证流程。如果验证由 PSP 自己执行，也可以在向 QI Tech 的请求中发送此信息。 要启动该流程，在这两种情况下，集成到 QI Tech 的 PSP 都必须在相应端点调用，响应以下状态之一： 枚举值 | 描述 :--------: | --------- automatically_approved | 自动批准 automatically_reproved | 自动拒绝 in_manual_analysis | 转人工分析 如果变更转为人工分析，分析师须批准或拒绝该变更。此时，可以生成 Webhook 向 PSP 通知状态变化，或 PSP 可通过 Polling 跟踪变更进度。在这两种情况下，可以返回以下状态： 枚举值 | 描述 :--------: | --------- manually_approved | 人工批准 manually_reproved | 人工拒绝 ## 认证 > 要认证一次调用，请使用以下代码： ```shell # 在 shell 中，您只需在每个请求中添加适当的 header curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。 我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。 我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key： `Authorization: EXAMPLE_API_KEY` :::info **注意** 您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。 ::: --- # 共享对象 URL: /zh-Hans/documentation/caas/banking/objects 大量数据在账户的不同事件之间共享。以下可以方便地找到这些对象的定义。 ## Client 对象 Request Body ```json { "id": "123456", "type": "natural_person", "document_number": "023.456.789-01", "name": "John Payer", "email": "john@payer.com", "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" } ``` 表示账户持有人数据的对象。 名称 | 类型 | 描述 :----: | :----: | --------- type | 枚举 *（必填）* | 客户类型："natural_person" 或 "legal_person" document_number | string *（必填）* | 文件编号，符合标准化部分 name | string *（必填）* | 客户姓名 email | string | 客户电子邮件 address | *address* | 客户地址数据 phone | *phone* | 客户电话数据 sales_channel | 枚举 *（必填）*| 客户注册的渠道 segment | string *（必填）*| 客户在机构内的细分（例如：premium、gold） 电话类型的枚举值为：`inbound_sales`、`app`、`website`、`call_center` 和 `branch` ## Address 对象 Request Body ```json { "street": "Rua do Teste", "number": "111", "neighbourhood": "Bairro do Exemplo", "city": "Aparecida de Goiânia", "uf": "GO", "complement": "Térreo", "postal_code": "00000-000", "country": "BRA" } ``` *address* 对象用于在整个 API 中表示地址，巴西境内地址的表示方式如下： 名称 | 类型 | 描述 ---- | :----: | --------- street | string *（必填）* | 地址的街道，包括公路名称，尽可能避免缩写。 number | string *（必填）* | 物业编号，如有字母则包含字母。 neighbourhood | string *（必填）*| 区域，不缩写。 **例如：Santa Felicidade** city | string *（必填）*| 城市全名，不缩写 uf | string *（必填）* | 联邦单位，两个大写字母。 **例如：SP** complement | string | 用于定位物业的任何补充信息。 **例如：Apartamento 101, Conjunto 12** postal_code | string *（必填）* | 该地点的邮政编码，含连字符。 country | string *（必填）* | 地址国家的 ISO 3166-1 alpha-3 代码。 对于国家不是巴西（"BRA"）的地址，postal_code 和联邦单位可以自由填写。 ## Phone 对象 Request Body ```json { "international_dial_code": "1", "area_code": "11", "number": "999999999", "type": "mobile" } ``` *phone* 对象表示巴西境内或境外的电话号码及其分类。字段如下： 名称 | 类型 | 描述 ---- | :----: | --------- international_dial_code | string *（必填）* | 国际拨号代码，不含零或加号，仅数字 area_code | string *（必填）* | 区号，不含零，仅数字 number | string *（必填）* | 电话号码，不含连字符 type | 枚举 *（必填）* | 号码类型：手机、住宅、商务等。 电话类型的枚举值为：`residential`、`commercial` 和 `mobile`。 ## Account 对象 Request Body ```json { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" } ``` 表示账户数据的对象。 名称 | 类型 | 描述 :----: | :----: | --------- participant | string *（必填）* | 账户所属机构的 ISPB branch | string *（必填）* | 账户支行 account_number | string *（必填）* | 不含校验位的账户号码 account_digit | string *（必填）* | 账户校验位 account_type | 枚举 *（必填）* | 来源账户类型，可能值："CACC"、"SLRY" 和 "SVGS" opening_date | datetime | 账户开户日期。 ## Source 对象 Request Body ```json { "channel": "app", "platform": "android", "ip":"255.201.26.1", "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a" } ``` source 对象表示用户用于执行操作的平台信息集合。字段如下： 名称 | 类型 | 描述 :----: | :----: | --------- channel | string | 用户执行操作使用的渠道，例如：网银、app platform | string | 应用程序使用的平台 ip | string | 从设备收集的 IP session_id | string | 会话的唯一标识符，用于将 Device Scan 与相关事件关联 ## Dict Key 对象 Request Body ```json { "key_type": "cpf", "key_value": "09991222669", "assignment_date": "2020-01-15T18:00:00-03:00" } ``` **dict_key** 对象用于表示客户（无论是收款人还是付款人）在 DICT 中的绑定密钥数据。该对象的字段为： 名称 | 类型 | 描述 :----: | :----: | --------- key_type | string *（必填）* | 包含 DICT 中绑定密钥类型的枚举值。 key_value | string | 包含在 DICT 中注册的绑定密钥。 assignment_date | datetime | 绑定密钥在 DICT 中注册的日期。 *key_type* 字段的枚举值与 DICT API 中定义的相同：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。 ## Destination Statistics 对象 Request Body ```json { "account":{ "settlements":{ "d3":4, "d30":67, "m6":618 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "owner":{ "settlements":{ "d3":6, "d30":88, "m6":996 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "key":{ "settlements":{ "d3":3, "d30":51, "m6":312 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } } } ``` 为了更准确地评估交易中的欺诈风险，需要通过 *Destination Statistics* 对象提供被入账方的交易和欺诈历史。此类数据可通过在 DICT 数据库中查询被入账方的绑定密钥获得。BACEN 要求在交易欺诈评估中使用这些数据。 名称 | 类型 | 描述 :----: | :----: | --------- account | *account* *（必填）* | 包含被入账方账户交易和欺诈历史的对象。 owner | *owner* *（必填）* | 包含与被入账方文件关联的交易和欺诈历史的对象。 key | *key* *（必填）* | 包含与被入账方提供的密钥关联的交易和欺诈历史的对象。 上述每个对象具有相同的字段： 名称 | 类型 | 描述 :----: | :----: | --------- settlements | *settlements* *（必填）* | 包含交易历史的对象。 rejected | *rejected* *（可选）* | 包含被拒绝操作历史的对象。 reported_frauds | *reported_frauds* *（必填）* | 包含欺诈举报历史的对象。 reported_aml_cft | *reported_aml_cft* *（可选）* | 包含 PLD/FT 举报历史的对象。 confirmed_frauds | *confirmed_frauds* *（必填）* | 包含已确认欺诈举报历史的对象。 confirmed_aml_cft | *confirmed_aml_cft* *（可选）* | 包含已确认 PLD/FT 举报历史的对象。 其中每个对象包含 **d3**、**d30** 和 **m6** 字段，分别包含过去 3 天、30 天和 6 个月的发生次数，均为必填字段。与 BCB DICT API 定义的方式相同。 --- # PIX Dict Operation URL: /zh-Hans/documentation/caas/banking/pix_dict_operations 当用户发起 DICT 变更时，数据应发送到我们的服务器，以便我们对该数据集所涉及的风险进行分析。 ## Dict Operation 对象定义 Request Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", "dict_key": { "key_type": "phone", "key_value": "16981610077", "assignment_date": "2020-01-15T18:00:00-03:00" }, "dict_operation_direction": "claimer", "dict_operation_reason": "user_requested", "dict_operation_creation_date": "2020-10-14T18:00:00-03:00", "dict_operation_type": "claim_portability", "client": { "id": "123456", "document_number": "099.912.226-69", "name": "João Jorge da Silva", "type": "natural_person", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "65", "number": "988961210", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "source_account": { "participant": "04184779", "branch": "0001", "account_number": "1122", "account_digit": "6", "owner": { "type": "legal_person", "document_number": "94.948.708/0001-12", "name": "Irmão Soares Ferragista LTDA." }, "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_account": { "participant": "00000000", "branch": "3675", "account_number": "10442", "account_digit": "6", "owner": { "type": "natural_person", "document_number": "099.912.226-69", "name": "João Jorge da Silva" }, "account_type": "SLRY", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_statistics": { "account":{ "settlements":{ "d3":12, "d30":65, "m6":344 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "owner":{ "settlements":{ "d3":4, "d30":12, "m6":88 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "key":{ "settlements":{ "d3":1, "d30":6, "m6":12 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065-98", "session_id": "7839jdqd9a8wd9" } } ``` Dict Operation 必须在转发到 BCB 处理系统之前发送到 API，以便进行注册预先欺诈验证。 Dict Operation 分析状态表示模型对该操作返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此操作。 automatically_reproved | 建议拒绝此操作。 in_manual_analysis | 建议由分析师对该操作进行人工分析。 pending | 操作正在处理中。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中操作的标识符。 **此编号对每个授权流程必须唯一** client | *client* | 表示客户数据的对象，无论是捐赠方还是接收方。 transaction_date | datetime | 交易开始的日期和时间，含时区。 dict_key | *dict_key* | 表示客户在交易中使用的 DICT 绑定密钥数据的对象。 dict_key_type | 枚举 | DICT 绑定密钥类型。 dict_operation_direction| 枚举 | DICT 中的操作方向，即密钥是被转让还是被获取。 dict_operation_reason | 枚举 | 执行 Dict 操作的原因。 dict_operation_creation_date | datetime | DICT 中操作的日期。 dict_operation_type | 枚举 | DICT 中操作的类型。 source_account | *source_account* | 表示正在转让绑定密钥的账户数据的对象。 destination_account | *destination_account* | 表示正在接收绑定密钥的账户数据的对象。 destination_statistics | *destination_statistics* | 表示正在接收绑定密钥的账户的交易和欺诈历史的对象。 source | *source* | Source 类型的对象，描述用于发送注册的应用程序信息 *dict_key_type* 字段接受与 DICT API 中定义的相同枚举值：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。 *dict_operation_direction* 字段接受枚举值：`donor` 和 `claimer`。 *dict_operation_type* 字段接受枚举值 `registration`、`claim_ownership` 和 `claim_portability`。 这些是 BCB 定义的 DICT 中所有操作类型。 ## 发送 Dict Operation Request Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", ... } ``` Response Body ```json { "dict_operation_key": "7f85e162-5a7d-41fa-a578-69df6f3df958", "status": "automatically_approved" } ``` 要评估支付，只需将 Payment 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/pix/dict_operation` ## 查询 Dict Operation Response Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", ... } ``` 要查询 Dict Operation，只需向以下端点发送请求： `GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}` 其中 *dict_operation_id* 是在注册时发送给我们的操作标识符，位于 "id" 字段中。 随后将返回与提供的密钥关联的 Dict Operation 对象。 ## 更新 Dict Operation Request Body ```json { "dict_operation_status": "cancelled_by_client", "reason": "user_requested", "event_date": "2020-10-07T15:06:25-03:00" } ``` Dict Operation 在 BCB 完成前有多个阶段。因此，需要通过以下端点通知操作的所有状态更新： `PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}` 这样可以确保我们的数据库保持更新，与 BCB 数据库始终保持一致。 某些 DICT 操作要求随数据一起提交操作原因。对于这些情况，需要在发送对象中填写 *reason* 字段，包含向 BCB 系统提供的相同枚举值。 这些枚举值为： 枚举值 | 描述 :--------: | --------- user_requested | 操作由客户请求。 account_closure | 操作因客户账户关闭而发起。 branch_transfer | 操作因客户支行变更而请求。 entry_inactivity | 操作因客户账户不活跃而请求。 reconciliation | 操作在对账流程后请求。 default_operation | 操作由参与方的默认操作请求。 fraud | 操作因与客户账户相关的欺诈而请求。 *dict_operation_status* 字段接受的操作阶段如下： 枚举值 | 描述 :--------: | --------- created | dict_operation 已创建但尚未分析。 reproved | dict_operation 在分析中被拒绝，不会发送给 BCB。 waiting_resolution | dict_operation 已发送给 BCB，等待解决。 cancelled_by_client | dict_operation 被客户取消。 cancelled_by_counterpart | dict_operation 被操作对方取消。 confirmed | dict_operation 已被操作对方确认。 completed | dict_operation 已完成并添加到 BCB 数据库。 --- # PIX Infraction Report URL: /zh-Hans/documentation/caas/banking/pix_infraction_reports ## Infraction Reports 对象定义 Request Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00", "infraction_report_status": "received", "infraction_report_events": [ { "new_status": "received", "event_date": "2020-10-14T00:25:42-03:00" } ] } ``` 如果交易任何一方发现可疑行为，可以创建 Infraction Report 来举报该嫌疑。该 Infraction Report 随后将由对方分析并决定是否确认。根据 BCB 的标准，Infraction Report 应具有以下字段： 名称 | 类型 | 描述 :----: | :----: | --------- infraction_report_type | 枚举 | 定义交易中存在的可疑活动类型的枚举值。 infraction_report_details | string | 导致 Infraction Report 创建者认为交易可能存在某种违规的情况详情。 infraction_report_creator | 枚举 | 定义 Infraction Report 创建者的枚举值。 infraction_report_date | datetime | 事件日期。 *infraction_report_type* 字段可包含枚举值：`fraud` 和 `compliance`。 *infraction_report_creator* 字段可包含枚举值：`client` 和 `external`。 ## 发送 Infraction Report Request Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00" } ``` Response Body ```json { "infraction_report_key": "7f85e162-5a7d-41fa-a578-69df6f3df958", "infraction_report_status": "received" } ``` 要发送 Infraction Report，只需向以下端点发送请求： `POST https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report` 其中 *transaction_id* 是在注册时发送给我们的交易标识符，位于 "id" 字段中。 ## 查询 Infraction Report Response Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00", "infraction_report_status": "received", "infraction_report_events": [ { "new_status": "received", "event_date": "2020-10-14T00:25:42-03:00" } ], "transaction_data": { "transaction_direction": "received", "id": "082373263", ... } } ``` 要查询 Infraction Report，只需向以下端点发送请求： `GET https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}` 随后将返回与提供的 *transaction_id* 关联且 *infraction_report_key* 与发送的密钥相同的 Infraction Report 对象。 ## 更新 Infraction Report Request Body ```json { "infraction_report_status": "acknowledged", "event_date": "2020-10-07T15:06:25-03:00" } ``` Infraction Report 在 BCB 完成前有多个阶段。因此，需要通过以下端点通知 Infraction Report 的所有状态更新： `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}` --- # PIX Transaction URL: /zh-Hans/documentation/caas/banking/pix_transactions 当付款人发起或接收支付时，交易数据应发送到我们的服务器。这样，可以根据该数据集对交易所涉及的风险进行分析。 ## Pix Transactions 对象定义 Request Body ```json { "transaction_direction": "received", "id": "082373263", "client": { "id": "123456", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "type": "natural_person", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "email": "mailto@qitech.com.br", "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "amount": 13725, "transaction_date": "2020-10-07T15:06:25-03:00", "dict_key": { "key_type": "cpf", "key_value": "09991222669", "assignment_date": "2020-01-15T18:00:00-03:00" }, "capture_method": "static_qr_code", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "source_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "owner": { "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA." }, "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_account": { "participant": "60701190", "branch": "3675", "account_number": "10442", "account_digit": "6", "owner": { "type": "natural_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti" }, "account_type": "SLRY", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_statistics": { "person":{ "settlements":{ "d90":4, "m12":67, "m60":618 }, "application_frauds":{ "d90":0, "m12":4, "m60":9 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "rejected_reports":{ "d90":0, "m12":0, "m60":0 }, "registered_accounts":0 }, "owner":{ "settlements":{ "d90":0, "m12":0, "m60":0 }, "application_frauds":{ "d90":0, "m12":0, "m60":0 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "registered_accounts":0 }, "key":{ "settlements":{ "d90":0, "m12":0, "m60":0 }, "application_frauds":{ "d90":0, "m12":0, "m60":0 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "rejected_reports":{ "d90":0, "m12":0, "m60":0 }, "distinct_accounts":{ "d90":0, "m12":0, "m60":0 } } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065.098", "session_id": "7839jdqd9a8wd9" } } ``` 交易必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 交易状态表示模型对该交易返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此交易。 automatically_reproved | 建议拒绝此交易。 approved_by_time | 交易因人工分析时间到期而被批准 reproved_by_time | 交易因人工分析时间到期而被批准 in_manual_analysis | 建议由分析师对该交易进行人工分析。 pending | 交易正在处理中。 名称 | 类型 | 描述 :----: | :----: | --------- transaction_direction | 枚举 | 注册交易的类型。定义客户是收款还是付款。*（必填）* id | string | 客户系统中支付的标识符。 **此编号对每个支付流程必须唯一** *（必填）* client | *client* | 表示客户数据的对象，无论是付款人还是收款人。*（必填）* amount | 整数 | 支付金额，以分为单位——如"标准"部分所述。*（必填）* pix_modality | string | 注册交易的类型。指示是否表示转账、找零或取款。 transaction_date | datetime | 交易开始的日期和时间，含时区。*（必填）* dict_key | *dict_key* | 表示客户在交易中使用的 DICT 绑定密钥数据的对象。 capture_method | 枚举 | 用于发起支付的方法，是否通过静态或动态 QR Code、数据填写或 DICT 密钥。*（必填）* face_recognition_key | string | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。 validation_key | string | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。 source_account | *source_account* | 表示被扣款账户数据的对象。*（必填）* destination_account | *destination_account* | 表示被入账账户数据的对象。*（必填）* destination_statistics | *destination_statistics* | 表示来自 BACEN DICT API 的被入账账户交易和欺诈历史的对象。*（必填）* source | *source* | Source 类型的对象，描述用于发送支付的应用程序信息 *transaction_direction* 的枚举值为：`sent` 和 `received`。 *pix_modality* 的枚举值为：`transacation`、`change` 和 `withdraw`。 *capture_method* 的枚举值为：`static_qr_code`、`dynamic_qr_code`、`offline_qr_code`、`typed`。 ## 发送交易 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "analysis_status": "automatically_approved", "reason": "rule_decision_enum" } ``` 要评估交易，只需将 Transaction 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/pix/transaction` ## 查询交易 Response Body ```json { "transaction_direction": "received", "id": "082373263", ... } ``` 要检索交易数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/pix/transaction/{transaction_id}` 其中 *transaction_id* 是在注册时发送给我们的交易标识符，位于 "id" 字段中。 ## 更新交易 Request Body ```json { "transaction_status": "sent", "event_date": "2020-10-07T15:06:25-03:00" } ``` 交易创建并分析后，应发送给 BCB 进行处理。因此，需要在交易发送给 BCB 时通过以下端点通知交易状态更新： `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}` 这样可以确保我们的数据库保持更新，与 BCB 数据库始终保持一致。 ## 未完成的交易 Request Body ```json { "transaction_status": "cancelled", "reason": "refused_by_counterpart", "event_date": "2020-10-07T15:06:25-03:00" } ``` 如果交易出于任何原因未能完成（即：未从来源账户扣款并入账到目标账户），可以将交易更新为 `cancelled` 状态，并注明取消原因，以便识别与未完成交易相关的欺诈模式。cancelled 状态只能用于仍处于 created 状态的交易，因为 `sent` 状态用于交易已完成的情况。 `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}` API 目前接受以下 reason，如果您认为需要将取消原因归入其他 reason，请联系 suporte.caas@qitech.com.br。 reason | 描述 :----: | --------- insufficient_balance | 客户账户余额不足以完成交易 fraud_prevention | 交易因未通过反欺诈系统而被取消 system_block | 某些系统锁定阻止了交易执行，例如账户已注销/不活跃或已达到限额 invalid_destination | 对方机构因目标账户不存在而拒绝了交易 refused_by_counterpart | 对方机构拒绝了交易 system_error | 交易因机构自身系统错误而被取消 invalid_authentication | 交易因客户未通过某个认证流程而被取消 --- # 标准 URL: /zh-Hans/documentation/caas/banking/standards 为便于集成并保证信息完整性，整个 API 遵循以下已定义的标准。 ## 货币金额 > 示例： ``` 10000 12345 98741 1223 1 0 ``` 金额必须以分为单位作为整数发送。 ## 带时区的日期和时间 > 一些示例： ``` 2019-10-15T22:35:12-03:00 2018-05-01T13:32:11+00:00 2019-05-01T00:00:00+00:00 ``` 按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效的地点的时区。例如，如果租约计划在巴西利亚机场于 09:30 开始，发送的时间应表示为 09:30-03:00；如果租约计划在马瑙斯于 09:30 开始，则应表示为 09:30-04:00。 用于验证的掩码如下： `YYYY-MM-ddThh:mm:ss±hh:mm` ## 不带时区的日期和时间 > 一些示例： ``` 2019-10-15T22:35:12Z 2018-05-01T13:32:11Z 2019-05-01T00:00:00Z ``` 按照 ISO 8601 表示。与时区无关的数据应不带时区发送，始终以 UTC 表示，字母 Z 表示该数据为 UTC。因此，将验证以下格式： `YYYY-MM-ddThh:mm:ssZ` ## 日期 > 一些示例 ``` 2019-10-15 2019-01-01 2017-03-20 ``` 对于只接收日期的字段（例如出生日期），应不包含任何时间，使用以下格式发送： `YYYY-MM-dd` --- # Webhook URL: /zh-Hans/documentation/caas/banking/webhook Webhook Atualizações no status de fraude (Para eventos que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. O cliente pode também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação para proceder com o polling. :::info **Atenção** Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS. ::: ## Assinatura do Webhook ## Webhook de Atualização de Evento Request Body ```json { "id": "123456", "analysis_status": "automatically_approved", "event_date": "2019-10-01T10:37:25-03:00" } ``` A requisição de atualização do status de análise de um evento possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8. Exemplos de endpoints para atualização de evento: * https://apidocliente.com.br/\{evento\} * https://apidocliente.com.br/admin/\{evento\}/123456 O campo \{evento\}, localizado na URL da requisição, pode assumir os seguintes valores, a depender do evento sendo notificado: * bill_payment * bankslip * wire_transfer * withdrawal * pix O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado. ## Retentativas A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem: * 10 segundos * 40 segundos * 160 segundos * 640 segundos * 2560 segundos * 10240 segundos * 40960 segundos --- # 转账 URL: /zh-Hans/documentation/caas/banking/wire_transfers 当用户执行或接收转账时，转账数据应发送给 QI Tech。这样，可以根据该数据集对交易所涉及的风险进行分析。 ## 转账对象定义 Request Body ```json { "id": "082373263", "wire_transfer_direction": "received", "wire_transfer_type": "ted", "amount": 13725, "wire_transfer_date": "2020-10-07T15:06:25-03:00", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "client": { "type": "natural_person", "id": "123456", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "email": "mailto@qitech.com.br", "sales_channel": "inbound_sales", "segment": "Personalité" }, "source_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "owner": { "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA." }, "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_account": { "participant": "60701190", "branch": "3675", "account_number": "10442", "account_digit": "6", "owner": { "type": "natural_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti" }, "account_type": "SLRY", "opening_date": "2020-01-15T18:00:00-03:00" }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065.098", "session_id": "7839jdqd9a8wd9" } } ``` 转账必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 转账状态表示模型对该转账返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此转账。 automatically_reproved | 建议拒绝此转账。 in_manual_analysis | 建议由分析师对该转账进行人工分析。 pending | 转账正在处理中。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中交易的标识符。 **此编号对每笔转账必须唯一** wire_transfer_direction | 枚举 | 注册转账的方式。定义客户是收款还是付款。 wire_transfer_type | 枚举 | 执行的转账类型，可以是 TED、DOC 或同一机构内账户间的内部转账。 amount | 整数 | 转账金额（分）——如"标准"部分所述。 wire_transfer_date | datetime | 转账开始的日期和时间，含时区。 face_recognition_key | string | 面部识别密钥，如果已通过我们的面部识别 API 进行面部识别。 validation_key | string | 验证密钥，如果已通过我们的验证 API 对客户进行验证测试。 client | *client* | 表示客户数据的对象，无论是执行转账的客户还是接收方。 source_account | *source_account* | 表示被扣款账户数据的对象。 destination_account | *destination_account* | 表示被入账账户数据的对象。 source | *source* | Source 类型的对象，描述用于发送转账的应用程序信息 *wire_transfer_direction* 的枚举值为：`sent` 和 `received`。 *wire_transfer_type* 的枚举值为：`ted`、`doc`、`internal_transfer`。 ## 发送转账 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` 要评估转账，只需将 Wire Transfer 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/wire_transfer/wire_transfer` ## 查询转账 Response Body ```json { "id": "082373263", "wire_transfer_direction": "received", ... } ``` 要检索转账数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}` 其中 *wire_transfer_id* 是发送转账时在客户系统中使用的交易标识符。 ## 更新转账 Request Body ```json { "wire_transfer_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "wire_transfer_status": "completed" } ``` 转账创建并分析后，将发送到清算中心进行处理。因此，需要在转账发送时通过以下端点通知转账状态更新： `PUT https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}` 这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的转账。 --- # 取款 URL: /zh-Hans/documentation/caas/banking/withdrawals 当用户执行取款时，取款数据应发送给 QI Tech。这样，可以根据该数据集对操作所涉及的风险进行分析。 ## 取款对象定义 Request Body ```json { "id": "082373263", "amount": 12979, "withdrawal_date": "2020-10-07T15:06:25-03:00", "service_description": "SAQUE EM CAIXA 24H", "source_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "client": { "id": "182373263", "type": "natural_person", "document_number": "023.456.789-01", "name": "John Payer", "email": "john@payer.com", "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "terminal": { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" }, "authentication": { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } } ``` 取款必须在转发到处理系统之前发送到 API，以便进行预先欺诈验证。 取款状态表示模型对该账户返回的决策。以下状态用于 **analysis_status** 标志： * `automatically_approved` * `automatically_reproved` 以下是 analysis_status 标志中返回的每个决策的含义： 状态 | 描述 :----: | --------- automatically_approved | 建议批准此取款。 automatically_reproved | 建议拒绝此取款。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中取款的标识符。 **此编号对每笔取款必须唯一** amount | 整数 | 取款金额（分）——如"标准"部分所述。 withdrawal_date | datetime | 取款执行的日期和时间——如"标准"部分所述 source_account | *account* | 确定待取款资金来源账户的对象 client | *client* | 包含来源账户持有人数据的对象 terminal | *terminal* | 包含执行取款的终端数据的对象 authentication | *authentication* | 包含认证信息的对象 ## 取款相关对象 ### Terminal 对象 Request Body ```json { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" } ``` 表示用于取款的终端的对象。 名称 | 类型 | 描述 :----: | :----: | --------- id | string | 客户系统中终端的标识符 latitude | number | 终端位置的纬度（度） longitude | number | 终端位置的经度（度） address | *address* | 终端地址 type | 枚举 | 终端类型，可能值："atm"、"counter" ### Authentication 对象 Request Body ```json { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } ``` 定义取款时使用的认证参数的对象。 名称 | 类型 | 描述 :----: | :----: | ----------- used_password | boolean | 确定用户是否使用了密码 used_card | boolean | 确定用户在认证时是否携带卡片 used_card_chip_and_pin | boolean | 确定用户是否使用了芯片和密码 used_card_magnetic_stripe | boolean | 确定用户是否使用了磁条 used_fingerprint | boolean | 确定用户是否使用了指纹 typed_account_number | boolean | 确定用户是否输入了账户数据 ## 发送取款 Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` 要评估账单支付，只需将 withdrawal 类型的对象发送到以下端点： `POST https://api.caas.qitech.app/withdrawal/withdrawal` ## 查询取款 Request Body ```json { "id": "082373263", "amount": 12979, ... } ``` 要检索取款数据，只需向以下端点发送请求： `GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}` 其中 *withdrawal_id* 是发送取款时在客户系统中使用的交易标识符。 ## 更新取款 Request Body ```json { "withdrawal_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "withdrawal_status": "completed" } ``` 取款创建并分析后，资金将提供给用户。此流程可能因其他业务规则而中断。因此，需要在取款完成时通过以下端点通知取款状态更新： `PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}` 这样可以确保我们的数据库保持更新，并能够识别真正易受欺诈影响的取款。