消费限额

消费限额可以限制持卡人单笔交易的最大金额、允许交易的商户类别，以及允许交易的具体商户。这些限制为可选项，可以在创建卡片时设置，也可以之后再更新。

单笔限额

为每笔交易设置最大金额。限额必须大于 0，且不能超过系统规定的最大授权上限。

在创建卡片时设置

在 Create Card 请求中加入 spending_controls：

{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
  "card_currency": "USD",
  "card_limit": 1000,
  "spending_controls": [
    {
      "amount": "500",
      "interval": "PER_TRANSACTION"
    }
  ]
}

对已有卡片进行更新

使用 Update Card 接口：

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "spending_controls": [
      {
        "amount": "1001",
        "interval": "PER_TRANSACTION"
      }
    ]
  }'

响应：

{
  "card_id": "f5d1e60a-6852-4fea-bb09-1d5bdab657a0",
  "card_order_id": "68363a75-6feb-40e0-aa90-4594dfd021bb",
  "card_status": "ACTIVE",
  "order_status": "PENDING"
}

修改在 card.update.succeeded webhook 触发后生效。

目前仅支持 PER_TRANSACTION 周期。币种与卡片的 card_currency 一致。创建卡片时若未指定，系统会使用账户级的最大单笔授权限额作为默认值。

MCC 限制

MCC（商户类别代码）限制可以限定卡片能与哪些类型的商户交易。你可以定义白名单或黑名单，但两者不能同时使用。

白名单（`allowed_mcc`）

只有 MCC 在此名单中的交易会被受理，其他 MCC 一律拒绝。

{
  "risk_controls": {
    "allowed_mcc": ["5411", "5541", "5812"]
  }
}

黑名单（`blocked_mcc`）

MCC 在此名单中的交易会被拒绝，其他 MCC 会被受理。

{
  "risk_controls": {
    "blocked_mcc": ["6551", "5533"]
  }
}

allowed_mcc 与 blocked_mcc 不能同时设置。两者只能选其一，或都不设置。

设置 MCC 限制

在创建卡片时加入 risk_controls，或使用 Update Card 接口：

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_controls": {
      "blocked_mcc": ["6551", "5533"]
    }
  }'

响应：

{
  "card_id": "f5d1e60a-6852-4fea-bb09-1d5bdab657a0",
  "card_order_id": "9492771e-5247-49fe-9846-55719bd9dabb",
  "card_status": "ACTIVE",
  "order_status": "PENDING"
}

交易被拒绝示例

当交易因 MCC 限制被拒绝时，授权 webhook 中会出现 transaction_status: DECLINED，并在 description 中说明原因：

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.authorization",
  "event_id": "9f0b529f-ad56-42f3-bef7-31393d543f40",
  "source_id": "07560ca4-5905-416f-a969-157094667d66",
  "data": {
    "card_id": "4e8f8c99-47e2-40a2-990d-c6f3e821a510",
    "card_number": "40963608****9191",
    "transaction_amount": "3",
    "transaction_currency": "SGD",
    "transaction_status": "DECLINED",
    "description": "Forbid MCC from account",
    "merchant_data": [
      {
        "category_code": "5999",
        "city": "CITY NAME",
        "country": "US",
        "name": "ACQUIRER NAME"
      }
    ],
    "transaction_type": "AUTHORIZATION"
  }
}

商户限制

商户限制用于控制卡片可以与哪些具体商户交易。当 MCC 限制粒度过粗时使用它——例如只屏蔽某一个网约车品牌，而放开该类别下的其他商户。

商户限制仅 Business Visa 支持。参见卡产品。

查询商户编码

allowed_merchants 和 blocked_merchants 接收的是商户编码，而不是商户名称。用 List Merchant Brands 查询编码。可按 display_name（大小写不敏感的前缀匹配）或 merchant_code（精确匹配）过滤。两者至少填一个——无法列出全量目录。两者都填时，只返回同时满足两个条件的条目。

curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/merchant_brands?display_name=Grab&page_number=1&page_size=10" \
  -H "x-auth-token: Bearer YOUR_API_TOKEN"

响应：

