Set merchant category

Set Merchant Category Spend Rule

The POST /api/spendRules/merchantCategory endpoint allows you to set or update merchant category-based spend rules for a specific payment card. You can define which merchant categories are permitted or explicitly blocked, giving you granular control over where and how a card can be used. This is useful for enforcing corporate spending policies, parental controls, or targeted budget management.

Endpoint

POST /api/spendRules/merchantCategory

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when you need to restrict or allow card spending based on merchant category codes (MCCs). For example, a business may want to allow only fuel and dining categories on a fleet card, or block gambling and entertainment categories on an employee card. Rules apply at the card level and take effect immediately upon creation.

Request Body

{
  "paymentCardId": "card_a1b2c3d4e5f6",
  "allowed": [
    "SERVICE_STATIONS",
    "EATING_PLACES_RESTAURANTS",
    "FAST_FOOD_RESTAURANTS",
    "GROCERY_STORES_SUPERMARKETS"
  ],
  "blocked": [
    "BETTING_CASINO_GAMBLING",
    "PACKAGE_STORES_BEER_WINE_AND_LIQUOR",
    "GOVERNMENT_LICENSED_ON_LINE_CASINO"
  ]
}

Merchant Category Enum Values (partial list)

The allowed and blocked arrays accept string values from the merchantCategory enum. Common values include:

For the complete list of supported enum values, refer to the bank.client.common.merchantcategory schema in the OpenAPI definition.

Response

200 OK

A 200 OK response indicates the merchant category spend rule was successfully created or updated on the specified payment card. The response body is empty on success.

{}

Error Codes

Common Mistakes

• Providing both allowed and blocked with overlapping merchant categories — a category should not appear in both arrays simultaneously, as this creates conflicting rules.
• Using free-text merchant names instead of the exact enum string values (e.g., using "McDonald's" instead of "FAST_FOOD_RESTAURANTS").
• Omitting paymentCardId — this is a required field and the request will fail with a 400 error without it.
• Sending an empty allowed array ([]) expecting it to allow all categories — use null instead if you do not want an explicit allowlist.
• Attempting to apply spend rules to a card that has already been deactivated or cancelled.

Related Endpoints

• POST /api/spendRules/merchantCategory — Set or update merchant category spend rules on a card
• POST /api/spendRules/velocityLimit — Set transaction velocity (frequency and amount) limits on a card
• GET /api/spendRules/{paymentCardId} — Retrieve all active spend rules for a payment card
• DELETE /api/spendRules/{spendRuleId} — Remove a specific spend rule from a card
• POST /api/paymentCards — Create a new payment card (Physical, Virtual, or Burner)

Example

curl -X POST https://api.banking.netevia.dev/api/spendRules/merchantCategory \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCardId": "card_a1b2c3d4e5f6",
    "allowed": [
      "SERVICE_STATIONS",
      "EATING_PLACES_RESTAURANTS",
      "FAST_FOOD_RESTAURANTS",
      "GROCERY_STORES_SUPERMARKETS"
    ],
    "blocked": [
      "BETTING_CASINO_GAMBLING",
      "PACKAGE_STORES_BEER_WINE_AND_LIQUOR",
      "GOVERNMENT_LICENSED_ON_LINE_CASINO"
    ]
  }'