> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 交易

> 当交易被授权、冲正、退款、结算或拒付时发送。

## 事件类型

| 事件类型                                      | 描述                                                                                                                                        |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `issuing.transaction.authorization`       | 发卡行批准持卡人发起的交易，一般用于描述普通的交易或消费。                                                                                                             |
| `issuing.transaction.reversal`            | 取消或冲正之前的一笔交易，可能由于欺诈、操作错误或交易取消等原因发生，资金会退回到持卡人账户。                                                                                           |
| `issuing.transaction.refund`              | 持卡人退回已购买的商品或服务时，商户将资金退回至持卡人所在的账户。                                                                                                         |
| `issuing.transaction.settlement.credit`   | 当结算金额低于原始交易金额时，差额资金返还至持卡人账户。                                                                                                              |
| `issuing.transaction.settlement.debit`    | 当结算金额高于原始交易金额时，从持卡人账户中扣除差额资金。                                                                                                             |
| `issuing.transaction.settlement.reversal` | 撤销之前的结算交易，在发生错误时将资金返还给持卡人。                                                                                                                |
| `issuing.transaction.fund.collection`     | 持卡人卡账户从外部收到资金时，由发卡网络（如 Visa/Mastercard）回传给 UQPAY 的入账通知，并以 webhook 形式转发给您。区别于持卡人主动充值（`CARD RECHARGE`）和大账户充值（funding your issuing balance）。 |
| `issuing.transaction.fund.transfer`       | 资金划转已处理。                                                                                                                                  |
| `issuing.transaction.validation`          | 验证银行卡的合法性，确保持卡人信息正确且卡片处于有效状态，通常与授权流程同时进行。                                                                                                 |
| `issuing.transaction.atm.deposit`         | 通过取款机向账户存入现金的交易；UQPAY 暂不支持该类交易，但仍会记录该次交易事件。                                                                                               |
| `issuing.transaction.chargeback.credit`   | 拒付入账已处理。                                                                                                                                  |
| `issuing.transaction.chargeback.debit`    | 拒付出账已处理。                                                                                                                                  |

## 识别ATM交易

<Accordion title="如何识别ATM取现和余额查询">
  两者都以 `issuing.transaction.authorization` 事件形式到达。

  **ATM取现**

  `merchant_data[].category_code = 6011`（MCC 6011 — 自动取现）。

  **ATM余额查询**

  `merchant_data[].category_code = 6011` **且** `billing_amount = "0"`。
</Accordion>


## OpenAPI

````yaml webhooks-issuing.yaml webhook transaction
openapi: 3.1.0
info:
  title: Issuing Webhooks
  version: 1.6.0
  description: |
    Webhook events for the Card Issuance product. UQPAY sends these events to
    your registered webhook endpoint as HTTP POST requests with a JSON body.

    All events share a common envelope (`event_id`, `event_name`, `event_type`,
    `source_id`, `version`) and carry event-specific data in the `data` field.
servers: []
security: []
paths: {}

````