API Evangelist enhancements for Token.io's Open Banking API for TPPs

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Token.io's Open Banking API for TPPs
  version: 1.0.0
extends: ../openapi/_original/token-io-openapi.yml
x-provenance:
  generated: '2026-09-17'
  method: generated
  source: >-
    Derived from the gaps found in openapi/_original/token-io-openapi.yml (fetched 2026-09-17 from
    https://docs.token.io/_bundle/products/tpp/api/reference/index.yaml) plus facts established in
    this repo's searched artifacts. NOTHING here is invented: every value below either restates a
    fact Token.io publishes elsewhere or points at an artifact in this repo. The original spec is
    never mutated.
  note: >-
    The apis.io score parses the ORIGINAL spec, so this overlay improves our derived artifacts and
    documents what a provider PR to Token.io would contain. The three gaps it closes are: an empty
    info.version (flagged by the refine pass), no contact block on a spec whose description links
    support in HTML, and no cross-reference to the platform conventions an integrator must know
    before calling anything.
actions:
  - target: $.info
    description: >-
      Set a usable version. The upstream spec ships info.version as an empty string, which makes the
      document unversionable by any client tooling. Token.io publishes no semantic release number
      for the platform, so the honest value is the date the document was harvested.
    update:
      version: '2026-09-17'
      x-version-note: >-
        Token.io does not publish a semantic version for this API. Generations are expressed in the
        URI path (v1 and v2 surfaces run concurrently). This value is the harvest date of the
        upstream bundle, not a Token.io release number.
  - target: $.info
    description: >-
      Lift the support and documentation contacts out of the HTML in info.description into the
      structured contact and externalDocs fields, where a client can read them.
    update:
      contact:
        name: Token.io Support
        url: https://support.token.io
        email: support@token.io
      x-documentation-feedback: devdocs@token.io
      x-terms-of-service: https://token.io/terms
      x-privacy-policy: https://token.io/privacy-policy
  - target: $.info
    description: >-
      Record the regulatory identity of the operator. Token.io is an authorised TPP and the
      regulatory posture determines what a caller is permitted to do — it belongs in the contract,
      not only in the FAQ.
    update:
      x-regulatory:
        entity: Token.io Limited
        uk:
          regulator: Financial Conduct Authority
          reference: '795904'
          basis: Payment Services Regulations 2017
          roles:
            - AISP
            - PISP
        germany:
          roles:
            - TPP
        open_banking_directory: https://www.openbanking.org.uk/regulated-providers/token/
        certifications:
          - ISO/IEC 27001:2022
          - PCI DSS Level 1
        source: https://token.io/faq
        artifact: conformance/token-io-conformance.yml
  - target: $.info
    description: >-
      Attach the cross-cutting runtime semantics an integrator has to know before the first call and
      which appear in no individual operation — above all that there is no idempotency mechanism on
      any write.
    update:
      x-conventions:
        artifact: conventions/token-io-conventions.yml
        idempotency:
          coverage: none
          note: >-
            No idempotency key, header or documented de-duplication on any write. On a timeout, poll
            the resource; do not resend a payment initiation.
        tracing:
          response_header: tokenTraceId
          note: Propagate it; quote it on support tickets.
        error_origin_header:
          name: token-external-error
          note: '"true" only when a 5xx originated at the bank. Absence must be read as false.'
        json_errors:
          request_header: token-json-error
          note: Set true to receive the JSON error envelope instead of text.
        presence_headers:
          - name: customer-initiated
            note: >-
              Declares a user-initiated call. Absent, the request is treated as TPP-initiated, which
              engages the PSD2 four-accesses-per-24-hours AIS limit at the bank.
          - name: token-customer-ip-address
            note: Recommended whenever the user is present.
        backward_compatibility: >-
          Seven classes of change are declared non-breaking and must be absorbed by the client (new
          endpoints, new response properties, reordering, new optional parameters, id format
          changes, error message changes, new webhook event types). Use a lenient JSON parser.
          Breaking changes are announced in advance by Technical Bulletin.
  - target: $.info
    description: >-
      Point at the asynchronous surface. The webhook catalogue is a first-class part of this API —
      ten event types delivered to one configured URL — but the spec describes only the
      configuration endpoints, not the events.
    update:
      x-event-surface:
        artifact: asyncapi/token-io-webhooks.yml
        asyncapi_published: false
        configuration: PUT /webhook/config (one configuration per member)
        event_types:
          - PAYMENT_STATUS_CHANGED
          - TRANSFER_STATUS_CHANGED
          - REFUND_STATUS_CHANGED
          - VRP_STATUS_CHANGED
          - VRP_CONSENT_STATUS_CHANGED
          - VIRTUAL_ACCOUNT_CREDIT_RECEIVED
          - PAYOUT_STATUS_CHANGED
          - SETTLEMENT_RULE_PAYOUT_EXECUTION_FAILED
          - BANK_AIS_OUTAGE_STATUS_CHANGED
          - BANK_SIP_OUTAGE_STATUS_CHANGED
        signature_header: token-signature
        retry: exponential backoff up to 72 hours, ~10 attempts
  - target: $.servers
    description: >-
      The upstream spec declares only the production host. Name the sandbox so a client can switch
      environments from the contract; the values are Token.io's own, published in api-basics.
    update:
      - url: https://api.token.io
        description: Production
      - url: https://api.sandbox.token.io
        description: >-
          Sandbox. HTTP Basic authentication is accepted here and only here; the mock-redirect bank
          drives outcomes from the payment amount (see sandbox/token-io-sandbox.yml).