{
  "openapi": "3.0.0",
  "info": {
    "title": "Wayl API",
    "version": "1.0.0",
    "description": "Wayl API enables merchants to integrate payment solutions, manage products, handle subscriptions, and process refunds. This RESTful API uses JSON for requests and responses, and requires authentication via API keys. All amounts are in Iraqi Dinar (IQD).",
    "contact": {
      "name": "Wayl API Support",
      "url": "https://thewayl.com/support"
    },
    "x-logo": {
      "url": "https://thewayl.com/logo.png"
    }
  },
  "servers": [
    {
      "url": "https://api.thewayl.com",
      "description": "Production Server"
    },
    {
      "url": "https://api.thewayl-staging.com",
      "description": "Testing Server"
    },
    {
      "url": "http://localhost:3006",
      "description": "Local Server"
    }
  ],
  "security": [
    {
      "apiWaylAuthentication": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Verify your API credentials and ensure your authentication key is valid before making API requests."
    },
    {
      "name": "Links",
      "description": "Payment links allow you to create shareable URLs that customers can use to complete payments. Each link is tied to a specific order and can include line item breakdowns, webhooks for status updates, and custom redirection URLs. Links support various statuses throughout their lifecycle (Created, Pending, Processing, Complete, etc.)."
    },
    {
      "name": "Products",
      "description": "Manage your Digital, Physical, and Service products. Products can have variants (inventories), discounts, stock tracking, and downloadable files."
    },
    {
      "name": "Refunds",
      "description": "Process refund requests for completed payments. Refunds require a detailed reason (minimum 100 characters) and can only be issued for paid orders linked to customers. Optionally provide an alternative refund method (QiCard, FIB, or ZainCash) with an account number. Track refund status from Request through to Refunded, Rejected, or Cancelled."
    }
  ],
  "paths": {
    "/api/v1/links": {
      "post": {
        "tags": [
          "Links"
        ],
        "summary": "Create a Link",
        "description": "Create a payment link for your customers. Store must be verified to create links. The referenceId must be unique across all your links.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "env": {
                    "type": "string",
                    "enum": [
                      "live",
                      "test"
                    ],
                    "example": "live",
                    "description": "The env of the link."
                  },
                  "referenceId": {
                    "type": "string",
                    "example": "dummy-reference-id",
                    "description": "A unique identifier for the link on your system (max 255 characters). Must be unique across all your links."
                  },
                  "total": {
                    "type": "number",
                    "example": 10000,
                    "description": "The total amount to be paid in IQD (minimum 1000). Must equal the sum of all line items if line items are provided."
                  },
                  "currency": {
                    "type": "string",
                    "example": "IQD",
                    "description": "The currency of the link. Currently only IQD is supported."
                  },
                  "customParameter": {
                    "type": "string",
                    "description": "Optional custom parameter for your internal tracking or display purposes."
                  },
                  "lineItem": {
                    "type": "array",
                    "description": "Optional line items breakdown. If provided, the sum of all line items must equal the total amount.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "label": {
                          "type": "string",
                          "example": "Basket Value",
                          "description": "Label for this line item (3-255 characters)"
                        },
                        "amount": {
                          "type": "number",
                          "example": 10000,
                          "description": "Amount for this line item in IQD (minimum 1)"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "increase",
                            "decrease"
                          ],
                          "description": "Whether this line item increases or decreases the total amount"
                        }
                      }
                    }
                  },
                  "webhookUrl": {
                    "type": "string",
                    "example": "https://webhook.site/your-webhook-url",
                    "description": "The webhook URL to be called when payment status changes. Must be a valid URL."
                  },
                  "webhookSecret": {
                    "type": "string",
                    "example": "1234567890",
                    "description": "Secret key used to verify webhook authenticity (10-255 characters). Will be encrypted in our system."
                  },
                  "redirectionUrl": {
                    "type": "string",
                    "example": "https://www.google.com",
                    "description": "The URL to redirect customers after successful payment. Will have referenceId and orderid appended as query parameters."
                  },
                  "linkExpiresIn": {
                    "type": "string",
                    "example": "24h",
                    "description": "Optional duration until the payment link expires. Format: number + unit (m, h, or d), e.g. \"30m\", \"1h\", \"24h\", \"7d\". Must be between 1m and 30d. Defaults to \"1h\" when omitted."
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Link created successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "type": "object",
                        "properties": {
                          "customParameter": {
                            "type": "string",
                            "nullable": true,
                            "description": "Custom parameter for internal tracking"
                          },
                          "referenceId": {
                            "type": "string",
                            "description": "Your unique reference ID"
                          },
                          "id": {
                            "type": "string",
                            "description": "Wayl's unique identifier for this link"
                          },
                          "code": {
                            "type": "string",
                            "description": "Short alphanumeric code used in the payment URL"
                          },
                          "total": {
                            "type": "string",
                            "description": "Total amount as string"
                          },
                          "currency": {
                            "type": "string",
                            "description": "Payment currency"
                          },
                          "type": {
                            "type": "string",
                            "description": "Link type identifier"
                          },
                          "paymentMethod": {
                            "type": "string",
                            "nullable": true,
                            "description": "Payment method used (null until payment is made)"
                          },
                          "reversable": {
                            "type": "boolean",
                            "description": "Whether this paid order can be reversed. Only present when type is Order."
                          },
                          "status": {
                            "type": "string",
                            "description": "Current payment status (Created, Pending, Processing, Complete, Delivered, Cancelled, Rejected, Returned)"
                          },
                          "completedAt": {
                            "type": "string",
                            "nullable": true,
                            "description": "Timestamp when payment was completed (null if not completed)"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "Link creation timestamp"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "Last update timestamp"
                          },
                          "url": {
                            "type": "string",
                            "description": "Payment URL to share with customers"
                          },
                          "webhookUrl": {
                            "type": "string",
                            "description": "Your webhook URL"
                          },
                          "redirectionUrl": {
                            "type": "string",
                            "description": "Customer redirection URL with appended query parameters (referenceId and orderid)"
                          },
                          "linkExpiresIn": {
                            "type": "string",
                            "example": "1h",
                            "description": "Duration until the payment link expires (e.g. \"30m\", \"1h\", \"24h\")"
                          }
                        }
                      },
                      "message": {
                        "type": "string",
                        "description": "Response message"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Links"
        ],
        "summary": "Retrieve Links",
        "description": "Get a paginated list of payment links with optional status filtering. Returns links ordered by creation date (newest first).",
        "parameters": [
          {
            "name": "take",
            "in": "query",
            "required": false,
            "description": "Number of links to retrieve per page (default: 10)",
            "schema": {
              "type": "integer",
              "default": 10
            }
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Number of links to skip for pagination (default: 0)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "statuses",
            "in": "query",
            "required": false,
            "description": "Filter by payment status. Can provide multiple values. Valid statuses: Created, Pending, Processing, Complete, Delivered, Cancelled, Rejected, Returned",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "example": "Pending"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of links",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "Array of payment links",
                      "items": {
                        "type": "object",
                        "properties": {
                          "customParameter": {
                            "type": "string",
                            "nullable": true,
                            "description": "Custom parameter for tracking"
                          },
                          "referenceId": {
                            "type": "string",
                            "description": "Your unique reference ID"
                          },
                          "id": {
                            "type": "string",
                            "description": "Wayl's unique identifier"
                          },
                          "total": {
                            "type": "string",
                            "description": "Total amount as string"
                          },
                          "currency": {
                            "type": "string",
                            "description": "Payment currency"
                          },
                          "type": {
                            "type": "string",
                            "description": "Link type"
                          },
                          "paymentMethod": {
                            "type": "string",
                            "nullable": true,
                            "description": "Payment method used"
                          },
                          "reversable": {
                            "type": "boolean",
                            "description": "Whether this paid order can be reversed. Only present when type is Order."
                          },
                          "status": {
                            "type": "string",
                            "description": "Current payment status"
                          },
                          "completedAt": {
                            "type": "string",
                            "nullable": true,
                            "description": "Payment completion timestamp"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "Creation timestamp"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "Last update timestamp"
                          },
                          "url": {
                            "type": "string",
                            "description": "Payment URL"
                          },
                          "webhookUrl": {
                            "type": "string",
                            "description": "Webhook URL"
                          },
                          "redirectionUrl": {
                            "type": "string",
                            "description": "Redirection URL"
                          },
                          "linkExpiresIn": {
                            "type": "string",
                            "example": "1h",
                            "description": "Duration until the payment link expires (e.g. \"30m\", \"1h\", \"24h\")"
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "description": "Response message"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/links/{referenceId}": {
      "get": {
        "tags": [
          "Links"
        ],
        "summary": "Retrieve a specific Link",
        "description": "Get details of a specific payment link using your reference ID.",
        "parameters": [
          {
            "name": "referenceId",
            "in": "path",
            "required": true,
            "description": "Your unique reference ID for the link",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Details of the link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "referenceId": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "total": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "paymentMethod": {
                          "type": "string"
                        },
                        "reversable": {
                          "type": "boolean",
                          "description": "Whether this paid order can be reversed. Only present when type is Order."
                        },
                        "status": {
                          "type": "string"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "webhookUrl": {
                          "type": "string"
                        },
                        "redirectionUrl": {
                          "type": "string"
                        },
                        "linkExpiresIn": {
                          "type": "string",
                          "example": "1h",
                          "description": "Duration until the payment link expires"
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/links/{referenceId}/invalidate": {
      "post": {
        "tags": [
          "Links"
        ],
        "summary": "Invalidate a specific Link",
        "description": "Cancel an unpaid payment link. Once invalidated, customers cannot make payments using this link.",
        "parameters": [
          {
            "name": "referenceId",
            "in": "path",
            "required": true,
            "description": "Your reference ID of the link to invalidate",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Link invalidated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "referenceId": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "total": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "paymentMethod": {
                          "type": "string"
                        },
                        "reversable": {
                          "type": "boolean",
                          "description": "Whether this paid order can be reversed. Only present when type is Order."
                        },
                        "status": {
                          "type": "string"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "webhookUrl": {
                          "type": "string"
                        },
                        "redirectionUrl": {
                          "type": "string"
                        },
                        "linkExpiresIn": {
                          "type": "string",
                          "example": "1h",
                          "description": "Duration until the payment link expires"
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/links/{referenceId}/invalidate-if-pending": {
      "post": {
        "tags": [
          "Links"
        ],
        "summary": "Invalidate a specific Link if it is pending",
        "description": "Invalidate a specific payment link if it is pending. If the link is not pending, it will return a success response.",
        "parameters": [
          {
            "name": "referenceId",
            "in": "path",
            "required": true,
            "description": "Your reference ID of the link to invalidate if it is pending",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Link invalidated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "referenceId": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        },
                        "total": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "paymentMethod": {
                          "type": "string"
                        },
                        "reversable": {
                          "type": "boolean",
                          "description": "Whether this paid order can be reversed. Only present when type is Order."
                        },
                        "status": {
                          "type": "string"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "webhookUrl": {
                          "type": "string"
                        },
                        "redirectionUrl": {
                          "type": "string"
                        },
                        "linkExpiresIn": {
                          "type": "string",
                          "example": "1h",
                          "description": "Duration until the payment link expires"
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/links/batch": {
      "post": {
        "tags": [
          "Links"
        ],
        "summary": "Retrieve a Group of Links by Reference IDs",
        "description": "Get details for multiple links by providing an array of reference IDs (1-100 items). Only returns links that belong to the authenticated merchant.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "referenceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Array of your reference IDs to retrieve. Minimum 1, maximum 100 items per request.",
                    "example": [
                      "ref-001",
                      "ref-002",
                      "ref-003"
                    ]
                  }
                },
                "required": [
                  "referenceIds"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch retrieval successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "referenceId": {
                            "type": "string"
                          },
                          "id": {
                            "type": "string"
                          },
                          "total": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string"
                          },
                          "paymentMethod": {
                            "type": "string",
                            "nullable": true
                          },
                          "reversable": {
                            "type": "boolean",
                            "description": "Whether this paid order can be reversed. Only present when type is Order."
                          },
                          "status": {
                            "type": "string"
                          },
                          "completedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "webhookUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "redirectionUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "linkExpiresIn": {
                            "type": "string",
                            "example": "1h",
                            "description": "Duration until the payment link expires"
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "example": "Found 2 links out of 3 requested reference IDs"
                    },
                    "totalRequested": {
                      "type": "integer",
                      "description": "Total number of reference IDs requested"
                    },
                    "totalFound": {
                      "type": "integer",
                      "description": "Total number of links found"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Invalid request. Please provide an array of referenceIds (1-100 items)."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "Retrieve All Products",
        "description": "Get a paginated list of your products (Digital, Physical, and Service products - excludes Subscription products). Returns products ordered by creation date (newest first).",
        "parameters": [
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Number of products to skip for pagination (default: 0)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "description": "Number of products to retrieve (default: 10)",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of Products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "Array of product objects",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique product identifier"
                          },
                          "name": {
                            "type": "string",
                            "description": "Product name/title"
                          },
                          "price": {
                            "type": "string",
                            "description": "Product price in IQD"
                          },
                          "url": {
                            "type": "string",
                            "description": "Public product page URL"
                          },
                          "status": {
                            "type": "string",
                            "description": "Product status (e.g., Active, Inactive)"
                          },
                          "image": {
                            "type": "string",
                            "description": "Primary product image URL"
                          },
                          "tags": {
                            "type": "string",
                            "description": "Product tag/category label"
                          },
                          "description": {
                            "type": "string",
                            "description": "Product description/content"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "Product creation timestamp"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "Last update timestamp"
                          },
                          "productType": {
                            "type": "string",
                            "description": "Type of product (Digital, Physical, Service)"
                          },
                          "downloadable": {
                            "type": "string",
                            "description": "Downloadable file URL for digital products"
                          },
                          "discountType": {
                            "type": "string",
                            "description": "Type of discount applied (e.g., percentage, fixed)"
                          },
                          "discountExpiry": {
                            "type": "string",
                            "description": "When the discount expires"
                          },
                          "discountValue": {
                            "type": "string",
                            "description": "Discount value"
                          },
                          "inventories": {
                            "type": "array",
                            "description": "Product variants and inventory options",
                            "items": {
                              "type": "object"
                            }
                          },
                          "qt": {
                            "type": "number",
                            "description": "Total quantity in stock"
                          },
                          "unlimited": {
                            "type": "boolean",
                            "description": "Whether product has unlimited stock"
                          },
                          "notifyOn": {
                            "type": "number",
                            "description": "Stock level to trigger low inventory notification"
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "description": "Response message"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products/{productId}": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "Retrieve a specific Product",
        "description": "Get detailed information about a specific product by its ID.",
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the product to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Details of the Product",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "price": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "image": {
                          "type": "string"
                        },
                        "tags": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/refunds": {
      "post": {
        "tags": [
          "Refunds"
        ],
        "summary": "Create a Refund",
        "description": "Request a refund for a completed payment. The order must be paid and linked to a customer. Amount must not exceed the amount paid on the gateway. Optionally provide refundMethod and accountNumber together to send the refund to an alternative account instead of the original payment method.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "referenceId": {
                    "type": "string",
                    "description": "Your reference ID for the order to be refunded (2-255 characters)"
                  },
                  "reason": {
                    "type": "string",
                    "description": "Detailed reason for the refund. Minimum 100 characters, maximum 1500 characters."
                  },
                  "amount": {
                    "type": "number",
                    "description": "Amount to refund in IQD (minimum 1000). Must be less than or equal to the amount paid on the payment gateway."
                  },
                  "refundMethod": {
                    "type": "string",
                    "enum": ["QiCard", "FIB", "ZainCash"],
                    "description": "Optional alternative refund method. Must be provided together with accountNumber."
                  },
                  "accountNumber": {
                    "type": "string",
                    "description": "Optional account ID or number for the alternative refund method. Must be provided together with refundMethod."
                  }
                }
              }
            }
          },
          "responses": {
            "201": {
              "description": "Refund created successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "data": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique refund identifier"
                          },
                          "reason": {
                            "type": "string",
                            "description": "Refund reason"
                          },
                          "linkId": {
                            "type": "string",
                            "description": "Associated order/link ID"
                          },
                          "referenceId": {
                            "type": "string",
                            "description": "Your order reference ID"
                          },
                          "amount": {
                            "type": "number",
                            "description": "Refund amount in IQD"
                          },
                          "initiatedBy": {
                            "type": "string",
                            "description": "Who initiated the refund (Merchant, Customer, or System)"
                          },
                          "status": {
                            "type": "string",
                            "description": "Current refund status (Requested, Refunded, Rejected, Cancelled)"
                          },
                          "refundMethod": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["QiCard", "FIB", "ZainCash"],
                            "description": "Alternative refund method, or null when refunding to the original account"
                          },
                          "accountNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "Account ID or number for the alternative refund method"
                          }
                        }
                      },
                      "message": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "Retrieve Refunds",
        "description": "Get a paginated list of refund requests with optional filtering by reference ID and status. Returns refunds ordered by creation date (newest first).",
        "parameters": [
          {
            "name": "referenceId",
            "in": "query",
            "required": false,
            "description": "Filter refunds by your order reference ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "description": "Number of refunds to retrieve (default: 10)",
            "schema": {
              "type": "integer",
              "default": 10
            }
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Number of refunds to skip for pagination (default: 0)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "statuses",
            "in": "query",
            "required": false,
            "description": "Filter by refund status. Can provide multiple values. Valid statuses: Requested, Refunded, Rejected, Cancelled",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "example": "Requested"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Details of the refunds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Refund identifier"
                          },
                          "reason": {
                            "type": "string",
                            "description": "Refund reason"
                          },
                          "linkId": {
                            "type": "string",
                            "description": "Associated order ID"
                          },
                          "referenceId": {
                            "type": "string",
                            "description": "Your order reference ID"
                          },
                          "amount": {
                            "type": "number",
                            "description": "Refund amount in IQD"
                          },
                          "initiatedBy": {
                            "type": "string",
                            "description": "Who requested the refund"
                          },
                          "status": {
                            "type": "string",
                            "description": "Current refund status"
                          },
                          "refundMethod": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["QiCard", "FIB", "ZainCash"],
                            "description": "Alternative refund method, or null when refunding to the original account"
                          },
                          "accountNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "Account ID or number for the alternative refund method"
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/refunds/{refundId}": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "Retrieve a specific Refund",
        "description": "Get details of a specific refund request by its ID.",
        "parameters": [
          {
            "name": "refundId",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the refund to retrieve",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Details of the refund",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reason": {
                          "type": "string"
                        },
                        "linkId": {
                          "type": "string"
                        },
                        "referenceId": {
                          "type": "string"
                        },
                        "amount": {
                          "type": "number"
                        },
                        "initiatedBy": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "refundMethod": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["QiCard", "FIB", "ZainCash"]
                        },
                        "accountNumber": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/refunds/{refundId}/cancel": {
      "delete": {
        "tags": [
          "Refunds"
        ],
        "summary": "Cancel a specific Refund",
        "description": "Cancel a pending refund request. Only refunds with 'Requested' status can be cancelled.",
        "parameters": [
          {
            "name": "refundId",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the refund to cancel",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Refund canceled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reason": {
                          "type": "string"
                        },
                        "linkId": {
                          "type": "string"
                        },
                        "amount": {
                          "type": "number"
                        },
                        "initiatedBy": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "refundMethod": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["QiCard", "FIB", "ZainCash"]
                        },
                        "accountNumber": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verify-auth-key": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Verify Authentication Key",
        "description": "Verify that your API authentication key is valid and working. Use this endpoint to test your API credentials before making actual API calls.",
        "responses": {
          "200": {
            "description": "Authentication key is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {},
                      "description": "Empty object on successful verification"
                    },
                    "message": {
                      "type": "string",
                      "description": "Response message confirming authentication"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiWaylAuthentication": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WAYL-AUTHENTICATION",
        "description": "API key for merchant authentication. Include your authentication key in the X-WAYL-AUTHENTICATION header for all API requests. You can find your API key in your Wayl merchant dashboard."
      },
      "merchant": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WAYL-AUTHENTICATION",
        "description": "Merchant API key authentication"
      },
      "admin": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WAYL-ADMIN-TOKEN",
        "description": "Admin token for administrative operations"
      }
    }
  }
}
