openapi: 3.2.0
info:
  title: Uzum Checkout Auxiliary Methods API
  version: 1.10.3
  description: '**Uzum Checkout** is a payment gateway for websites and mobile applications.'
tags:
- name: Auxiliary Methods
paths:
  /api/v1/acquiring/purchaseReceipt:
    post:
      tags:
      - Auxiliary Methods
      summary: Purchase receipt fiscalization based on a prepaid receipt
      description: ''
      operationId: purchase_receipt_api_v1_acquiring_purchaseReceipt_post
      parameters:
      - name: X-Operation-Id
        in: header
        required: true
        schema:
          type: string
          format: uuid
          description: Idempotency key. Must be unique for each operation
          title: X-Operation-Id
      - name: X-Terminal-Id
        in: header
        required: true
        schema:
          type: string
          format: uuid
          description: Terminal identifier
          title: X-Terminal-Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          type: string
          description: A unique key used to authenticate requests
          title: X-API-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseReceiptRequest'
      callbacks:
        receipt_merchant_callback:
          '{$receipt_callback_url}':
            post:
              summary: Receipt Merchant Callback
              description: '[OPTIONAL] Callbacks for receipt creation'
              operationId: receipt_merchant_callback__receipt_callback_url__post
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ReceiptGeneratedCallbackData'
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_PurchaseReceiptResponse_'
  /api/v1/payment/getOrderStatus:
    post:
      tags:
      - Auxiliary Methods
      summary: Get payment status
      description: Retrieves the current status of a payment
      operationId: get_order_status_api_v1_payment_getOrderStatus_post
      parameters:
      - description: Terminal ID
        required: true
        schema:
          title: X-Terminal-Id
          type: string
          description: Terminal ID
          format: uuid
        name: X-Terminal-Id
        in: header
      - description: A unique key is used to authenticate requests.
        required: false
        schema:
          title: X-API-Key
          type: string
          description: A unique key is used to authenticate requests.
          format: uuid
        name: X-API-Key
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetOrderStatusCommand'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_GetOrderStatusResponse_'
  /api/v1/payment/getOperationState:
    post:
      tags:
      - Auxiliary Methods
      summary: Get operation status
      description: Retrieves the current status of an operation
      operationId: get_operation_state_api_v1_payment_getOperationState_post
      parameters:
      - description: Terminal ID
        required: true
        schema:
          title: X-Terminal-Id
          type: string
          description: Terminal ID
          format: uuid
        name: X-Terminal-Id
        in: header
      - description: A unique key is used to authenticate requests.
        required: false
        schema:
          title: X-API-Key
          type: string
          description: A unique key is used to authenticate requests.
          format: uuid
        name: X-API-Key
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetOperationStateCommand'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_GetOperationStateResponse_'
  /api/v1/payment/getReceipts:
    post:
      tags:
      - Auxiliary Methods
      summary: Getting information about receipts
      operationId: get_merchant_receipts_api_v1_payment_getReceipts_post
      parameters:
      - description: Terminal ID
        required: true
        schema:
          title: X-Terminal-Id
          type: string
          description: Terminal ID
          format: uuid
        name: X-Terminal-Id
        in: header
      - description: A unique key is used to authenticate requests.
        required: false
        schema:
          title: X-API-Key
          type: string
          description: A unique key is used to authenticate requests.
          format: uuid
        name: X-API-Key
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetReceiptRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_GetReceiptsResponse_'
components:
  schemas:
    ApiResponse_PurchaseReceiptResponse_:
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        result:
          $ref: '#/components/schemas/PurchaseReceiptResponse'
      type: object
      required:
      - errorCode
      title: ApiResponse[PurchaseReceiptResponse]
    UZReceiptParams:
      title: UZReceiptParams
      required:
      - spic
      - packageCode
      - vatPercent
      type: object
      properties:
        spic:
          title: Spic
          maxLength: 17
          minLength: 17
          type: string
          description: IKPU (SPIC) product code
        packageCode:
          title: Packagecode
          maxLength: 20
          minLength: 1
          type: string
          description: Packaging code
        vatPercent:
          title: Vatpercent
          minimum: 0
          type: integer
          description: VAT rate
        TIN:
          title: Tin
          maxLength: 9
          minLength: 1
          type: string
          description: Committee TIN. Must be filled in if the PINFL is not filled in. Can't be filled in together
        PINFL:
          title: Pinfl
          maxLength: 14
          minLength: 1
          type: string
          description: Committee PINFL. Must be filled in if the TIN is not filled in. Can't be filled in together
        discount:
          title: Discount
          exclusiveMinimum: 0
          type: integer
          description: Discount amount
        voucher:
          title: Voucher
          exclusiveMinimum: 0
          type: integer
          description: Discount marketplace (in tiyins)
        labels:
          title: Labels
          type: array
          items:
            type: string
          description: Array of product labels. Quantity of labels must correspond to the quantity of labelled items in the cart
      description: Data for autofiscalization
    GetReceiptRequest:
      title: GetReceiptRequest
      required:
      - orderId
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID
          format: uuid
    GetReceiptsResponse:
      title: GetReceiptsResponse
      required:
      - receipts
      type: object
      properties:
        receipts:
          title: Receipts
          type: array
          items:
            $ref: '#/components/schemas/GetReceiptResponse'
          description: Issued receipts
    PurchaseReceiptResponse:
      properties:
        operationId:
          type: string
          format: uuid
          title: Operationid
          description: Operation ID on the Uzum Checkout side
      type: object
      required:
      - operationId
      title: PurchaseReceiptResponse
    Operation:
      title: Operation
      required:
      - operationId
      - startAt
      - operationType
      - state
      type: object
      properties:
        operationId:
          title: Operationid
          type: string
          description: Operation ID on the checkout side
          format: uuid
        merchantOperationId:
          title: Merchantoperationid
          type: string
          description: Operation ID on the merchant side
          format: uuid
        startAt:
          title: Startat
          type: string
          description: Operation start time
          format: date-time
        doneAt:
          title: Doneat
          type: string
          description: Operation end time
          format: date-time
        operationType:
          allOf:
          - $ref: '#/components/schemas/PaymentOperationType'
          description: Operation type
        state:
          allOf:
          - $ref: '#/components/schemas/PaymentOperationState'
          description: Operation Status
        rrn:
          title: Rrn
          type: string
          description: RRN of the operation
        actionCodeDescription:
          title: Actioncodedescription
          type: string
          description: Reason why payment was declined
    ErrorCode:
      title: ErrorCode
      type: integer
    PurchaseReceiptRequest:
      properties:
        orderId:
          type: string
          format: uuid
          title: Orderid
          description: Order identifier
        cart:
          allOf:
          - $ref: '#/components/schemas/PurchaseReceiptCartRequest'
          description: Cart data for purchase receipt fiscalization
      type: object
      required:
      - orderId
      - cart
      title: PurchaseReceiptRequest
    GetReceiptResponse:
      title: GetReceiptResponse
      required:
      - receiptUrl
      - receiptType
      type: object
      properties:
        receiptUrl:
          title: Receipturl
          type: string
          description: Link to the receipt
        receiptType:
          allOf:
          - $ref: '#/components/schemas/ReceiptType'
          description: Type of the receipt (purchase/refund)
    PaymentOperationState:
      title: PaymentOperationState
      enum:
      - IN_PROGRESS
      - SUCCESS
      - FAIL
      type: string
      description: An enumeration.
    AcquiringStatus:
      title: AcquiringStatus
      enum:
      - REGISTERED
      - AUTHORIZED
      - TOP_UP_COMPLETED
      - COMPLETED
      - REFUNDED
      - REVERSED
      - DECLINED
      type: string
      description: An enumeration.
    PurchaseReceiptCartRequest:
      properties:
        total:
          type: integer
          exclusiveMinimum: 0
          title: Total
          description: Total cart amount
        items:
          items:
            $ref: '#/components/schemas/FiscalizationCartItemRequest'
          type: array
          minItems: 1
          title: Items
          description: Detailed list of items or services in the customer's cart
      type: object
      required:
      - total
      - items
      title: PurchaseReceiptCartRequest
    PaymentOperationType:
      title: PaymentOperationType
      enum:
      - AUTHORIZE
      - COMPLETE
      - REFUND
      - REVERSE
      - TOP_UP_COMPLETED
      type: string
      description: An enumeration.
    ApiResponse_GetReceiptsResponse_:
      title: ApiResponse[GetReceiptsResponse]
      required:
      - errorCode
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        result:
          $ref: '#/components/schemas/GetReceiptsResponse'
    GetOrderStatusCommand:
      title: GetOrderStatusCommand
      required:
      - orderId
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID
          format: uuid
    GetOrderStatusResponse:
      title: GetOrderStatusResponse
      required:
      - orderId
      - status
      - merchantOrderId
      - amount
      - totalAmount
      - completedAmount
      - refundedAmount
      - reversedAmount
      - operations
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID
          format: uuid
        status:
          allOf:
          - $ref: '#/components/schemas/AcquiringStatus'
          description: Payment status
        cardType:
          title: Card Type
          description: "Type of card used for the transaction:\n* `1` – Corporate card  \n* `2` – Personal card\n"
          type: integer
          enum:
          - 1
          - 2
        actionCode:
          title: Actioncode
          type: integer
          description: Reason why payment was declined
        merchantOrderId:
          title: Merchantorderid
          type: string
          description: Order ID on the merchant's side
        amount:
          title: Amount
          type: integer
          description: Amount transferred when registering a payment
        totalAmount:
          title: Totalamount
          type: integer
          description: Total payment amount
        completedAmount:
          title: Completedamount
          type: integer
          description: Complete amount
        refundedAmount:
          title: Refundedamount
          type: integer
          description: Refund amount
        reversedAmount:
          title: Reversedamount
          type: integer
          description: Reverse amount
        bindingId:
          title: Binding Id
          maxLength: 255
          type: string
          description: Binding ID
        operations:
          title: Operations
          type: array
          items:
            $ref: '#/components/schemas/Operation'
          description: Operations history
    GetOperationStateCommand:
      title: GetOperationStateCommand
      required:
      - operationId
      type: object
      properties:
        operationId:
          title: Operationid
          type: string
          description: Operation ID on the checkout side
          format: uuid
    FiscalizationCartItemRequest:
      title: FiscalizationCartItemRequest
      required:
      - productId
      - quantity
      - receiptParams
      type: object
      properties:
        productId:
          title: Productid
          minLength: 1
          type: string
          description: Item ID on the merchant's side
        quantity:
          title: Quantity
          exclusiveMinimum: 0
          type: integer
          description: Quantity of the item
        receiptParams:
          title: Receiptparams
          allOf:
          - $ref: '#/components/schemas/UZReceiptParams'
    ReceiptGeneratedCallbackData:
      title: ReceiptGeneratedCallbackData
      required:
      - orderId
      - receiptType
      - receiptUrl
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID on Checkout side
        receiptType:
          allOf:
          - $ref: '#/components/schemas/ReceiptType'
          description: Receipt type
        receiptUrl:
          title: Receipturl
          type: string
          description: Link to the receipt
    ApiResponse_GetOrderStatusResponse_:
      title: ApiResponse[GetOrderStatusResponse]
      required:
      - errorCode
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        result:
          $ref: '#/components/schemas/GetOrderStatusResponse'
    ApiResponse_GetOperationStateResponse_:
      title: ApiResponse[GetOperationStateResponse]
      required:
      - errorCode
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        result:
          $ref: '#/components/schemas/GetOperationStateResponse'
    ReceiptType:
      title: ReceiptType
      enum:
      - PURCHASE
      - PREPAID
      - REFUND
      type: string
      description: An enumeration.
    GetOperationStateResponse:
      title: GetOperationStateResponse
      required:
      - operation
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
x-tagGroups:
- name: API
  tags:
  - One-Step Payment
  - Managing Credit Cards Bindings
  - Back-to-back Payment
  - Auxiliary Methods
- name: Additional Info
  tags:
  - Testing
  - Error Codes
  - Post Messages