Spending controls

Spending controls let you restrict how much a cardholder can spend per transaction, which merchant categories they can transact with, and which individual merchants 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"
  }
}

Merchant controls

Merchant controls restrict which individual merchants a card can transact with. Use them when MCC controls are too coarse — for example, to block one ride-hailing brand while leaving the rest of the category open.

Merchant controls are supported on Business Visa only. See Card products.

Find merchant codes

allowed_merchants and blocked_merchants take merchant codes, not merchant names. Look them up with List Merchant Brands. Filter by display_name (case-insensitive prefix match) or merchant_code (exact match). At least one filter is required — there is no way to list the whole catalog. Supplying both returns only the entries that match each filter.

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"

Response:

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

A brand can span several catalog entries. Configure every entry you want covered — selecting Grab does not imply Grabtaxi.

Allowlist (`allowed_merchants`)

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

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

Blocklist (`blocked_merchants`)

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

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

allowed_merchants and blocked_merchants cannot be set at the same time, and the list cannot exceed 20 entries. An unknown merchant code is rejected.

Set merchant 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: Bearer YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_controls": {
      "blocked_merchants": ["10000668", "10000418"]
    }
  }'

Response:

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

Retrieve Card returns the configured merchant codes under risk_controls:

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

Update and clear merchant controls

On Update Card, omitting allowed_merchants and blocked_merchants leaves the current configuration unchanged. Pass an empty array to clear it:

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

Switching between the two lists is a single call — setting a non-empty allowed_merchants clears any existing blocked_merchants, and the reverse.

How merchant and MCC controls interact

Merchant controls and MCC controls are evaluated independently, so one card can carry both. An update that touches only merchant fields leaves the existing MCC configuration in place, and an update that touches only MCC fields leaves the merchant configuration in place.

Create Card API
Update Card API
List Merchant Brands API
Card Updated webhook
Card products — Which products support MCC and merchant 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

Merchant controls

Find merchant codes

Allowlist (`allowed_merchants`)

Blocklist (`blocked_merchants`)

Set merchant controls

Update and clear merchant controls

How merchant and MCC controls interact

​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

​Merchant controls

​Find merchant codes

​Allowlist (allowed_merchants)

​Blocklist (blocked_merchants)

​Set merchant controls

​Update and clear merchant controls

​How merchant and MCC controls interact

​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

Merchant controls

Find merchant codes

Allowlist (`allowed_merchants`)

Blocklist (`blocked_merchants`)

Set merchant controls

Update and clear merchant controls

How merchant and MCC controls interact

Related