❗️

Authorization Rules (V1) has been discontinued.

Auth Rules (V1) has been superseded by a newer, improved version and V1 endpoints have been removed. The methods described on this page are no longer available. Please see Auth Rules (V2) for current information about improved Lithic-hosted Authorization Rules.

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.

See Merchant Category Codes (MCCs) for a detailed list of MCCs that can be used in creating and modifying Auth Rules.

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
}

Auth Rules FAQ