Filtered Spend Programs Quick Start

This guide covers programs where spend controls are the primary complexity — OTC benefits, healthy food allowances, rewards, and other restricted spend programs.

Filtered spend programs follow the same enrollment and funding model as plan-owned programs. This guide focuses on what's different: Approved Product Lists (APLs), purse configuration, and authorization rules.

What Makes Filtered Spend Different

Spend is restricted by merchant, category, or item (UPC/SKU level)
Authorization logic checks APL before approving transactions
Members may have multiple purses on one card (OTC + Food + Rewards)
Can be funded via PBP (Plan Benefit Package) with scheduled allocations
Common for Medicare Advantage supplemental benefits

Primary Audience

Health plans offering MA supplemental benefits (OTC, Food, Rewards, etc.)
Employers offering wellness incentives with restrictions
Programs requiring SKU-level or merchant-level controls

Products Covered

Product	Description	Typical Funding
OTC	Over-the-counter items	Good-Faith
FOOD	Grocery / healthy food	Good-Faith
REWARDS	Rewards & incentives	Fully-Funded
INCENTIVE	Incentive programs	Good-Faith
FILTERED	Any custom filtered purse t	Varies

How Filtered Spend Works

Member swipes card
       ↓
Merchant allowed? (MCC)
       ↓
Item allowed? (APL check)
       ↓
Sufficient balance?
       ↓
APPROVE / DECLINE

Key Concepts

Concept	Description
APL	Defines eligible UPCs/SKUs
Purse	Balance bucket per benefit
MCC	Merchant category restrictions
Sub_Program	Links BIN, purses, APL

Configuration Responsibilities

Lynx Configures

Sub_Program
Purses
APL (default or custom)
MCC restrictions
Funding rules
Card package

You Configure

Member product assignments
Benefit amounts
Custom APL (if applicable)
Branding

Enrollment

Filtered spend follows plan-owned model:

No KYC
Immediate approval

Required Fields

Field	Type
clientMemberId	string
clientOrg.name	string
firstName	string
lastName	string
dateOfBirth	string
addresses	array
phones	array
memberProducts	array
memberCardPreferences.planName	string
memberCardPreferences.cardPackageName	string
idempotencyKey	string

Example: OTC + Food + Rewards

curl -X POST "https://sandbox.lynx-fh.co/api/v1/member" \
  -H "Authorization: Bearer {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientMemberId": "MA-MEMBER-001",
    "clientOrg": { "name": "HEALTHPLAN_MA_2026" },
    "firstName": "Mary",
    "lastName": "Johnson",
    "dateOfBirth": "1955-03-20",
    "addresses": [{
      "addressLine1": "789 Palm Dr",
      "city": "Miami",
      "state": "FL",
      "postalCode": "33101",
      "country": "US",
      "primaryIndicator": true
    }],
    "phones": [{
      "number": "+13055551234",
      "primaryIndicator": true
    }],
    "memberProducts": [
      { "product": { "name": "OTC" }, "effectiveDate": "2026-01-01" },
      { "product": { "name": "FOOD" }, "effectiveDate": "2026-01-01" },
      { "product": { "name": "REWARDS_01" }, "effectiveDate": "2026-01-01" }
    ],
    "memberCardPreferences": {
      "planName": "MA_SUPP_BENEFITS_2026",
      "cardPackageName": "HEALTHPLAN_CARD_2026"
    },
    "idempotencyKey": "enrollment-mary-johnson-001"
  }'

What Happens After Enrollment

Validation occurs
Member created (ACTIVE)
Products created (Account_Active)
Purses created with balances
Card issued
Webhooks fire

Checking Account Balances

curl -X GET "https://sandbox.lynx-fh.co/api/v1/member/{clientMemberId}/accounts?clientOrgName={clientOrgName}" \
  -H "Authorization: Bearer {your_api_token}"

{
  "memberAccounts": [
    { "product": { "name": "OTC" }, "balance": 50.00, "purse": "OTC_PURSE" },
    { "product": { "name": "FOOD" }, "balance": 75.00, "purse": "FOOD_PURSE" },
    { "product": { "name": "REWARDS_01" }, "balance": 25.00, "purse": "REWARDS_PURSE" }
  ]
}

Authorization Logic

Step	Description
Merchant Check	Allowed merchant?
Item Check	UPC on APL?
Balance Check	Enough funds?
Decision	Approve or decline

Example Transaction

Item	APL	Purse	Result
Vitamins	Yes	OTC	Approved
Vegetables	Yes	Food	Approved
Cigarettes	No	None	Declined

APL Types

Type	Description
Lynx Managed	Standard list
Client Custom	Custom UPC list
Category-Based	MCC-level

Funding Models

Model	Description
PBP	Scheduled allocations
Good Faith	Front-loaded
Lump Sum	Full upfront

Authorization Webhooks

Event	Meaning
lynx.authorization.approved	Approved
lynx.authorization.declined	Declined
lynx.transaction.settled	Settled

Decline Reasons

Reason	Description
INSUFFICIENT_BALANCE	Not enough funds
ITEM_NOT_ELIGIBLE	Not on APL
MERCHANT_NOT_ALLOWED	MCC blocked
CARD_NOT_ACTIVE	Card inactive
PROGRAM_NOT_ACTIVE	Benefit expired

Card Model

One card
Multiple purses
Smart routing at authorization

Virtual vs Physical

Type	Use
Physical	Retail
Virtual	Online
Both	Hybrid

E-Commerce Integration

Filtered spend can pair with storefront:

APL filtering
Cart validation
Order processing

Sandbox Testing

No special data required
All enrollments succeed

After Enrollment

Action	Guide
Build storefront	Commerce Quick Start
Show card	VGS