Skip to content

docs: add Level II purchasing data (tax information + purchase order number) - #208

Open
ecunado wants to merge 1 commit into
devfrom
docs/level-two-purchasing-data
Open

docs: add Level II purchasing data (tax information + purchase order number)#208
ecunado wants to merge 1 commit into
devfrom
docs/level-two-purchasing-data

Conversation

@ecunado

@ecunado ecunado commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Documents Level II purchasing data in the REST API: the taxInformation object (taxAmount, taxExempt) and the top-level purchaseOrderNumber field, on:
    • The Transaction Request Object, for the sale, moToSale and preAuthorizationCapture operations sent via POST /transactions.
    • The MotoSaleRequest object, for POST /moto/sale (server-to-server MOTO sale via card token, no terminal involved).
  • Adds a dedicated ## Tax Information reference section in restobjects.md, modeled on the Billing section added for MOTO AVS (API-58 docs: add Billing object for MoTo AVS support #196).
  • The section documents the rules enforced by the gateway: the two fields are always sent as a pair (4263 / 4264), taxAmount must be 0 when taxExempt is true (4262) and greater than 0 when it is false (4266), purchaseOrderNumber is limited to 25 alphanumeric characters (4267), and Level II data must be enabled on the merchant's agreement (4261).

Context

  • Gateway support is already implemented in Viscus (L2DataFeatureBuilder / L2DataFeature), gated by the agreement flag l2DataEnabled, on exactly the operations documented here: authorization/payment (sale), MOTO sale, and pre-authorization capture.
  • Terminal-side support is implemented in the Android SDK (Options.taxInformation / Options.purchaseOrderNumber, Level2Operation.applyLevel2).
  • The REST API path is not implemented yet: neither cloudapi's TransactionRequest / EcommMotoSaleRequest nor the terminal's cloud request DTO (CloudFinancialRequest) carry Level II fields today. This PR therefore defines the REST contract ahead of the cloudapi work, the same way API-58 docs: add Billing object for MoTo AVS support #196 landed ahead of the AVS implementation.
  • Contract decision worth reviewing: the docs expose taxExempt as a boolean, mirroring the Android SDK public API, instead of the gateway's taxAmountIdentifier code (1 = local sales tax, 2 = tax exempt). This keeps the REST API consistent with how it already exposes booleans where the gateway uses codes (duplicate_check, cardPresent, duplicationCheck) and gives one single object for both endpoints. It does mean cloudapi must map taxExempt to taxAmountIdentifier when forwarding to Viscus, including on the otherwise pass-through POST /moto/sale.
  • taxAmount is documented as "the same denomination as the amount field of the request", because POST /transactions uses minor units and POST /moto/sale uses major units.
  • Out of scope, flagged for a follow-up: saleAndTokenizeCard also carries Level II data in the Android SDK and would map to the same Viscus payment request, but it is not part of the requested scope; and the already-implemented flat surchargeAmount / taxAmount fields of POST /transactions are still undocumented in restapi/.

Test plan

  • yarn build passes with no new broken links or anchors
  • Visual review of the rendered restobjects.md page in the docs site
  • Confirm the #tax-information anchor resolves from both the Transaction Request Object and MotoSaleRequest properties tables

🤖 Generated with Claude Code

Documents the taxInformation object (taxAmount, taxExempt) and the
purchaseOrderNumber field used for Level II purchasing data, on the
Transaction Request Object for the sale, moToSale and
preAuthorizationCapture operations, and on the MotoSaleRequest object
for POST /moto/sale.

Adds a dedicated Tax Information reference section covering the pairing
rule, the tax-exempt amount rules, the purchase order number format and
the agreement-level gating, modeled on the existing Billing section.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant