overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay for the SoFi Tech Solutions Program API
  version: 1.0.0
extends: openapi/sofi-technologies-program-api-openapi.json
x-provenance:
  generated: '2026-09-06'
  method: generated
  source: >-
    Everything asserted below was read from the SoFi Tech Solutions developer hub on 2026-09-06
    and is cited to the page it came from. The harvested specification is never mutated; this
    overlay records only what API Evangelist added on top of it.
  target_note: >-
    The harvested Program API document carries info.title "Program API" and info.version "4.0"
    with no description, no contact, no externalDocs and no securitySchemes. Those absences are
    the provider's, not an artefact of the harvest.
actions:
  - target: $.info
    description: >-
      Name the publisher and point at the reference. The harvested info block does not say whose
      API this is, which is precisely the ownership problem STEP 0c exists to catch.
    update:
      description: >-
        The SoFi Tech Solutions Program API - accounts, cards, authorizations, ACH, bill pay,
        fees, adjustments and spend controls for the card issuer-processor platform operated by
        SoFi Technologies, Inc. (formerly Galileo Financial Technologies). Every operation is a
        POST with application/x-www-form-urlencoded parameters; the outcome is in the response
        body's status_code, not in the HTTP status.
      contact:
        name: SoFi Tech Solutions Pro Documentation
        url: https://docs.tech.sofi.com/pro/
  - target: $
    description: Link the specification to the human reference it was harvested from.
    update:
      externalDocs:
        description: SoFi Tech Solutions Pro API reference
        url: https://docs.tech.sofi.com/pro/reference/program-api-intro
  - target: $
    description: >-
      Record the runtime semantics that are documented on the hub but absent from the contract.
      An agent reading only the specification cannot learn any of these.
    update:
      x-api-evangelist-conventions:
        artifact: conventions/sofi-technologies-conventions.yml
        authentication:
          style: body-parameter credentials
          parameters: [apiLogin, apiTransKey, providerId, transactionId]
          bound_to: the requesting IP address
          docs: https://docs.tech.sofi.com/pro/reference/api-reference-authentication
        idempotency:
          key: transactionId
          scope: transactionId + providerId + endpoint
          retention_days: 90
          duplicate_status_code: 24
          coverage: partial
          covered_operations: 35
          total_operations: 167
          docs: https://docs.tech.sofi.com/pro/reference/idempotency
        pagination:
          request: [recordCnt, page]
          response: [total_record_count, number_of_pages, page]
          default_max_page_size: 200
          docs: https://docs.tech.sofi.com/pro/reference/record-set-paging
        error_envelope:
          format: proprietary
          code_field: status_code
          message_field: status
          detail_field: errors
          correlation_field: rtoken
          http_status_note: HTTP 200 is returned on business failures; branch on status_code.
          docs: https://docs.tech.sofi.com/pro/reference/errors
        system_time:
          zone: America/Phoenix (Arizona Standard Time, GMT-0700, no daylight saving)
          applies_to: every date and time parameter sent to or returned by the API
          docs: https://docs.tech.sofi.com/pro/reference/system-time
        rate_limits:
          production_limit_published: false
          sandbox_limit: 1000 requests per 10 minutes
          response_headers: []
          docs: https://docs.tech.sofi.com/pro/reference/rate-limits
  - target: $.servers
    description: >-
      Annotate the templated server rather than replacing it. The harvested value
      "api-{corename}.{env}.gpsrv.com/intserv/4.0/" is correct and complete - it names the real
      host shape and says which parts are per-client variables - so it is left intact and only
      described.
    update:
      x-api-evangelist-server-note: >-
        corename is the client's core name as assigned by SoFi Tech Solutions; env is cv (client
        validation) or pd (production). The shared Sandbox is reached instead at
        https://sandbox-api.gpsrv.com/intserv/4.0/. Scheme is https; the harvested value omits
        it. All non-standard URIs return 404.
  - target: $
    description: Record the standards the contract itself speaks, for the conformance artifact.
    update:
      x-api-evangelist-conformance:
        artifact: conformance/sofi-technologies-conformance.yml
        declared_in_contract: [nacha-ach, emv, rtp]
        platform_wide: [iso-8583, 3-d-secure, pci-dss]