Spending controls

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 request:

{
  "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 endpoint:

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:

{
  "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.

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.

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.

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

Blocklist (`blocked_mcc`)

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

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

allowed_mcc and blocked_mcc cannot be set at the same time. Set one or the other, or omit both.

Set MCC controls

Include risk_controls at card creation or use the Update Card endpoint:

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:

{
  "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:

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

Create Card API
Update Card API
Card Updated webhook
Card products — Which products support MCC controls

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

Per-transaction limits

Set at card creation

Update on an existing card

MCC controls

Allowlist (`allowed_mcc`)

Blocklist (`blocked_mcc`)

Set MCC controls

Declined transaction example

​Per-transaction limits

​Set at card creation

​Update on an existing card

​MCC controls

​Allowlist (allowed_mcc)

​Blocklist (blocked_mcc)

​Set MCC controls

​Declined transaction example

​Related

Per-transaction limits

Set at card creation

Update on an existing card

MCC controls

Allowlist (`allowed_mcc`)

Blocklist (`blocked_mcc`)

Set MCC controls

Declined transaction example

Related