openapi: 3.0.3
info:
  title: Reach Pay API
  description: >-
    Reach Pay is Reachware's payment API for Saudi Arabia payment gateways.
    It provides a hosted checkout (Request Payment), payment status retrieval
    (Payment Details), refunds, and card-save (tokenization) flows. Reach Pay
    does not store card information; sensitive card data is handled by the
    underlying payment gateway. This specification was generated by the API
    Evangelist enrichment pipeline from Reach Pay's published API reference at
    https://docs.reachware.com — it captures the documented operations, request
    and response fields verbatim; it is not the provider's own machine-readable
    spec.
  version: '1.0'
  x-generated-by: api-evangelist-enrichment
  x-source: https://docs.reachware.com/api-reference
  contact:
    name: Reach Pay Support
    email: support@reachware.com
    url: https://docs.reachware.com
servers:
  - url: https://api.reachware.com
    description: Sandbox (production base URL provided after integration verification)
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Request payments, retrieve payment details, and refunds
  - name: Cards
    description: Card save / tokenization flows
paths:
  /pay/RequestPayment:
    post:
      operationId: requestPayment
      tags: [Payments]
      summary: Request Payment
      description: >-
        Initiate a payment and receive a hosted payment gateway URL to redirect
        the payer to for completing the checkout.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_id, order_id, payment_id, amount, return_url]
              properties:
                client_id: { type: string }
                order_id: { type: string }
                payment_id: { type: string }
                amount: { type: number, format: float }
                return_url: { type: string, format: uri }
                location_id: { type: string }
                card_token: { type: string }
                redirect_url: { type: string, format: uri }
                lang: { type: string }
                card_save: { type: string }
      responses:
        '200':
          description: Payment initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment_id: { type: string }
                  payment_gateway_url: { type: string, format: uri }
        '400':
          description: Bad request (e.g. return_url missing)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorFlag' }
        '404':
          description: Config not found for id
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorFlag' }
        '500':
          description: Server error (e.g. payment submitted before)
          content:
            application/json:
              schema:
                type: object
                properties:
                  body: { type: string }
                  message: { type: string }
  /pay/PaymentDetails:
    get:
      operationId: getPaymentDetails
      tags: [Payments]
      summary: Payment Details
      description: Retrieve the details and status of a payment transaction.
      parameters:
        - name: client_id
          in: header
          required: true
          schema: { type: string }
          description: Unique identifier of the client making the request
        - name: gateway_payment_id
          in: query
          required: true
          schema: { type: string }
          description: Unique identifier of the payment transaction provided by the payment gateway
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id: { type: string }
                  transaction_id: { type: string }
                  amount: { type: string }
                  message: { type: string }
                  status: { type: integer }
                  source: { type: string }
                  card_save: { type: boolean }
                  payment_option: { type: string }
                  card_mask: { type: string }
        '404':
          description: Config not found for id
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorFlag' }
  /pay/Refund:
    post:
      operationId: refundPayment
      tags: [Payments]
      summary: Refund
      description: Refund all or part of a previously captured payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_id, amount, gateway_payment_id]
              properties:
                client_id: { type: string }
                amount: { type: number }
                gateway_payment_id: { type: string }
      responses:
        '200':
          description: Refund processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction_id: { type: string }
                  status: { type: integer }
                  amount: { type: integer }
                  fee: { type: integer }
                  currency: { type: string }
                  refunded: { type: integer }
        '404':
          description: Record not found or refund not permitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum: [record_not_found, invalid_request_error]
                  message: { type: string }
  /pay/RequestSaveCard:
    post:
      operationId: requestSaveCard
      tags: [Cards]
      summary: Save Cards
      description: >-
        Start a card save (tokenization) flow and receive a hosted card
        registration URL to redirect the payer to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_id, request_id, return_url]
              properties:
                client_id: { type: string }
                request_id: { type: string }
                return_url: { type: string, format: uri }
      responses:
        '200':
          description: Card save flow initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id: { type: string }
                  card_gateway_url: { type: string, format: uri }
        '400':
          description: Bad request (e.g. return_url missing)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorFlag' }
        '404':
          description: Config not found for client id
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorFlag' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Merchant API token: Authorization: Bearer {reachToken}'
  schemas:
    ErrorFlag:
      type: object
      properties:
        error: { type: boolean }
        message: { type: string }