openapi: 3.0.3
info:
  title: Tap Payments Authorize Cards API
  description: REST API for Tap Payments, a payment gateway and financial infrastructure provider for the Middle East and North Africa. Merchants accept online payments across the GCC and Egypt using cards (Visa, Mastercard, Amex), local schemes (mada, KNET, Benefit), and wallets (Apple Pay, Google Pay). The core flows are Charges (charge a source now), Authorize/Capture (hold then capture), Tokens (single-use tokenization of a card or wallet), Customers and Cards (vaulting for recurring / card-on-file), Refunds, Invoices, Payouts, and Business/merchant onboarding. All requests are authenticated with a secret API key passed as a Bearer token; separate test (sk_test_...) and live (sk_live_...) keys are issued from the Tap dashboard. Endpoint paths and methods are grounded in the public Tap developer reference and its published OpenAPI index (developers.tap.company/llms.txt); request and response schemas below are modeled for common fields and are not an exhaustive reproduction of Tap's object schemas - verify field-level detail against the live reference.
  version: '1.0'
  contact:
    name: Tap Payments Developers
    url: https://developers.tap.company
  x-modeled-note: Endpoint list and HTTP methods are grounded in Tap's public developer reference and OpenAPI index. Property-level schemas are modeled (representative), not copied verbatim from Tap.
servers:
- url: https://api.tap.company/v2
  description: Tap Payments production API (test vs live selected by API key)
security:
- bearerAuth: []
tags:
- name: Cards
  description: Saved cards (card-on-file) attached to a customer.
paths:
  /card/{customer_id}:
    parameters:
    - $ref: '#/components/parameters/CustomerId'
    get:
      operationId: listCards
      tags:
      - Cards
      summary: List all cards
      description: Lists the saved cards (card-on-file) stored against a customer.
      responses:
        '200':
          description: A list of saved cards.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /card/{customer_id}/{card_id}:
    parameters:
    - $ref: '#/components/parameters/CustomerId'
    - name: card_id
      in: path
      required: true
      description: The id of the saved card.
      schema:
        type: string
    get:
      operationId: retrieveCard
      tags:
      - Cards
      summary: Retrieve a card
      description: Retrieves a saved card by id for a given customer.
      responses:
        '200':
          description: The requested card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCard
      tags:
      - Cards
      summary: Delete a card
      description: Deletes a saved card from a customer.
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DeleteResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        deleted:
          type: boolean
    Card:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: card
        last_four:
          type: string
        brand:
          type: string
        exp_month:
          type: integer
        exp_year:
          type: integer
        funding:
          type: string
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
  parameters:
    CustomerId:
      name: customer_id
      in: path
      required: true
      description: The id of the customer (e.g. cus_XXXXXXXX).
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Secret API key passed as a Bearer token in the Authorization header: `Authorization: Bearer sk_test_...` (test) or `sk_live_...` (live). Keys are issued from the Tap dashboard. Never expose the secret key in client-side code.'