PayTabs Payments API

openapi: 3.0.1
info:
  title: PayTabs PT2 Payments 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: Payments
  description: Create and manage transactions.
paths:
  /payment/request:
    post:
      operationId: createPaymentRequest
      tags:
      - Payments
      summary: Create or act on a transaction
      description: Creates a transaction. The `tran_type` field selects the action - `sale` or `auth` initiate a new payment (returning a hosted `redirect_url` for HPP/managed/own-form flows, or authorizing a stored `token`), while `capture`, `void`, `release`, `refund` and `register` act on a prior transaction referenced by `tran_ref`. Invoice and recurring flows reuse the same endpoint with additional fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Transaction created or actioned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Validation error (missing or conflicting parameters).
        '401':
          description: Authentication failed (wrong server key or region host).
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.
    PaymentRequest:
      type: object
      required:
      - profile_id
      - tran_type
      - tran_class
      - cart_id
      - cart_description
      - cart_currency
      - cart_amount
      properties:
        profile_id:
          oneOf:
          - type: integer
          - type: string
          description: The PayTabs profile that owns the transaction.
        tran_type:
          type: string
          enum:
          - sale
          - auth
          - capture
          - void
          - release
          - refund
          - register
          description: The transaction action to perform.
        tran_class:
          type: string
          enum:
          - ecom
          - recurring
          - moto
          description: Transaction class - e-commerce, recurring, or mail/telephone order.
        cart_id:
          type: string
          maxLength: 64
          description: Merchant-side cart/order identifier.
        cart_description:
          type: string
          maxLength: 128
        cart_currency:
          type: string
          description: ISO 4217 currency (e.g. SAR, AED, EGP, USD).
        cart_amount:
          type: number
          minimum: 0.01
        tran_ref:
          type: string
          description: Prior transaction reference (required for capture/void/release/refund).
        callback:
          type: string
          format: uri
          maxLength: 255
          description: Server-to-server IPN callback URL.
        return:
          type: string
          format: uri
          maxLength: 255
          description: Browser return URL after the hosted payment page.
        customer_details:
          $ref: '#/components/schemas/CustomerDetails'
        shipping_details:
          $ref: '#/components/schemas/CustomerDetails'
        hide_shipping:
          type: boolean
        payment_methods:
          type: array
          items:
            type: string
          description: Restrict allowed methods, e.g. creditcard, mada, applepay, stcpay, valu, unionpay, amex, meeza, knet, benefit, omannet, urpay.
        token:
          type: string
          description: Saved-card token for token-based / recurring charges.
        tokenise:
          type: integer
          minimum: 1
          maximum: 6
          description: Request tokenization of the card in the returned response.
        show_save_card:
          type: boolean
        config_id:
          type: integer
          description: Hosted page theme/config identifier.
        card_filter:
          type: string
          maxLength: 255
          description: Restrict accepted BIN ranges.
        framed:
          type: boolean
          description: Render the hosted page inside an iframe (managed form).
        user_defined:
          type: object
          description: Up to nine merchant fields udf1..udf9.
    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.