openapi: 3.0.1
info:
  title: OMNO API Documentation
  contact:
    email: support@omno.com
  version: 2.0.0
servers:
  - url: https://api.omno.com
    description: Production
  - url: https://api.stagingsseu.com
    description: Sandbox
tags:
  - name: Payout
    description: Payout API
  - name: Cashier
    description: Cashier API
  - name: PayIn
    description: PayIn API
paths:
  /public/payout/{payoutId}/reject:
    put:
      tags:
        - Payout
      summary: Reject payout transaction
      description: >-
        Confirm payout transaction for the given ID and after this transaction
        will not be sent to PSP for processing.
      operationId: rejectPayout
      parameters:
        - name: payoutId
          in: path
          description: Payout ID. Returned by `createPayout` method
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Payout transaction rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unit'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/payout/{payoutId}/confirm:
    put:
      tags:
        - Payout
      summary: Confirm payout transaction
      description: >-
        Confirm payout transaction for the given ID and after this confirmation
        transaction will start processing.
      operationId: confirmPayout
      parameters:
        - name: payoutId
          in: path
          description: Payout ID. Returned by `createPayout` method
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Payout transaction confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unit'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/cashier/session/{sessionId}/balance:
    put:
      tags:
        - Cashier
      summary: Update cashier session balance
      description: Updates cashier session balance for customer.
      operationId: updateCashierSessionBalance
      parameters:
        - name: sessionId
          in: path
          description: Cashier Session ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Cashier session balance updated
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/payout:
    post:
      tags:
        - Payout
      summary: Create payout
      description: Creates payout transaction for the given request
      operationId: createPayout
      requestBody:
        description: Create Payout Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
        required: true
      responses:
        '200':
          description: Payout transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/payin:
    post:
      tags:
        - PayIn
      summary: Create payin
      description: Creates pay-in transaction for the given request
      operationId: createPayIn
      requestBody:
        description: Create PayIn Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayInRequest'
        required: true
      responses:
        '200':
          description: PayIn transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/cashier/session:
    post:
      tags:
        - Cashier
      summary: Create cashier session
      description: Creates cashier session for customer.
      operationId: createCashierSession
      requestBody:
        description: Create Cashier Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCashierSessionRequest'
        required: true
      responses:
        '200':
          description: Cashier session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCashierSessionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/payout/{payoutId}:
    get:
      tags:
        - Payout
      summary: Fetch payout transaction
      description: Fetch payout transaction for the given ID
      operationId: fetchPayoutTransaction
      parameters:
        - name: payoutId
          in: path
          description: Payout ID. Returned by `createPayout` method
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payout transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutDetailedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /public/payin/{payinId}:
    get:
      tags:
        - PayIn
      summary: Fetch payin transaction
      description: Get pay-in Transaction Details for the given ID
      operationId: fetchPayInTransaction
      parameters:
        - name: payinId
          in: path
          description: Payment Transaction ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payment Transaction Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayInTransaction'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorKey:
          type: string
          example: INVALID_CURRENCY
        errorMessage:
          type: string
          example: Currency not supported by provider
        errorCode:
          type: integer
          format: int32
          example: 402
    Unit:
      type: object
    CreatePayoutRequest:
      required:
        - currency
        - customer
        - kycVerified
        - orderId
        - value
      type: object
      properties:
        orderId:
          type: string
          description: Unique identifier for checkout session
          example: example_orderid
        value:
          type: number
          description: Payout transaction amount
          example: 0
        currency:
          type: string
          description: >-
            Payout transaction currency. If processor psp doesn't allow this
            currency but if this currency is enabled it will be automatically
            converted to PSP currency and final transaction currency will be set
            respectively.
          example: example_currency
        kycVerified:
          type: boolean
          description: >-
            Whether or not this customer is KYC verified in your system. This
            flag is required to determine right PSP to process this payout.
          example: true
        customer:
          $ref: '#/components/schemas/CustomerRequest'
    CustomerBilling:
      required:
        - address
        - city
        - countryCode
        - postalCode
        - state
      type: object
      properties:
        address:
          type: string
          description: Customer billing address
          example: example_address
        city:
          type: string
          description: Customer billing city
          example: example_city
        state:
          type: string
          description: Customer billing state
          example: example_state
        countryCode:
          type: string
          description: >-
            Customer billing country code (ISO 3166-1 alpha-2). Ex: GE for
            Georgia
          example: example_countrycode
        postalCode:
          type: string
          description: Customer billing postal code
          example: example_postalcode
      description: Customer billing information
    CustomerRequest:
      required:
        - billing
        - dateOfBirth
        - email
        - externalUserId
        - firstName
        - lastName
        - phoneNumber
      type: object
      properties:
        externalUserId:
          type: string
          description: Your defined unique identifier for this customer.
          example: example_externaluserid
        firstName:
          type: string
          description: Customer first name
          example: example_firstname
        lastName:
          type: string
          description: Customer last name
          example: example_lastname
        email:
          type: string
          description: Customer email
          example: example_email
        phoneNumber:
          type: string
          description: Customer phone number
          example: example_phonenumber
        dateOfBirth:
          type: string
          description: Customer date of birth
          format: date
          example: example_dateofbirth
        billing:
          $ref: '#/components/schemas/CustomerBilling'
      description: Customer information
    IframeUrls:
      required:
        - apm
        - card
      type: object
      properties:
        card:
          type: string
          description: Card IFrame URL
          example: example_card
        apm:
          type: string
          description: Alternate Payment Method IFrame URL
          example: example_apm
      description: Payout Iframe URLs
    PayoutResponse:
      required:
        - iframeUrls
        - payoutId
        - status
      type: object
      properties:
        payoutId:
          type: string
          description: Payout ID
          example: example_payoutid
        status:
          type: string
          description: Payout status
          enum:
            - CREATED
            - WAITING_FOR_CONFIRMATION
            - PENDING
            - PROCESSED
            - REJECTED
            - FAILED
          example: PROCESSED
        iframeUrls:
          $ref: '#/components/schemas/IframeUrls'
    CreatePayInRequest:
      required:
        - amount
        - currency
        - customer
        - kycVerified
        - orderId
        - previousTransactionCount
        - returnUrls
      type: object
      properties:
        orderId:
          type: string
          description: Unique identifier for payin session
          example: example_orderid
        amount:
          type: number
          description: PayIn transaction amount
          example: 0
        currency:
          type: string
          description: >-
            PayIn transaction currency. If processor psp doesn't allow this
            currency but if this currency is enabled it will be automatically
            converted to PSP currency and final transaction currency will be set
            respectively.
          example: example_currency
        kycVerified:
          type: boolean
          description: >-
            Whether or not this customer is KYC verified in your system. This
            flag is required to determine right PSP to process this payin.
          example: true
        customer:
          $ref: '#/components/schemas/CustomerRequest'
        previousTransactionCount:
          type: integer
          description: Number of previous transactions in different payment system.
          format: int32
          example: 0
        returnUrls:
          $ref: '#/components/schemas/ReturnUrls'
    ReturnUrls:
      required:
        - failure
        - success
      type: object
      properties:
        success:
          type: string
          description: Url where user will be redirected after successful transaction.
          example: example_success
        failure:
          type: string
          description: Url where user will be redirected after failed transaction.
          example: example_failure
    CreateCashierSessionRequest:
      required:
        - currency
        - customer
        - kycVerified
        - previousTransactionCount
        - returnUrls
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/CustomerRequest'
        returnUrls:
          $ref: '#/components/schemas/ReturnUrls'
        currency:
          type: string
          description: >-
            Currency for the cashier session, in which all payin/payout
            transaction will be created
          example: example_currency
        kycVerified:
          type: boolean
          description: Whether or not this customer is KYC verified in your system.
          example: true
        previousTransactionCount:
          type: integer
          description: Number of previous transactions in different payment system.
          format: int32
          example: 0
        balance:
          type: number
          description: >-
            Current balance of the customer. Balance will be shown on withdrawal
            widget.
          example: 0
    CreateCashierSessionResponse:
      required:
        - checkoutUrl
        - sessionId
      type: object
      properties:
        sessionId:
          type: string
          description: Session ID
          example: example_sessionid
        checkoutUrl:
          type: string
          description: Checkout URL
          example: example_checkouturl
    CardDetails:
      required:
        - cardBrand
        - cardMask
        - cardholderName
        - expirationDate
      type: object
      properties:
        cardMask:
          type: string
          description: Card Mask
          example: example_cardmask
        cardholderName:
          type: string
          description: Cardholder Name
          example: example_cardholdername
        expirationDate:
          type: string
          description: Card Expiration Date. MM/YY
          example: example_expirationdate
        cardBrand:
          type: string
          description: Card Brand
          example: example_cardbrand
      description: Card details
    PayoutDetailedResponse:
      required:
        - currency
        - orderId
        - payoutId
        - status
        - value
      type: object
      properties:
        payoutId:
          type: string
          description: Payout ID
          example: example_payoutid
        orderId:
          type: string
          description: Unique identifier for checkout session
          example: example_orderid
        value:
          type: number
          description: Payout transaction amount
          example: 0
        currency:
          type: string
          description: Payout transaction currency.
          example: example_currency
        status:
          type: string
          description: Payout status
          enum:
            - CREATED
            - WAITING_FOR_CONFIRMATION
            - PENDING
            - PROCESSED
            - REJECTED
            - FAILED
          example: PROCESSED
        cardDetails:
          $ref: '#/components/schemas/CardDetails'
        payoutMethod:
          type: string
          description: Payout Method
          enum:
            - CARD
            - BANK
            - APM
          example: CARD
    PayInStatusWithReason:
      type: object
      properties:
        reason:
          type: string
          example: example_reason
        detailedStatus:
          type: string
          enum:
            - GENERAL_DECLINE
            - BANK_ISSUES
            - PSP_ISSUES
            - CUSTOMER_ISSUES
            - INSUFFICIENT_FUNDS
            - CVV_INVALID
            - CARD_EXPIRED
            - CARD_BLOCKED
            - CARD_NOT_SUPPORTED
            - NO_PROVIDER_AVAILABLE
            - FRAUD_SCORE_ABOVE_THRESHOLD
            - OTHER
          example: INSUFFICIENT_FUNDS
        status:
          type: string
          enum:
            - CREATED
            - PENDING
            - PENDING_3DS
            - SUCCESS
            - REFUNDED
            - PARTIALLY_REFUNDED
            - DECLINED
            - FAILED
            - TIMEOUT
          example: SUCCESS
    PayInTransaction:
      required:
        - amount
        - createdAt
        - currency
        - customerId
        - id
        - initialAmount
        - initialCurrency
        - merchantId
        - orderId
        - returnUrls
        - status
        - updatedAt
      type: object
      properties:
        id:
          type: string
          example: example_id
        amount:
          type: number
          example: 0
        merchantId:
          type: string
          example: example_merchantid
        customerId:
          type: string
          example: example_customerid
        orderId:
          type: string
          example: example_orderid
        currency:
          type: string
          example: example_currency
        status:
          type: string
          enum:
            - CREATED
            - PENDING
            - PENDING_3DS
            - SUCCESS
            - REFUNDED
            - PARTIALLY_REFUNDED
            - DECLINED
            - FAILED
            - TIMEOUT
          example: SUCCESS
        initialAmount:
          type: number
          example: 0
        initialCurrency:
          type: string
          example: example_initialcurrency
        routerId:
          type: string
          example: example_routerid
        returnUrls:
          $ref: '#/components/schemas/ReturnUrls'
        cardId:
          type: string
          example: example_cardid
        cardMask:
          type: string
          example: example_cardmask
        cardBrand:
          type: string
          example: example_cardbrand
        cardHash:
          type: string
          example: example_cardhash
        merchantPspId:
          type: string
          example: example_merchantpspid
        pspTransactionId:
          type: string
          example: example_psptransactionid
        statusReason:
          $ref: '#/components/schemas/PayInStatusWithReason'
        previousTransactionCount:
          type: integer
          format: int32
          example: 0
        metadata:
          $ref: '#/components/schemas/TransactionMetadata'
        transactionType:
          type: string
          enum:
            - CARD
            - BANK
            - WALLET
            - CASH
            - CRYPTO
            - OTHER
          example: CARD
        createdAt:
          type: string
          format: date-time
          example: example_createdat
        updatedAt:
          type: string
          format: date-time
          example: example_updatedat
    TransactionMetadata:
      type: object
      properties:
        ipAddress:
          type: string
          example: example_ipaddress
  securitySchemes:
    ApiKeyAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://sso.omno.com/realms/omno/protocol/openid-connect/token
          scopes:
            name: merchant
x-tagGroups:
  - name: Payments
    tags:
      - Cashier
      - PayIn
      - Payout
security:
  - ApiKeyAuth: []
