openapi: 3.0.0
info:
  title: YinWallet API
  description: >
    API for processing orders through the payment gateway.


    ## Before you start

    Before using the API endpoints, please ensure you have reviewed the [Getting
    Started page](/docs/getting-started).


    ## OpenAPI File Export

    You can download the OpenAPI file of our API: [download
    yinwallet-api.yaml](/wallet-api.yaml)
  version: "1.0"
servers:
  - url: https://cold.yinwallet.com/api/gateway
    description: Base URL for production API endpoints.
  - url: https://wallet--crypto-demo.d.apicworld.com/api/gateway
    description: Base URL for test API endpoints.
paths:
  /api/v1/integrations:
    get:
      tags:
        - Common
      summary: Get integrations
      description: >
        Get a paginated list of all available integrations.


        To configure available integrations, refer to the [manage integrations
        guide](/docs/manage-integrations#disabling-an-integration).
      operationId: get_app_integration_integrations_integrations_getall
      parameters:
        - name: page
          in: query
          description: The page number to retrieve.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: quantity
          in: query
          description: The number of items to retrieve per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
            minimum: 1
      responses:
        "200":
          description: A list of integrations.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    description: The list of integrations.
                    items:
                      $ref: "#/components/schemas/IntegrationItem"
                  pagination:
                    $ref: "#/components/schemas/PaginationResponse"
  /api/v1/assets:
    get:
      summary: Get crypto assets
      description: >
        Returns a list of supported crypto assets, including their blockchain
        details, display names, and token standards. This endpoint helps you
        understand which assets are supported.
      tags:
        - Common
      operationId: get_app_integration_assets_assets_get
      responses:
        "200":
          description: Available assets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetList"
  /api/v1/exchange-rates:
    get:
      summary: Get exchange rates
      description: >
        Returns a list of crypto assets along with their conversion rates based
        on the provided fiat amount and currency. Use this endpoint to see how
        much crypto you would receive for a given amount of USD or EUR.

        The fiat amount to be converted into all supported crypto assets [Get crypto assets](/docs/wallet-api/get-app-integration-assets-assets-get).
      tags:
        - Common
      operationId: get_app_integration_exchangerates_exchangerates_get
      parameters:
        - name: amount
          in: query
          required: true
          description: >
            The fiat amount to be converted into all supported crypto assets [Get crypto assets](/docs/wallet-api/get-app-integration-assets-assets-get). Use a decimal point as a separator.
          schema:
            type: string
            minimum: 0
            exclusiveMinimum: true
            example: "10.00"
        - name: currency
          in: query
          required: true
          description: >
            The fiat currency of the provided amount.
          schema:
            type: string
            enum:
              - USD
              - EUR
            example: USD
      responses:
        "200":
          description: Exchange rates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetRateList"
  /api/v1/order/payment:
    post:
      tags:
        - Incoming Orders
      summary: Create payment
      description: >
        Create a new payment order. The payment order specifies the amount and
        currency you want to receive from the payer. On the payment page, the
        payer can choose to pay in a different currency, and the amount will be
        converted, so you will receive the amount you specified here.


        The payer can pay the order in multiple transactions. The order status
        will be updated to `completed` once 19 transaction confirmations are
        received from the network.

        If the full amount is not paid within the order's lifetime, the order
        status will be marked as `failed`.


        The order is valid for 20 minutes. During this time, the payer must
        complete the payment.


        **Minimum Limits**:


        Every transaction must meet the minimum amount requirements based on
        the asset and network. If the specified amount is below the minimum,
        the request will be rejected. For detailed information see the
        **[Transaction Limits](/docs/transaction_limits)**.


        **Difference between Create a payment order and Create a deposit
        order:**


        - **[Create a payment
        order](/docs/wallet-api/post-app-integration-order-order-createpayment)**
        is used to charge a customer for a specific service or product. The
        order defines the amount to receive, and the payer can complete the
        payment in multiple transactions. Use this when you want to collect a
        specific payment from a customer.


        - **[Create a deposit
        order](/docs/wallet-api/post-app-integration-order-order-createdeposit)**
        allows clients to deposit funds into their balance for a specific
        integration. The client chooses the amount to deposit, and the order is
        completed after the first transaction. Use this for topping up an
        account or balance, not for one-time payments.
      operationId: post_app_integration_order_order_createpayment
      requestBody:
        description: Details of the payment order to create.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePaymentOrderRequest"
      responses:
        "201":
          description: Payment order created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateIncomingPaymentResponse"
        "400":
          description: Failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      enum:
                        - unknownError
                        - invalidAddress
                        - notEnoughFunds
                        - limitExceeded
                        - wrongData
                  type: object
  /api/v1/order/deposit:
    post:
      tags:
        - Incoming Orders
      summary: Create deposit
      description: >
        Create a new deposit order for a specific integration. This endpoint
        allows the client to decide how much money they want to deposit into
        their balance.


        Once the first transaction from the client is detected, the payment is
        considered complete, and the status is updated to `completed` after 19
        transaction confirmations from the network.


        The order is valid for 20 minutes. During this time, the payer must
        complete the payment.


        **Minimum Limits**:


        Every transaction must meet the minimum amount requirements based on
        the asset and network. If the specified amount is below the minimum,
        the request will be rejected. For detailed information see the
        **[Transaction Limits](/docs/transaction_limits)**.



        **Difference between Create a payment order and Create a deposit
        order:**


        - **[Create a payment
        order](/docs/wallet-api/post-app-integration-order-order-createpayment)**
        is used to charge a customer for a specific service or product. The
        order defines the amount to receive, and the payer can complete the
        payment in multiple transactions. Use this when you want to collect a
        specific payment from a customer.


        - **[Create a deposit
        order](/docs/wallet-api/post-app-integration-order-order-createdeposit)**
        allows clients to deposit funds into their balance for a specific
        integration. The client chooses the amount to deposit, and the order is
        completed after the first transaction. Use this for topping up an
        account or balance, not for one-time payments.
      operationId: post_app_integration_order_order_createdeposit
      requestBody:
        description: Details of the deposit order to create.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDepositOrderRequest"
      responses:
        "201":
          description: Deposit order created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateIncomingDepositResponse"
        "400":
          description: Failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      enum:
                        - unknownError
                        - invalidAddress
                        - notEnoughFunds
                        - limitExceeded
                        - wrongData
                  type: object
  /api/v1/order/refund:
    post:
      tags:
        - Outgoing Orders
      summary: Create refund
      description: >
        Create a refund for an incoming, completed payment or deposit order.
        This endpoint allows you to return part or all of the funds received
        from a payment or deposit order to the payer. Refunds can only be
        processed if there are sufficient funds in the wallet balance, including
        fees.

        Refunds cannot exceed the total amount received for the order. For
        example, if the original order was 10, and a refund of 5 has already
        been issued, the maximum you can refund in a second transaction is 5.

        **Important:** Refunds are processed from the withdrawal  
        wallet specified for the integration. The necessary funds will be
        deducted from that withdrawal wallet.
      operationId: post_app_integration_order_order_createrefund
      requestBody:
        description: Details of the refund order to create.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRefundOrderRequest"
      responses:
        "201":
          description: Refund order created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateOutgoingOrderResponse"
        "400":
          description: Failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      enum:
                        - unknownError
                        - invalidAddress
                        - notEnoughFunds
                        - limitExceeded
                        - wrongData
                  type: object
  /api/v1/order/withdrawal:
    post:
      tags:
        - Outgoing Orders
      summary: Create withdrawal
      description: >
        Create a withdrawal order to transfer funds from your balance to an
        external wallet. Specify the amount, asset type, and the destination
        wallet address. The integration ID must also be provided to link the
        withdrawal to a specific integration.


        Withdrawal can only be processed if there are sufficient funds in the
        withdrawal wallet balance, including fees.

        **Important:** Refunds are processed from the withdrawal  
        wallet specified for the integration. The necessary funds will be
        deducted from that withdrawal wallet.
      operationId: post_app_integration_order_order_createwithdrawal
      requestBody:
        description: Details of the withdrawal order to create.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWithdrawalOrderRequest"
      responses:
        "201":
          description: Withdrawal order created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateOutgoingOrderResponse"
        "400":
          description: Failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      enum:
                        - unknownError
                        - invalidAddress
                        - notEnoughFunds
                        - limitExceeded
                        - wrongData
                  type: object
  /api/v1/order/send:
    post:
      tags:
        - Outgoing Orders
      operationId: post_app_integration_order_order_createsend
      summary: Send crypto
      description: >
        This endpoint allows you to send an amount of a specified crypto asset from one
        blockchain address to another address.

      requestBody:
        description: Details for creating a send order.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSendOrderRequest"
      responses:
        "201":
          description: Created send order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSendOrderResponse"
        "400":
          description: Failed.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      enum:
                        - unknownError
                        - invalidAddress
                        - notEnoughFunds
                        - limitExceeded
                        - wrongData
                  type: object
  /api/v1/orders:
    get:
      tags:
        - Orders Info
      summary: Get orders
      description: Get a paginated list of all orders, optionally filtered by integration.
      operationId: get_app_integration_orders_orders_getall
      parameters:
        - name: page
          in: query
          description: The page number to retrieve.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: quantity
          in: query
          description: The number of items to retrieve per page.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
            minimum: 1
        - name: integrationId
          in: query
          description: The ID of the integration to filter orders by.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        "200":
          description: A list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: The list of orders.
                    items:
                      $ref: "#/components/schemas/OrderListItem"
                  pagination:
                    $ref: "#/components/schemas/PaginationResponse"
  /api/v1/orders/{orderId}:
    get:
      tags:
        - Orders Info
      summary: Get order by ID
      description: Get details of a specific order by its ID.
      operationId: get_app_integration_orders_orders_getorder
      parameters:
        - name: orderId
          in: path
          description: The unique identifier of the order.
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: Order details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleOrderItem"
        "404":
          description: Order not found.
  /api/v1/orders/{orderId}/transactions/{transactionId}:
    get:
      tags:
        - Orders Info
      operationId: get_app_integration_transactions_transactions_get
      summary: Get transaction by ID
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
            pattern: "[0-9]+"
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
      responses:
        "200":
          description: Transaction.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionItem"
        "404":
          description: Transaction not found.
components:
  schemas:
    IntegrationItem:
      type: object
      required:
        - name
        - id
        - url
        - status
      properties:
        name:
          type: string
          description: The name of the integration.
          example: test
        id:
          type: string
          description: The unique identifier of the integration.
          example: 1ef65bda-11ad-63ca-8afe-73770edda314
        url:
          type: string
          description: The URL associated with the integration.
          example: https://example.com
        status:
          type: string
          description: >
            The current status of the integration. 


            - **active**: The integration is active and ready to use.

            - **disabled**: The integration is disabled and cannot be used to
            create orders.


            To change the status of the integration, refer to the instructions
            in the [manage integrations
            guide](/docs/manage-integrations#disabling-an-integration).
          enum:
            - active
            - disabled
        webhook:
          $ref: "#/components/schemas/Webhook"
          nullable: true
    PaginationResponse:
      type: object
      required:
        - quantity
        - totalQuantity
        - currentPage
        - pages
      properties:
        quantity:
          type: integer
          description: The number of items per page.
          example: 1
        totalQuantity:
          type: integer
          description: The total number of items available.
          example: 1
        currentPage:
          type: integer
          description: The current page number.
          example: 1
        pages:
          type: integer
          description: The total number of pages available.
          example: 1
    CreatePaymentOrderRequest:
      type: object
      required:
        - integrationId
        - amount
        - assetId
      properties:
        integrationId:
          type: string
          description: The ID of the integration for which the payment order is created.
            Retrieve it from the [Retrieve a list of integrations](/docs/wallet-api/get-app-integration-integrations-integrations-getall)
            endpoint.
          pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
        amount:
          type: string
          description: The amount to be paid by the client. Use a decimal point as a
            separator, up to 6 decimal places. If more than 6 decimal places are
            provided, the value will be rounded.
          minimum: 0
          exclusiveMinimum: true
        assetId:
          type: string
          description: |
            The asset identifier you want to receive for this payment. Retrieve available asset IDs from the [Get crypto assets](/docs/wallet-api/get-app-integration-assets-assets-get) endpoint.
        externalId:
          type: string
          maxLength: 255
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the transaction with an internal reference in your system.
          example: "123"
    CreateIncomingDepositResponse:
      type: object
      required:
        - orderId
        - operationId
        - paymentLink
        - widgetCode
      properties:
        orderId:
          type: string
          description: The unique identifier of the created order.
          example: 123e4567-e89b-12d3-a456-426614174000
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        paymentLink:
          type: string
          description: The URL to the payment page where the client needs to be redirected
            to complete the payment.
          example: https://example.com/payment/123e4567-e89b-12d3-a456-426614174000
        widgetCode:
          type: string
          description: The HTML code for embedding the payment widget on your site.
          example: <iframe
            src=https://example.com/iframe?integrationId=1ef9694f-68a3-630c-843d-5920a49afe21&orderId=1ef9b4d3-aa4f-6146-b1e1-5920a49afe21
            width="100%" height="800px" allow="clipboard-write *" ></iframe>
        paymentAddress:
          type: string
          nullable: true
          description: |
            A blockchain address to which the payer must send the funds.
            This is only provided if you specified an `assetId` in the request.
          example: "TYZGEHnuoA8AjoCeLmAhSuQ6EcQ7s7xoVi"
    CreateIncomingPaymentResponse:
      type: object
      required:
        - orderId
        - operationId
        - paymentLink
        - widgetCode
      properties:
        orderId:
          type: string
          description: The unique identifier of the created order.
          example: 123e4567-e89b-12d3-a456-426614174000
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        paymentLink:
          type: string
          description: The URL to the payment page where the client needs to be redirected
            to complete the payment.
          example: https://example.com/payment/123e4567-e89b-12d3-a456-426614174000
        widgetCode:
          type: string
          description: The HTML code for embedding the payment widget on your site.
          example: <iframe
            src=https://example.com/iframe?integrationId=1ef9694f-68a3-630c-843d-5920a49afe21&orderId=1ef9b4d3-aa4f-6146-b1e1-5920a49afe21
            width="100%" height="800px" allow="clipboard-write *" ></iframe>
        paymentAddress:
          type: string
          nullable: true
          description: |
            A blockchain address to which the payer must send the funds.
          example: "TYZGEHnuoA8AjoCeLmAhSuQ6EcQ7s7xoVi"
    CreateDepositOrderRequest:
      type: object
      required:
        - integrationId
      properties:
        integrationId:
          type: string
          description: The ID of the integration for which the deposit order is created.
            Retrieve it from the [Retrieve a list of integrations](/docs/wallet-api/get-app-integration-integrations-integrations-getall)
            endpoint.
          pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
        assetId:
          type: string
          nullable: true
          example: "TRX"
          description: >
            The asset identifier you want to receive for this deposit.
            If not provided, the payer can select the asset at the payment page.
            If provided, the payer must use this specific asset.
            Retrieve available asset IDs from [Get crypto assets](/docs/wallet-api/get-app-integration-assets-assets-get).
        externalId:
          type: string
          maxLength: 255
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the transaction with an internal reference in your system.
          example: "123"
    CreateSendOrderRequest:
      description: >
        Represents the required parameters to create a new send order.
      required:
        - amount
        - assetId
        - transferAddress
        - destinationAddress
        - integrationId
      properties:
        amount:
          type: string
          minimum: 0
          exclusiveMinimum: true
          description: >
            The amount of the asset to send. Use a decimal point as a separator, up to 6 decimal places. If more than 6 decimal places are provided, the value will be rounded.
          example: "1.20"
        assetId:
          type: string
          example: "TRX"
          description: >
            The identifier of the asset you want to send.
            Retrieve possible values from the [Get crypto assets](/docs/wallet-api/get-app-integration-assets-assets-get) endpoint.
        transferAddress:
          type: string
          description: >
            The blockchain address from which the funds will be sent. This should be an address managed by your integration.
          example: "TNs2gAuuxn5oqPMHBYoXk8uzayXKrYRahC"
        destinationAddress:
          type: string
          description: >
            The blockchain address where the funds will be sent. It should be a valid address on the same blockchain as the `transferAddress`.
          example: "TKL1W68UWCGHSemfdSirJ5ohAiD29XJbWi"
        integrationId:
          type: string
          description: >
            The UUID of the integration under which this order is being created.
            Obtain this from the [Get integrations](/docs/wallet-api/get-app-integration-integrations-integrations-getall) endpoint.
          pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
          example: "1efa26e3-b54d-6a8e-a125-2b8a249e7453"
        externalId:
          type: string
          nullable: true
          description: >
            An external identifier for this order, provided by your application.
            Use this field to match the transaction with an internal reference in your system.
          maxLength: 255
          example: "123"
      type: object
    CreateSendOrderResponse:
      description: >
        The response returned after successfully creating a send order.
      required:
        - orderId
        - operationId
        - transactionId
      properties:
        orderId:
          type: string
          description: >
            The unique identifier of the created order. Use this to track the order status in future requests.
          example: "1efb977d-d88e-69a6-ba14-a1441192c49f"
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        transactionId:
          type: string
          description: >
            The identifier of the transaction initiated by this order. This can be used to track the transaction details on the blockchain or within the platform.
      type: object
    OrderListItem:
      type: object
      description: >
        Contains details about a specific order.
      required:
        - id
        - operationId
        - status
        - createdAt
        - updatedAt
        - transactionsCount
      properties:
        id:
          type: string
          description: The unique identifier of the order.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        status:
          type: string
          description: |
            The current status of the order. Possible values include:

             **inProgress**: The order is currently being processed and has not yet been completed.
             
            **completed**: The payer has completed the order, and the funds have
            been credited to the merchant's wallet.

            **failed**: The client either did not complete the payment within
            the order's lifetime or did not fully pay the order if it was a
            payment order.
          enum:
            - inProgress
            - completed
            - failed
        createdAt:
          type: string
          description: The timestamp when the order was created, in the ISO 8601 format,
            including the date, time, and timezone information.
          example: 2024-08-29T05:04:24+00:00
        updatedAt:
          type: string
          description: The timestamp when the order status was last updated, in the ISO
            8601 format, including the date, time, and timezone information.
          example: 2024-08-29T05:34:02+00:00
        transactionsCount:
          description: >
            The total number of transactions associated with this order.
          type: integer
        primaryAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.995000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The amount and currency the merchant will receive after deducting
            the service fee.
        secondaryAmount:
          nullable: true
          type: object
          description: The amount and currency of the order in euros.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 2 decimal
                places.
              example: "0.14"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
        serviceFeeAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.005000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
          description: The service fee applied to the order. The currency of the service
            fee always matches the currency of the primaryAmount.
        totalAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "1.000000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The total amount and currency involved in the order, including
            fees. This is the amount the payer actually paid.
        externalId:
          type: string
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the transaction with an internal reference in your system.
          example: "123"
    SingleOrderItem:
      type: object
      description: >
        Contains details about a specific order.
      required:
        - id
        - operationId
        - status
        - createdAt
        - updatedAt
        - transactions
      properties:
        id:
          type: string
          description: The unique identifier of the order.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        status:
          type: string
          description: |
            The current status of the order. Possible values include:
             **inProgress**: The order is currently being processed and has not yet been completed.
             
            **completed**: The payer has completed the order, and the funds have
            been credited to the merchant's wallet.

            **failed**: The client either did not complete the payment within
            the order's lifetime or did not fully pay the order if it was a
            payment order.
          enum:
            - inProgress
            - completed
            - failed
        createdAt:
          type: string
          description: The timestamp when the order was created, in the ISO 8601 format,
            including the date, time, and timezone information.
          example: 2024-08-29T05:04:24+00:00
        updatedAt:
          type: string
          description: The timestamp when the order status was last updated, in the ISO
            8601 format, including the date, time, and timezone information.
          example: 2024-08-29T05:34:02+00:00
        transactions:
          type: array
          description: >
            A list of transactions related to this order. Each item provides details about an individual blockchain transaction.
          items:
            $ref: "#/components/schemas/OrderTransactionItem"
        primaryAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.995000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The amount and currency the merchant will receive after deducting
            the service fee.
        secondaryAmount:
          nullable: true
          type: object
          description: The amount and currency of the order in euros.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 2 decimal
                places.
              example: "0.14"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
        serviceFeeAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.005000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
          description: The service fee applied to the order. The currency of the service
            fee always matches the currency of the primaryAmount.
        totalAmount:
          nullable: true
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "1.000000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The total amount and currency involved in the order, including
            fees. This is the amount the payer actually paid.
        externalId:
          type: string
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the transaction with an internal reference in your system.
          example: "123"
    TransactionItem:
      required:
        - id
        - operationId
        - orderId
        - status
        - createdAt
        - updatedAt
        - receiverAddress
        - primaryBlockchain
        - primaryAmount
        - secondaryAmount
        - serviceFeeAmount
        - totalAmount
      properties:
        id:
          type: string
          description: >
            The unique identifier of the transaction. Use this to track the transaction status and details.
          example: "314"
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
        orderId:
          type: string
          description: >
            The unique identifier of the order this transaction belongs to.
          example: "1ef65c5c-8fae-6bf2-91fd-73770edda314"
        status:
          type: string
          description: >
            The current status of the transaction. Possible values:

             **inProgress**: The transaction is being processed and is not yet confirmed.
             
            **completed**: The transaction has been successfully confirmed on the blockchain.


            **failed**: The transaction did not complete successfully.
          enum:
            - inProgress
            - completed
            - failed
          example: "completed"
        createdAt:
          type: string
          description: >
            The timestamp when the transaction was created, in ISO 8601.
          example: "2024-08-29T05:10:00+00:00"
        updatedAt:
          type: string
          description: >
            The timestamp when the transaction status was last updated, in ISO 8601 format.
          example: "2024-08-29T05:20:00+00:00"
        receiverAddress:
          type: string
          description: >
            The blockchain address that received the funds in this transaction.
          example: "TKL1W68UWCGHSemfdSirJ5ohAiD29XJbWi"
        primaryBlockchain:
          type: string
          description: >
            The blockchain used for the primary amount.
          enum:
            - TRX
            - USDT_TRC20
          example: USDT_TRC20
        primaryAmount:
          description: >
            The amount and currency the merchant will receive after deducting the service fee.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal places.
              example: "0.995000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
              example: "USDT"
        secondaryAmount:
          description: >
            The amount and currency of the transaction in euros.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 2 decimal places.
              example: "0.14"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
              example: "EUR"
        serviceFeeAmount:
          description: >
            The service fee applied to the transaction. The currency of the service fee always matches the currency of the primaryAmount.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal places.
              example: "0.005000"
            currency:
              type: string
              description: The currency of the fee, matching the primaryAmount currency.
              enum:
                - EUR
              example: "EUR"
        totalAmount:
          description: >
            The total amount involved in the transaction, including fees. This is what the payer actually paid.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal places.
              example: "1.000000"
            currency:
              type: string
              description: The currency of the total amount.
              enum:
                - USDT
                - TRX
              example: "USDT"
        hash:
          type: string
          nullable: true
          description: >
            The blockchain transaction hash. Use this to verify and track the transaction on a blockchain explorer.
          example: "000000000000000000000000000000000000000000000000000000000000abcd"
        externalId:
          type: string
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the transaction with an internal reference in your system.
          example: "123"
      type: object
    OrderTransactionItem:
      description: >
        Contains details about a single transaction associated with an order, including its identifiers, status, timestamps, and monetary amounts.
      type: object
      required:
        - id
        - status
        - createdAt
        - updatedAt
        - receiverAddress
      properties:
        id:
          type: string
          description: >
            The unique identifier of the transaction.
          example: "314"
        status:
          type: string
          description: >
            The current status of the transaction. Possible values:

             **inProgress**: The transaction is being processed and is not yet confirmed.
             
            **completed**: The transaction has been successfully confirmed on the blockchain.


            **failed**: The transaction did not complete successfully.
          enum:
            - inProgress
            - completed
            - failed
          example: "completed"
        createdAt:
          type: string
          description: >
            The timestamp when this transaction was created, in ISO 8601 format.
          example: "2024-08-29T05:10:00+00:00"
        updatedAt:
          type: string
          description: >
            The timestamp when this transaction was last updated, in ISO 8601 format.
          example: "2024-08-29T05:20:00+00:00"
        receiverAddress:
          type: string
          description: >
            The blockchain address that received the funds in this transaction.
          example: "TKL1W68UWCGHSemfdSirJ5ohAiD29XJbWi"
        hash:
          type: string
          nullable: true
          description: >
            The blockchain transaction hash. Use this to verify the transaction on a blockchain explorer.
          example: "000000000000000000000000000000000000000000000000000000000000abcd"
        primaryAmount:
          nullable: true
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.995000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The amount and currency the merchant will receive after deducting
            the service fee.
        secondaryAmount:
          nullable: true
          type: object
          description: The amount and currency of the order in euros.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 2 decimal
                places.
              example: "0.14"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - EUR
        serviceFeeAmount:
          nullable: true
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "0.005000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - TRX
          description: The service fee applied to the order. The currency of the service
            fee always matches the currency of the primaryAmount.
        totalAmount:
          nullable: true
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: The monetary value, as a decimal number with up to 6 decimal
                places.
              example: "1.000000"
            currency:
              type: string
              description: The currency of the amount.
              enum:
                - USDT
                - TRX
          description: The total amount and currency involved in the order, including
            fees. This is the amount the payer actually paid.
    CreateRefundOrderRequest:
      type: object
      required:
        - amount
        - assetId
        - destinationAddress
        - refundOrderId
      properties:
        amount:
          type: string
          description: >
            The amount to refund to the payer. It should be a positive decimal
            number, specified with up to 6 decimal places.
          minimum: 0
          exclusiveMinimum: true
          example: "50.000000"
        assetId:
          type: string
          description: >
            The asset used for the refund. Ensure that the asset matches the one
            used in the original payment order.
          enum:
            - TRX
            - USDT_TRC20
          example: USDT_TRC20
        destinationAddress:
          type: string
          description: >
            The wallet address where the refund will be sent. It should be a
            valid blockchain address for the specified asset.
          example: T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb
        refundOrderId:
          type: string
          description: >
            The unique identifier of the original order that is being refunded.
            This ID helps link the refund to the correct order.
          pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
          example: 123e4567-e89b-12d3-a456-426614174000
    CreateWithdrawalOrderRequest:
      type: object
      required:
        - amount
        - assetId
        - destinationAddress
        - integrationId
      properties:
        amount:
          type: string
          description: >
            The amount to withdraw from the balance. It should be a positive
            decimal number, specified with up to 6 decimal places.
          minimum: 0
          exclusiveMinimum: true
          example: "100.000000"
        assetId:
          type: string
          description: |
            The asset type to be withdrawn.
          enum:
            - TRX
            - USDT_TRC20
          example: TRX
        destinationAddress:
          type: string
          description: >
            The wallet address where the funds will be sent. This must be a
            valid address compatible with the selected asset.
          example: T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb
        integrationId:
          type: string
          description: >
            The unique identifier of the integration through which the
            withdrawal is being processed. This ID helps link the withdrawal to
            a specific integration.
          pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
          example: 1ef65bda-11ad-63ca-8afe-73770edda314
        externalId:
          type: string
          maxLength: 255
          nullable: true
          description: An external identifier for this order, provided by your application. Use this field to match the order with an internal reference in your system.
          example: "123"
    CreateOutgoingOrderResponse:
      type: object
      required:
        - orderId
        - operationId
      properties:
        orderId:
          type: string
          description: >
            The unique identifier of the created refund or withdrawal order. Use
            this ID to track the order's status .
          example: 123e4567-e89b-12d3-a456-426614174000
        operationId:
          type: string
          description: The unique identifier of the operation.
          example: 1ef65c5c-8fae-6bf2-91fd-73770edda314
    AssetList:
      type: object
      description: |
        A list of available crypto assets supported by the gateway.
      required:
        - assets
      properties:
        assets:
          type: array
          description: An array of supported crypto assets and their details.
          items:
            $ref: "#/components/schemas/AssetListItem"
    AssetRateList:
      type: object
      description: >
        A list of crypto assets and their corresponding conversion rates based
        on the provided fiat amount and currency.
      required:
        - rates
      properties:
        rates:
          type: array
          description: An array of rate objects, each representing conversion details for
            an asset.
          items:
            $ref: "#/components/schemas/AssetRateListItem"
    AssetListItem:
      type: object
      description: >
        Details of a single supported crypto asset, including its identifiers
        and display names.
      required:
        - id
        - currencyCode
        - displayName
        - blockchainId
        - blockchainDisplayName
        - name
        - disabled
      properties:
        id:
          type: string
          description: A unique identifier for the asset.
          example: USDT_TRC20
        currencyCode:
          type: string
          description: The code of the asset's currency.
          example: USDT
        displayName:
          type: string
          description: A user-friendly name for the asset.
          example: Tether
        blockchainId:
          type: string
          description: The blockchain on which the asset resides.
          example: tron
        blockchainDisplayName:
          type: string
          description: A user-friendly name for the blockchain.
          example: Tron
        name:
          type: string
          description: A descriptive name for the asset, including token standards.
          example: Tether (TRC20)
        disabled:
          type: boolean
          description: Indicates whether the asset is currently disabled for operations.
          example: false
    AssetRateListItem:
      type: object
      description: |
        Details of a single asset's conversion rate.
      required:
        - assetId
        - rate
        - crypto
      properties:
        assetId:
          type: string
          description: The unique identifier of the asset.
          example: USDT_TRC20
        rate:
          type: string
          description: >
            The conversion rate from 1 unit of the specified fiat currency to
            the equivalent amount of this asset.
          example: "0.999839"
        crypto:
          $ref: "#/components/schemas/MoneyResponse"
    MoneyResponse:
      type: object
      description: >
        Represents a monetary amount in a specified currency, typically used to
        show the converted crypto amount.
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: The decimal amount of the currency.
          example: "9.998389"
        currency:
          type: string
          description: The currency code of the amount.
          example: USDT
    Webhook:
      type: object
      required:
        - id
        - integrationId
        - url
        - orderTypes
        - orderStatuses
      properties:
        id:
          type: string
          description: >
            The unique identifier of the webhook configuration.
          example: "webhook-1"
        integrationId:
          type: string
          description: >
            The unique identifier of the integration to which this webhook belongs.
          example: "1ef65bda-11ad-63ca-8afe-73770edda314"
        url:
          type: string
          description: >
            The URL to which webhook notifications will be sent.
          example: "https://example.com/webhook"
        orderTypes:
          type: array
          description: >
            The list of types for which webhook notifications will be triggered.
          items:
            type: string
            enum:
              - deposit
            example: "deposit"
        orderStatuses:
          type: array
          description: >
            The list of statuses for which webhook notifications will be sent.
          items:
            type: string
            enum:
              - completed
            example: "completed"
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
security:
  - ApiKeyAuth: []

x-webhooks:
  orderStatus:
    post:
      summary: "Order status callback"
      description: >
        Notifies your application when a deposit order transitions to the `completed` status.

        The payload structure is identical to the response of the [Get order by ID](/docs/wallet-api/get-app-integration-orders-orders-getorder) endpoint.

        We send a POST request with the order data to your configured endpoint. To ensure the security and authenticity of the notification, a control signature is included in the `X-Api-Signature` (SHA256) header.

        For details on configuring your callback endpoint, see [how to configure callback](/docs/webhooks).
      operationId: orderStatusCallback
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SingleOrderItem"
