openapi: 3.0.3
info:
  title: MyFatoorah Invoicing Refunds 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: Refunds
  description: Full and partial refunds.
paths:
  /MakeRefund:
    post:
      operationId: makeRefund
      tags:
      - Refunds
      summary: Issue a full or partial refund
      description: Refunds a paid invoice or payment, in full or partially, with an optional comment and external identifier. CONFIRMED from public documentation.
      x-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MakeRefundRequest'
      responses:
        '200':
          description: Refund created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakeRefundResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /GetRefundStatus:
    post:
      operationId: getRefundStatus
      tags:
      - Refunds
      summary: Track refund processing status
      description: Returns the processing status of a previously requested refund. MODELED - endpoint is documented by name; request/response shapes here are representative.
      x-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                KeyType:
                  type: string
                  enum:
                  - InvoiceId
                  - PaymentId
                  - RefundId
                Key:
                  type: string
      responses:
        '200':
          description: Refund status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /MakeSupplierRefund:
    post:
      operationId: makeSupplierRefund
      tags:
      - Refunds
      summary: Refund with supplier apportionment
      description: Issues a refund on a marketplace invoice, deducting the supplier's portion. MODELED representative shape.
      x-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Supplier refund created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    MakeRefundResponse:
      allOf:
      - $ref: '#/components/schemas/GenericResponse'
      - type: object
        properties:
          Data:
            type: object
            properties:
              Key:
                type: string
              RefundId:
                type: integer
              RefundReference:
                type: string
              RefundInvoiceId:
                type: string
              Amount:
                type: number
              Comment:
                type: string
              ExternalIdentifier:
                type: string
    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
    MakeRefundRequest:
      type: object
      required:
      - KeyType
      - Key
      - Amount
      properties:
        KeyType:
          type: string
          enum:
          - InvoiceId
          - PaymentId
        Key:
          type: string
        Amount:
          type: number
          description: Refund amount (full or partial).
        Comment:
          type: string
        ServiceChargeOnCustomer:
          type: boolean
        ExternalIdentifier:
          type: string
          description: External data linked to the refund; echoed in webhooks.
        AmountDeductedFromSupplier:
          type: number
  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.'