openapi: 3.0.3
info:
  title: Geidea Payment Gateway Checkout Transaction Management API
  description: 'The Geidea Payment Gateway API lets merchants across the MENA region accept card and wallet payments. Merchants that are not PCI-DSS compliant create a payment session and render the hosted Geidea Checkout (HPP) page; PCI-DSS compliant merchants use the server-to-server Direct API to run 3-D Secure authentication and payment themselves. This document models the confirmed, publicly documented endpoints for the session, Direct card flow, transaction management, and tokenization surfaces.


    Authentication is HTTP Basic - the merchant Public Key is the username and the API Password is the password - and requests additionally carry an HMAC request `signature` computed with the API Password as the secret key. All Direct API calls must be made server-to-server; the API password must never be exposed in a front-end.


    Note on scope: request and response schemas below are representative models grounded in the Geidea API reference; field sets are illustrative and should be reconciled against the live documentation before production use. Pay by Link and Pay by Invoice are documented Geidea products but their request paths are not modeled here.'
  version: '1.0'
  contact:
    name: Geidea
    url: https://docs.geidea.net
  x-modeled-note: Endpoint paths and HTTP methods are confirmed from the Geidea API reference (docs.geidea.net). Request/response bodies are representative and modeled, not copied verbatim from an official OpenAPI file.
servers:
- url: https://api.ksamerchant.geidea.net
  description: Saudi Arabia (KSA) production
- url: https://api.merchant.geidea.net
  description: Egypt production
- url: https://api.geidea.ae
  description: UAE production
security:
- basicAuth: []
tags:
- name: Transaction Management
  description: Capture, void, refund, cancel, and fetch transactions and orders.
paths:
  /pgw/api/v1/direct/capture:
    post:
      operationId: captureTransaction
      tags:
      - Transaction Management
      summary: Capture Transaction
      description: Captures a previously authorized (pre-authorised) transaction, in full or in part.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmountOperationRequest'
      responses:
        '200':
          description: Capture result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v3/direct/void:
    post:
      operationId: voidPayment
      tags:
      - Transaction Management
      summary: Void Payment
      description: Voids an authorization that has not yet been captured or settled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderReferenceRequest'
      responses:
        '200':
          description: Void result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v2/direct/refund:
    post:
      operationId: refund
      tags:
      - Transaction Management
      summary: Refund - Full or Partial
      description: Refunds a captured/settled transaction in full or in part. The request is signed with an HMAC signature.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmountOperationRequest'
      responses:
        '200':
          description: Refund result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v1/direct/cancel:
    post:
      operationId: cancelOrder
      tags:
      - Transaction Management
      summary: Cancel Order
      description: Cancels an order that has not completed payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderReferenceRequest'
      responses:
        '200':
          description: Cancel result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v1/direct/order/{orderId}:
    get:
      operationId: getOrder
      tags:
      - Transaction Management
      summary: Fetch Transaction or Order
      description: Retrieves the full details and status of a transaction or order by its id.
      parameters:
      - name: orderId
        in: path
        required: true
        description: The Geidea order id.
        schema:
          type: string
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        detailedResponseCode:
          type: string
        detailedResponseMessage:
          type: string
    OrderResponse:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        order:
          type: object
          properties:
            orderId:
              type: string
            status:
              type: string
            amount:
              type: number
              format: double
            currency:
              type: string
            merchantReferenceId:
              type: string
    AmountOperationRequest:
      type: object
      required:
      - orderId
      properties:
        orderId:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        signature:
          type: string
          description: HMAC-SHA256 signature (Base64) for the operation.
        reason:
          type: string
    OrderReferenceRequest:
      type: object
      required:
      - orderId
      properties:
        orderId:
          type: string
        reason:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid credentials or signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the merchant Public Key as the username and the API Password as the password. Requests additionally carry an HMAC `signature` field computed with the API Password as the secret key.