> ## 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.

# 消费限额

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

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

<h2 id="per-transaction-limits">单笔限额</h2>

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

<h3 id="set-at-card-creation">在创建卡片时设置</h3>

在 [Create Card](/zh/card-issuance/v1.6/api-reference/create-card) 请求中加入 `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"
    }
  ]
}
```

<h3 id="update-on-an-existing-card">对已有卡片进行更新</h3>

使用 [Update Card](/zh/card-issuance/v1.6/api-reference/update-card) 接口：

```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` 一致。创建卡片时若未指定，系统会使用账户级的最大单笔授权限额作为默认值。
</Note>

<h2 id="mcc-controls">MCC 限制</h2>

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

<h3 id="allowlist-allowed_mcc">白名单（`allowed_mcc`）</h3>

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

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

<h3 id="blocklist-blocked_mcc">黑名单（`blocked_mcc`）</h3>

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

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

<Warning>
  `allowed_mcc` 与 `blocked_mcc` **不能**同时设置。两者只能选其一，或都不设置。
</Warning>

<h3 id="set-mcc-controls">设置 MCC 限制</h3>

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

```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"
}
```

<h3 id="declined-transaction-example">交易被拒绝示例</h3>

当交易因 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"
  }
}
```

<h2 id="related">相关链接</h2>

* [Create Card API](/zh/card-issuance/v1.6/api-reference/create-card)
* [Update Card API](/zh/card-issuance/v1.6/api-reference/update-card)
* [Card Updated webhook](/zh/card-issuance/v1.6/webhooks/card-updated)
* [卡产品](/zh/card-issuance/v1.6/guide/card-products) —— 哪些产品支持 MCC 限制