Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Running the application locally is possible with [Docker and Docker Compose][doc
The user interface and content is available in both English and Spanish. Additional language support is possible via Django's
[i18n and l10n features][i18n].

The application communicates with external services like [Littlepay][littlepay] via API calls and others like the [Identity Gateway](https://dev.auth.cdt.ca.gov) via redirects, both over the public internet. See [all the system interconnections][interconnections].
The application communicates with external [transit processor vendors](#transit-processors) via API calls and others like the [Identity Gateway](https://digitalidstrategy.cdt.ca.gov/primary-elements.html) via redirects, both over the public internet. See [all the system interconnections][interconnections].

### Infrastructure

Expand All @@ -79,19 +79,29 @@ The Benefits application doesn't collect or store any user data directly, and we

Sensitive user information exists in the following places:

- To enroll in a senior discount, users need to [provide personal information to Login.gov](https://benefits.calitp.org/help#login-gov-verify).
- Users need to [provide their credit or debit card information to our transit processor (Littlepay)](https://benefits.calitp.org/help#littlepay) to enroll in a discount.
- To enroll for reduced fares as an older adult, U.S. Veteran, or Calfresh cardholder, riders need to [provide personal information to Login.gov](https://benefits.calitp.org/help#login-gov-verify).
- To enroll for reduced fares as a Medicare cardholder, riders need to [provide personal information to Medicare.gov](https://www.medicare.gov/basics/get-started-with-medicare).
- Eligible riders need to provide their contactless credit or debit card information to one of our [transit processors](#transit-processors), to register their card for reduced fares.

None of that information is accessible to the Benefits system/team.

Learn more about the security/privacy practices of some of our third-party integrations:

- [Amplitude](https://amplitude.com/amplitude-security-and-privacy)
- [Littlepay](https://littlepay.com/privacy-policy/)
- [Switchio](https://switchio.com/privacy-policy/)
- [Login.gov](https://www.login.gov/policy/)

Benefits collects analytics on usage, without any identifying information. You can find more details on [our analytics page](product-and-design/analytics/).

### Transit processors

The Benefits application integrates with transit processors to securely register credit or debit cards. This application currently supports the following transit processors:

- [Littlepay][littlepay]
- [Switchio][switchio]


### Practices

[Dependabot](https://github.com/features/security/software-supply-chain) immediately notifies the team of vulnerabilities in application dependencies.
Expand All @@ -107,4 +117,5 @@ All code changes are reviewed by at least one other member of the engineering te
[interconnections]: deployment/infrastructure/#system-interconnections
[hosting]: deployment/
[littlepay]: https://littlepay.com/
[switchio]: https://switchio.com/transport/
[i18n]: https://docs.djangoproject.com/en/5.0/topics/i18n/
80 changes: 43 additions & 37 deletions docs/enrollment-pathways/agency-cards.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,46 @@
# Agency Cards
# Agency cards

_Agency Cards_ is a generic term for reduced fare programs offered by Transit Providers, such as the
[Courtesy Card program from Monterey-Salinas Transit (MST)](https://mst.org/riders-guide/how-to-ride/courtesy-card/).
An _agency card_ is a generic term for the proprietary physical card tranist providers issue to eligible riders to show they participate in the provider's reduced fare program. The [Courtesy Card program](https://mst.org/riders-guide/how-to-ride/courtesy-card/) at Monterey-Salinas Transit (MST) is a good example. Agency card programs pre-date the option of fare collection using contactless payments. Transit providers often require riders to show the card to bus operators when boarding to prove their eligibility for reduced fares.

Agency cards are different from our other use cases in that eligibility verification happens on the agency side (offline) rather
than through the Benefits app, and the Benefits app then checks for a valid Agency Card via an [Eligibility API call](https://docs.calitp.org/eligibility-api/specification/).
During the pilot phase of Cal-ITP Benefits, we offered the agency card enrollment option to transit providers that were early adopters of contactless payments and wanted to use Cal-ITP Benefits as a way to enroll riders in discount groups the application didn't yet support, such as Medicare cardholders and people with disabilities. As the range of enrollment options in the app expands to cover previously unsupported discount groups, the agency card enrollment option becomes less necessary. We plan to deprecate the agency card enrollment option when the application offers enrollment pathways for all required groups.

The agency card enrollment option differs from other options in the application because of the way the app verifies a rider's eligibility for transit benefits. When a rider chooses the agency card enrollment pathway, the application uses the [Eligibility API call](https://docs.calitp.org/eligibility-api/specification/). This API call queries data stored offline on the agency side to confirm the rider is active in the program. For all other enrollment options, the Cal-ITP Benefits app confirms rider eligibility by querying external data sources via to the CDT Identity Gateway. See the [older adult enrollment pathway](https://docs.calitp.org/benefits/enrollment-pathways/older-adults/) as one example.

## Demonstration

Here's a video showing what the flow looks like, having agency cardholders confirm eligibility via the Eligibility Server and enroll via Littlepay:
This video shows the rider experience enrolling for transit benefits using the agency card enrollment pathway.

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/_iOb19cLg30?si=G-4-CiNd88_vp0dj&amp;controls=0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

## Architecture

In order to support an Agency Cards deployment, the Transit Provider produces a list of eligible users
(CSV format) that is loaded into an instance of [Eligibility Server](https://docs.calitp.org/eligibility-server/) running in the Transit Provider's cloud.
To support an agency card deployment in Cal-ITP Benefits, the transit provider produces a list of eligible riders in CSV format. That file is loaded into an instance of the [Eligibility Server](https://docs.calitp.org/eligibility-server/) running in the transit provider's cloud.

Cal-ITP makes the [`hashfields` tool](https://docs.calitp.org/hashfields) to facilitate masking user data before it leaves Transit Provider on-premises systems.
Cal-ITP uses the [`hashfields` tool](https://docs.calitp.org/hashfields) to mask user data before it leaves the transit provider's on-premises systems to protect rider personal information.

The complete system architecture looks like:
### System architecture

```mermaid
flowchart LR
rider((User's browser))
rider((Rider's browser))
benefits[Cal-ITP Benefits]
api[Eligibility Server]
data[Hashed Agency Card data]
cardsystem[Data source]
data[Hashed list of eligible riders]
cardsystem[Agency card data source]

rider --> Benefits
rider --> benefits

subgraph CDT Azure
Benefits
subgraph CDT Azure Environment
benefits
end

Benefits --> api
benefits <--> api

subgraph Transit Provider cloud
subgraph Transit provider cloud
api --> data
end

subgraph Transit Provider on-prem
subgraph Transit provider on-prem
cardsystem --> hashfields
end

Expand All @@ -52,27 +52,33 @@ Notes:
- [Eligibility Server source code](https://github.com/cal-itp/eligibility-server)
- [hashfields source code](https://github.com/cal-itp/hashfields)
- [More details about the Benefits architecture](../../deployment/infrastructure/#architecture)
- In MST, the `Data Source` is Velocity, the system MST uses to manage and print Courtesy Cards
- At MST, the `Data Source` is Velocity, the product MST uses to manage and print Courtesy Cards.

## Process

```mermaid
sequenceDiagram
actor Rider
participant Benefits as Benefits app
participant elig_server as Eligibility Server
participant cc_data as Hashed data
participant Data Source
participant Littlepay

Data Source-->>cc_data: exports nightly
cc_data-->>elig_server: gets loaded on Server start

Rider->>Benefits: visits site
Benefits-->>elig_server: passes entered Agency Card details
elig_server-->>Benefits: confirms eligibility

Benefits-->>Littlepay: enrollment start
Rider->>Littlepay: enters payment card details
Littlepay-->>Benefits: enrollment complete
autonumber
actor Transit rider
participant Benefits as Cal-ITP Benefits
participant elig_server as Eligibility server
participant ac_data as Hashed listed of eligible riders
participant Agency card data source
participant Transit processor

Agency card data source-->>ac_data: exports nightly
activate ac_data
ac_data-->>elig_server: loaded on server start
Transit rider->>Benefits: visits benefits.calitp.org
activate Benefits
Benefits-->>elig_server: provides agency card details
activate elig_server
elig_server-->>Benefits: returns eligibility status (y/n)
deactivate elig_server
Benefits-->>Transit processor: payment enrollment start
activate Transit processor
Transit rider->>Transit processor: provides debit or credit card details
Transit processor-->>Benefits: card registration confirmation
deactivate Transit processor
deactivate Benefits
```
26 changes: 13 additions & 13 deletions docs/enrollment-pathways/low-income.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

## Overview

This use case describes a feature in the Cal-ITP Benefits app that allows Californians to verify their active participation in the CalFresh Program—as a proxy for low-income status—to receive reduced fares for transit when paying by contactless debit or credit card at participating transit operators in California.
This use case describes a feature in the Cal-ITP Benefits app that allows Californians to verify their active participation in the CalFresh Program—as a proxy for low-income status—to receive reduced fares for transit when paying by contactless debit or credit card at participating transit providers in California.

**Actor:** A person who uses public transit in California. For benefit eligibility, a “low-income rider” is a person who has received [CalFresh benefits](https://www.cdss.ca.gov/food-nutrition/calfresh) in any of the previous three months.

**Goal:** To verify a transit rider’s financial need so they receive reduced fares when paying by contactless debit or credit card.

**Precondition:** The California transit operator offers fixed route service, has installed and tested validator hardware necessary to collect fares using contactless payment on bus or rail lines, and the operator has a policy in place to offer a transit discount to low-income riders.
**Precondition:** The California transit provider offers fixed route service, has installed and tested validator hardware necessary to collect fares using contactless payment on bus or rail lines, and the operator has a policy in place to offer a transit discount to low-income riders.

## Demonstration

This video demonstrates how a person receiving CalFresh benefits uses the Cal-ITP Benefits web application to confirm their eligibility for a transit benefit and then register their contactless debit or credit card with Littlepay. Once registered, they will automatically receive reduce fares each time they tap-to-pay for transit.
Here's a video showing what the flow looks like for a person receiving CalFresh benefits to confirm their eligibility for a transit benefit through Login.gov and then register their contactless debit or credit card with Littlepay, one of the supported transit processors:

<iframe width="560" height="315" src="https://www.youtube.com/embed/LrNyy8k2DPA?si=30hPKkR1valKZFzA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Expand All @@ -27,7 +27,7 @@ autonumber
participant IdG as Identity Gateway
participant Login.gov
participant CDSS
participant Littlepay
participant Transit processor
Transit Rider->>Benefits: visits benefits.calitp.org
activate Benefits
Benefits-->>IdG: eligibility verification
Expand All @@ -46,17 +46,17 @@ CDSS-->>IdG: return Calfresh enrollment status
IdG-->>Benefits: eligibility response
deactivate IdG
deactivate Login.gov
Benefits-->>Littlepay: payment enrollment start
activate Littlepay
Transit Rider->>Littlepay: provides debit or credit card details
Littlepay-->>Benefits: payment method enrollment confirmation
deactivate Littlepay
Benefits-->>Transit processor: payment enrollment start
activate Transit processor
Transit Rider->>Transit processor: provides debit or credit card details
Transit processor-->>Benefits: payment method enrollment confirmation
deactivate Transit processor
deactivate Benefits
```

1. The transit rider visits the web application at `benefits.calitp.org` in a browser on their desktop computer.

1. The transit rider chooses the transit operator that serves their area.
1. The transit rider chooses the transit provider that serves their area.

1. The transit rider chooses to verify their eligibility as a participant in the [CalFresh Program](https://www.cdss.ca.gov/food-nutrition/calfresh).

Expand All @@ -68,7 +68,7 @@ Littlepay-->>Benefits: payment method enrollment confirmation

1. The IdG then passes the response from CDSS as low-income status = TRUE to the Cal-ITP Benefits app to indicate the person is eligible for a benefit.

1. The transit rider provides the debit or credit card details they use to pay for transit to Littlepay, the transit processor that facilitates transit fare collection.
1. The transit rider provides the debit or credit card details they use to pay for transit to the transit processor that facilitates fare collection for the transit provider.

1. The app registers the low-income benefit with the transit rider’s debit or credit card.

Expand All @@ -86,7 +86,7 @@ Littlepay-->>Benefits: payment method enrollment confirmation

- Suppose the transit rider attempts to re-enroll for a transit benefit as a CalFresh Program participant three months after their enrollment period started. The app will inform them they must wait re-enroll within 14 days of the benefit expiration.

- Suppose the transit rider doesn’t re-enroll for a transit benefit after one year, but continues paying for transit using the card they registered. The transit operator will charge the rider full fare.
- Suppose the transit rider doesn’t re-enroll for a transit benefit after one year, but continues paying for transit using the card they registered. The transit provider will charge the rider full fare.

- If the transit rider uses more than one debit or credit card to pay for transit, they repeat the basic flow for each card.

Expand Down Expand Up @@ -118,4 +118,4 @@ The transit rider receives a fare reduction each time they use the debit or cred

A CalFresh Program participant uses public transit regularly. They don’t have a car and depend on buses to get to appointments and do errands that take too long to use their bicycle. Even though this person already qualifies for benefits from the California Department of Social Services, they had to navigate another extensive, in-person eligibility process with different requirements to qualify for reduced fares from their local transit agency. They now receive a 50% fare reduction but have to pay for transit rides using the closed loop card provided by the operator to receive the reduced fare. It’s frustrating and inconvenient to reload this closed loop card in $10 payments every week, especially because they sometimes they could use the money tied up on the card to make ends meet. In summary, this person pays for daily expenses using three forms of payment: their Electronic Benefits Transfer (EBT) card for eligible items, their agency card for transportation, and their bank card (or cash) for everything else.

The transit operator serving their region of California implements contactless payments on fixed bus routes throughout the service area. This rider uses `benefits.calitp.org` on their mobile device to confirm their participation in the CalFresh Program offered by CDSS and registers their debit card for reduced fares. They tap to pay when boarding buses in their area and are automatically charged the reduced fare. While they still need to manage funds on their EBT card _and_ their bank card, they no longer need to use their transit operator card to pay for transit. Best of all, they have complete access to all funds in their weekly budget. If other expenses are higher one week, they can allocate additional funds to those areas and ride transit less.
The transit provider serving their region of California implements contactless payments on fixed bus routes throughout the service area. This rider uses `benefits.calitp.org` on their mobile device to confirm their participation in the CalFresh Program offered by CDSS and registers their debit card for reduced fares. They tap to pay when boarding buses in their area and are automatically charged the reduced fare. While they still need to manage funds on their EBT card _and_ their bank card, they no longer need to use their transit provider card to pay for transit. Best of all, they have complete access to all funds in their weekly budget. If other expenses are higher one week, they can allocate additional funds to those areas and ride transit less.
Loading
Loading