openapi: 3.0.3
info:
  title: MyFatoorah Invoicing 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: Invoicing
  description: Create invoices and payment links.
paths:
  /SendPayment:
    post:
      operationId: sendPayment
      tags:
      - Invoicing
      summary: Create an invoice and generate a payment link
      description: Creates a MyFatoorah invoice and generates a shareable InvoiceURL, optionally delivered to the customer by email, SMS, or link. CONFIRMED from public documentation.
      x-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendPaymentRequest'
      responses:
        '200':
          description: Invoice created; InvoiceURL returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendPaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    InvoiceItem:
      type: object
      properties:
        ItemName:
          type: string
        Quantity:
          type: number
        UnitPrice:
          type: number
    SendPaymentResponse:
      allOf:
      - $ref: '#/components/schemas/GenericResponse'
      - type: object
        properties:
          Data:
            type: object
            properties:
              InvoiceId:
                type: integer
              InvoiceURL:
                type: string
              CustomerReference:
                type: string
    SendPaymentRequest:
      type: object
      required:
      - InvoiceValue
      - CustomerName
      - NotificationOption
      properties:
        InvoiceValue:
          type: number
        CustomerName:
          type: string
        NotificationOption:
          type: string
          description: Delivery channel for the invoice link.
          enum:
          - EML
          - SMS
          - LNK
          - ALL
        CustomerMobile:
          type: string
          description: Required when NotificationOption is SMS or ALL.
        CustomerEmail:
          type: string
          description: Required when NotificationOption is EML or ALL.
        DisplayCurrencyIso:
          type: string
        CallBackUrl:
          type: string
        ErrorUrl:
          type: string
        CustomerReference:
          type: string
        InvoiceItems:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceItem'
    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
  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.'