overlay: 1.0.0
info:
  title: Tabby Checkout API — API Evangelist enrichment overlay
  version: 1.0.0
  x-generated: '2026-08-26'
  x-method: generated
  x-source: openapi/tabby-checkout-api-openapi.yml
  x-note: >-
    Captures runtime semantics Tabby publishes in its documentation but does not express in the
    contract — rate limits, idempotency, reversal windows, environment selection and webhook
    delivery guarantees. Applies to openapi/tabby-checkout-api-openapi.yml; the original spec is never mutated.
extends: openapi/tabby-checkout-api-openapi.yml
actions:
  - target: $.info
    description: Record the region-specific base URLs and the API Evangelist enrichment provenance.
    update:
      x-api-evangelist:
        enriched: '2026-08-26'
        repo: https://github.com/api-evangelist/tabby
        conventions: conventions/tabby-conventions.yml
        errors: errors/tabby-problem-types.yml
        rate_limits: rate-limits/tabby-rate-limits.yml
        sandbox: sandbox/tabby-sandbox.yml
        data_model: data-model/tabby-data-model.yml
      x-regions:
        - region: UAE, Kuwait
          api: https://api.tabby.ai
          checkout: https://checkout.tabby.ai
          dashboard: https://merchant.tabby.ai
        - region: KSA
          api: https://api.tabby.sa
          checkout: https://checkout.tabby.sa
          dashboard: https://merchant.tabby.sa
  - target: $
    description: >-
      Record the rate limits Tabby publishes in prose but does not express in the contract, and the
      429 response the spec never declares.
    update:
      x-rate-limits:
        source: https://docs.tabby.ai/introduction/technical-requirements#rate-limit
        scope: per-api-key, per-operation-class
        exhaustion_status: 429
        response_headers: none
        live:
          create_session: 200 per 10s
          other: 100 per 1s
        test:
          create_session: 10 per 10s
          other: 50 per 1s
  - target: $.components.securitySchemes.bearerAuth
    description: Clarify the key prefixes that select environment, which the description omits.
    update:
      x-key-prefixes:
        live_secret: sk_
        test_secret: sk_test_
        live_public: pk_
        test_public: pk_test_
      x-environment-selection: >-
        Environment is chosen by the key, not by the host. The same base URL serves test and live.
  - target: $.paths['/api/v2/checkout'].post
    description: >-
      Record the session TTL and the absence of an idempotency key on session creation.
    update:
      x-ttl:
        session_expires: 20 minutes from creation
        payment_expires: ~10 minutes after session expiry
        source: https://docs.tabby.ai/pay-in-4-custom-integration/payment-processing#session-expiration
      x-idempotent: false
      x-idempotency-note: >-
        No idempotency key exists on session creation. A retried call creates a second session and a
        second payment.
      x-agentic-consequence: creates-a-financial-record