docs: revise and simplify agency onboarding instructions by jgravois · Pull Request #3547 · cal-itp/benefits

jgravois · 2026-03-03T00:05:40Z

divide existing onboarding documentation into 4 distinct guides
simplify/update steps to account for recent model updates
write new documentation for Switchio

i don't have a better recommendation for testing this than opening the new pages and the old guide side-by-side.

https://docs.calitp.org/benefits/guides/onboard-transit-provider/

i think the reorganization is an improvement, but it certainly makes it such that you can't pick up on the line item changes in the existing steps in the diff.

github-actions · 2026-03-03T00:06:23Z

Coverage report

This PR does not seem to contain any modification to coverable code.

github-actions · 2026-03-03T00:06:37Z

Preview url: https://benefits-3547--cal-itp-previews.netlify.app

jgravois · 2026-03-05T22:13:03Z

i was surprised that an injected partial like this stops converting /secrets.md to /secrets automatically.

jgravois · 2026-03-05T22:14:21Z

+      - Choose the new `TransitAgency`.
+      - Retrieve Audience and Client ID values for the **production** config from shared LastPass note.
+      - Client Secret Name: `${agency_slug}-payment-processor-client-secret`
+      --8<-- "./inc/create-secret.md"


i was also surprised to find that i couldn't just place the partial in the previous /guides/inc directory and reference it like this 👇

--8<-- "../inc/create-secret.md"

As in, the partial/include is always relative to the top-level of the docs dir, regardless of where it is being used?

i've been thinking of it in terms of the --8<-- specifically possibly not being able to back out (or escape) the parent directory of the file currently being read.

it seemed harmless enough to scope the /inc where it ended up since no other guides reference it and i was clueless regarding how to debug the error, so i readily admit that i gave up trying to solve the riddle quite quickly.

jgravois · 2026-03-05T22:40:42Z

the hardest part of implementing this was figuring out how to dig up the v2 doc for this renamed plugin. 😂

https://github.com/lukasgeiter/mkdocs-awesome-nav/tree/v2

jgravois · 2026-03-06T19:07:27Z

i believe i addressed all @thekaveman's good feedback in ~~1727533~~ / 5f80d7e

lalver1

It's looking real nice @jgravois! I like how the guide flows, the tabbed sections work well and splitting out the add, prod validation, prod, and post-launch sections to individual pages was a great idea! I only have a few minor comments/typo sort of things below.

lalver1 · 2026-03-06T19:57:32Z

