Uh oh!
There was an error while loading. Please reload this page.
add Payment Transaction and Payment Attempt field reference pages - #82
add Payment Transaction and Payment Attempt field reference pages#82suliman-ottu wants to merge 4 commits into
Conversation
suliman-ottu
commented
May 25, 2026
- Add docs/business/payment-management/transaction-fields.md — full field reference for PaymentTransaction (identifiers, state, amounts with worked examples, gateway & routing, customer details, URLs, notifications, misc, relationships, and internal fields)
- Add docs/business/payment-management/attempt-fields.md — full field reference for PaymentAttempt (identifiers, state, amounts, gateway interaction, webhook diagnostics, and internal fields)
- Add both pages to the Payment Management sidebar in sidebars.ts
- Add docs/business/payment-management/transaction-fields.md — full field reference for PaymentTransaction (identifiers, state, amounts with worked examples, gateway & routing, customer details, URLs, notifications, misc, relationships, and internal fields) - Add docs/business/payment-management/attempt-fields.md — full field reference for PaymentAttempt (identifiers, state, amounts, gateway interaction, webhook diagnostics, and internal fields) - Add both pages to the Payment Management sidebar in sidebars.ts
jab3z
commented
May 25, 2026
@claude review |
Claude finished @jab3z's task in 3m 14s —— View job PR Review — Payment Transaction & Attempt Field Reference Pages
Overall the content is solid — the amounts section with nine worked examples is genuinely excellent, the cross-linking strategy is consistent, and the transaction/attempt split is well-explained. There are a handful of issues that need attention before merge. Issues1. Empty stub fields will render as blank headings (High — |
| Field heading | Line | Notes |
|---|---|---|
### minimal_amount | 340 | No description at all |
### notification_set | 470 | No description at all |
### bulk_transaction | 543 | No description at all |
### booking_event | 545 | No description at all |
### attempt_reference | 547 | No description at all |
### in_es | 564 | Inside the <details> block but empty |
### es_id | 578 | Inside the <details> block but empty |
### parent_es_id | 580 | Inside the <details> block but empty |
### unit_config | 582 | Inside the <details> block but empty |
The four internal stubs (in_es, es_id, parent_es_id, unit_config) are at least hidden behind a <details> collapse, but they still appear as blank headings when expanded. Either add at least a one-line note (even "Internal Elasticsearch ID — not exposed to merchants") or omit the heading entirely for fields that have nothing to say yet.
Fix stubs in transaction-fields.md →
2. Empty stub fields will render as blank headings (High — attempt-fields.md)
Same issue in the attempt page:
| Field heading | Line | Notes |
|---|---|---|
### total | 58 | No description — likely "amount + fee for this attempt" |
### settings | 73 | No description — looks like an important gateway-config field |
settings in particular looks like it could hold significant data (gateway config, 3DS options, etc.) and an empty heading is worse than omitting it. Fix stubs in attempt-fields.md →
3. redirect_url description has a grammar error and is misleading (transaction-fields.md, line 440)
"Only used when the webhook delivery is success."
This is grammatically incorrect ("is success" → "succeeds"). More importantly, the phrasing "only used" implies the field itself is unused when webhook delivery fails. A clearer statement: "Ottu redirects the customer to this URL only when your webhook endpoint responds with HTTP 200."
Fix redirect_url description →
4. disclosure_url vs webhook_url naming gap (transaction-fields.md, line 444)
The description correctly says "The webhook URL where Ottu sends a POST request…" but the field is named disclosure_url on the model while merchants set it via the webhook_url parameter in the Checkout API. A reader who just came from the Checkout API docs expecting webhook_url won't connect the dots. Suggest adding a short note:
This is the model field. When creating a transaction via the Checkout API, set this value using the
webhook_urlrequest parameter.
Minor nits
typefield, line 54: "The kind of transaction, this is set when…" — comma splice. Split into two sentences or use a semicolon.customer_shipping_address, line 431: The description says "May be used for fraud prevention…" but doesn't say whether this is a structured object (with sub-fields likeline1,city, etc.) or a flat string. Worth one sentence clarifying the format.is_amount_editablevsminimal_amount:is_amount_editable(line 337) references the customer modifying the amount but there's no cross-link tominimal_amountright below it. Givenminimal_amountis currently empty, this can wait — but the two fields are closely related and should cross-reference each other onceminimal_amountis filled in.
Positives
- The amounts section is outstanding: the quick-reference table + nine worked examples (purchase, refund, auth/capture, void, editable, save-card) is exactly the kind of concrete illustration that prevents support requests.
- Sidebar placement is correct — plain string shorthand, consistent with the other Payment Management items, no mixing of Pattern A and Pattern B.
- The webhook diagnostic fields section in
attempt-fields.md(disclosed_to_merchant,disclosed_data,disclosed_states,disclosure_url_error) is very well-structured and clearly explains their purpose for debugging. - Strong cross-linking throughout — almost every concept links somewhere useful.
The main ask before merge is to resolve the empty stub fields (items 1 & 2 above). Items 3 and 4 are quick text fixes. The minor nits can be addressed in a follow-up if preferred.
|
- Fix grammar in `redirect_url` description and clarify when it is used - Rename `disclosure_url` heading to `webhook_url` to match the API parameter name - Clarify that `customer_shipping_address` is a structured object with sub-fields - Split a comma splice in the `type` field description - Pull internal & diagnostic fields out of the trailing list into their own section
jab3z
commented
May 25, 2026
@claude review |
Claude finished @jab3z's task in 1m 42s —— View job PR Review — Payment Transaction & Attempt Field Reference Pages (re-review after |
| Issue | Status |
|---|---|
redirect_url grammar ("is success" → "is successful") | ✅ Fixed |
disclosure_url renamed to webhook_url to match Checkout API param | ✅ Fixed |
type field comma splice | ✅ Fixed |
customer_shipping_address — clarified as a structured object with sub-fields | ✅ Fixed |
Remaining Issues
1. Empty stub fields still render as blank headings (High — transaction-fields.md)
The empty stubs from the first review were not addressed in the apply review notes commit. These will still render as visible but empty sections:
| Field | Location | Hidden behind <details>? |
|---|---|---|
### minimal_amount | Line 339 | No — visible immediately |
### notification_set | Line 469 | No — visible immediately |
### bulk_transaction | Line 541 | No — visible immediately |
### booking_event | Line 543 | No — visible immediately |
### attempt_reference | Line 545 | No — visible immediately |
### in_es | Line 566 | Yes (collapsed by default) |
### es_id | Line 580 | Yes (collapsed by default) |
### parent_es_id | Line 582 | Yes (collapsed by default) |
### unit_config | Line 584 | Yes (collapsed by default) |
The five that are not hidden by <details> are the highest priority — a reader landing on the page will immediately see blank headings for minimal_amount, notification_set, bulk_transaction, booking_event, and attempt_reference. Either add a one-line note or remove the heading entirely.
Fix stubs in transaction-fields.md →
2. Empty stub fields still render as blank headings (High — attempt-fields.md)
Both empty stubs from the first review are still empty:
### total(line 58) — heading with no body. Likelyamount + feefor this attempt — a one-liner would suffice.### settings(line 73) — heading with no body. Given thatgateway_responsegets a description,settingsis conspicuously blank. Either describe it (gateway config/3DS options passed to the gateway for this attempt) or remove the heading.
Fix stubs in attempt-fields.md →
Everything Else Looks Good
- Sidebars — the two new entries are plain string shorthand, correctly placed inside the Payment Management items array, consistent with the other items in that section.
- Webhook diagnostics section — well-structured, clear purpose, accurate field descriptions.
- Amounts section — the quick-reference table and nine worked examples remain excellent.
- Cross-linking — thorough throughout both pages.
- All nits from the previous review were resolved.
The only blocker before merge is resolving the empty stub headings (items 1 & 2 above) — they are user-visible quality gaps on an otherwise polished pair of pages.