openapi: 3.0.1
info:
  title: Dynamic QR (QR CRM Scan Specification)
  version: 1.0.0
  x-logo:
    url: https://uzumbank.uz/_nuxt/img/uzumbank-logo-light.f4c13a0.svg
    href: /
  description: >

    **Dynamic QR** is a payment service that enables **QR code payments by
    scanning a QR code printed on a POS receipt** using the Uzum Bank mobile
    application.


    #### ⚙️ Key features

    - Order creation and generation of a payment link

    - Client-side QR code payment

    - Fiscalization and delivery of the receipt link

    - Payment cancellation

    - Order / payment status checks


    #### 🚀 **Quick start**

    - [Authentication](#section/Authentication)

    - [Methods](#tag/Methods)


    ---


    ## Getting started

    **To get started** with the Uzum Bank API, follow these steps:


    1. Contact your Uzum Bank account manager to enable the service.

    2. After the service is enabled, you will receive the following confidential
    credentials required for authentication and API requests:
        - **merchant_id** — a unique identifier of the merchant in the Uzum Bank system.
        - **secret_key** — a unique key used for API authentication.
        - **service_id** — a unique identifier of the branch or service location where the payment is processed.
        - **merchant_service_user_id** — a unique identifier of the POS terminal or cashier within a specific branch. This parameter allows the system to identify the exact checkout where the request originates or the operation is performed.

    These credentials are strictly confidential and must be used exclusively for
    interacting with the Uzum Bank API.


    3. Complete the API integration.



    ## Authentication


    Authentication is performed using **merchant_service_user_id** and
    **secret_key**. If you do not have this data, contact your Uzum Bank
    manager.


    When sending requests, you must include the following headers:


    - **Authorization**: merchant_service_user_id:hash:timestamp
        - **merchant_service_user_id** — unique identifier of the cash register or cashier within a specific branch.
        - **hash** — the result of calculating the SHA1 hash of the string formed by concatenating timestamp and secret_key: sha1(timestamp + secret_key)
        - **timestamp** — UNIX timestamp in milliseconds in the UTC+5 time zone (time for the region).
    - **Content-Type**: application/json


    **Request Example**

    ```

    curl --location 'https://mobile.apelsin.uz/api/dynamic-qr/merchant/payment'
    \
        --header 'Authorization: 8461:964bd9d82f6f3c13052f205e92af508cdd7085cc:1727122154352' \
        --header 'Content-Type: application/json' \
        --data '{}'
    ```


    ### Required Headers

    - `Authorization`


    - `Content-Type`


    - `Accept`


    ### Supported Content Types

    - `application/json`


    ## Error Message


    Methods only return HTTP status 200. If the request is successfully
    processed, the result is returned with `error_code` = 0.


    If an error occurs during request processing, the response is returned in
    JSON format, containing an `error_code` (Integer type) and an
    `error_message` (String type).

    <br/><br/>

    <strong> Examples of `error_code`:</strong>

    Error Code | Description

    -|-

    0 | • success

    400 | • missing one of the required fields

    401 | • Format of Authorization in Header incorrect: <br/> • regex:
    `(^\d*):([\da-f]{40}):(\d*$)`  <br /> <br /> • One of them is not ACTIVE:
    <br /> • `Merchant ID` <br /> • `Merchant service ID` <br /> • `Merchant
    service user ID`  <br /> <br /> • Incorrect `hash` <br /> <br /> •
    `service_id` does not belong to the specified partner.

    503 | • The service is not found or is not active.


    <br/><br/>

    <strong> Examples of `error_message`:</strong>


    `null` -> no errors


    `apelsin.pay.authorization.error` -> authorization is not successful


    `apelsin.pay.service.not.working` -> bank service is not available


    `apelsin.pay.fiscalization.service.not.working` -> the Fiscalization service
    is not working


    `apelsin.pay.unsupported.operation` -> invalid operation


    `apelsin.pay.reverse.not.allowed` -> reverse is not allowed for the partner


    `unsupported.fiscal.url` -> the link to fiscalization is incorrect


    `order.not.found` -> the order is not found


    `order.id.duplicated` -> retry payment `order_id`


    `operation.not.found` -> the service is not active or not found


    `external.service.unavailable` -> external service not available


    `operation.failed` -> The operation is not successful


    `operation.forbidden` -> if the card type is UNKNOWN, the service is blocked
    for some types of cards, there is a problem with commission deduction


    `operation.is.inProcess` -> no response received from processing
tags:
  - name: Methods
    description: >
      QR CRM methods that are used to create an order, check the status of the
      order and transfer links to the fiscal receipt and cancel payment
      transactions.
paths:
  /api/dynamic-qr/merchant/payment/create:
    post:
      summary: Create Order
      description: |
        Method for creating an order.

        Endpoint: `/api/dynamic-qr/merchant/payment/create`
      tags:
        - Methods
      operationId: create_order
      requestBody:
        $ref: '#/components/requestBodies/CreateOrderRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreateOrderResponse'
        '401':
          $ref: '#/components/responses/AuthErrorResponse'
  /api/dynamic-qr/merchant/payment/status-by-order:
    post:
      summary: Check Order
      description: |
        Method for checking the status of the order.

        Endpoint: `/api/dynamic-qr/merchant/payment/status-by-order`
      tags:
        - Methods
      operationId: check_order
      requestBody:
        $ref: '#/components/requestBodies/CheckOrderRequest'
      responses:
        '200':
          $ref: '#/components/responses/CheckOrderResponse'
        '401':
          $ref: '#/components/responses/AuthErrorResponse'
  /api/dynamic-qr/merchant/payment/fiscal:
    post:
      summary: Fiscal
      description: |
        The method is used to transmit a link to a fiscalized check.

        Endpoint: `/api/dynamic-qr/merchant/payment/fiscal`
      tags:
        - Methods
      operationId: fiscal
      requestBody:
        $ref: '#/components/requestBodies/FiscalRequest'
      responses:
        '200':
          $ref: '#/components/responses/FiscalResponse'
        '401':
          $ref: '#/components/responses/AuthErrorResponse'
  /api/dynamic-qr/merchant/payment/reversal:
    post:
      summary: Reverse
      description: |
        The method is used to cancel payment transactions.

        Endpoint: `/api/dynamic-qr/merchant/payment/reversal`
      tags:
        - Methods
      operationId: reversal
      requestBody:
        $ref: '#/components/requestBodies/ReversalRequest'
      responses:
        '200':
          $ref: '#/components/responses/ReversalResponse'
        '401':
          $ref: '#/components/responses/AuthErrorResponse'
  /api/dynamic-qr/merchant/payment/cancel-order:
    post:
      summary: Cancel order
      description: |
        This method is for order cancellation.

        Endpoint: `/api/dynamic-qr/merchant/payment/cancel-order`
      tags:
        - Methods
      operationId: cancel_order
      requestBody:
        $ref: '#/components/requestBodies/CancelRequest'
      responses:
        '200':
          $ref: '#/components/responses/CancelResponse'
        '401':
          $ref: '#/components/responses/AuthErrorResponse'
components:
  requestBodies:
    CreateOrderRequest:
      description: |
        Request fields
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateOrderRequest'
    CheckOrderRequest:
      description: |
        Request fields
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckOrderRequest'
    FiscalRequest:
      description: |
        Request fields
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FiscalRequest'
    ReversalRequest:
      description: |
        Request fields
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReversalRequest'
    CancelRequest:
      description: |
        Атрибуты запроса
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CancelRequest'
  responses:
    CreateOrderResponse:
      description: |
        Response fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateOrderResponse'
    CheckOrderResponse:
      description: |
        Response fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CheckOrderResponse'
    FiscalResponse:
      description: |
        Response fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FiscalResponse'
    ReversalResponse:
      description: |
        Response fields
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReversalResponse'
    CancelResponse:
      description: |
        Атрибуты ответа
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CancelResponse'
    AuthErrorResponse:
      description: |
        If an error occurred during authorization
  schemas:
    CreateOrderRequest:
      type: object
      properties:
        amount:
          description: |
            Payment amount in tiyins.
          type: integer
          format: int64
          example: 100000
        order_id:
          description: >
            Unique sale number (Shopping Cart): The unique order number in the
            partner's system.


            The partner is responsible for ensuring the uniqueness of the
            `order_id`.

            If the `order_id` is not unique, the payment will not be processed.
          type: string
          example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
        service_id:
          description: |
            Partner ID number in Uzum Bank.
          type: integer
          format: int64
          example: 111
        details:
          description: |
            Details of the order.
          type: object
          example:
            fio: Laziz Djurayev
            something: something value
      required:
        - amount
        - order_id
        - service_id
    CreateOrderResponse:
      type: object
      properties:
        payment_link:
          description: |
            The data for generating QR.
          type: string
          example: >-
            https://www.apelsin.uz/open-service?serviceId=498615418&orderId=a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
        error_code:
          description: |
            0 - Success
          type: integer
          format: int32
          example: 0
      required:
        - payment_link
        - error_code
    CheckOrderRequest:
      type: object
      properties:
        order_id:
          description: |
            Unique id of order.
          type: string
          example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
        service_id:
          description: |
            Partner ID number in Uzum Bank.
          type: integer
          format: int64
          example: 111
      required:
        - order_id
        - service_id
    CheckOrderResponse:
      type: object
      properties:
        payment_id:
          description: |
            Transaction identifier in the bank's system.
          type: string
          example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
        payment_status:
          description: >

            <br /> Transaction status:


            `CREATED` - The operation was created.


            `SUCCESS` - The operation is successful.


            `FAILED` - The operation was not performed.


            `HOLD` - The operation was created, but the transaction was not
            received.


            `REVERSE_PENDING` - Waiting for the transaction to be canceled.


            `REVERSED` - Successful transaction cancellation.


            `PARTIAL_CANCELLED` - Partial cancellation completed successfully.


            `CANCELLED` - The Operation was cancelled.
          type: string
          enum:
            - CREATED
            - SUCCESS
            - FAILED
            - HOLD
            - REVERSE_PENDING
            - REVERSED
            - PARTIAL_CANCELLED
            - CANCELLED
          example: SUCCESS
        error_code:
          description: |
            0 - Success
          type: integer
          format: int32
          example: 0
        client_phone_number:
          description: |
            Client phone number
          type: string
          example: '998909090900'
        processingReferenceNumber:
          description: >
            Processing reference number. This field is sent only when paying
            with Uzcard, Humo, Visa Uzum Bank, or Visa Kapital Bank cards.
            Otherwise, the value of this field will be `null`.
          type: string
          format: string
          example: '000'
        cardType:
          description: >
            Client bank card type (1 - corporate bank card, 2 - private bank
            card).
          type: integer
          format: int32
          example: 2
      required:
        - payment_id
        - payment_status
        - error_code
    FiscalRequest:
      type: object
      properties:
        payment_id:
          description: |
            Transaction identifier in the bank's system.
          type: string
          example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
        service_id:
          description: |
            Partner ID number in Uzum Bank.
          type: integer
          format: int64
          example: 111
        fiscal_url:
          description: >
            Link to fiscal receipt.


            May contain special symbols, in this case the Unscape operation is
            necessary
          type: string
          example: http://…
      required:
        - fiscal_url
        - service_id
        - payment_id
    FiscalResponse:
      type: object
      properties:
        payment_id:
          description: |
            Transaction identifier in the bank's system.
          type: string
          example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
        payment_status:
          description: >

            <br /> Transaction status:


            `SUCCESS` - The operation is successful.


            `FAILED` - The operation was not performed.


            `HOLD` - The operation was created, but the transaction was not
            received.


            `REVERSE_PENDING` - Waiting for the transaction to be canceled.


            `REVERSED` - Successful transaction cancellation.


            `PARTIAL_CANCELLED` - Partial cancellation completed successfully.
          type: string
          enum:
            - SUCCESS
            - FAILED
            - HOLD
            - REVERSE_PENDING
            - REVERSED
            - PARTIAL_CANCELLED
          example: SUCCESS
        error_code:
          description: |
            0 - Success
          type: integer
          format: int32
          example: 0
      required:
        - payment_id
        - payment_status
        - error_code
    ReversalRequest:
      type: object
      properties:
        service_id:
          description: |
            Partner ID number in Uzum Bank.
          type: integer
          format: int64
          example: 111
        payment_id:
          description: |
            Payment transaction ID.
          type: string
          example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
      required:
        - service_id
        - payment_id
    ReversalResponse:
      type: object
      properties:
        payment_id:
          description: |
            Transaction identifier in the bank's system.
          type: string
          example: c4f89d18-62b1-4b08-9256-3a8d7d60f28a
        payment_status:
          description: |
            <br/>Transaction status:

            `REVERSE_PENDING` - Waiting for the transaction to be canceled.

            `REVERSED` - Successful transaction cancellation.
          type: string
          enum:
            - REVERSE_PENDING
            - REVERSED
          example: REVERSED
        error_code:
          description: |
            0 - Success
          type: integer
          format: int32
          example: 0
      required:
        - payment_id
        - payment_status
        - error_code
    CancelRequest:
      type: object
      properties:
        order_id:
          description: |
            Unique id of order.
          type: string
          example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
        service_id:
          description: |
            Partner ID number in Uzum Bank.
          type: integer
          format: int64
          example: 111
      required:
        - order_id
        - service_id
    CancelResponse:
      type: object
      properties:
        payment_id:
          description: |
            Order id from the request.
          type: string
          example: a98dcb7e-5b6e-431d-b780-5fd7d93d7e3d
        payment_status:
          description: |
            `CANCELLED` - order is cancelled.
          type: string
          example: CANCELLED
        error_code:
          description: |
            0 - success

            400 - error during cancellation if current status COMPLETED, EXPIRED
          type: integer
          format: int32
          example: 0
        error_message:
          description: >
            `this.order.has.already.be.paid.for` - order was already paid
            (COMPLETED)


            `order.id.is.expired` - order is expired (EXPIRED)
          type: string
          nullable: true
      required:
        - payment_id
        - payment_status
        - error_code