{
  "total_items": 12,
  "total_pages": 2,
  "data": [
    { "merchant_code": "10000668", "display_name": "Grab" },
    { "merchant_code": "10011330", "display_name": "Grab-Ec" },
    { "merchant_code": "10011331", "display_name": "Grabcab" },
    { "merchant_code": "10011332", "display_name": "Grabexpress-Ec" },
    { "merchant_code": "10011333", "display_name": "Grabtaxi" }
  ]
}

同一品牌可能对应目录中的多条记录。需要覆盖哪些条目就要逐条配置——选择 Grab 并不会自动包含 Grabtaxi。

白名单（`allowed_merchants`）

只有与列表内商户的交易会被接受，与其他商户的交易都会被拒绝。

{
  "risk_controls": {
    "allowed_merchants": ["10000418"]
  }
}

黑名单（`blocked_merchants`）

与列表内商户的交易会被拒绝，与其他商户的交易正常接受。

{
  "risk_controls": {
    "blocked_merchants": ["10000668", "10000418"]
  }
}

allowed_merchants 与 blocked_merchants 不能同时设置，且列表不得超过 20 条。传入不存在的商户编码会被拒绝。

设置商户限制

在创建卡片时加入 risk_controls，或使用 Update Card 接口：

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id} \
  -H "x-auth-token: Bearer YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_controls": {
      "blocked_merchants": ["10000668", "10000418"]
    }
  }'

响应：

{
  "card_id": "34dd5c5f-a13a-4069-bfaf-bbc33600d7a0",
  "card_order_id": "8e3c8aa5-4fbc-4bb6-9d4e-4cf131b8d2c3",
  "card_status": "ACTIVE",
  "order_status": "PENDING"
}

Retrieve Card 会在 risk_controls 中返回已配置的商户编码：

{
  "risk_controls": {
    "allow_3ds_transactions": "Y",
    "enable_3ds": "Y",
    "blocked_merchants": ["10000668", "10000418"]
  }
}

更新与清空商户限制

调用 Update Card 时，不传 allowed_merchants 和 blocked_merchants 表示保持当前配置不变。传空数组表示清空：

{
  "risk_controls": {
    "allowed_merchants": [],
    "blocked_merchants": []
  }
}

在两个列表之间切换只需一次调用——设置非空的 allowed_merchants 会清空已有的 blocked_merchants，反之亦然。

商户限制与 MCC 限制的关系

商户限制与 MCC 限制相互独立评估，因此同一张卡可以同时配置两者。只涉及商户字段的更新不会影响已有的 MCC 配置，只涉及 MCC 字段的更新也不会影响已有的商户配置。

Create Card API
Update Card API
List Merchant Brands API
Card Updated webhook
卡产品 —— 哪些产品支持 MCC 限制和商户限制

入门

持卡人

卡片

充值

管理与安全

集成

参考

单笔限额

在创建卡片时设置

对已有卡片进行更新

MCC 限制

白名单（`allowed_mcc`）

黑名单（`blocked_mcc`）

设置 MCC 限制

交易被拒绝示例

商户限制

查询商户编码

白名单（`allowed_merchants`）

黑名单（`blocked_merchants`）

设置商户限制

更新与清空商户限制

商户限制与 MCC 限制的关系

​单笔限额

​在创建卡片时设置

​对已有卡片进行更新

​MCC 限制

​白名单（allowed_mcc）

​黑名单（blocked_mcc）

​设置 MCC 限制

​交易被拒绝示例

​商户限制

​查询商户编码

​白名单（allowed_merchants）

​黑名单（blocked_merchants）

​设置商户限制

​更新与清空商户限制

​商户限制与 MCC 限制的关系

​相关链接

单笔限额

在创建卡片时设置

对已有卡片进行更新

MCC 限制

白名单（`allowed_mcc`）

黑名单（`blocked_mcc`）

设置 MCC 限制

交易被拒绝示例

商户限制

查询商户编码

白名单（`allowed_merchants`）

黑名单（`blocked_merchants`）

设置商户限制

更新与清空商户限制

商户限制与 MCC 限制的关系

相关链接