openapi: 3.0.3
info:
  title: Moyasar Invoices API
  description: 'Moyasar is a Saudi Arabian payment gateway. Its REST API lets businesses accept online payments across mada, Visa, Mastercard, American Express, Apple Pay, Samsung Pay, and STC Pay, issue hosted invoices, tokenize cards, receive webhooks, and send payouts. All requests are made over HTTPS to https://api.moyasar.com/v1 and authenticated with HTTP Basic auth using an API key as the username and an empty password. Publishable keys (pk_test_ / pk_live_) may only create payments and tokens from the client side; secret keys (sk_test_ / sk_live_) authorize all account operations from the backend. Monetary amounts are expressed in the smallest currency unit (for SAR, halalas: 1.00 SAR = 100).

    This description captures a representative, grounded subset of the documented API. Request and response schemas are modeled from the public documentation and are intentionally partial (additionalProperties allowed); consult the Moyasar docs for exhaustive field-level detail.'
  version: '1.0'
  contact:
    name: Moyasar
    url: https://moyasar.com
  license:
    name: Proprietary
    url: https://moyasar.com/en/terms/
servers:
- url: https://api.moyasar.com/v1
  description: Moyasar production API
security:
- basicAuth: []
tags:
- name: Invoices
  description: Hosted invoices with a Moyasar-hosted checkout URL.
paths:
  /invoices:
    get:
      operationId: listInvoices
      tags:
      - Invoices
      summary: List invoices
      description: Lists invoices on the account with pagination.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: A paginated list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createInvoice
      tags:
      - Invoices
      summary: Create an invoice
      description: Creates a hosted invoice and returns a Moyasar-hosted checkout `url` to present to the payer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '201':
          description: The created invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/bulk:
    post:
      operationId: createInvoicesBulk
      tags:
      - Invoices
      summary: Bulk create invoices
      description: Creates multiple invoices in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invoices:
                  type: array
                  items:
                    $ref: '#/components/schemas/InvoiceInput'
      responses:
        '201':
          description: The created invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/{id}:
    parameters:
    - $ref: '#/components/parameters/InvoiceId'
    get:
      operationId: fetchInvoice
      tags:
      - Invoices
      summary: Fetch an invoice
      description: Retrieves a single invoice by its ID.
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateInvoice
      tags:
      - Invoices
      summary: Update an invoice
      description: Updates an existing invoice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '200':
          description: The updated invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelInvoice
      tags:
      - Invoices
      summary: Cancel an invoice
      description: Cancels an invoice so it can no longer be paid.
      responses:
        '200':
          description: The canceled invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Invalid or missing authorization credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request payload failed validation.
      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:
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        next_page:
          type: integer
          nullable: true
        prev_page:
          type: integer
          nullable: true
        total_pages:
          type: integer
        total_count:
          type: integer
    InvoiceInput:
      type: object
      required:
      - amount
      - currency
      - description
      properties:
        amount:
          type: integer
          description: Amount in the smallest currency unit (minimum 100).
        currency:
          type: string
          default: SAR
        description:
          type: string
        callback_url:
          type: string
          format: uri
        success_url:
          type: string
          format: uri
        back_url:
          type: string
          format: uri
        expired_at:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties: true
    Invoice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - initiated
          - paid
          - failed
          - refunded
          - canceled
          - on_hold
          - expired
          - voided
        amount:
          type: integer
        amount_format:
          type: string
        currency:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
          description: Hosted checkout URL to present to the payer.
        expired_at:
          type: string
          format: date-time
          nullable: true
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        metadata:
          type: object
          nullable: true
          additionalProperties: true
      additionalProperties: true
    Payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - initiated
          - paid
          - authorized
          - failed
          - refunded
          - captured
          - voided
          - verified
        amount:
          type: integer
        fee:
          type: integer
        currency:
          type: string
        refunded:
          type: integer
        refunded_at:
          type: string
          format: date-time
          nullable: true
        captured:
          type: integer
        captured_at:
          type: string
          format: date-time
          nullable: true
        voided_at:
          type: string
          format: date-time
          nullable: true
        amount_format:
          type: string
        description:
          type: string
          nullable: true
        invoice_id:
          type: string
          nullable: true
        ip:
          type: string
          nullable: true
        callback_url:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        source:
          type: object
          additionalProperties: true
      additionalProperties: true
    Error:
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
  parameters:
    InvoiceId:
      name: id
      in: path
      required: true
      description: The invoice UUID.
      schema:
        type: string
        format: uuid
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Pass your API key as the username and leave the password empty (e.g. `-u sk_test_123:`). Publishable keys (pk_test_ / pk_live_) may only create payments and tokens; secret keys (sk_test_ / sk_live_) authorize all operations.