API Evangelist enhancements for Aaron's Hosted Payment Page

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Aaron's Hosted Payment Page
  version: 1.0.0
extends: ../openapi/aarons-hpp-openapi.json
x-provenance:
  generated: '2026-08-29'
  method: generated
  source: >-
    Derived entirely from the verbatim contract at https://hpp.aarons.com/openapi.json plus probes
    recorded in this repo. Nothing below asserts behaviour Aaron's has not published or that we did
    not observe. The original document is never mutated.
  note: >-
    The upstream document is machine-generated by ServiceStack and carries no info.description, no
    contact, no licence, no external docs, no operation summaries or descriptions, and no 4xx/5xx
    responses. This overlay supplies only the descriptive metadata we can honestly state.
actions:
  - target: $.info
    description: Add a substantive description, contact and terms to an otherwise bare info block.
    update:
      description: >-
        Aaron's Hosted Payment Page (HPP) service. Creates a payment session, collects and tokenises
        a customer card, runs a zero-dollar authorisation with AVS/CVV2 verification, authorises the
        session, and receives authorisation and card-vault postbacks from the Fiserv and Repay
        payment gateways. Used by Aaron's own lease-payment and EZPay experiences. There is no
        public developer program: bearer tokens are not issued to third parties.
      termsOfService: https://www.aarons.com/terms-of-service.html
      contact:
        name: Aaron's Customer Service
        url: https://www.aarons.com/contact
  - target: $.externalDocs
    description: There is no published developer documentation; point at the closest real page.
    update:
      description: >-
        Aaron's publishes no developer documentation for this contract. The link below is the
        consumer-facing EZPay page, which is the nearest human-readable description of the flow.
      url: https://www.aarons.com/ezpay.html
  - target: $.tags
    description: Group the 14 machine-generated tags into the flows they actually belong to.
    update:
      - name: CreateSession
        description: Session lifecycle — opens the hosted payment session a card is collected into.
      - name: CustomerData
        description: Customer context attached to a session (application id, email, language, consent to save on file).
      - name: CreateToken
        description: Card tokenisation.
      - name: SaveToken
        description: Persists a tokenised instrument against the customer, with a terms version.
      - name: AuthorizeSession
        description: Authorises the payment for an open session.
      - name: MemoryBearerToken
        description: Short-lived bearer token exchange for the hosted page.
      - name: MemoryTokenGuid
        description: Token GUID exchange for the hosted page.
      - name: SaveDeviceIntelligence
        description: Device fingerprint / navigator data captured for fraud screening.
      - name: AutoPayCustomerRetry
        description: Retries a failed automatic (EZPay) payment by payment GUID.
      - name: UpdateCustomerRetryNotification
        description: Updates the customer notification state for a retried payment.
      - name: FiservPostback
        description: Inbound authorisation callback from the Fiserv gateway.
      - name: RepayAuthPostback
        description: Inbound authorisation event from the Repay gateway, in Repay's versioned event envelope.
      - name: RepayCardVaultPostback
        description: Inbound stored-payment lifecycle event from the Repay card vault.
      - name: ping
        description: Unauthenticated liveness check.
  - target: $.securityDefinitions.Bearer
    description: State what the bearer token is and how it is obtained, since the contract does not.
    update:
      description: >-
        Bearer token supplied in the Authorization header. Not self-service: tokens are minted by
        Aaron's for its own hosted-page session flow (see /MemoryBearerToken and /CreateToken).
        No lifetime, rotation or scope model is published.
  - target: $.paths['/ping'].get
    description: Mark the one operation that is genuinely callable without credentials.
    update:
      summary: Liveness check.
      description: >-
        Unauthenticated liveness endpoint. Observed live returning HTTP 200 with an HTML "Ping
        Snapshot" page at https://hpp.aarons.com/ping on 2026-08-29.
x-notes:
  - >-
    NOT applied by this overlay, deliberately: the upstream document declares GET, PUT, POST and
    DELETE on all 15 paths — a ServiceStack any-verb routing artefact, not a designed method
    contract. Pruning the phantom verbs would require knowing which one is real for each route, and
    Aaron's does not publish that. Recorded as a finding in conventions/aarons-conventions.yml
    instead of guessed at here.
  - >-
    NOT applied: error responses. Adding 4xx/5xx responses would improve our derived artifacts while
    misrepresenting the provider's contract quality. The gap is recorded in
    errors/aarons-problem-types.yml.