跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorization Decision API 让你能对卡交易做出实时的通过/拒绝决定。当一笔交易通过 UQPAY 的内部风控后，交易详情会被转发到你的 endpoint，由你做出最终决定。
前置条件
  • 通过 UQPAY 风控审核以启用此功能
  • 一个可公开访问的 HTTPS endpoint，用于接收授权请求
  • 用于请求/响应加密的 PGP 密钥对

​
工作原理

核心原则：
  • 你只会收到已经通过 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-Typeapplication/json; charset=utf-8
x-request-id每个请求的唯一 UUID
解密后的请求体包含：
字段类型说明
transaction_idstring (UUID)交易唯一标识符
transaction_typeinteger1000 授权、1100 转出、1200 取现、2000 退款
card_idstring (UUID)卡标识符
processing_codestring卡组织处理码
billing_amountfloat账单金额
transaction_amountfloat交易金额
auth_amountfloat授权金额
date_of_transactionstring格式：YYYY-MM-DD HH:MM:SS
billing_currency_codestring3 位 ISO 货币代码
transaction_currency_codestring3 位 ISO 货币代码
auth_currency_codestring3 位 ISO 货币代码
card_balancefloat卡片可用余额
merchant_idstring商户标识符
merchant_namestring商户名称
merchant_category_codestringMCC
merchant_citystring商户所在城市
merchant_countrystring2 位 ISO 国家代码
terminal_idstring终端标识符
pos_entry_modestringPOS 录入方式（见下方）
pos_condition_codestring交易条件码（见下方）
pin_entry_capabilitystring0 未知、1 可接受 PIN、2 不可接受 PIN、8 PIN 键盘故障
retrieval_reference_numberstringRRN，12 位
system_trace_audit_numberstringSTAN，6 位
acquiring_institution_country_codestring2 位 ISO 国家代码
acquiring_institution_idstring收单机构标识符
wallet_typestringAPPLE、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按磁条数据规则非接触式读取
95IC 卡读取；可能无法进行 CVV 或 iCVV 校验
Code说明
00正常交易
01客户不在场
02无人值守的持卡人自助环境，有 PIN 数据
03商户对交易（或卡片）存疑
05客户在场，卡片不在场
06预授权请求
08邮件、电话、定期、预付或分期订单
51地址/CVV2/账户验证，无授权
59通过公共网络发起的电商请求
请求体示例（解密后）： 
{
  "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",
  "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_idstring (UUID)必须与请求的 transaction_id 一致，否则该笔交易会被拒绝
response_codestring授权响应码（见下表）
partner_reference_idstring你内部的对账参考 ID（选填，可为空）
响应体示例（加密前）： 
{
  "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。
  3. 实现你的 endpoint —— 构建一个 POST endpoint，使用你的 PGP 私钥解密请求体，按业务逻辑评估交易，使用 UQPAY 的公钥加密响应，并在配置的超时时间内返回加密后的响应。
  4. 测试集成 —— 与 UQPAY 协作在沙盒环境运行测试交易，验证加解密和响应处理的正确性。
如果你的 endpoint 未能正确响应 —— 包括响应格式错误、transaction_id 不匹配、或超时后才返回 —— 交易将被拒绝。上线前务必充分测试。