Merchant Spend Rules are used to limit where transactions are approved, and are based entirely on the merchant data of a transaction.

General Principles

Merchant Spend Rule Types

To create a merchant spend rule, create a spend rule where the SpendRule.type is merchant_allow or merchant_block.

As a rule of thumb, when you think about these SpendRule.types, its worth mentally picturing the word 'only' next to them. merchant_allow means that transactions are only allowed at merchants that match the rule criteria, and merchant_block means that transactions are only blocked at merchants that match the rule criteria.

For example, if you created a merchant_allow rule that triggers when the merchantCategory is "GROCERY_STORES_SUPERMARKETS", then that rule only approves transactions at grocery stores and super markets, all other transactions at merchants with a different merchantCategory will be declined.

Likewise, if you wanted to create a merchant_block that triggers when the merchantCategory is "GROCERY_STORES_SUPERMARKETS", then that rule only declines transactions at grocery stores and super markets, all other transactions at merchants with a different merchantCategory will be approved.

Spend Rule Restrictions

The restrictions array on the SpendRule is where we do the matching logic for a merchant rule - it's where you pass in all the merchant criteria that should trigger this rule.

For Merchant Spend Rules, the most important fields on each restriction are type and value.

Restriction Types

There are 3 applicable Restriction types for merchant spend rules:

merchant_category
merchant_name
merchant_id

To set a merchant restriction, you simply provide a restriction type and a value and our spend rule engine will determine if each transaction attempt triggers any of your set restrictions. The logic behind how our engine matches the values varies by each type, explained below:

merchant_category matches to the merchant.category field on the transaction, and corresponds to Mastercard and Visa's MCC designations for each merchant. To view all of the possible values you can provide associated with this type, please visit the MerchantCategories page in our documentation.

merchant_name matches to the merchant.name field on the transaction, and uses case-insensitive string.Contains matching. For example, if you wanted the restriction to trigger at a merchant where merchant.name = 'Walmart.com #55901', the values 'WALMART', 'walmart', 'walmar' and 'Walm' would all match this merchant here and trigger your rule. If you wanted to enforce an exact match for this rule to trigger, then you'd just need to set the value as 'Walmart.com #55901' instead.

merchant_id matches to the merchant.id field on the transaction and corresponds to Mastercard and VIsa's MID designation. This field uses case-sensitive string.Exact matching. For example, if you wanted to have the restriction to trigger at a specific merchant where the MID is '11098901234', then setting the value as '11098901234' is the only way to match and trigger this rule. Similarly, if the MID was 'WALM55901000', then only the setting the value to 'WALM55901000' will match, 'walm55901000' will not, nor will 'WALM5590'.

Examples

Example 1: lets create a merchant spend rule that blocks transactions at fast food, florists and veterinarian clinics.

We'll need to call CreateSpendRuleV1 with the following:

{
	"name": "Block Fast Food, Florists and Vets",
	"description": "This rule blocks transactions at fast food restaurants, florists and vet clinics",
	"type": "merchant_block",
	"applyTo": "cards",
	"restrictions": [
		{
		  "type": "merchant_category",
		  "value": "FAST_FOOD_RESTAURANTS"
		},
		{
			"type": "merchant_category",
			"value": "FLORISTS",
		},
		{
			"type": "merchant_category",
			"value": "VETERINARY_SERVICES",
		}
	]
}

This accomplishes exactly what we wanted. As a reminder, since our rule engine allows for stacking, we could also have created 3 separate rules, one with each restriction, and just applied them all instead to the same effect, but this is a lot neater, especially if this is going to be reused. Note that here the applyTo was set to "cards", and so this card isn't actually active unless its specifically added to selected cards via AddSpendRuleToCardsV1. If we wanted to apply this rule to all cards within a program instead, we'd need to set applyTo to program and pass in a programId.

Lets say we wanted to make the rule even more restrictive, and also block transactions at department stores. We can call UpdateSpendRuleV1 and just add an extra restriction to the above rule.

{
	"restrictionsToAdd": [
    {
    	"type": "merchant_category",
      "value": "DEPARTMENT_STORES"
    }
  ]
}

Example 2 Lets say we want to create a rule where all cards in the business are only allowed to work at Car Washes. But, we've noticed that there are two particular car washes chains that have MCCs that are mistakenly labeled as gas stations. We don't want to allow gas stations as an MCC, but we do want to make exceptions at these chains for all cards so that transactions do work there. Here, we can use a combination of our different restriction types.

{
	"name": "Only Allow Car Washes",
	"description": "This rule only allows car washes, and handles missed exceptions",
	"type": "merchant_allow",
	"applyTo": "business",
	"restrictions": [
		{
		  "type": "merchant_category",
		  "value": "CAR_WASHES"
		},
		{
			"type": "merchant_id",
			"value": "11092849551234",
		},
		{
			"type": "merchant_name",
			"value": "SPEEDY CAR WASH",
		}
	]
}

As we can see above, here the cards will only work at merchants where the merchantCategory is car washes, and also at Speedy Car Wash, or any place with the MID 11092849551234, so now the two mislabeled chains are also eligible here!

Never hesitate to reach out to your GiveCard implementation team for design guidance on getting your specific rule configuration right!