openapi: 3.0.3
info:
  title: Moyasar Invoices Webhooks 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: Webhooks
  description: Server-to-server event notifications over HTTP POST.
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List webhooks
      description: Lists all registered webhooks.
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Create a webhook
      description: Registers an HTTPS endpoint to receive event notifications. Omit `events` to subscribe to all current and future events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{id}:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    get:
      operationId: fetchWebhook
      tags:
      - Webhooks
      summary: Fetch a webhook
      description: Retrieves a single webhook by its ID.
      responses:
        '200':
          description: The requested webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook
      description: Removes a registered webhook.
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks/{id}/attempts:
    parameters:
    - $ref: '#/components/parameters/WebhookId'
    get:
      operationId: listWebhookAttempts
      tags:
      - Webhooks
      summary: List webhook attempts
      description: Lists delivery attempts for a given webhook.
      responses:
        '200':
          description: A list of webhook delivery attempts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  attempts:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/available_events:
    get:
      operationId: listAvailableWebhookEvents
      tags:
      - Webhooks
      summary: List available webhook events
      description: Lists the event types available for webhook subscription.
      responses:
        '200':
          description: The available event types.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    WebhookInput:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
        http_method:
          type: string
          default: post
        shared_secret:
          type: string
        events:
          type: array
          description: Event types to subscribe to. Omit to receive all events.
          items:
            type: string
            enum:
            - payment_paid
            - payment_failed
            - payment_voided
            - payment_authorized
            - payment_captured
            - payment_refunded
            - payment_abandoned
            - payment_verified
            - card_auth_authenticated
            - card_auth_failed
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        http_method:
          type: string
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
      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:
    WebhookId:
      name: id
      in: path
      required: true
      description: The webhook ID.
      schema:
        type: string
  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.