Geidea Checkout API

openapi: 3.2.0
info:
  title: Geidea Payment Gateway Checkout API
  description: The Geidea Payment Gateway API lets merchants across the MENA region accept card and wallet payments.
  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: Checkout
  description: Create a payment session for the hosted Geidea Checkout page.
paths:
  /payment-intent/api/v2/direct/session:
    post:
      operationId: createSession
      tags:
      - Checkout
      summary: Create Session
      description: Creates a payment session used to launch the hosted Geidea Checkout (HPP) page or to begin a Direct API flow. The request is signed with an HMAC signature generated from the merchant public key, amount, currency, merchant reference id, and a timestamp.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: The created session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    SessionResponse:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        session:
          type: object
          properties:
            id:
              type: string
            expiryDate:
              type: string
    Error:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        detailedResponseCode:
          type: string
        detailedResponseMessage:
          type: string
    CreateSessionRequest:
      type: object
      required:
      - amount
      - currency
      - timestamp
      - merchantReferenceId
      - signature
      properties:
        amount:
          type: number
          format: double
          example: 100.0
        currency:
          type: string
          example: SAR
        timestamp:
          type: string
          example: 7/12/2026 10:00:00 AM
        merchantReferenceId:
          type: string
          description: Merchant-generated unique reference for the order.
        callbackUrl:
          type: string
          format: uri
          description: Webhook URL to receive the payment result notification.
        signature:
          type: string
          description: HMAC-SHA256 signature (Base64) generated from the merchant public key, amount, currency, merchant reference id, and timestamp, keyed by the API Password.
        paymentOperation:
          type: string
          enum:
          - Pay
          - Authorize
          - Preauthorize
          example: Pay
  responses:
    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.