openapi: 3.0.3
info:
  title: Moyasar Invoices Payments 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: Payments
  description: Create and manage card and wallet payments.
paths:
  /payments:
    get:
      operationId: listPayments
      tags:
      - Payments
      summary: List payments
      description: Lists payments on the account with filtering and pagination.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - initiated
          - paid
          - authorized
          - failed
          - refunded
          - captured
          - voided
          - verified
      - name: created[gt]
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: created[lt]
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: card_last_digits
        in: query
        required: false
        schema:
          type: string
      - name: receipt_no
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of payments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPayment
      tags:
      - Payments
      summary: Create a payment
      description: Creates a payment. Can be called with a publishable key from the client side or a secret key from the backend. The `source` object selects the payment method (creditcard, token, applepay, samsungpay, stcpay).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInput'
      responses:
        '201':
          description: The created payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /payments/{id}:
    parameters:
    - $ref: '#/components/parameters/PaymentId'
    get:
      operationId: fetchPayment
      tags:
      - Payments
      summary: Fetch a payment
      description: Retrieves a single payment by its ID.
      responses:
        '200':
          description: The requested payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/refund:
    parameters:
    - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: refundPayment
      tags:
      - Payments
      summary: Refund a payment
      description: Refunds a paid payment in full or in part. Omit `amount` for a full refund.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: Amount to refund in the smallest currency unit. Full refund if omitted.
      responses:
        '200':
          description: The refunded payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/capture:
    parameters:
    - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: capturePayment
      tags:
      - Payments
      summary: Capture a payment
      description: Captures an authorized payment, in full or in part. Omit `amount` to capture the full authorized amount.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: Amount to capture in the smallest currency unit. Full capture if omitted.
      responses:
        '200':
          description: The captured payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payments/{id}/void:
    parameters:
    - $ref: '#/components/parameters/PaymentId'
    post:
      operationId: voidPayment
      tags:
      - Payments
      summary: Void a payment
      description: Voids an authorized payment that has not yet been captured.
      responses:
        '200':
          description: The voided payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaymentInput:
      type: object
      required:
      - amount
      - currency
      - source
      properties:
        amount:
          type: integer
          description: Positive amount in the smallest currency unit (halalas for SAR).
        currency:
          type: string
          description: ISO-4217 three-letter code (e.g. SAR).
          default: SAR
        source:
          $ref: '#/components/schemas/PaymentSource'
        description:
          type: string
        callback_url:
          type: string
          format: uri
          description: Required for creditcard and token sources.
        given_id:
          type: string
          description: Client-supplied UUID for idempotency.
        metadata:
          type: object
          additionalProperties: true
        splits:
          type: array
          items:
            type: object
            additionalProperties: true
    PaymentSource:
      type: object
      description: Payment source. The `type` field selects the method. Additional fields depend on the source type (card fields, token id, wallet token, etc.).
      properties:
        type:
          type: string
          enum:
          - creditcard
          - token
          - applepay
          - samsungpay
          - stcpay
        name:
          type: string
        number:
          type: string
        cvc:
          type: string
        month:
          type: string
        year:
          type: string
        token:
          type: string
      additionalProperties: true
    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
    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
  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'
  parameters:
    PaymentId:
      name: id
      in: path
      required: true
      description: The payment 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.