---
swagger: "2.0"
info:
  x-ibm-name: partner-qr-code-management-api
  title: Partner QR Code Management API
  version: 1.0.0
  description: QR Code Management API segregated from Merchant Onboarding API. Provides
    endpoints for QR code registration, deletion, status checking, and static QR retrieval.
  contact:
    name: API developer
    email: apideveloper@rakbank.ae
  name: ""
schemes:
- https
host: sandboxapi.rakbank.ae
basePath: /v1/npss
consumes:
- application/json
produces:
- application/json
paths:
  /merchant/groups/{group_code}/banks/{bank_code}/bank_user/{bank_user_id}/tag/{merchant_tag}/retrieve_static_qr:
    get:
      tags:
      - QR Code Management
      summary: Retrieve Static QR
      description: This endpoint will be used to retrieve static QR code for merchant
      operationId: retrieveStaticQr
      parameters:
      - name: group_code
        in: path
        required: true
        type: string
        description: Group code identifier
      - name: bank_code
        in: path
        required: true
        type: string
        description: Bank code identifier
      - name: bank_user_id
        in: path
        required: true
        type: string
        description: Bank user identifier
      - name: merchant_tag
        in: path
        required: true
        type: string
        description: Merchant tag identifier
      responses:
        200:
          description: Static QR retrieved successfully
          schema:
            $ref: '#/definitions/RetrieveStaticQrResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: Static QR not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters:
    - name: MsgId
      type: string
      required: true
      in: header
      description: Unique Id sent by client. Value should be a unique identifier of
        the request in UUID format.
  /merchant/groups/{group_code}/banks/{bank_code}/bank_user/{bank_user_id}/tag/{merchant_tag}/delete_qr_code:
    delete:
      tags:
      - QR Code Management
      summary: Delete QR Code
      description: This endpoint will be used to delete an existing QR code
      operationId: deleteQrCode
      parameters:
      - name: group_code
        in: path
        required: true
        type: string
        description: Group code identifier
      - name: bank_code
        in: path
        required: true
        type: string
        description: Bank code identifier
      - name: bank_user_id
        in: path
        required: true
        type: string
        description: Bank user identifier
      - name: merchant_tag
        in: path
        required: true
        type: string
        description: Merchant tag identifier
      - name: qr_code_id
        in: query
        type: string
        description: QR code identifier to be deleted
      - name: qr_code_transaction_id
        in: query
        type: string
        description: QR code transaction identifier
      responses:
        200:
          description: QR code deleted successfully
          schema:
            $ref: '#/definitions/DeleteQrCodeResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: QR code not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters:
    - name: MsgId
      type: string
      required: true
      in: header
      description: Unique Id sent by client. Value should be a unique identifier of
        the request in UUID format.
  /inquiry_payment/groups/{group_code}/banks/{bank_code}/bank_user/{bank_user_id}/tag/{merchant_tag}/check_qr_code_status:
    get:
      tags:
      - QR Code Management
      summary: Check QR Code Status
      description: This endpoint will be used to check the status of a QR code transaction
      operationId: checkQrCodeStatus
      parameters:
      - name: group_code
        in: path
        required: true
        type: string
        description: Group code identifier
      - name: bank_code
        in: path
        required: true
        type: string
        description: Bank code identifier
      - name: bank_user_id
        in: path
        required: true
        type: string
        description: Bank user identifier
      - name: merchant_tag
        in: path
        required: true
        type: string
        description: Merchant tag identifier
      - name: qr_code_id
        in: query
        required: true
        type: string
        description: QR code identifier to check status
      responses:
        200:
          description: QR code status retrieved successfully
          schema:
            $ref: '#/definitions/CheckStatusQrCodeResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: QR code not found
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters:
    - name: MsgId
      type: string
      required: true
      in: header
      description: Unique Id sent by client. Value should be a unique identifier of
        the request in UUID format.
  /merchant/groups/{group_code}/banks/{bank_code}/bank_user/{bank_user_id}/tag/{merchant_tag}/register_qr_code:
    post:
      tags:
      - QR Code Management
      summary: Register QR Code
      description: This endpoint will be used to register a new QR code for merchant
        transactions
      operationId: registerQrCode
      parameters:
      - name: group_code
        in: path
        required: true
        type: string
        description: Group code identifier
      - name: bank_code
        in: path
        required: true
        type: string
        description: Bank code identifier
      - name: bank_user_id
        in: path
        required: true
        type: string
        description: Bank user identifier
      - name: merchant_tag
        in: path
        required: true
        type: string
        description: Merchant tag identifier
      - name: register_qr_code_request
        in: body
        required: true
        schema:
          $ref: '#/definitions/RegisterQrCodeRequest'
        description: Request body for QR code registration
      responses:
        200:
          description: QR code registered successfully
          schema:
            $ref: '#/definitions/RegisterQrCodeResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
    parameters:
    - name: MsgId
      type: string
      required: true
      in: header
      description: Unique Id sent by client. Value should be a unique identifier of
        the request in UUID format.
