PEX Release Notes 4.4

April 5, 2016

This release includes three new enhancements to our API functionality and one to our Administrator and Cardholder websites. Address validation will now prevent you from entering invalid billing or shipping address information on your account. API users can now leverage the new spend rule sets functionality to limit card spend. API users no longer have to worry about triggering duplicate API requests. 

Enhancement 1: Address Validation
Enhancement 2: Spending Rulesets - API
Enhancement 3: Duplicate API Call Detection
Enhancement 1: Address Validation
Attention: Admins and API users

Now you don’t have to worry about entering in the wrong mailing address. The PEX platform will validate the address against a USPS database and provide a suggestion before you can submit your card order.

POST /Card/Create

A valid shipping address needs to be populated as part of request while creating new cards.

POST /Card/CreateAsync

A valid shipping address needs to be populated as part of request while creating new cards. 
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.
Enhancement 3: Duplicate API Call Detection
Attention: API users

The purpose of the duplicate detection logic within the API component of the PEX solution is to ensure that duplicate calls are not serviced if a specific pattern of calls is defined to be considered a duplicate. The Bulk Funding Endpoint will be configured with a 60 second time window setting. This means that if an identical request body is detected within 60 seconds, the call will not be serviced and will return a 409 response. This will prevent a customer from incorrectly funding the same batch of cards within a one minute period. The criteria is for the request to be identical in content of which cards are being funded and the amounts being funded. If two calls are made with different cards, or different amounts, the calls will not be considered as duplicates and will be serviced.
Questions or comments about the release? Please email or call us at 1-877-274-3390.


Email Us Release Archive
Back to Top