Geidea Tokenization API

openapi: 3.0.3
info:
  title: Geidea Payment Gateway 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: Checkout
    description: Create a payment session for the hosted Geidea Checkout page.
  - name: Direct API
    description: Server-to-server 3-D Secure authentication and card payment.
  - name: Transaction Management
    description: Capture, void, refund, cancel, and fetch transactions and orders.
  - name: Tokenization
    description: Retrieve stored instrument tokens for cards on file.
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'
  /pgw/api/v6/direct/authenticate/initiate:
    post:
      operationId: initiateAuthentication
      tags:
        - Direct API
      summary: Initiate Authentication
      description: >-
        Starts 3-D Secure authentication for a card within an existing session,
        returning the data needed to challenge or frictionlessly authenticate the
        payer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateAuthenticationRequest'
      responses:
        '200':
          description: Authentication initiation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v6/direct/authenticate/payer:
    post:
      operationId: authenticatePayer
      tags:
        - Direct API
      summary: Authenticate Payer
      description: >-
        Completes 3-D Secure payer authentication, returning a threeDSecureId that
        is passed to the Pay operation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticatePayerRequest'
      responses:
        '200':
          description: Payer authentication result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pgw/api/v2/direct/pay:
    post:
      operationId: pay
      tags:
        - Direct API
      summary: Pay
      description: >-
        Processes a card payment against an authenticated session. Requires the
        sessionId, an orderId (GUID), the threeDSecureId from Authenticate Payer,
        and the payment method / card details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayRequest'
      responses:
        '200':
          description: Payment result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /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:
  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.
  parameters: {}
  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'
  schemas:
    CreateSessionRequest:
      type: object
      required:
        - amount
        - currency
        - timestamp
        - merchantReferenceId
        - signature
      properties:
        amount:
          type: number
          format: double
          example: 100.00
        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
    SessionResponse:
      type: object
      properties:
        responseCode:
          type: string
        responseMessage:
          type: string
        session:
          type: object
          properties:
            id:
              type: string
            expiryDate:
              type: string
    InitiateAuthenticationRequest:
      type: object
      required:
        - sessionId
        - cardOnFile
      properties:
        sessionId:
          type: string
        orderId:
          type: string
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        cardOnFile:
          type: boolean
    AuthenticatePayerRequest:
      type: object
      required:
        - sessionId
        - threeDSecureId
      properties:
        sessionId:
          type: string
        threeDSecureId:
          type: string
        cardHolderResponseUrl:
          type: string
          format: uri
    PayRequest:
      type: object
      required:
        - sessionId
        - orderId
      properties:
        sessionId:
          type: string
        orderId:
          type: string
          description: Unique order identifier (GUID).
        threeDSecureId:
          type: string
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
    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
    PaymentMethod:
      type: object
      properties:
        cardHolderName:
          type: string
        cardNumber:
          type: string
        expiryDate:
          type: object
          properties:
            month:
              type: integer
            year:
              type: integer
        cvv:
          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
    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