Enhancement 2: Spending Rulesets - API
Attention: API users
You no longer need to go to the Admin website to create, view or set spending rulesets.
A spending ruleset is a group of spend rules that can be applied to multiple card accounts. For example, if all cardholders should be allowed to spend at restaurants and fuel pumps, the administrator can create a spending ruleset that has only those merchant categories 'checked.' Every card with that ruleset applied can only spend at restaurants and fuel pumps.
At card creation, the spend rule defaults are:
- Daily spend limit NONE
- International spending is OFF
- All merchant categories are ON
CardNotPresentEnabled: This parameter allows you to control if PEX card can be used for the purchase when it is not present physically at POS (point of sale) E.g. Using PEX card for purchases over Internet or Telephone.
True - Can use when card is not present.
False - Cannot use when card is not present.
PEX has combined Merchant Category Codes (MCC) into larger groupings based upon merchant or service type. Below is the list of those combinations with examples of merchant types for each (this is not an exhaustive merchant listing):
- Associations & Organizations: post office, local and federal government services, religious organizations
- Automotive Dealers: vehicle dealerships (car, RV, motorcycle, boat, recreational)
- Educational Dervices: schools, training programs
- Entertainment: movies, bowling, golf, sports clubs
- Fuel & Convenience Stores: convenience stores and inside gas stations with an attendant
- Grocery Stores: food, bakeries, candy
- Healthcare & Childcare Services: medical services, hospitals, daycare
- Professional Services: heating, plumbing, HVAC, freight, storage, utilities, fuel oil, coal, dry cleaners
- Restaurants: fast food and sit-down restaurants
- Retail Stores: clothing, office supplies, hardware, building supplies, furniture, electronics
- Travel & Transportation: airlines, rental cars, trains, tolls, hotels, parking
- Fuel Pump Only: putdoor fuel pumps (i.e. pay at the pump)
- Hardware Stores: hardware, building supplies, construction materials, paint stores, and industrial equipment.
GET /spendingruleset
Implementation Notes
What it does: Return details of all spending rulesets for the business.
Model Schema
GetSpendingRulesetsResponse {
SpendingRulesets (array[SpendingRuleset], optional)
}
SpendingRuleset {
RulesetId (integer, optional),
BacctId (integer, optional),
Name (string),
CountCardsPresent (integer, optional),
DailySpendLimit (number, optional),
SpendingRulesetCategories (SpendingRulesetCategories, optional),
MccRestrictions (boolean, optional),
InternationalAllowed (boolean, optional),
CardNotPresentAllowed (boolean, optional)
}
SpendingRulesetCategories {
CategoryId (integer, optional),
AssociationsOrganizationsAllowed (boolean, optional),
AutomotiveDealersAllowed (boolean, optional),
EducationalServicesAllowed (boolean, optional),
EntertainmentAllowed (boolean, optional),
FuelPumpsAllowed (boolean, optional),
GasStationsConvenienceStoresAllowed (boolean, optional),
GroceryStoresAllowed (boolean, optional),
HealthcareChildcareServicesAllowed (boolean, optional),
ProfessionalServicesAllowed (boolean, optional),
RestaurantsAllowed (boolean, optional),
RetailStoresAllowed (boolean, optional),
TravelTransportationAllowed (boolean, optional),
HardwareStoresAllowed (boolean, optional)
}
POST /SpendingRuleset
Implementation Notes
What it does: Create a new spending ruleset for the business. Once the ruleset is created, it can be assigned to one or many cards.
Model Schema
CreateSpendingRulesetRequest {
Name (string): Spending Ruleset name,
DailySpendLimit (number, optional):Spending Ruleset daily spending limit,
SpendingRulesetCategories(SpendingRulesetCategories, optional):Spending Ruleset categories,
InternationalAllowed (boolean, optional):Spending Ruleset international purchases allowed,
CardNotPresentAllowed (boolean,optional): Spending Ruleset card not present allowed on purchases
}
SpendingRulesetCategories {
CategoryId (integer, optional),
AssociationsOrganizationsAllowed(boolean, optional),
AutomotiveDealersAllowed (boolean,optional),
EducationalServicesAllowed (boolean,optional),
EntertainmentAllowed (boolean, optional),
FuelPumpsAllowed (boolean, optional),
GasStationsConvenienceStoresAllowed(boolean, optional),
GroceryStoresAllowed (boolean, optional),
HealthcareChildcareServicesAllowed(boolean, optional),
ProfessionalServicesAllowed (boolean,optional),
RestaurantsAllowed (boolean, optional),
RetailStoresAllowed (boolean, optional),
TravelTransportationAllowed (boolean,optional),
HardwareStoresAllowed (boolean, optional)
}
PUT /SpendingRuleset
Implementation Notes
What it does: Modify an existing spending ruleset.
When you might use it.
1. Renaming the spend ruleset.
2. Resetting the daily spending limit (including the ability to assign no limit).
3. Allowing or not allowing international use.
4. Allowing or not allowing card not present use.
5. Turning merchant categories on or off.
Model Schema
UpdateSpendingRulesetRequest {
RulesetId (integer): Spending Ruleset Id,
Name (string): Spending Ruleset name,
CountCardsPresent (integer, optional):Spending Ruleset count cards present,
DailySpendLimit (number, optional):Spending Ruleset daily spending limit,
SpendingRulesetCategories(SpendingRulesetCategories, optional):Spending Ruleset categories,
MccRestrictions (boolean, optional):Spending Ruleset MCC restrictions,
InternationalAllowed (boolean, optional):Spending Ruleset international purchases allowed,
CardNotPresentAllowed (boolean,optional): Spending Ruleset card not present allowed on purchases
}
SpendingRulesetCategories {
CategoryId (integer, optional),
AssociationsOrganizationsAllowed(boolean, optional),
AutomotiveDealersAllowed (boolean,optional),
EducationalServicesAllowed (boolean,optional),
EntertainmentAllowed (boolean, optional),
FuelPumpsAllowed (boolean, optional),
GasStationsConvenienceStoresAllowed(boolean, optional),
GroceryStoresAllowed (boolean, optional),
HealthcareChildcareServicesAllowed(boolean, optional),
ProfessionalServicesAllowed (boolean,optional),
RestaurantsAllowed (boolean, optional),
RetailStoresAllowed (boolean, optional),
TravelTransportationAllowed (boolean,optional),
HardwareStoresAllowed (boolean, optional)
}
DELETE /SpendingRuleset
Implementation Notes
What it does: Delete an existing spending ruleset for the business. If one or more cards are assigned to a ruleset, that ruleset cannot be deleted.
Model Schema
DeleteSpendingRulesetRequest {
RulesetId (integer): Spending Ruleset Id
}
GET /SpendingRuleset/{Id}
Implementation Notes
What it does: Retrieve details of a specific spending ruleset.
Model Schema
GetSpendingRulesetResponse {
SpendingRuleset (SpendingRulesetGet, optional)
}
SpendingRulesetGet {
RulesetId (integer, optional),
Name (string),
DailySpendLimit (number, optional),
SpendingRulesetCategories (SpendingRulesetCategories, optional),
MccRestrictions (boolean, optional),
InternationalAllowed (boolean, optional),
CardNotPresentAllowed (boolean, optional)
}
SpendingRulesetCategories {
CategoryId (integer, optional),
AssociationsOrganizationsAllowed (boolean, optional),
AutomotiveDealersAllowed (boolean, optional),
EducationalServicesAllowed (boolean, optional),
EntertainmentAllowed (boolean, optional),
FuelPumpsAllowed (boolean, optional),
GasStationsConvenienceStoresAllowed (boolean, optional),
GroceryStoresAllowed (boolean, optional),
HealthcareChildcareServicesAllowed (boolean, optional),
ProfessionalServicesAllowed (boolean, optional),
RestaurantsAllowed (boolean, optional),
RetailStoresAllowed (boolean, optional),
TravelTransportationAllowed (boolean, optional),
HardwareStoresAllowed (boolean, optional)
}
GET /SpendingRuleset/{Id}/Cards
Implementation Notes
What it does: Retrieve all cards assigned to a particular spending ruleset. The response includes all card details.
Model Schema
CardholderDetailsResponse {
AccountId (integer): Unique cardholder account id,
Group (CardholderGroup, optional): Cardholder group details,
AccountStatus (string): Cardholder account status (OPEN or CLOSED),
LedgerBalance (number): Ledger balance for the card account, rounded to 2 decimal places,
AvailableBalance (number): Available balance for the card account, rounded to 2 decimal places,
ProfileAddress (Address): Profile address for the cardholder account,
Phone (string, optional): Phone number,
ShippingAddress (Address): Shipping address for the cardholder account,
ShippingPhone (string, optional): Shipping Phone number,
DateOfBirth (string): Cardholder date of birth,
Email (string): Cardholder email address,
CardList (array[CardDetail]): List of details about cards associated with the account,
SpendRules (SpendRules): Spend rules for the cardholder account,
ScheduledFunding (ScheduledFunding, optional): Scheduled funding details, if set,
LowBalanceFunding (LowBalanceFunding, optional): Low balance funding details, if set
}
CardholderGroup {
CardholderGroupId (integer): Unique id of the cardholder group,
GroupName (string): Name of the cardholder group,
Status (string) = ['Valid' or 'Deleted']: Cardholder group status (VALID, DELETED)
}
Address {
ContactName (string, optional): Contact first and last name,
AddressLine1 (string): Address line one,
AddressLine2 (string, optional): Address line two,
City (string): City,
State (string): State,
PostalCode (string): Zip code,
Country (string): Country
}
CardDetail {
CardId (integer): Unique id for the card,
IssuedDate (string): Date card was issued,
ExpirationDate (string): Expiration date for the card,
Last4CardNumber (string): Last four digits of card number,
CardStatus (string): Card status
}
SpendRules {
UseMerchantCategory (boolean, optional),
MerchantCategories (MerchantCategories, optional),
InternationalSpendEnabled (boolean, optional),
IsDailySpendLimitEnabled (boolean, optional),
DailySpendLimit (number, optional),
CardNotPresentUse (boolean, optional)
}
MerchantCategories {
AssociationsAndOrganizations (boolean, optional),
AutomotiveDealers (boolean, optional),
EducationalServices (boolean, optional),
Entertainment (boolean, optional),
FuelAndConvenienceStores (boolean, optional),
GroceryStores (boolean, optional),
HealthcareAndChildcareServices (boolean, optional),
ProfessionalServices (boolean, optional),
Restaurants (boolean, optional),
RetailStores (boolean, optional),
TravelAndTransportation (boolean, optional),
FuelPumpOnly (boolean, optional),
HardwareStores (boolean, optional)
}
ScheduledFunding {
Amount (number): Amount of scheduled funding, rounded to 2 decimal places,
Frequency (string) = ['DAY' or 'MONDAY' or 'TUESDAY' or 'WEDNESDAY' or 'THURSDAY' or 'FRIDAY' or 'SATURDAY' or 'SUNDAY' or 'FIRSTOFMONTH']: Describes when scheduled funding should occur.
Possible string values for Frequency parameter of scheduled funding are:
'0' or 'DAY' - every Day
'1' or 'MONDAY' - every Monday
'2' or 'TUESDAY' - every Tuesday
'3' or 'WEDNESDAY' - every Wednesday
'4' or 'THURSDAY' - every Thursday
'5' or 'FRIDAY' - every Friday
'6' or 'SATURDAY' - every Saturday
'7' or 'SUNDAY' - every Sunday
'8' or 'FIRSTOFMONTH' - every 1st of the Month
}
LowBalanceFunding {
ThresholdAmount (number): Threshold, rounded to 2 decimal places, to determine when funding should occur,
AmountToFund (number): Amount, rounded to 2 decimal places, to fund when threshold is hit
}
GET /Card/Profile/{Id}
A new optional field, SpendRulesetId, is returned with card profile. If there is no spending ruleset for the card, the field value is 0.
PUT /Card/SetSpendingRuleset
Add a spending ruleset to a card accountID.
To remove a card from the spending ruleset, use a zero (0) in the SpendRulesetId field.