openapi: 3.0.3
info:
  title: Tap Payments Authorize Charges 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: Charges
  description: Charge a card or other payment source.
paths:
  /charges:
    post:
      operationId: createCharge
      tags:
      - Charges
      summary: Create a charge
      description: Initiates a charge to charge a card or other payment source. The source may be a token id, a saved card, an authorize id (to capture), or a local scheme / wallet. For 3D Secure, pass redirect.url to receive the customer back after authentication.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeInput'
      responses:
        '200':
          description: The created charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listCharges
      tags:
      - Charges
      summary: List all charges
      description: Lists charges, filterable by date, status, method, customer, and charge id.
      responses:
        '200':
          description: A list of charges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /charges/{charge_id}:
    parameters:
    - $ref: '#/components/parameters/ChargeId'
    get:
      operationId: retrieveCharge
      tags:
      - Charges
      summary: Retrieve a charge
      description: Retrieves the details of a charge by its id.
      responses:
        '200':
          description: The requested charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCharge
      tags:
      - Charges
      summary: Update a charge
      description: Updates mutable fields on a charge, such as description, metadata, or notifications.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Redirect:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL Tap redirects the customer to after 3D Secure authentication.
    Source:
      type: object
      description: The payment source. Provide a token id, a saved card id, an authorize id (to capture), or a scheme identifier such as src_kw.knet, src_sa.mada, src_bh.benefit, src_card, src_apple_pay, or src_google_pay.
      properties:
        id:
          type: string
    Customer:
      allOf:
      - $ref: '#/components/schemas/CustomerInput'
      - type: object
        properties:
          id:
            type: string
          object:
            type: string
            example: customer
    Charge:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: charge
        status:
          type: string
          description: For example INITIATED, IN_PROGRESS, CAPTURED, AUTHORIZED, DECLINED, VOID.
        amount:
          type: number
        currency:
          type: string
        threeDSecure:
          type: boolean
        customer:
          $ref: '#/components/schemas/Customer'
        source:
          $ref: '#/components/schemas/Source'
        transaction:
          type: object
          additionalProperties: true
        reference:
          type: object
          additionalProperties: true
        response:
          type: object
          additionalProperties: true
    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
    ChargeInput:
      type: object
      required:
      - amount
      - currency
      - source
      properties:
        amount:
          type: number
        currency:
          type: string
        customer_initiated:
          type: boolean
        threeDSecure:
          type: boolean
        save_card:
          type: boolean
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        reference:
          type: object
          additionalProperties: true
        receipt:
          type: object
          additionalProperties: true
        customer:
          $ref: '#/components/schemas/CustomerInput'
        source:
          $ref: '#/components/schemas/Source'
        redirect:
          $ref: '#/components/schemas/Redirect'
        post:
          $ref: '#/components/schemas/Redirect'
    ChargeList:
      type: object
      properties:
        charges:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ChargeId:
      name: charge_id
      in: path
      required: true
      description: The id of the charge (e.g. chg_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.'