An authorization rule (Auth Rule) is a control you can set to better manage the transactions on your cards. It enables you to allow or block transactions in specific countries, and allow or block transactions at specific merchant types.

To minimize conflict, any given entity (program, account, card) that makes up your program can only have one Auth Rule directly applied to it. However, any higher-level entity's Auth Rule will apply to all entities below it - e.g., a given card's transactions will be subject to the Auth Rule applied to the account that the card belongs to AND the Auth Rule applied to the program that the card belongs to.

Auth Rule Schema

{
  "token": String,
  "allowed_countries": List, 
  "blocked_countries": List, 
  "allowed_mcc": List,
  "blocked_mcc": List, 
  "state": String,
  "program_level": Boolean, 
  "card_tokens": List,
  "account_tokens": List
}

🚧

Note that the use of MCC or country restrictions beyond the terms included in your cardholder agreement with end-users may require additional steps to ensure compliance with card network policies. Use of these restrictions is an agreement from the API user that the restrictions are in compliance with your cardholder agreement terms. Reach out to your Customer Success rep for additional support.

Create Auth Rules

Creates an authorization rule and applies it at the program, account, or card level.

📘

This endpoint will reject an attempt to create an Auth Rule that conflicts with an existing Auth Rule that applies to the target entity. For example, if a program level Auth Rule blocks transactions in Canada, and an attempt is made to create a card level Auth Rule to allow transactions in Canada (on a card belonging to that program), the POST /auth_rules call will be rejected.

POST https://api.lithic.com/v1/auth_rules

Sample Request

curl https://api.lithic.com/v1/auth_rules \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "allowed_countries":["USA"],
      "allowed_mcc":["3000", "3001"],
      "program_level": true
}
'

Sample Response

{
    "allowed_countries": ["USA"],
    "blocked_countries": [],
    "allowed_mcc": ["3000", "3001"],
    "blocked_mcc": [],
    "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
    "program_level": true,
    "state": "ACTIVE",
    "card_tokens": [],
    "account_tokens": []
}

To successfully create an Auth Rule, at least one type of control parameter (country control, MCC control) and only one type of entity parameter (card, account, program-level) should be included in the request.

Update Auth Rules

Update the properties associated with an existing authorization rule.

PUT https://api.lithic.com/v1/auth_rules/{auth_rule_token}

Sample Request

curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f \
  -X PUT \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "allowed_countries":["USA","CAN"],
      "blocked_mcc":["3000","3001"]
}
'

Sample Response

{
    "allowed_countries": ["USA","CAN"],
    "blocked_countries": [],
    "allowed_mcc": ["3000","3001"],
    "blocked_mcc": [],
    "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
    "program_level": true,
    "state": "ACTIVE",
    "card_tokens": [],
    "account_tokens": []
}

To update an Auth Rule, at least one type of control parameter (country control, MCC control) should be included in the request. Note that using this endpoint will update the entire configuration of the Auth Rule, not just the parameters passed in.

List Auth Rules

List the properties and entities (program, accounts, and cards) associated with an existing authorization rule. If no Auth Rule token is provided, this endpoint will return all of the Auth Rules under the program.

GET https://api.lithic.com/v1/auth_rules/{auth_rule_token}

Sample Request

curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" 

Sample Response

{
    "allowed_countries": [
            "USA",
            "CAN"
    ],
    "blocked_countries": [],
    "allowed_mcc": [],
    "blocked_mcc": [
            "3000",
            "3001"
    ],
    "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
    "program_level": true,
    "state": "ACTIVE",
    "card_tokens": [],
    "account_tokens": []
}

Apply Auth Rule to Entity

Applies an existing authorization rule to a program, account(s), or card(s).

POST https://api.lithic.com/v1/auth_rules/{auth_rule_token}/apply

Sample Request

curl https://api.lithic.com/v1/auth_rules/d39e680e-af95-47ad-a78e-2415a0c8a81f/apply \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" 
  -d '
{
      "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec3"]
}
'

Sample Response

{
    "allowed_countries":["USA","CAN"],
    "blocked_countries": [],
    "allowed_mcc": [],
    "blocked_mcc": ["3000","3001"],
    "token": "d39e680e-af95-47ad-a78e-2415a0c8a81f",
    "program_level": true,
    "state": "ACTIVE",
    "card_tokens": [],
    "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec3"]
}

Remove Auth Rule from Entity

Remove an existing authorization rule from a program, account(s), or card(s). Note that any Auth Rule not applied to an entity will be automatically deactivated (i.e., status will be set to INACTIVE).

DELETE https://api.lithic.com/v1/auth_rules/remove

Sample Request

curl https://api.lithic.com/v1/auth_rules/remove/ \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" 
  -d '
{
    "account_tokens":["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec1"]
}
'

Sample Response

{
    "account_tokens": ["ecbd1d58-0299-48b3-84da-6ed7f5bf9ec1"],
    "card_tokens": [],
    "program_level": false
}

Merchant Category Codes (MCCs)

The below set of merchant category codes (MCCs) is provided for reference as you create and update Auth Rules.

Note that codes are subject to change and may differ by card network. The below codes and descriptions are for informational purposes only, and Lithic cannot guarantee that each will match those maintained by the networks. Additional MCCs not listed below can be passed in to the Create Auth Rules and Update Auth Rules endpoints to fit your use case.

Please refer to network-published MCC materials for the most recent information. We also recommend referring to actual data from past transactions on your cards to build the list of MCCs that you would like to allow or block via an Auth Rule.

Auth Rules FAQ