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

# 消费限额

> 为已签发的卡片设置单笔消费限额、商户类别限制和商户限制。

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

## 单笔限额

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

### 在创建卡片时设置

在 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 请求中加入 `spending_controls`：

```json theme={null}
{
  "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](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) 接口：

```bash theme={null}
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"
      }
    ]
  }'
```

**响应：**

```json theme={null}
{
  "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 触发后生效。

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

## MCC 限制

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

### 白名单（`allowed_mcc`）

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

```json theme={null}
{
  "risk_controls": {
    "allowed_mcc": ["5411", "5541", "5812"]
  }
}
```

### 黑名单（`blocked_mcc`）

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

```json theme={null}
{
  "risk_controls": {
    "blocked_mcc": ["6551", "5533"]
  }
}
```

> [!WARNING]
>
> `allowed_mcc` 与 `blocked_mcc` **不能**同时设置。两者只能选其一，或都不设置。

### 设置 MCC 限制

在创建卡片时加入 `risk_controls`，或使用 [Update Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) 接口：

```bash theme={null}
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"]
    }
  }'
```

**响应：**

```json theme={null}
{
  "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` 中说明原因：

```json theme={null}
{
  "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 限制粒度过粗时使用它——例如只屏蔽某一个网约车品牌，而放开该类别下的其他商户。

> [!NOTE]
>
> 商户限制仅 Business Visa 支持。参见[卡产品](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)。

### 查询商户编码

`allowed_merchants` 和 `blocked_merchants` 接收的是商户编码，而不是商户名称。用 [List Merchant Brands](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-merchant-brands.md) 查询编码。

可按 `display_name`（大小写不敏感的前缀匹配）或 `merchant_code`（精确匹配）过滤。两者至少填一个——无法列出全量目录。两者都填时，只返回同时满足两个条件的条目。

```bash theme={null}
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"
```

**响应：**

```json theme={null}
{
  "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`）

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

```json theme={null}
{
  "risk_controls": {
    "allowed_merchants": ["10000418"]
  }
}
```

### 黑名单（`blocked_merchants`）

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

```json theme={null}
{
  "risk_controls": {
    "blocked_merchants": ["10000668", "10000418"]
  }
}
```

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

### 设置商户限制

在创建卡片时加入 `risk_controls`，或使用 [Update Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) 接口：

```bash theme={null}
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"]
    }
  }'
```

**响应：**

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

[Retrieve Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-card.md) 会在 `risk_controls` 中返回已配置的商户编码：

```json theme={null}
{
  "risk_controls": {
    "allow_3ds_transactions": "Y",
    "enable_3ds": "Y",
    "blocked_merchants": ["10000668", "10000418"]
  }
}
```

### 更新与清空商户限制

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

```json theme={null}
{
  "risk_controls": {
    "allowed_merchants": [],
    "blocked_merchants": []
  }
}
```

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

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

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

## 相关链接

* [Create Card API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)
* [Update Card API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md)
* [List Merchant Brands API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-merchant-brands.md)
* [Card Updated webhook](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/card-updated.md)
* [卡产品](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md) —— 哪些产品支持 MCC 限制和商户限制


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.