docs(reference): add surcharging integration guide

[flozanofdez]

Closes API-78.

Why

Surcharging ships with Android SDK 7.1014.0 / App 4.14.0 / REST API 2.28.0 and has no user-facing documentation. This adds a guide to docs/reference/, alongside avs-for-moto and pre-authorization-guide, which is where cross-cutting feature guides live on this branch.

The source material was the surcharging spec doc, condensed and rewritten against the actual SDK and Cloud API source rather than transcribed — the spec was written ahead of implementation and diverges from what shipped.

The main thing reviewers should check

The two integration paths assemble the amount differently, and the guide leads with that:

Path	What amount contains
Cloud API	The total — surcharge and tax already included (transaction-request.model.ts: "Already included in amount")
Android SDK — sale / MOTO sale / refund	The base only; SharedRequestFactory adds surcharge and tax on top
Android SDK — pre-auth capture	The total; the capture amount is sent verbatim

Sending the wrong shape either overcharges the cardholder or double-counts the surcharge. Worth confirming this asymmetry is intended rather than an SDK bug.

Corrections made against the spec

Spec	Shipped
ConfigurationManager, getBooleanKey() / getFloatKey()	HapiConfigurationManager via hapi.getConfigurationManager(); getKey(name).asBooleanKey() / .asDecimalKey()
surchargePercent is a float	Decimal / BigDecimal — phoenix-config-resource validates it as a decimal param
ConfigurationNotFoundException	ConfigurationKeyNotFoundException
HapiConfigurationListener.newConfiguration()	Events.ConfigurationUpdatesEvent.newConfigurations()
PreAuthorizationCaptureOptions	No such class — capture takes the base Options
SurchargeReason enum	reason is a plain String
"RefundOptions needs a surchargeAmount field"	Already inherited from Options and forwarded by RefundRequestFactory

Support matrix — needs a second opinion

Marked ✅ for Cloud API and Android (PAX); ❌ for Android (HiLite), iOS (HiLite) and Cordova. The ❌ marks are inferred from the absence of any surcharge field in those SDKs plus the "App 4.14.0" gating, not from a positive statement of scope. Please correct if wrong.

Also worth a look

• The rounding mode for proportional refunds is still an open item in the spec. The guide uses HALF_UP throughout; if the gateway team settles on something else, the Refunds section needs updating.
• Options.taxAmount is @Deprecated in favour of taxInformation, yet it is the field that actually adds tax to the charged total. The guide uses it without commentary.

Checklist

• yarn build passes; no new broken links or anchors
• Page renders at /reference/surcharging and appears in the Reference sidebar
• No secrets or PII
• Technical review of the amount semantics and the support matrix

🤖 Generated with Claude Code