openapi: 3.0.3
info:
  title: MyFatoorah Invoicing Payment Status API
  description: 'MyFatoorah is a GCC/MENA online payment gateway and invoicing platform. This OpenAPI document models a representative subset of the MyFatoorah v2 REST API: payment method discovery (InitiatePayment), invoice creation against a gateway (ExecutePayment), payment-link invoicing (SendPayment), payment status inquiry (GetPaymentStatus), refunds (MakeRefund), embedded sessions, marketplace suppliers, shipping, recurring payments, and webhook retrieval.


    Access model: MyFatoorah uses a single shared TEST/sandbox host and separate per-country LIVE hosts (Kuwait/Bahrain/Jordan/Oman share one host; Saudi Arabia, UAE, Qatar, and Egypt each have their own). All requests are authenticated with a Bearer API token issued per country from the merchant portal (Integration Settings -> API Key). The `servers` list below enumerates the real hosts; pick the one matching your account''s country.


    Endpoint status: InitiatePayment, ExecutePayment, SendPayment, GetPaymentStatus, and MakeRefund are CONFIRMED from the public documentation (method, path, and core request/response fields). Remaining operations (sessions, suppliers, shipping, recurring, webhooks, supplier refunds, token cancellation) are documented by name and follow MyFatoorah''s `/v2/<Endpoint>` POST convention; their request/response schemas here are MODELED representative shapes and are marked with `x-status: modeled`. Verify exact fields against docs.myfatoorah.com before production use.'
  version: '2.0'
  contact:
    name: MyFatoorah
    url: https://myfatoorah.com
  x-api-version-note: MyFatoorah versions its REST endpoints under a /v2 path prefix. There is no documented public WebSocket API; asynchronous notifications are delivered as HTTP POST webhooks to a merchant-configured URL.
servers:
- url: https://apitest.myfatoorah.com/v2
  description: Test / Sandbox (shared, all regions)
- url: https://api.myfatoorah.com/v2
  description: Live - Kuwait, Bahrain, Jordan, Oman
- url: https://api-sa.myfatoorah.com/v2
  description: Live - Saudi Arabia
- url: https://api-ae.myfatoorah.com/v2
  description: Live - United Arab Emirates
- url: https://api-qa.myfatoorah.com/v2
  description: Live - Qatar
- url: https://api-eg.myfatoorah.com/v2
  description: Live - Egypt
security:
- bearerAuth: []
tags:
- name: Payment Status
  description: Inquire on invoice and transaction status.
paths:
  /GetPaymentStatus:
    post:
      operationId: getPaymentStatus
      tags:
      - Payment Status
      summary: Inquire on invoice/payment status
      description: Verifies whether an invoice was paid and returns its transactions, keyed by InvoiceId, PaymentId, or CustomerReference. CONFIRMED from public documentation.
      x-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPaymentStatusRequest'
      responses:
        '200':
          description: Invoice status and transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    GetPaymentStatusRequest:
      type: object
      required:
      - Key
      - KeyType
      properties:
        Key:
          type: string
          description: Invoice number, payment id, or customer reference value.
        KeyType:
          type: string
          enum:
          - InvoiceId
          - PaymentId
          - CustomerReference
    GenericResponse:
      type: object
      description: MyFatoorah standard envelope shared by all endpoints.
      properties:
        IsSuccess:
          type: boolean
        Message:
          type: string
        ValidationErrors:
          type: array
          nullable: true
          items:
            type: object
            properties:
              Name:
                type: string
              Error:
                type: string
        Data:
          type: object
          nullable: true
    GetPaymentStatusResponse:
      allOf:
      - $ref: '#/components/schemas/GenericResponse'
      - type: object
        properties:
          Data:
            type: object
            properties:
              InvoiceId:
                type: integer
              InvoiceStatus:
                type: string
                enum:
                - Pending
                - Paid
                - Canceled
              InvoiceValue:
                type: number
              CustomerReference:
                type: string
              InvoiceTransactions:
                type: array
                items:
                  type: object
                  properties:
                    TransactionId:
                      type: string
                    PaymentGateway:
                      type: string
                    TransactionStatus:
                      type: string
                    PaidCurrency:
                      type: string
                    PaidCurrencyValue:
                      type: number
                    Card:
                      type: string
                      description: Masked card number when applicable.
                    Error:
                      type: string
                      nullable: true
  responses:
    Unauthorized:
      description: Missing, invalid, or insufficiently-permissioned token. MyFatoorah returns 401 with a message such as "The token does not have the required permissions!".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Per-country API token issued from the MyFatoorah portal (Integration Settings -> API Key). Passed as `Authorization: Bearer {token}`. Each enabled country requires its own token.'