openapi: 3.0.1
info:
  title: PayTabs PT2 Payments Transactions API
  description: 'PayTabs PT2 REST API for MENA payment acceptance. A small, uniform surface: POST /payment/request creates and manages transactions (hosted payment page, managed/own form, invoices, tokenized and recurring charges, and follow-up capture / void / release / refund actions selected via tran_type), and POST /payment/query reads transaction status by tran_ref or cart_id. Requests are JSON; the merchant server key is sent in the `authorization` header and the profile is identified by `profile_id` in the body.'
  termsOfService: https://paytabs.com/en/terms-and-conditions/
  contact:
    name: PayTabs Support
    url: https://support.paytabs.com/
  version: '2.0'
servers:
- url: https://secure.paytabs.com
  description: UAE / default region
- url: https://secure.paytabs.sa
  description: Saudi Arabia (KSA)
- url: https://secure-egypt.paytabs.com
  description: Egypt
- url: https://secure-oman.paytabs.com
  description: Oman
- url: https://secure-jordan.paytabs.com
  description: Jordan
- url: https://secure-kuwait.paytabs.com
  description: Kuwait
- url: https://secure-iraq.paytabs.com
  description: Iraq
- url: https://secure-morocco.paytabs.com
  description: Morocco
- url: https://secure-doha.paytabs.com
  description: Qatar
- url: https://secure-global.paytabs.com
  description: Global
security:
- serverKey: []
tags:
- name: Transactions
  description: Query and manage existing transactions.
paths:
  /payment/query:
    post:
      operationId: queryTransaction
      tags:
      - Transactions
      summary: Query a transaction
      description: Returns the current state of a transaction. Provide `profile_id` plus exactly one of `tran_ref` (single transaction) or `cart_id` (array of transactions for that cart). Only one of `tran_ref` or `cart_id` may be set or a 400 is returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Transaction detail (object) or list (array for cart_id).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Both tran_ref and cart_id supplied, or neither.
        '401':
          description: Authentication failed.
components:
  schemas:
    PaymentResponse:
      type: object
      properties:
        tran_ref:
          type: string
        tran_type:
          type: string
        cart_id:
          type: string
        cart_description:
          type: string
        cart_currency:
          type: string
        cart_amount:
          type: string
        redirect_url:
          type: string
          format: uri
          description: Hosted payment page URL to redirect the customer to (sale/auth HPP flows).
        customer_details:
          $ref: '#/components/schemas/CustomerDetails'
        payment_result:
          type: object
          properties:
            response_status:
              type: string
              description: A (authorized), H (hold), P (pending), V (voided), E (error), D (declined).
            response_code:
              type: string
            response_message:
              type: string
            transaction_time:
              type: string
        payment_info:
          type: object
          properties:
            payment_method:
              type: string
            card_type:
              type: string
            card_scheme:
              type: string
            payment_description:
              type: string
        token:
          type: string
          description: Card token returned when tokenise/register was requested.
    QueryRequest:
      type: object
      required:
      - profile_id
      properties:
        profile_id:
          oneOf:
          - type: integer
          - type: string
        tran_ref:
          type: string
        cart_id:
          type: string
    CustomerDetails:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        street1:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code (e.g. SA, AE, EG).
        zip:
          type: string
        ip:
          type: string
  securitySchemes:
    serverKey:
      type: apiKey
      in: header
      name: authorization
      description: Merchant server key sent as the raw value of the `authorization` HTTP header (not a Bearer token), obtained from the PayTabs merchant dashboard under Developers > Key management. Format resembles SXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX. Must match the profile's region host.