Webhooks

注意！

QI Tech 的 webhooks 不应以严格方式进行映射。 返回的 API webhooks payload 中可能会包含额外字段。

Webhook 重发

您可以按照文档中的详细说明查询和重发 webhooks：重发 Webhooks。

支付 Webhook

Webhook 请求体

Request Body: 支付已执行

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "executed",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}

Request Body: 支付待执行

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "pending_execution",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}

Request Body: 支付已拒绝

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": null,
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "rejected",
    "payment_type":"bank_slip",
    "error_code": "BIP000023",
    "error_message": "The source account has insufficient balance. Payment cannot be made."
  }
}

Request Body: 支付已冲销

{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "reverted",
    "payment_type":"bank_slip",
    "error_code": "BIP000029",
    "error_message": "Bank slip payment write off rejected."
  }
}

Webhook Body 参数

字段	类型	描述
webhook_type	string	定义所报告事件类型的枚举值
webhook_datetime	string	webhook 发送的日期和时间
request_control_key	uuid4	客户请求唯一标识键。
source_account_key *	uuid4	被扣款账户的键。
payment_key	uuid4	支付唯一标识键。
payment_schedule_key	uuid4	预约唯一标识键（仅适用于由预约生成的支付）。
barcode	string	条形码。
digitable_line	string	数字行。
payment_type	enum	支付类型。
payment_status	enum	支付状态。
error_code	string	错误代码。
error_message	string	错误信息。

payment_type 枚举值

枚举值	类型	描述
bank_slip	string	银行票据
collection_slip	string	征税发票

payment_status 枚举值

枚举值	类型	描述
executed	string	已执行
rejected	string	已拒绝
reverted	string	已冲销

HTTP 代码	QI 代码	标题	描述（英文）	描述（葡文）
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000014	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
400	BIP000023	Bad Request	The source account has insufficient balance. Payment cannot be made.	A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado.
400	BIP000025	Bad Request	It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance.	Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência.
400	BIP000029	Bad Request	Bank slip payment write off rejected.	Baixa de pagamento de boleto rejeitada.
400	BIP000034	Bad Request	Collection slip already paid.	Fatura de recolhimento já paga.
400	BIP000036	Bad Request	Covenant slip overdue.	Fatura de recolhimento vencida.
400	BIP000038	Bad Request	Outside of covenant payment hours.	Fora do horário de pagamento do convênio.

支付预约 Webhook

支付预约的 Webhook 流程

预约和执行支付的过程涉及使用不同的 webhooks，每个 webhook 在通知和跟踪支付状态方面都有其特定作用。

当预约在请求的日期执行时，可能进入 executed 状态，届时将触发状态为 executed 的 payment_schedule webhook，预约执行会创建状态为 pending 的 payment 并发送相应 webhook。或者，在账户关闭或票据金额变更等情况下，预约可能进入 rejected 状态，而不会创建 payment。在这种情况下，仅发送状态为 rejected 的 payment_schedule webhook，并附带相应错误代码。

• 最初，支付状态为 pending，因为支付过程正在进行中。支付完成后，将发送新的 payment webhook，此时状态为 executed。
• 如果支付无法完成（例如因账户余额不足），将发送状态为 rejected 的 payment webhook，并附带相应错误代码。
• 在账户余额不足的情况下，系统将进行最多 3 次支付尝试，每次间隔 30 分钟。在这种情况下，同一个已执行预约可能会生成多条支付记录。例如，如果仅在第三次尝试时才有足够余额，则前两次支付的 webhooks 将以 payment 和 rejected 状态触发，第三次支付的 webhooks 则以 payment 和 executed 状态触发。

Webhook 请求体

Request Body: 支付预约已执行

{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "executed",
    "error_code": null,
    "error_message": null
  }
}

Request Body: 支付预约已拒绝

{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "rejected",
    "error_code": "BIP000007",
    "error_message": "Bank slip blocked for payment"
  }
}

Webhook Body 参数

字段	类型	描述
webhook_type	string	定义所报告事件类型的枚举值
webhook_datetime	string	webhook 发送的日期和时间
request_control_key	uuid4	客户请求唯一标识键。
source_account_key *	uuid4	被扣款账户的键。
payment_key	uuid4	支付唯一标识键。
payment_schedule_key	uuid4	支付预约唯一标识键。
barcode	string	条形码。
digitable_line	string	数字行。
payment_type	enum	支付预约类型。
payment_schedule_status	enum	支付预约状态。
error_code	string	错误代码。
error_message	string	错误信息。

payment_type 枚举值

枚举值	类型	描述
bank_slip	string	银行票据
collection_slip	string	征税发票

payment_schedule_status 枚举值

枚举值	类型	描述
executed	string	已执行
rejected	string	已拒绝

HTTP 代码	QI 代码	标题	描述（英文）	描述（葡文）
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000014	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
400	BIP000006	Bad Request	Bank slip already written off	Boleto já baixado
400	BIP000007	Bad Request	Bank slip blocked for payment	Boleto bloqueado para pagamento
400	BIP000008	Bad Request	Bank slip already paid	Boleto já pago
400	BIP000009	Bad Request	Invalid bank slip. Please consult issuing bank	Boleto inválido. Favor consultar banco emissor
400	BIP000034	Bad Request	Collection slip already paid.	Fatura de recolhimento já paga.