Reachware Inc. Payments API

openapi: 3.0.3
info:
  title: Reach Pay Cards Payments 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
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
components:
  schemas:
    ErrorFlag:
      type: object
      properties:
        error:
          type: boolean
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Merchant API token: Authorization: Bearer {reachToken}'