openapi: 3.0.3
info:
  title: Tap Payments Authorize Invoices 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: Invoices
  description: Hosted, payable invoices.
paths:
  /invoices:
    post:
      operationId: createInvoice
      tags:
      - Invoices
      summary: Create an invoice
      description: Creates a hosted invoice that produces a payable link delivered by email or SMS. Carries line items, currency, due date, and customer details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '200':
          description: The created invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listInvoices
      tags:
      - Invoices
      summary: List all invoices
      description: Lists invoices in the account.
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/{invoice_id}:
    parameters:
    - name: invoice_id
      in: path
      required: true
      description: The id of the invoice.
      schema:
        type: string
    get:
      operationId: retrieveInvoice
      tags:
      - Invoices
      summary: Retrieve an invoice
      description: Retrieves an invoice by id.
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateInvoice
      tags:
      - Invoices
      summary: Update an invoice
      description: Updates an existing invoice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '200':
          description: The updated invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '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:
    InvoiceInput:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
        currency:
          type: string
        customer:
          $ref: '#/components/schemas/CustomerInput'
        order:
          type: object
          additionalProperties: true
        due:
          type: integer
          description: Due date as a Unix timestamp (milliseconds).
        expiry:
          type: integer
        description:
          type: string
        mode:
          type: string
          enum:
          - INVOICE
          - PAYMENT
        notifications:
          type: object
          additionalProperties: true
        currencies:
          type: array
          items:
            type: string
        charge:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
    Invoice:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: invoice
        status:
          type: string
        url:
          type: string
          format: uri
        amount:
          type: number
        currency:
          type: string
    CustomerInput:
      type: object
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: object
          properties:
            country_code:
              type: string
            number:
              type: string
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
  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.'