+    - Transit provider uses their Littlepay merchant ID 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`.
+      - The new `LittlepayGroup` is then associated with an enrollment flow and transit provider using the dropdowns. (See [Configuration data](../tutorials/load-sample-data.md) for more on loading the database.)


🤔 looks like something is broken in the Configuration data link.

lalver1 · 2026-03-06T19:58:16Z

+
+Next steps:
+
+- [Configure for production validation](./b-configure-production-validation.md)


Similarly, looks like something is broken in the Configure for production validation link.

lalver1 · 2026-03-06T19:58:26Z

+Next steps:
+
+- [Configure for production validation](./b-configure-production-validation.md)
+- [Configure for production](./c-configure-production.md)


Similarly, looks like something is broken in the Configure for production link.

lalver1 · 2026-03-06T20:14:31Z

-      - _Typically performed by transit provider's Account Manager_
-      - Once this is complete, verify that the setup is correct by using the [littlepay CLI](https://github.com/cal-itp/littlepay). Example:
+    1. Transit provider staff creates the discount product and associated customer groups in production Littlepay.
+    1. Transit provider provides group names and ids to Cal-ITPstaff takes a screenshot of the discount product in the Merchant Portal, making sure the browser URL is visible, and sends that to Cal-ITP.


Hmm, looks like something weird happened to this paragraph. I think we can remove the reference to taking a screenshot (I believe Kegan also mentioned this) and we could add something along the lines of "names and IDs of the groups that are relevant to the Benefits application". Because I feel like sometimes there's been a misunderstanding about which discounts Benefits actually supports. This way we don't get groups for youth or student discounts, for example.

lalver1 · 2026-03-06T20:33:37Z

-        - This will be set back to QA after final production configuration is complete.
+      - Set Environment to **Production** for production validation.
+        - This will be set back to **Testing** after final production configuration is complete.
      - Choose the new `TransitAgency`.


Would we need to update this from "Choose" to something like "Enter the slug of the new TransitAgency"? I think this is how the admin UI looks like at the moment.

good catch. there is definitely a dropdown, but this relationship is actually set from TransitAgency now. 🙃

i went with:

return to the TransitAgency and associate the new LittlepayConfig as its 'Transit processor config'.

lalver1 · 2026-03-06T20:52:20Z

-    1.  Cal-ITP associates the group with the discount product [created previously during production validation](#configuration-for-production-validation).
-      - Once this is complete, verify that the setup is correct by using the [littlepay CLI](https://github.com/cal-itp/littlepay).
+    1.  Transit agency creates a customer group **for production use** in production Littlepay.
+    1.  Transit agency associates the group with the discount product [created previously during production validation](#configuration-for-production-validation).


Something about this link seems like it's not taking me to the right place 🤔.

lalver1 · 2026-03-06T20:56:13Z

+    1.  Transit agency creates a customer group **for production use** in production Littlepay.
+    1.  Transit agency associates the group with the discount product [created previously during production validation](#configuration-for-production-validation).
+      - Once this is complete, Cal-ITP verifies that the setup is correct by using the [littlepay CLI](https://github.com/cal-itp/littlepay).
    1.  Cal-ITP creates a new `LittlepayGroup` in the Benefits prod environment:


Are we missing the "Cal-ITP creates a new TransitAgency in the Admin" step just before this one?

lalver1 · 2026-03-06T21:02:30Z


 === "Switchio"

    1. Cal-ITP creates a new `SwitchioConfig` in the Benefits production environment:


Are we missing a "Cal-ITP creates a new TransitAgency in the Admin" step just before this one?

lalver1 · 2026-03-06T21:03:07Z

Small typo, we have test instead of production

lalver1 · 2026-03-06T21:03:50Z

This link wasn't working for me 🤔

jgravois · 2026-03-06T23:15:20Z

great notes @lalver1! i incorporated your suggestions in ef3fb32.

lalver1

great notes @lalver1! i incorporated your suggestions in ef3fb32.

Thanks for making these changes @jgravois! It looks great! Just one tiny thing I noticed below.

lalver1 · 2026-03-09T16:08:54Z

+    1. Cal-ITP creates a new `LittlepayConfig` in the Benefits test environment:
+      - Set Environment to **Production** for production validation.
+        - This will be set back to **Testing** after final production configuration is complete.
+      - return to the `TransitAgency` and associate the new `LittlepayConfig` as its 'Transit processor config'.


Sorry, very minor comment, maybe we can capitalize "Return" here to keep the same formatting as the other bullet points.

no need to apologize 20bb81c 🤙

this feedback has been addressed.

lalver1

Nice job @jgravois! Looks good to me! 👍

jgravois · 2026-03-09T20:22:37Z

thank you @lalver1 et. al. 🌈

i'll go ahead and merge but if anyone else has any constructive criticism related to these updated guides, i'm genuinely interested in hearing it.

thekaveman

This is looking really good. I like the separated pages, tabbed sections, etc.

Just a few more content comments and questions.

this feedback has been addressed.

thekaveman

Nice 😎

Scotchester · 2026-03-09T21:46:05Z

I didn't do a thorough review since Luis and Kegan had it covered, but this looks great at a glance. Awesome work, John!

jgravois · 2026-03-09T21:54:33Z

i guarantee there's still room for improvement. we can keep iterating as we onboard new agencies (and further simplify the steps!) 😈

github-actions Bot assigned jgravois Mar 3, 2026

github-actions Bot added the documentation [auto] Improvements or additions to documentation label Mar 3, 2026

jgravois force-pushed the docs/3539 branch 8 times, most recently from a2e8bcd to 27eb88c Compare March 5, 2026 22:07

jgravois commented Mar 5, 2026

View reviewed changes

jgravois marked this pull request as ready for review March 5, 2026 22:38

jgravois requested a review from a team as a code owner March 5, 2026 22:38

jgravois commented Mar 5, 2026

View reviewed changes

thekaveman previously requested changes Mar 5, 2026

View reviewed changes

jgravois requested a review from a team March 6, 2026 19:07

lalver1 reviewed Mar 6, 2026

View reviewed changes

jgravois requested a review from a team March 7, 2026 00:03

jgravois added 8 commits March 6, 2026 16:32

docs: revise and simplify agency onboarding instructions

c5914f4

chore: split out guides and use tabs

fd2cb6d

chore: add switchio instructions

b27f378

docs: replace agency references with transit provider

68b071f

docs: use pages plugin instead of hack to order guides

bed4d14

docs: less prescriptive

5f80d7e

docs: fix broken links and other QA

ef3fb32

docs: fix one more issue caught during QA

487826b

jgravois force-pushed the docs/3539 branch from 2290626 to 487826b Compare March 7, 2026 00:32

lalver1 reviewed Mar 9, 2026

View reviewed changes

chore: doc copyedits

20bb81c

jgravois requested a review from a team March 9, 2026 17:13

lalver1 previously approved these changes Mar 9, 2026

View reviewed changes

thekaveman previously requested changes Mar 9, 2026

View reviewed changes

chore: copyedits from code review

7125c1b

jgravois dismissed lalver1’s stale review via 7125c1b March 9, 2026 20:38

jgravois requested a review from a team March 9, 2026 20:40

thekaveman requested changes Mar 9, 2026

View reviewed changes

Comment thread docs/guides/transit-provider-onboarding/add-transit-provider.md

chore: fix mangled tabbed content

aba19b4

thekaveman approved these changes Mar 9, 2026

View reviewed changes

lalver1 approved these changes Mar 9, 2026

View reviewed changes

jgravois merged commit 1077079 into main Mar 9, 2026
13 checks passed

jgravois deleted the docs/3539 branch March 9, 2026 21:42


		Next steps:

		- [Configure for production validation](./b-configure-production-validation.md)


		=== "Switchio"

		1. Cal-ITP creates a new `SwitchioConfig` in the Benefits production environment:

Uh oh!

Conversation

jgravois commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Uh oh!

github-actions Bot commented Mar 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgravois Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jgravois commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lalver1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgravois commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lalver1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lalver1 left a comment

Choose a reason for hiding this comment

Uh oh!

jgravois commented Mar 9, 2026

Uh oh!

thekaveman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jgravois commented Mar 3, 2026 •

edited

Loading

github-actions Bot commented Mar 3, 2026 •

edited

Loading

jgravois Mar 5, 2026 •

edited

Loading

jgravois commented Mar 6, 2026 •

edited

Loading

jgravois commented Mar 6, 2026 •

edited

Loading