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

# Spending controls

> Set per-transaction spending limits and merchant category restrictions on issued cards.

Spending controls let you restrict how much a cardholder can spend per transaction and which merchant categories they can transact with. These controls are optional and can be set at card creation or updated later.

## Per-transaction limits

Set a maximum amount for each individual transaction. The limit must be greater than 0 and cannot exceed the system-defined maximum authorization threshold.

### Set at card creation

Include `spending_controls` in the [Create Card](/card-issuance/v1.6/api-reference/create-card) request:

```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 on an existing card

Use the [Update Card](/card-issuance/v1.6/api-reference/update-card) endpoint:

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

**Response:**

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

The change takes effect after the `card.update.succeeded` webhook fires.

<Note>
  Only the `PER_TRANSACTION` interval is currently supported. The currency matches the card's `card_currency`. When omitted during card creation, the system defaults to the account-level maximum per-transaction authorization limit.
</Note>

## MCC controls

Merchant Category Code (MCC) controls restrict which types of merchants a card can transact with. You can define either an **allowlist** or a **blocklist**, but not both.

### Allowlist (`allowed_mcc`)

Only transactions with MCCs in this list are accepted. All other MCCs are declined.

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

### Blocklist (`blocked_mcc`)

Transactions with MCCs in this list are declined. All other MCCs are accepted.

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

<Warning>
  `allowed_mcc` and `blocked_mcc` **cannot** be set at the same time. Set one or the other, or omit both.
</Warning>

### Set MCC controls

Include `risk_controls` at card creation or use the [Update Card](/card-issuance/v1.6/api-reference/update-card) endpoint:

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

**Response:**

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

### Declined transaction example

When a transaction is declined due to MCC controls, the authorization webhook shows `transaction_status: DECLINED` with a description indicating the reason:

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

## Related

* [Create Card API](/card-issuance/v1.6/api-reference/create-card)
* [Update Card API](/card-issuance/v1.6/api-reference/update-card)
* [Card Updated webhook](/card-issuance/v1.6/webhooks/card-updated)
* [Card products](/card-issuance/v1.6/guide/card-products) — Which products support MCC controls