openapi: 3.2.0
info:
  title: Uzum Checkout Two-Step Payment API
  version: 1.10.3
  description: '**Uzum Checkout** is a payment gateway for websites and mobile applications.'
tags:
- name: Two Step Payment
paths:
  /api/v1/acquiring/complete:
    post:
      tags:
      - Two Step Payment
      summary: Confirmation of two-step payment
      operationId: complete_api_v1_acquiring_complete_post
      parameters:
      - description: Idempotency key. Unique for each operation.
        required: true
        schema:
          title: X-Operation-Id
          type: string
          description: Idempotency key. Unique for each operation.
          format: uuid
        name: X-Operation-Id
        in: header
      - 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/Complete2SPCommand'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_Complete2SPResponse_'
      callbacks:
        acquiring_merchant_callback:
          '{$callback_url}':
            post:
              summary: Acquiring Merchant Callback
              description: "[REQUIRED] Callbacks about performing financial transactions,\n configured on the terminal side"
              operationId: acquiring_merchant_callback__callback_url__post
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/AcquiringCallbackData'
                required: true
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
        event_merchant_callback:
          '{$event_callback_url}':
            post:
              summary: Event Merchant Callback
              description: '[OPTIONAL] Business event callbacks are configured on the terminal side'
              operationId: event_merchant_callback__event_callback_url__post
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/BusinessEvent'
                required: true
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
        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:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ReceiptGeneratedCallbackData'
                required: true
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
  /api/v1/acquiring/reverse:
    post:
      tags:
      - Two Step Payment
      summary: Reverse
      description: 'The method is used to cancel payment for an order. This is a method for unholding funds in an account.

        Cancellation can be performed when the payment is in the "AUTHORIZED" status.'
      operationId: reverse_api_v1_acquiring_reverse_post
      parameters:
      - description: Idempotency key. Unique for each operation.
        required: true
        schema:
          title: X-Operation-Id
          type: string
          description: Idempotency key. Unique for each operation.
          format: uuid
        name: X-Operation-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
      - description: Terminal ID
        required: true
        schema:
          title: X-Terminal-Id
          type: string
          description: Terminal ID
          format: uuid
        name: X-Terminal-Id
        in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseCommand'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ReverseResponse_'
      callbacks:
        acquiring_merchant_callback:
          '{$callback_url}':
            post:
              summary: Acquiring Merchant Callback
              description: "[REQUIRED] Callbacks about performing financial transactions,\n configured on the terminal side"
              operationId: acquiring_merchant_callback__callback_url__post
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/AcquiringCallbackData'
                required: true
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
        event_merchant_callback:
          '{$event_callback_url}':
            post:
              summary: Event Merchant Callback
              description: '[OPTIONAL] Business event callbacks are configured on the terminal side'
              operationId: event_merchant_callback__event_callback_url__post
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/BusinessEvent'
                required: true
              responses:
                '200':
                  description: Successful Response
                  content:
                    application/json:
                      schema: {}
components:
  schemas:
    CallbackOperationState:
      title: CallbackOperationState
      enum:
      - SUCCESS
      - FAIL
      type: string
      description: An enumeration.
    ApiResponse_ReverseResponse_:
      title: ApiResponse[ReverseResponse]
      required:
      - errorCode
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        result:
          $ref: '#/components/schemas/ReverseResponse'
    Complete2SPResponse:
      title: Complete2SPResponse
      required:
      - operationId
      type: object
      properties:
        operationId:
          title: Operationid
          type: string
          description: Operation ID on the Uzum Checkout side
          format: uuid
    ReverseCommand:
      title: ReverseCommand
      required:
      - orderId
      - amount
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Payment identifier
          format: uuid
        amount:
          title: Amount
          minimum: 1
          type: integer
          description: Amount to reverse in tiyins
    ApiResponse_Complete2SPResponse_:
      title: ApiResponse[Complete2SPResponse]
      required:
      - errorCode
      type: object
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          title: Message
          type: string
        result:
          $ref: '#/components/schemas/Complete2SPResponse'
    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
    ReceiptType:
      title: ReceiptType
      enum:
      - PURCHASE
      - PREPAID
      - REFUND
      type: string
      description: An enumeration.
    PaymentOperationType:
      title: PaymentOperationType
      enum:
      - AUTHORIZE
      - COMPLETE
      - REFUND
      - REVERSE
      - TOP_UP_COMPLETED
      type: string
      description: An enumeration.
    ReverseResponse:
      title: ReverseResponse
      required:
      - operationId
      type: object
      properties:
        operationId:
          title: Operationid
          type: string
          description: Operation ID on the checkout side
          format: uuid
    Complete2SPCommand:
      title: Complete2SPCommand
      required:
      - orderId
      - amount
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID
          format: uuid
        amount:
          title: Amount
          minimum: 1
          type: integer
          description: Amount for Complete in tiyins
    BusinessEventType:
      title: BusinessEventType
      enum:
      - FORM_CLOSED
      type: string
      description: An enumeration.
    AcquiringCallbackData:
      title: AcquiringCallbackData
      required:
      - orderId
      - operationState
      - operationType
      - orderNumber
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID on the Checkout side
        operationState:
          allOf:
          - $ref: '#/components/schemas/CallbackOperationState'
          description: Operation status
        operationType:
          allOf:
          - $ref: '#/components/schemas/PaymentOperationType'
          description: Operation type
        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
        merchantOperationId:
          title: Merchantoperationid
          type: string
          description: "Operation ID on the merchant's side, will be returned if it was\n passed when initializing the operation"
        orderNumber:
          title: Ordernumber
          type: string
          description: Order ID on the merchant's side
        rrn:
          title: Rrn
          type: string
          description: Unique identifier of the banking transaction
    ErrorCode:
      title: ErrorCode
      type: integer
    BusinessEvent:
      title: BusinessEvent
      required:
      - orderId
      - orderNumber
      - eventType
      - actionCode
      - actionCodeDescription
      type: object
      properties:
        orderId:
          title: Orderid
          type: string
          description: Order ID on the Checkout side
        orderNumber:
          title: Ordernumber
          type: string
          description: Order ID on the merchant's side
        eventType:
          allOf:
          - $ref: '#/components/schemas/BusinessEventType'
          description: Business event type
        actionCode:
          allOf:
          - $ref: '#/components/schemas/ErrorCode'
          description: Event code
        actionCodeDescription:
          title: Actioncodedescription
          type: string
          description: Event code description
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