Skip to content

Add a new transit provider

This set of guides describe the steps needed to add a new transit provider to the application and take them from testing to production.

Before starting any configuration, the Cal-ITP team and transit provider staff should have a kickoff meeting to confirm that information provided is complete, implementation plan is feasible, and any approvals needed have been obtained.

Then, the Cal-ITP team completes the steps below to configure the new transit provider in the Benefits application.

These items can all be done in parallel.

Create transit provider onboarding epic

Typically performed by the Benefits Product Manager.

  1. Navigate to the Cal-ITP Benefits repository, Actions tab
  2. Look in the left bar for the (pinned) workflow called Agency Onboarding Issue Scaffold, click on this to open the workflow run history
  3. In the center view, on the top right, look for a drop-down button that says Run workflow, and click this
  4. Leaving the branch selection the default (main), provide values for the other inputs (some of which are required)
    • For the Estimated launch date, enter a value like August 2026
    • For the Initiative issue, enter the number only like 1234
  5. Click the green Run workflow button under the input fields
  6. Refresh the current page to see an in-progress workflow run, wait for it to finish with a green checkmark

Once the workflow runs successfully, the onboarding epic and all sub-issues will have been created based on the input data provided. They can be further edited, modified from the USB, etc. as normal.

Add transit provider to adoption table

Typically performed by the Benefits Product Manager.

The workflow above will also open a Pull Request that adds the new transit provider to the adoption table in the README, similar to this example. It can be further modified as needed.

Typically performed by a designer.

The application currently requires one transit provider logo for display on the landing page. The logo should be white with a clear background in the dimensions below:

  • height: 64px
  • width: any

Add the transit provider to the application

Typically performed by a developer.

The basic config below is required, and typically the same whether you are adding the agency to the dev, test or prod environment:

  • Slug: Defines the agency’s unique landing page (no spaces or special characters)
  • Short name, long name, info URL, phone, enrollment flows and supported card schemes: Typically comes from the onboarding form
  • Logo: Found attached to the GitHub issue for logo production and in the Figma source
  • Transit processor config: leave blank for now
  • Active: Leave unchecked for now

The steps to create a transit processor config and associate it with your new agency are specific to the payment processor they contract with.

Agency naming guidance

When helping an agency decide on their long and short name configuration for the app, the following guiding principles should be considered:

  • The long name needs to be unique among all agencies, the short name does not
  • The short name should be recognizable to end-users
  • The long name and short name can match
  • If the agency is just a place-name (e.g. a city), tack the word Transit (or transit) onto it

Additional context about how and where agency names are displayed to users within the app:

Homepage

The agency drop-down selector:

  • [long name 1]
  • [long name 2]
  • [long name 3]

Help page

Don’t have access to a contactless card? … You can still get your transit benefit by going through [short name]’s application process. For updates on additional options, please check back on this website, or contact [short name].

[long name]

  • [phone number]
  • [website]

Agency landing page

Get your reduced fare when you tap to ride on [short name]

Benefit selection page

Cal-ITP doesn’t save any of your information. [short name] provides reduced fares to riders who qualify.

Or for agencies that are part of a region:

Cal-ITP doesn’t save any of your information. [short name] and nearby transit providers offer reduced fares to riders who qualify.

Enrollment success page

You were not charged anything today. When boarding public transit provided by [short name], tap this card and you will be charged a reduced fare.

Or for agencies that are part of a region:

You were not charged anything today. When boarding public transit at the following providers, tap this card and you will be charged a reduced fare:

  • [short name 1]
  • [short name 2]
  • [short name 3]

Configure for development and testing

For development and testing, only a Littlepay customer group is needed since there is no need to interact with any discount product. (We don’t have a way to tap a card against the QA system to trigger a discount and therefore have no reason to associate the group with any product.)

This work can begin once the transit provider has a contract in place with Littlepay.

  • Transit provider uses the Littlepay Merchant Portal to create a customer group in the Littlepay QA environment for each type of eligibility (e.g. older adult).
    • Typically performed by transit provider’s Account Manager
    • For each group that was created, a group ID will be returned and should be set as the group_id on a new LittlepayGroup.
  • Cal-ITP requests and receives Littlepay Back Office API access (for both PROD and QA) for the new transit provider.
    • Typically requested by a developer via email to Littlepay

For development and testing, the agency can use the same INT credentials as CST (stored in LastPass).

  • Switchio API credentials are typically requested by a Cal-ITP developer in Slack.
  • A SwitchioGroup is created in admin for each enrollment flow using identifiers common to other agencies.

Next steps: