158910 :: fix: correct merchant API auth, and stop disclosing internal topology

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909

[ankitottu]

Follow-up to #169. Two corrections to the AutoPay developer page that were made after that PR was already merged, so they need a second pass.

Redmine #158910 · epic #158909

1. The merchant API auth was wrong

The six subscription-management endpoints were documented against AutoPay's internal service — wrong path, wrong credential. The page told developers to obtain a Keycloak JWT and send a Merchant-Id header, and carried a warning that the JWT flow "isn't documented yet".

None of that is true for a merchant. Verified live on betabulk:

Api-Key -> 200
no auth -> 401
Merchant-Id omitted -> 200

	Before	After
Path	.../subscriptions/	.../b/pbl/v2/subscriptions/
Credential	Authorization: Bearer <jwt_token>	Authorization: Api-Key <YOUR_API_KEY>
Extra header	Merchant-Id: required	not needed — removed
Warning block	"Getting the JWT isn't documented yet"	deleted; there is no JWT

Also brought the retrieve response example in line with the live payload — added setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description. Diffed field-by-field against a real response: zero differences either direction.

2. The page disclosed internal service topology

Merchants integrate against Connect. How Ottu routes a request internally is not their concern and does not belong on a public page. Five disclosures removed:

• "You never talk to AutoPay directly … Connect resolves your merchant from the API key and forwards the call"
• "reach AutoPay through Ottu Connect at …"
• Workflow step 2: "Ottu Connect commits and calls AutoPay synchronously …"
• The flow diagram — two boxes, Ottu Connect / Commits the transaction → AutoPay / Creates the subscription, with an internal creates subscription · sync arrow between them. Now one AutoPay box; the ongoing box reads Handled for you rather than "Owned by AutoPay".
• The <desc> and alt text — invisible in the browser, shipped to every screen reader, and spelled the topology out in full. This one would not have shown up in any review of the rendered page.

Workflow step 2 now states the merchant-visible fact instead: the result comes back on the same response, not later by webhook; a failure returns 4xx with no usable session_id.

The endpoint path stays — a caller needs the URL. What is gone is narrating what sits behind it.

Added a PUBLIC SURFACE note in the diagram source so the topology does not get reintroduced by a future edit.

Verification

POST /b/pbl/v2/subscriptions/ 200
GET /b/pbl/v2/subscriptions/{id}/ 200
GET /b/pbl/v2/subscriptions/{id}/cycles/ 200

• npm run typecheck ✅ · npm run build ✅
• 0 matches for Ottu Connect / forwards the call / talk to AutoPay across both pages, the diagram source, and the served HTML
• 0 matches for Bearer / jwt / Merchant-Id; retry_window_days gone
• All 20 business-page images resolve
• Diagram checked in Chrome in light and dark mode

⚠️ Still open

page-link 404s through the proxy. Five path spellings tried, and there is no page_url on the retrieve response either — so a merchant currently has no documented way to fetch the customer's self-service link, which is the whole delivery mechanism for the customer page. Left documented rather than deleted, on the assumption it should exist. @yamen.

cancel and regenerate-page-token are not probed — both are destructive.

Knock-on:#158911's field table needs the same correction, or the enrichment YAML and the eventual <ApiDocEmbed> will inherit the wrong base path and auth. That table also still lists retry_window_days, which was dropped in migrations/0028_drop_retry_window_days.py.

Do not merge until reviewed.

[ankitottu]

@claude review

[claude]

Claude finished @ankitottu's task in 2m 58s —— View job

---

Review of PR #170

• Gather context (diff, changed files, CLAUDE.md)
• Review docs/developers/payments/autopay/index.mdx
• Review src/diagrams/AutoPayFlowDiagram.tsx
• Check verification claims (auth path, removed disclosures)
• Post review feedback

---

Diffed both files against 34e4484 (the commit immediately preceding this PR's two commits — the repo is shallow-cloned so origin/dev...HEAD has no merge base, but the changed files match exactly).

Finding: the diagram's "submits payment" arrow now points at the wrong box

src/diagrams/AutoPayFlowDiagram.tsx — the AutoPay box (line 80) and the arrows that terminate on it (lines 92, 104).

Before this PR, the diagram had two accent boxes: Ottu Connect (Commits the transaction) and AutoPay (Creates the subscription). Two separate arrows fed them: the merchant's checkout call · auto_pay went into Connect, and the customer's submits payment (the CIT) also went into Connect — matching the removed accuracy-note comment that said "AutoPay never touches cardholder data. The CIT charge is processed by Ottu Connect."

This PR collapses the two boxes into one, labeled AutoPay, to stop disclosing the internal Connect→AutoPay hop — correct per the PR's own goal. But both arrows now terminate on that single box:

• Line 92: checkout call · auto_pay → ends at (330, 236), inside the AutoPay rect (x 330–550, y 200–290, line 80).
• Line 104: submits payment → ends at (552, 212), also inside/touching that same rect.

So the diagram now visually claims the customer's card payment is submitted directly to AutoPay, and that the merchant's checkout call goes to AutoPay rather than through the checkout/Connect layer. That's not a topology detail being hidden — it's a new factual claim, and it's the one thing the deleted comment explicitly said was false ("AutoPay never touches cardholder data"). Merging the boxes was the right call for hiding internal routing, but the box that survived still carries a specific label ("AutoPay / Creates the subscription") and both flows now read as going to that labeled entity.

Suggested fix (either works):

• Re-route the submits payment arrow to end at the "Ottu Platform" container boundary (the dashed box, line 62) rather than the AutoPay rect specifically, so it doesn't visually attribute card processing to AutoPay, or
• Keep two boxes but give the first a generic label (e.g. "Ottu Platform" or "Checkout") instead of removing it — satisfies "no internal service names" without merging distinct responsibilities into one.

The <desc>/alt text (lines 28, 117) don't have this problem — they only say "AutoPay creates the subscription synchronously," which is accurate and doesn't mention card processing.

Fix this →

Everything else checks out

• Auth/path correction — every Bearer/jwt/Merchant-Id reference is gone from the mdx (verified via grep); all six endpoints now show Authorization: Api-Key <YOUR_API_KEY> against /b/pbl/v2/subscriptions/..., matching the PR's stated live verification.
• Retrieve-response fields — the added fields (setup_session_id, amount_variability, cycle_interval_days, total_cycles, cancellation_initiator/reason/note, description) sit in valid JSON with correct comma placement.
• New :::note replacing the two :::warning blocks — appropriate admonition choice per the root CLAUDE.md convention (:::note for clarifications vs. :::warning for gotchas), since there's no longer anything to warn about.
• Anchor integrity — the new note links #customer-self-service-page, which exists at line 424 of the mdx (#### Customer Self-Service Page {#customer-self-service-page}); #step-by-step is unchanged.
• Topology disclosures — confirmed removed from body text, workflow steps, and the diagram's <desc>/alt, matching the PR description.
• Diagram box/arrow geometry otherwise stays within the "Ottu Platform" container and doesn't overlap the "Handled for you" box.

Not verified

I wasn't able to run npm run typecheck / npm run build myself — Bash execution required interactive approval in this environment and none was available. The PR description states both passed locally; the static diff review above doesn't contradict that (no syntax issues found in either file).
· branch epic/158909