openapi: 3.0.3
info:
  title: Geidea Payment Gateway Checkout Tokenization 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: Tokenization
  description: Retrieve stored instrument tokens for cards on file.
paths:
  /pgw/api/v1/direct/token/{tokenId}:
    get:
      operationId: retrieveToken
      tags:
      - Tokenization
      summary: Retrieve Token
      description: Retrieves a stored payment instrument (card on file) token by its id.
      parameters:
      - name: tokenId
        in: path
        required: true
        description: Token id of the stored instrument.
        schema:
          type: string
      responses:
        '200':
          description: The requested token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        responseCode:
          type: string
        token:
          type: object
          properties:
            tokenId:
              type: string
            cardScheme:
              type: string
            maskedCardNumber:
              type: string
            expiryDate:
              type: string
    Error:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        detailedResponseCode:
          type: string
        detailedResponseMessage:
          type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credentials or signature.
      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.