跳到主要内容

QI 卡 - 预付卡

使用场景​

注意！

QI Tech 的 Webhooks 不应以严格限制的方式映射。 我们 API 返回的 Webhook payload 中可能会添加额外字段。

Webhook 重发

您可以按照文档中的详细说明查询和重发 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"
}