Configure Spend Rules

Spend rules allow you to automate decision-making on authorizations based on configurable logic like merchant category codes (MCC), dollar amount, authorization count, and more. Spend rules work by applying logic to authorizations and either permitting or restricting transactions based on that logic. The following graphic shows how a spend rule is create at the organization level, applied to a card product, and in turn applied to payment cards under that card product:

Spend rules can be coupled with velocity controls to allow for even more control. Velocity controls allow you to set time boundary constraints to established spend rules. For more information on velocity controls, see Configure Velocity Controls.

You can create spend rules from the Highnote dashboard or using the Highnote API. This guide provides an overview of creating spend rules using the Highnote API.

To create spend rules using the Highnote API, you must call the API using the spend rule's unique mutation. Each spend rule has a unique mutation and input variables.

We recommend factoring in potential ATM fees when creating an amount spend rule. For example, if you want to create an amount spend rule of $500, we recommend setting the spend rule at $505 or $510 to avoid potential declines due to ATM fees.

Amount spend rules are used to set limits on the maximum dollar amount a cardholder can spend in a single transaction. For example, if you set a limit of $100 for business expenses, the cardholder can purchase $100 worth of business expenses per transaction.

Use the following mutation to create amount spend rules:

You must attach authorization count spend rules to a velocity control. For more information on creating velocity controls, see Configure Velocity Controls.

Authorization count spend rules set a maximum number of transactions a cardholder can authorized within a given time period.

For example, you may want to limit cardholders to three transactions per week. To create this limit, you must create an authorization count spend rule for three and attach the spend rule to a velocity control with a weekly window.

Use the following mutation to create an authorization count spend rule:

A card transaction processing type refers to the method or protocol used to process a card event, such as a purchase or withdrawal.

A card transaction processing type rule is a spend rule that allows or blocks card transaction processing types. For a full list of card transaction processing types, see the CardTransactionProcessingType enum in the API Reference.

Use the following mutation to create a card transaction processing type rule:

Card verification value (CVV) spend rules require cardholders to enter their payment card’s CVV at the point of purchase. CVV validation reduces the risk of fraudulent transactions. When a mismatched CVV is entered at checkout, this spend rule blocks authorizations. An example use case for CVV spend rules is configuring the rule to auto-decline all authorizations in the event of a CVV mismatch.

Use the following mutation to create a card verification value spend rule:

You must pair conditional rules with a velocity control. For more information on creating velocity controls, see Configuring Velocity Controls.

A conditional rule is a spend rule that combines multiple spend rules together in an all-or-nothing approach. Conditional rules are always paired with velocity rules. Due to the all-or-nothing approach, for a conditional rule to pass, it must meet the following requirements:

• All rules contained within the velocity control must pass
• All rules contained within the velocity control must fail

Use the following mutation to create a conditional rule:

A deposit amount spend rule limits the dollar amount that an account holder can deposit in their Highnote financial account. Use the following mutation to create a deposit amount spend rule:

You must pair count spend rules a velocity control. For more information on creating velocity controls, see Configuring Velocity Controls.

A deposit count spend rule limits the numbers of times a cash deposit can be made within a set time period.

Use the following mutation to create a deposit count spend rule:

A deposit processing network spend rule limits which deposit processing networks can be used to make a deposit. For a full list of deposit processing networks, see the DepositProcessingNetwork enum in the API Reference.

Use the following example to create a deposit processing network spend rule:

Merchant category code (MCC) spend rules limit and prevent spending at specific merchants. For example, you can create MCC spend rules with the following logic:

• Block spending at specific merchants, for example, block cardholders from purchasing airline tickets.
• Exclusively permit cardholders to purchase fuel by blocking all other non-fuel related MCCs.

For a full list of MCCs, see the MerchantCategory enum in the API Reference.

Use the following mutation to create a merchant category spend rule:

When processing transactions, some merchants supply an identifier, called the merchant identifier (MID). In the Highnote API, the merchant identifier field accepts the input of either merchant or card acceptor identifiers.

A merchant identifier spend rule allows you to limit transactions for specific merchant identifiers. For example, you can restrict cardholders from using their payment cards at a particular online retailer.

Use the following mutation to create a merchant identifier spend rule:

Merchant country spend rules limit spending based on merchants' geographical locations. For example, you can create a merchant country spend rule that blocks cardholders from using their payment cards at merchants located in a specific country that your business has deemed high risk.

For a full list of countries that can be blocked using spend rules, see the ISO3166Alpha3Country enum in the API Reference.

Use the following mutation to create a merchant country spend rule:

Point of service category spend rules can permit or restrict purchases at certain types of payment terminals, such as ATMs or gas station fuel dispensers.

For a full list of point of service categories, see the PointOfServiceCategory enum in the API Reference.

Use the following mutation to create a point of service category spend rule:

Postal code verification spend rules specify which zip codes are allowed or blocked during address verification services (AVS).

Use the following mutation to create a postal code verification spend rule:

Street address spend rules require cardholders to enter their payment card’s associated address at the point of checkout for address validation service (AVS). AVS reduces the risk of fraud for card-not-present transactions, such as online transactions. When an address mismatch is entered at checkout, this spend rule blocks authorizations. An example use case for street address spend rules is configuring the rule to auto-decline all authorizations in the vent of an address mismatch.

Use the following mutation to create a street address spend rule:

Once you have created a spend rule, you can attach it to a card product. Spend rules attached to card products apply to all payment cards issued to the card product.

Use the following mutation to attach a spend rule to a card product:

Once you have created a spend rule, you can attach it to a payment card. Spend rules attached to payment cards apply to only that specific payment card.

Use the following mutation to attach a spend rule to a payment card:

Additionally, you can create different versions of spend rules. For example, you may want to update a spend rule without affecting existing card products or payment cards. By creating a new version of a spend rule, you can attach the new version to new card products or payment cards without affecting the already applied spend rules on existing ones. To create and attach different versions of spend rules, refer to the following steps:

1. Use the unique mutation for each spend rule to create a spend rule.
2. In the input variable field, add the version input field and provide a version number.
3. Run the mutation.
4. Use the AttachSpendRuleToCardProduct or AttachSpendRuleToPaymentCard mutations to attach a spend rule to your card product or payment card.
5. In the input variable field, add the version input field and provide the version number of your new spend rule.
6. Optional - Alternatively, you can use LATEST instead of the version number to ensure the card product or payment card always uses the latest version.
7. Run the mutation.

In some cases, you may need to update or remove the logic of a spend rule. Use the following mutation to detach a spend rule from a card product:

Use the following mutation to detach a spend rule from a payment card:

You can query TransactionEventIds to view the results of an authorization decision and any associated spend rules that may have declined an authorization. Use the following query to view spend rule results:

In some cases, you may need to update the logic of a spend rule. To update a spend rule:

1. Use the spend rule's unique UpdateSpendRule mutation.
2. Assign the updated spend rule a new version number.
3. Attach the new version to any card products or payment cards using the original spend rule.

For a full list of available UpdateSpendRule mutations, refer to the following API Reference links:

• updateConditionalRuleSetSpendRule
• updateCountLimitSpendRule
• updateCVVSpendRule
• updateDepositAmountLimitSpendRule
• updateDepositCountLimitSpendRule
• updateDepositProcessingNetworkSpendRule
• updateMerchantCategorySpendRule
• updateMerchantCountrySpendRule
• updateMerchantIdentifierSpendRule
• updatePointOfServiceCategorySpendRule
• updateStreetAddressSpendRule

The following code snippet provides an example of how you would update a merchant category spend rule: