openapi: 3.0.1
info:
  title: HyperPay Payment COPYandPAY Query API
  description: 'HyperPay is a MENA / Saudi Arabia payment gateway built on the ACI / OPPWA Open Payment Platform. This REST API powers the COPYandPAY hosted widget and the Server-to-Server integration, supporting card brands (VISA, MASTER, AMEX), the Saudi domestic scheme mada, STC Pay, and Apple Pay. All requests are sent as application/x-www-form-urlencoded over TLS, authenticated with an `entityId` (channel identifier) plus an `Authorization: Bearer` access token. Amounts are decimal strings and currency is an ISO 4217 code (SAR for Saudi merchants).'
  termsOfService: https://www.hyperpay.com/terms-and-conditions/
  contact:
    name: HyperPay Support
    url: https://www.hyperpay.com/contact-us/
    email: info@hyperpay.com
  version: '1.0'
servers:
- url: https://eu-prod.oppwa.com
  description: Production (live) host
- url: https://test.oppwa.com
  description: Integration / test host
security:
- bearerAuth: []
tags:
- name: Query
  description: Query the status of a prior payment.
paths:
  /v1/query/{id}:
    get:
      operationId: queryPayment
      tags:
      - Query
      summary: Query a payment status
      description: Retrieves the status of a payment by its id (or by the resourcePath returned in a redirect/webhook notification).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: entityId
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Payment status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
components:
  schemas:
    PaymentResponse:
      type: object
      properties:
        id:
          type: string
        paymentType:
          type: string
        paymentBrand:
          type: string
        amount:
          type: string
        currency:
          type: string
        result:
          $ref: '#/components/schemas/Result'
        card:
          type: object
          properties:
            bin:
              type: string
            last4Digits:
              type: string
            holder:
              type: string
            expiryMonth:
              type: string
            expiryYear:
              type: string
        registrationId:
          type: string
        merchantTransactionId:
          type: string
        timestamp:
          type: string
        ndc:
          type: string
    Result:
      type: object
      properties:
        code:
          type: string
          description: Result code, e.g. 000.000.000 (success) / 000.100.110 (test success).
          example: 000.100.110
        description:
          type: string
          example: Request successfully processed in 'Merchant in Integrator Test Mode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: accessToken
      description: 'Access token issued by HyperPay, sent as `Authorization: Bearer <token>`. Every request must ALSO carry an `entityId` channel identifier (as a form field on writes or a query parameter on reads).'