definitions:
  QrPayload:
    type: object
    properties:
      emv_string:
        type: string
        example: 00020101021243650016A000000677010111...
        description: EMV QR code string
      qr_image:
        type: string
        example: iVBORw0KGgoAAAANSUhEUgAA...
        description: Base64 encoded QR image
    additionalProperties: false
  MerchantDetails:
    type: object
    properties:
      merchant_tag:
        type: string
        example: MERCHANT123
        description: Merchant tag identifier
      static_qr_code:
        type: string
        example: QR123456789
        description: Static QR code
      qr_payload:
        $ref: '#/definitions/QrPayload'
    additionalProperties: false
  RetrieveStaticQrDetails:
    type: object
    properties:
      code:
        type: string
        example: SUCCESS
        description: Response code
      desc:
        type: string
        example: Static QR retrieved successfully
        description: Response description
      merchant_dtl:
        $ref: '#/definitions/MerchantDetails'
    additionalProperties: false
  RetrieveStaticQrResponseDetail:
    type: object
    properties:
      retrieve_static_qr_dtl:
        $ref: '#/definitions/RetrieveStaticQrDetails'
    additionalProperties: false
  RetrieveStaticQrResponse:
    type: object
    properties:
      header:
        $ref: '#/definitions/ResponseHeader'
      resp_dtl:
        $ref: '#/definitions/RetrieveStaticQrResponseDetail'
    additionalProperties: false
  PaymentDetails:
    type: object
    properties:
      payment_id:
        type: string
        example: PAY123456789
        description: Payment identifier
      amount:
        type: number
        format: double
        example: 100.500000
        description: Transaction amount
      currency:
        type: string
        example: AED
        description: Transaction currency
      fees:
        type: number
        format: double
        example: 2.500000
        description: Transaction fees
      total_amt:
        type: number
        format: double
        example: 103
        description: Total amount including fees
      reason:
        type: string
        example: Payment for goods
        description: Transaction reason
      shop_id:
        type: integer
        format: int32
        example: 12345
        description: Shop identifier
      cash_desk_id:
        type: integer
        format: int32
        example: 67890
        description: Cash desk identifier
    additionalProperties: false
  DeleteQrCodeDetails:
    type: object
    properties:
      code:
        type: string
        example: SUCCESS
        description: Response code
      desc:
        type: string
        example: QR code deleted successfully
        description: Response description
      payment:
        $ref: '#/definitions/PaymentDetails'
    additionalProperties: false
  DeleteQrCodeResponseDetail:
    type: object
    properties:
      delete_qr_code_dtl:
        $ref: '#/definitions/DeleteQrCodeDetails'
    additionalProperties: false
  DeleteQrCodeResponse:
    type: object
    properties:
      header:
        $ref: '#/definitions/ResponseHeader'
      resp_dtl:
        $ref: '#/definitions/DeleteQrCodeResponseDetail'
    additionalProperties: false
  QrCodeStatus:
    type: object
    properties:
      qr_code_request_status:
        type: string
        example: COMPLETED
        description: Current status of QR code request
      payment_id:
        type: integer
        format: int32
        example: 123456789
        description: Payment identifier
      last_update_date:
        type: string
        format: date-time
        example: "2025-06-10T10:30:00Z"
        description: Last update timestamp
      payment_id_sct:
        type: string
        example: SCT123456789
        description: SCT payment identifier
    additionalProperties: false
  CheckQrCodeStatusDetails:
    type: object
    properties:
      code:
        type: string
        example: SUCCESS
        description: Response code
      desc:
        type: string
        example: QR code status retrieved successfully
        description: Response description
      qr_code_status:
        $ref: '#/definitions/QrCodeStatus'
    additionalProperties: false
  CheckQrCodeStatusResponseDetail:
    type: object
    properties:
      check_qr_code_status_dtl:
        $ref: '#/definitions/CheckQrCodeStatusDetails'
    additionalProperties: false
  CheckStatusQrCodeResponse:
    type: object
    properties:
      header:
        $ref: '#/definitions/ResponseHeader'
      resp_dtl:
        $ref: '#/definitions/CheckQrCodeStatusResponseDetail'
    additionalProperties: false
  RegisterQrData:
    type: object
    required:
    - amount
    - currency
    properties:
      amount:
        type: number
        format: double
        example: 100.500000
        description: Amount for the QR code transaction
      currency:
        type: string
        example: AED
        description: Currency code for the transaction
      reason:
        type: string
        example: Payment for goods
        description: Reason for the transaction
      shop_id:
        type: integer
        format: int32
        example: 12345
        description: Shop identifier
      cash_desk_id:
        type: integer
        format: int32
        example: 67890
        description: Cash desk identifier
      category_purpose:
        type: string
        example: RETAIL
        description: Category purpose of the transaction
    additionalProperties: false
  RegisterQrCodeRequest:
    type: object
    required:
    - header
    - register_qr
    properties:
      header:
        $ref: '#/definitions/RequestHeader'
      register_qr:
        $ref: '#/definitions/RegisterQrData'
      payment_category:
        type: string
        example: MERCHANT
        description: Payment category
      payment_type:
        type: string
        example: QR
        description: Payment type
      qr_code_transaction_id:
        type: string
        example: TXN123456789
        description: QR code transaction identifier
    additionalProperties: false
  RegisterQrDetails:
    type: object
    properties:
      qr_code_id:
        type: string
        example: QR123456789
        description: Generated QR code identifier
      link:
        type: string
        example: https://payment.rakbank.ae/qr/123456
        description: Payment link
    additionalProperties: false
  RegisterQrResponseData:
    type: object
    properties:
      code:
        type: string
        example: SUCCESS
        description: Response code
      desc:
        type: string
        example: QR code registered successfully
        description: Response description
      register_qr_dtl:
        $ref: '#/definitions/RegisterQrDetails'
    additionalProperties: false
  RegisterQrResponseDetail:
    type: object
    properties:
      register_qr:
        $ref: '#/definitions/RegisterQrResponseData'
      qr_payload:
        $ref: '#/definitions/QrPayload'
    additionalProperties: false
  RegisterQrCodeResponse:
    type: object
    properties:
      header:
        $ref: '#/definitions/ResponseHeader'
      resp_dtl:
        $ref: '#/definitions/RegisterQrResponseDetail'
    additionalProperties: false
  RequestHeader:
    type: object
    required:
    - channel
    - channel_ref
    - time_stamp
    properties:
      channel:
        type: string
        example: API
        description: Channel identifier
      channel_ref:
        type: string
        example: REF123456
        description: Channel reference
      time_stamp:
        type: string
        format: date-time
        example: "2025-06-10T10:30:00Z"
        description: Request timestamp
    additionalProperties: false
  ResponseHeader:
    type: object
    properties:
      channel:
        type: string
        example: API
        description: Channel identifier
      channel_ref:
        type: string
        example: REF123456
        description: Channel reference
      time_stamp:
        type: string
        format: date-time
        example: "2025-06-10T10:30:00Z"
        description: Response timestamp
      status_code:
        type: string
        example: "200"
        description: Status code
      status_desc:
        type: string
        example: Success
        description: Status description
      MsgId:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
        description: Message identifier from request
    additionalProperties: false
  ErrorResponse:
    type: object
    properties:
      status:
        type: string
        example: "400"
        description: HTTP Status
      response_code:
        type: string
        example: QR_001
        description: API specific error code
      property:
        type: string
        example: amount
        description: Property that caused the error
      response_message:
        type: string
        description: Brief type of the error
        example: Invalid amount
      description:
        type: string
        description: Detailed description of the error
        example: The amount must be greater than zero
    additionalProperties: false
    required:
    - response_code
    - status
    - response_message
    description: Response in case of error
tags:
- name: QR Code Management
  description: Operations related to QR code management
x-ibm-endpoints:
- endpointUrl: https://sandboxapi.rakbank.ae/sb/api
  type:
  - production
  - development
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
...