QI 卡 - 预付卡
使用场景
QI Tech 的 Webhooks 不应以严格限制的方式映射。 我们 API 返回的 Webhook payload 中可能会添加额外字段。
您可以按照文档中的详细说明查询和重发 Webhooks：重发 Webhooks。
为便于理解，将发行并为其客户提供卡片服务的 BaaS 客户称为"客户"，持有所发行卡片的最终用户称为"持卡人"。
1. 交易的完整授权与确认
这是卡片交易最常见的路径：持卡人在 POS 机上刷卡进行金额为 X 的交易，收单机构从发卡机构处扣取该金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如授权请求中所述。客户随后进行验证并选择回复，将 autorization_request_response 设为 authorized。
QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。
此时，将发送一个引用刚刚获批授权的 Webhook。
授权已批准的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此交易转为 completed 状态。可在 Authorization 对象的 captured_amount 变量中查询已扣划金额。
授权已确认的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "capture",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
2. 交易的授权与不足额确认
在此情况下，收单机构扣划的金额小于授权金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如授权请求中所述。客户随后进行验证并选择回复，将 autorization_request_response 设为 authorized。
QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。
此时，将发送一个引用刚刚获批授权的 Webhook。
授权已批准的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此授权转为 completed 状态。可在 Authorization 对象的 captured_amount 变量中查询已扣划金额。
不足额确认的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 23,
"billing_currency_code": "BRL",
"billing_amount": 23,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "capture",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
如果授权在未完全扣划的情况下过期，差额将作为信用返还到持卡人账户。
3. 交易的授权与超额确认
在此情况下，收单机构扣划的金额大于授权金额。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如授权请求中所述。客户随后进行验证并选择回复，将 autorization_request_response 设为 authorized。
QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。
此时，将发送一个引用刚刚授权交易的 Webhook。
授权已批准的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
收单机构在交易授权后进行资金扣划。该扣划由 QI 处理，并发送授权状态更新 Webhook，将此授权转为 completed 状态。可在 Authorization 对象的 captured_amount 变量中查询已扣划金额。在此使用场景中，扣划金额将大于原授权金额。
超额确认的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 27,
"billing_currency_code": "BRL",
"billing_amount": 27,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "capture",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
此情况将在持卡人的 QI 账户中产生超额差额的借记，本例中将从持卡人的 QI 账户中扣除 R$ 2,00。如果在任何情况下均无法执行此借记，QI 将与客户（使用 QI 卡片服务的 BaaS 客户）单独处理这些情况。
部分取消
在此超额确认情况下，收单机构可通过发送全额退款 refund 或部分退款 partial_refund 来纠正错误，这些将以授权事件的形式呈现。以下是对不当多收的 R$2,00 进行部分退款的示例。
部分退款授权的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 2,
"billing_currency_code": "BRL",
"billing_amount": 2,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "partial_refund",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
4. 交易的授权与取消
在此情况下，交易已获授权，但由于某种原因，卖家决定在扣划之前在 POS 机上取消该交易。流程从持卡人在 POS 机上使用卡片开始。QI 将收到授权请求并向客户发起授权，如授权请求中所述。客户随后进行验证并选择回复，将 approve 设为 true。
QI 将向卡网络回复授权，持卡人的账户余额将扣除交易金额。
此时，将发送一个引用刚刚授权交易的 Webhook。
交易已授权的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
卖家在交易授权后，因某种原因（例如输入错误）决定取消该交易。该取消消息由 QI 处理，并发送交易状态更新 Webhook，将该交易转为已冲正 reversed 状态。在此情况下，授权全额已被取消。
授权已冲正的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 27,
"billing_currency_code": "BRL",
"billing_amount": 27,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization_reversal",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}
在此情况下，全额取消金额将作为信用返还到持卡人的 QI 账户。
授权过期
可能出现授权已批准但在卡片品牌规定的期限内未被扣划的情况。在此情况下，将发送授权过期 Webhook，未扣划金额将作为信用返还到持卡人的 QI 账户。
授权已过期的 Webhook
{
"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"data": {
"merchant_currency_code": "BRL",
"merchant_amount": 25,
"billing_currency_code": "BRL",
"billing_amount": 25,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization_expiration",
"authorization": {Objeto da Autorização}
},
"webhook_type": "prepaid_card.authorization_event",
"event_datetime": "2023-07-24T12:00:00.000Z"
}