Update transactions and travel rule documentation

[ricardobcl]

Description

Fixes significant drift between the Transactions page and the current API behavior, verified against uphold/backend master. This is the largest correction of the documentation-audit follow-ups.

_transactions.md

• Rewrote the Beneficiary Information section, which described a validation system removed from the backend (BKO-5438): there are no $3,000 / $1,000-Arizona thresholds, no name/alphabet rules, and no invalid_beneficiary errors anymore. The backend persists only relationship (free-form, 1–255 chars) — name and address are stripped; email+name are kept only for Interac withdrawals; ACH withdrawals are always recorded as relationship: myself. Crypto-withdrawal originator/beneficiary data is collected via the Travel Rule endpoints, now cross-linked. ?validate=true is documented as generic quote validation plus commit-time scope/OTP checks.
• Fixed the scope lists for create and commit: transactions:deposit is not accepted at route level (a token holding only it fails with invalid_scope); the route scopes are the transfer/withdraw/write set, with the deposit scope checked per transaction type after route authorization.
• Reserve endpoints: GET /v0/reserve/transactions requires an OAuth token from an authorization_code client with the reserve:read scope — not the previously claimed "API key" (which is defined nowhere); the sample now carries an Authorization header. GET /v0/reserve/transactions/:id is explicitly documented as requiring no authentication.
• Pruned the public JSON examples to the fields the public mask actually returns (removed message, network, normalized, CardId, description, origin/destination type, denomination.pair/rate, params.progress/ttl/type; added application and priority).
• Priority fast is no longer Dash-only: it enables instant US bank (ACH) withdrawals; on Dash it buys a higher network fee.
• Transaction types table refreshed: FPS (and SWIFT/WIRE for unlinked accounts) bank networks, card and alternative-payment-method withdrawal destinations.
• securityCode for card deposits is accepted as optional by this API ("may be required" — the card gateway can still require it).
• Documented: 202 on create without ?commit=true; commit-time overrides (beneficiary, purpose, reference besides message); the denomination.target parameter; ?q= filters on List User Transactions (createdAt comparisons/ranges, origin/destination card ids with OR); requirements/requirementsDetails appearing only on uncommitted transactions, with the optional reason field.
• Fixed OTP-Token: Required → lowercase required (matching the header the API actually sends), noted the OTP challenge can occur at create time with ?commit=true, and several typos.

_travelrule.md

• A token lacking the required scope fails with a 400 invalid_scope error, not the documented 403 (all three endpoints).

Notes for reviewers

• The Travel Rule response field shapes (amount/threshold) and the possible requirementsDetails.reason values are owned by risk-assessment-service and proxied verbatim; they could not be verified from uphold/backend (its test mocks disagree with the documented flat-string shape). Worth confirming with that team — not changed here.
• Undocumented endpoints found but deliberately not added (flagging in case they should be): GET /v0/me/transactions/:id, GET /v0/me/transactions/:id/sources, GET /v0/reserve/transactions/:id/sources. Same for the exotic create parameters ttlMilliseconds, order, parentTransactionId, recurringType and redirectUri.
• The "Get All Transactions (Public)" heading was kept for anchor stability even though the endpoint now requires a token; the body text makes the distinction explicit.

Related issues

Follow-up to #250 (documentation audit against uphold/backend master).

Impacted areas

Transactions and Travel Rule pages of the API reference.

Steps to reproduce or test

Development

Every claim was traced to the enforcing code in uphold/backend master (card/transaction/reserve/travel-rule controllers, transaction-beneficiary-service.js, transaction-scope-resolver.js, quote and transaction models and their tests).

QA

Render both pages; optionally verify against sandbox that an uncommitted create returns 202, that a deposit-only-scoped token is rejected with invalid_scope, and that beneficiary name/address are not persisted.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• The Architectural diagram, if required, has been updated.

Deploy notes

N/A — no files added or removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the Transactions and Travel Rule API documentation to better match current backend behavior, focusing on scope/authorization semantics, Travel Rule interactions, beneficiary handling, and response/field shapes.

Changes:

• Updates Travel Rule endpoint docs to state missing-scope failures return 400 invalid_scope (instead of 403).
• Revises Transactions docs for create/commit scope requirements, Travel Rule requirement fields, reserve transaction authentication, and several transaction/beneficiary/validation details.
• Prunes and refreshes examples/tables to reflect the public masking behavior and current supported transaction networks/destinations.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
_travelrule.md	Updates auth error semantics for insufficient scopes to 400 invalid_scope across Travel Rule endpoints.
_transactions.md	Broad documentation refresh: scopes, commit/create behavior, Travel Rule/beneficiary sections, filtering, reserve endpoints, and example payloads.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.