> ## 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.
# 授权决策
> 接入 Authorization Decision API，实时对卡交易做出通过或拒绝决定。
Business Visa & Personal Visa only
Authorization Decision API 让你能对卡交易做出实时的通过/拒绝决定。当一笔交易通过 UQPAY 的内部风控后，交易详情会被转发到你的 endpoint，由你做出最终决定。
**前置条件**
* 通过 UQPAY 风控审核以启用此功能
* 一个可公开访问的 HTTPS endpoint，用于接收授权请求
* 用于请求/响应加密的 PGP 密钥对
工作原理
```mermaid theme={null}
sequenceDiagram
participant C as Cardholder
participant U as UQPAY
participant P as Your endpoint
C->>U: Card transaction
U->>U: Internal risk control
alt UQPAY declines
U-->>C: Transaction declined
U->>P: issuing.transaction.authorization webhook (notification only)
else UQPAY approves
U->>P: Authorization decision request (encrypted)
P->>P: Decrypt → evaluate → encrypt response
P->>U: Authorization decision response (encrypted)
U-->>C: Transaction result
end
```
核心原则：
* 你只会收到已经通过 UQPAY 风控的交易的授权请求。
* 被 UQPAY 拒绝的交易不会发送到你的 endpoint —— 你只会收到 `issuing.transaction.authorization` webhook 通知。
* 你必须在配置的超时时间内响应（1 到 5 秒，按你与 UQPAY 的约定设置）。如果未收到有效响应，交易结果由你配置的默认超时动作决定（通过或拒绝）。
安全：PGP 加密
整个请求和响应体都使用 PGP 加密。接入前，你和 UQPAY 需要交换 PGP 公钥：
| 方向 | 加密方式 |
| ------------- | ---------------------- |
| UQPAY → 你（请求） | 使用**你的**公钥加密。用你的私钥解密。 |
| 你 → UQPAY（响应） | 发送前使用 **UQPAY 的**公钥加密。 |
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQENBGkIsmwBCADUvVdRpSMTnhZ9/hfzkDmmChj/2DwcRLg2YB4/wA2pCwSSYdh9
LmFWdHk5OYe41a6H0z3Bc0C5PUp3dU2V9D1rZMBJkSOb8kSCprfh6ayegp8O3hX8
Q2CCveakh8vB+UkRkKumLXBcMasraUCXTOdQ4m9KKO3zSC16nJIT907Uo1973y1/
LqkWzkBUgDAjUpH/YocCo2jzAh6Uz90zoRQWJK4i8iTfBciALqgZTSSmuN/rEZ5z
5BM5AK2dA4D0LJ8Cr7R9Y8eHdsZrDrPpGoIDbyY/9wvpDLnxZc+SRihKUu2RWxNt
PFpjOkEl9AXkqU5N7LccAHnYnP1HAXAcSsjPABEBAAG0HlVRUEFZIDxpc3N1aW5n
LnRlY2hAdXFwYXkuY29tPokBUQQTAQgAOxYhBMzRRL71/SkUZCFtKL6p85GBc+r+
BQJpCLJsAhsDBQsJCAcCAiICBhUKCQgLAgQWAgMBAh4HAheAAAoJEL6p85GBc+r+
Ev4IAI2CGpMHHcTitO9V+Lf5c4BmXtNlHqnsqFQNVMrIfgt9re9dWCyvKxaCFCLK
cfw5Vjugt/qz7Wl63NpJpDhAl+eO+cZfYzYY5Tb/VHAKzihOFpAlKtPw1fhdANUC
LB1aGGq+cHsbltr7sBD1OuHUi95rKskr3jctd6lp97B6qFtqc58sChk7JoikJMqw
NybHIoyVjCKHWj0jBw+qppB4+IcfS3HXxGxGzy7iIAeB0wQX54OohMXJHgdopPuO
xufTif6dZbw1g0NwzWekirghf4BUW76WNDPR2BxD/zE3fxgoh7Mid1IC855JiHXW
SnEaB1XsBF/faGotMRpX8t7+H0a5AQ0EaQiybAEIALhicwMCb9nwReS91HUU2yC+
Xu7Ay3gd5/8xX9EC63XqzvFSE83OVzKOEEE9sGsvKQcCLKOoBksfPtnaZqek/mix
/ChNSHFZK5+UrZpsMgFNeUBYQg5zcX/w8T91WZJllmYjEdglzh89Gp82zwzF3Wmt
gB+c2/3hYBxuKXjhW5x5xSli8nCz2hxWLouXiNqfqBHUDJIHJQO2Nrms7FVp8S4Y
dXlDxJfJodn8JL8PIpuHyEV2+2BWADQrM+qxkyfcFbqpVEyGad8kMB2G10gOWM/f
3sZEQ238G/q7odEKsY5BVpYaPTL1PfpxEkq69oYkCfcdRCXZxj7dhqyDkzn0wXEA
EQEAAYkBNgQYAQgAIBYhBMzRRL71/SkUZCFtKL6p85GBc+r+BQJpCLJsAhsMAAoJ
EL6p85GBc+r+tM4IAI3P4yLnVR21DysTjlOueZVv75zJnjYTMHmS2BTIYVcwYCWX
n+Fjqn5ylxwuql53SjENavi543GzZ31z8w6wWVICS36WhGG6tpy5VOFzomqj1hAN
1lOPY3ADwCtphV4Cn21WbhA/MGF+l9rIVoVuMLdmug/wOeM2VkzVlnGJPhr+RFPE
L+6wV3UFP68uk3nGshwj09roeKZV/wRfCmJhnNt2ufQzl2FbtlbSP8xBIprW0xnf
UBqR1Wp4Lg0hCKWRgRFftMjqDz51iBWbxsdkF7GCMWuv7ko3THaYSDMcsxGndOTd
P8G2/doToAnlb3vozoRN/7uW7yIhpAL4PWJkzfU=
=4/ki
-----END PGP PUBLIC KEY BLOCK-----
```
API 规格
请求
UQPAY 向你配置的 endpoint 发送 `POST` 请求，请求头包含：
| Header | 说明 |
| -------------- | --------------------------------- |
| `Content-Type` | `application/json; charset=utf-8` |
| `x-request-id` | 每个请求的唯一 UUID |
解密后的请求体包含：
| 字段 | 类型 | 说明 |
| ------------------------------------ | ------------- | -------------------------------------------------------------------------------------------- |
| `transaction_id` | string (UUID) | 交易唯一标识符 |
| `transaction_type` | integer | `1000` 授权、`1100` 转出、`1200` 取现、`2000` 退款 |
| `card_id` | string (UUID) | 卡标识符 |
| `processing_code` | string | 卡组织处理码 |
| `billing_amount` | float | 账单金额 |
| `transaction_amount` | float | 交易金额 |
| `auth_amount` | float | 授权金额 |
| `date_of_transaction` | string | 格式：`YYYY-MM-DD HH:MM:SS` |
| `billing_currency_code` | string | 3 位 ISO 货币代码 |
| `transaction_currency_code` | string | 3 位 ISO 货币代码 |
| `auth_currency_code` | string | 3 位 ISO 货币代码 |
| `card_balance` | float | 卡片可用余额 |
| `merchant_id` | string | 商户标识符 |
| `merchant_name` | string | 商户名称 |
| `merchant_category_code` | string | MCC |
| `merchant_city` | string | 商户所在城市 |
| `merchant_country` | string | 2 位 ISO 国家代码 |
| `terminal_id` | string | 终端标识符 |
| `pos_entry_mode` | string | POS 录入方式（见下方） |
| `pos_condition_code` | string | 交易条件码（见下方） |
| `pos_env` | string | POS 环境 —— 用于识别 credential-on-file、分期和周期性（订阅）交易（见下方） |
| `eci` | string | 邮购/电话、电商及支付标识（见下方） |
| `pin_entry_capability` | string | `0` 未知、`1` 可接受 PIN、`2` 不可接受 PIN、`8` PIN 键盘故障 |
| `retrieval_reference_number` | string | RRN，12 位 |
| `system_trace_audit_number` | string | STAN，6 位 |
| `acquiring_institution_country_code` | string | 2 位 ISO 国家代码 |
| `acquiring_institution_id` | string | 收单机构标识符 |
| `wallet_type` | string | `APPLE`、`SAMSUNG`、`GOOGLE`、`GOOGLE ECOMMERCE`、`GOOGLE PAY`、`MI PAY`、`Garmin Pay`、`ECOMMERCE` |
| Code | 说明 |
| ---- | -------------------------------- |
| `00` | 未知或未使用终端 |
| `01` | 手动（键盘输入） |
| `02` | 磁条读取；可能无法进行 CVV 校验 |
| `03` | 光学码 |
| `05` | 按 VSDC 芯片数据规则接触式读取 IC 卡 |
| `07` | 按 qVSDC 芯片数据规则非接触式读取 |
| `10` | 存档凭证 |
| `90` | 磁条读取，精确 Track 1/2 内容（可进行 CVV 校验） |
| `91` | 按磁条数据规则非接触式读取 |
| `95` | IC 卡读取；可能无法进行 CVV 或 iCVV 校验 |
| Code | 说明 |
| ---- | --------------------- |
| `00` | 正常交易 |
| `01` | 客户不在场 |
| `02` | 无人值守的持卡人自助环境，有 PIN 数据 |
| `03` | 商户对交易（或卡片）存疑 |
| `05` | 客户在场，卡片不在场 |
| `06` | 预授权请求 |
| `08` | 邮件、电话、定期、预付或分期订单 |
| `51` | 地址/CVV2/账户验证，无授权 |
| `59` | 通过公共网络发起的电商请求 |
| Code | 说明 |
| ---- | ------------------------------------------------------------- |
| `C` | Credential on file（首次存储）/ Unscheduled card on file（后续商户发起的交易） |
| `I` | 分期付款 |
| `R` | 周期性 —— 持卡人与商户已就商品或服务的定期扣费达成一致，如话费账单、杂志订阅 |
| Code | 说明 |
| ---- | ------------------------------------------------------ |
| `00` | 不适用 |
| `01` | 单笔邮购/电话订单 |
| `02` | 周期性交易 |
| `03` | 分期付款 |
| `04` | 分类未知 |
| `05` | 安全电子商务交易 |
| `06` | 在支持 3-D Secure 的商户发生的未认证安全交易，且商户已尝试通过 3-D Secure 验证持卡人 |
| `07` | 未认证安全交易 |
| `08` | 非安全交易 |
**请求体示例（解密后）：**
```json theme={null}
{
"transaction_id": "7ae57f4d-930d-41b9-83a8-4274f6a23a3b",
"transaction_type": 1000,
"card_id": "b3dd7e47-f8b7-4790-aa47-a0e37bae7757",
"processing_code": "00",
"billing_amount": "2.31",
"transaction_amount": "2.31",
"billing_currency_code": "SGD",
"transaction_currency_code": "CAD",
"auth_currency_code": "USD",
"auth_amount": "0",
"date_of_transaction": "2025-11-14 15:07:25",
"card_balance": "90085.59",
"merchant_category_code": "5972",
"merchant_id": "CARD ACCEPTOR ",
"terminal_id": "TERMID01",
"merchant_country": "US",
"merchant_name": "ACQUIRER NAME",
"merchant_city": "CITY NAME",
"pos_entry_mode": "01",
"pos_condition_code": "08",
"pos_env": "R",
"eci": "02",
"pin_entry_capability": "2",
"retrieval_reference_number": "529430718653",
"system_trace_audit_number": "000653",
"acquiring_institution_country_code": "TK",
"acquiring_institution_id": "30954284708",
"wallet_type": "GOOGLE ECOMMERCE"
}
```
响应
以 HTTP `200` 返回以下 JSON 响应体，使用 UQPAY 的 PGP 公钥加密：
| 字段 | 类型 | 说明 |
| ---------------------- | ------------- | ------------------------------------- |
| `transaction_id` | string (UUID) | 必须与请求的 `transaction_id` 一致，否则该笔交易会被拒绝 |
| `response_code` | string | 授权响应码（见下表） |
| `partner_reference_id` | string | 你内部的对账参考 ID（选填，可为空） |
**响应体示例（加密前）：**
```json theme={null}
{
"transaction_id": "7ae57f4d-930d-41b9-83a8-4274f6a23a3b",
"response_code": "00",
"partner_reference_id": ""
}
```
响应码
| Code | 说明 |
| ---- | -------- |
| `00` | 通过 |
| `04` | 吞卡 |
| `05` | 不予授权 |
| `06` | 错误 |
| `13` | 金额无效 |
| `14` | 账号无效 |
| `43` | 失卡 |
| `51` | 余额不足 |
| `59` | 疑似欺诈 |
| `65` | 超出活动次数限制 |
只有同时满足以下三个条件时，交易才会**通过**：
1. HTTP 状态码为 `200`
2. `response_code` 为 `"00"`
3. `transaction_id` 与请求匹配
其余情况一律拒绝。
接入步骤
1. **联系 UQPAY** —— 联系 UQPAY 为你的账户启用 Authorization Decision API 功能。
2. **交换配置** —— 向 UQPAY 提供以下内容：
* 你的 PGP 公钥（RSA 2048 位）
* 你的授权决策 endpoint URL（HTTPS）
* 决策超时时间（1 到 5 秒，默认 2 秒）
* 默认超时动作：`decline`（超时自动拒绝）或 `delegate`（由 UQPAY 代为决定）
UQPAY 将提供其 PGP 公钥（见上方）和需要加入防火墙白名单的出口 IP：**生产环境** `18.139.246.78`、`54.251.52.172`。
3. **实现你的 endpoint** —— 构建一个 POST endpoint，使用你的 PGP 私钥解密请求体，按业务逻辑评估交易，使用 UQPAY 的公钥加密响应，并在配置的超时时间内返回加密后的响应。
4. **测试集成** —— 与 UQPAY 协作在沙盒环境运行测试交易，验证加解密和响应处理的正确性。
如果你的 endpoint 未能正确响应 —— 包括响应格式错误、`transaction_id` 不匹配、或超时后才返回 —— 交易将被拒绝。上线前务必充分测试。
* [Create Card API](/zh/card-issuance/v1.6/api-reference/create-card)
* [Transaction Authorization webhook](/zh/card-issuance/v1.6/webhooks/transaction)