openapi: 3.0.3
info:
  version: ''
  title: FX Order Cancel
  description: |

    The FX Order Cancel API allows you to cancel an order that you have placed.
    ### Platform Operational Hours

      The CitiFX Gateway is available during standard FX market trading hours. The platform is not available during weekend hours.
      * Start of business is Monday 07:00 AM Auckland
      * End of business is Friday 17:00 EST New York
servers:
  - url: https://sandbox.api.citivelocity.com/markets
    description: sandbox URL
  - url: https://api.citivelocity.com/markets
    description: production URL
security:
  - OAuth2:
      - fxapi
  - client_id: []
paths:
  /fxgateway/sync/ordercancel/api/v1:
    post:
      summary: Order Cancellation Synchronous Request
      description: |
        Use this endpoint to cancel an order you have placed. 

        Note:
         - FX Bench QUOTED orders cannot be cancelled through this cancel request
         - FX Bench FIXING orders cannot be cancelled once they are rated
         - FX Market orders cannot be cancelled once they are rated
            
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FXOrderCancel'
        required: true
      responses:
        '200':
          description: |
            OK Acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order_Cancel_Response'
        '401':
          description: >-
            Unauthorized user/ Invalid_client (Not authorized to Oauth API)/ Not
            registered to the plan
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >-
        Citi Velocity APIs use the oAuth2 authentication scheme, which requires
        a bearer token to authenticate your API call. See <a
        href="../../fx/authentication/authentication-api-reference/"
        target="_blank">the Citi Authentication API reference</a> for
        information on requesting a token.
      flows:
        clientCredentials:
          scopes:
            fxapi: ''
          tokenUrl: https://sandbox.api.citivelocity.com/markets/cv/api/fx/oauth2/token
    client_id:
      type: apiKey
      in: query
      name: client_id
  schemas:
    FXOrderCancel:
      type: object
      required:
        - action
        - jsonReqId
        - senderCompId
        - onBehalfOfCompId
        - deals
      properties:
        action:
          type: string
          description: 'The service you are requesting. Allowed values: CANCEL.'
        jsonReqId:
          type: string
          example: Req20181011776
          description: The unique identifier for the JSON request. Format is alphanumeric.
          maxLength: 60
        senderCompId:
          type: string
          description: >-
            The Citi-assigned value used to identify the message sender. This
            was assigned to you during onboarding.
          example: ClientName
        onBehalfOfCompId:
          type: string
          description: >-
            The Citi-assigned value used to identify the sub-entity. This was
            assigned to you during onboarding.
          example: Sub Entity
        sendingTime:
          type: string
          description: >-
            The time of the message transmission expressed in UTC (Universal
            Time Coordinated, also known as "GMT"). Format:
            YYYYMMDD-HH:MM:SS.mmm.
          example: 20180820-04:48:29.125
        deals:
          type: array
          description: >-
            Order can be cancelled based on the given fields below. clOrdId is
            required, and should be sent along with origClOrdID OR
            origJsonReqId.
          items:
            required:
              - clOrdId
              - origClOrdID
              - origJsonReqId
            properties:
              clOrdId:
                type: string
                description: >-
                  The unique identifier that you assign to the order. A
                  reference specific to this client/request combination. Market
                  orders support max 15 characters. Benchmark orders support 45
                  characters. Alphanumeric and special character hyphen (-)
                  allowed.
                example: TEST12345
              origClOrdID:
                type: string
                description: >-
                  ClOrdID of the previous non-rejected order (NOT the initial
                  order of the day) when cancelling or replacing an order. This
                  has to be given along with ClOrdId.
                example: OR12345
              origJsonReqId:
                type: string
                description: >-
                  The unique identifier for the original JSON Request. ClOrdId
                  must be populated along with this field. All the deals
                  originally given under this JsonReqD will be eligible for
                  cancellation.
                example: Req20181011776
      example:
        action: CANCEL
        senderCompId: TESTCLIENT0
        onBehalfOfCompId: TCL0
        jsonReqId: 27SepT30
        sendingTime: 20180829-04:48:29.125
        deals:
          - clOrdId: CANCELTEST01
            origClOrdId: TEST01
    Order_Cancel_Response:
      description: >-
        In case of multiple orders, multiple dealResponse JSON objects will be
        present in the dealResponses JSON array. Response array can be of both
        Ack / Nack.
      required:
        - action
        - jsonReqId
        - senderCompId
        - onBehalfOfCompId
        - sendingTime
        - dealResponses
        - deals
      properties:
        action:
          type: string
          example: order-response
          description: 'Allowed value: cancel-response.'
        jsonReqId:
          type: string
          example: Req20181011776
          description: The unique identifier for the JSON request. Format is alphanumeric.
          maxLength: 60
        senderCompId:
          type: string
          description: >-
            The Citi-assigned value used to identify the firm sending the
            message.
          example: ClientName
        onBehalfOfCompId:
          type: string
          description: >-
            The Citi-assigned value used to identify the sub-entity. May contain
            special characters ( ‘_’, ‘.’, ‘-‘).
          example: Sub Entity
        sendingTime:
          type: string
          description: >-
            The time of message transmission. Always expressed in UTC (Universal
            Time Coordinated, also known as 'GMT.' Format is
            YYYYMMDD-HH:MM:SS.mmm.
          example: 20180820-04:48:29.125
        deals:
          type: array
          items:
            required:
              - clOrdId
              - orderId
              - transactTime
              - execId
              - orderStatus
            properties:
              account:
                type: string
                description: Your Citi-assigned client identifier.
                example: 109430258
              clOrdId:
                type: string
                description: >-
                  The unique identifier you assign. Market order cancellations
                  support max 15 characters. Benchmark order cancellations
                  support max 45 characters.
                example: TEST12345
              side:
                type: string
                enum:
                  - B
                  - S
                description: >-
                  The Buy Or Sell Indicator from your perspective. B=Client buys
                  dealt ccy, S=Client sells dealt ccy.
                example: B
              valueDate:
                type: string
                description: The value date of the deal placed.
                example: 20240502
              ccyPair:
                type: string
                description: The currency pair that you are dealing on. CCY1CCY2.
                maxLength: 6
                example: GBPUSD
              dealtCcy:
                type: string
                description: The currency for which you supplied the dealt amount.
                maxLength: 3
                example: GBP
              transactTime:
                type: string
                description: Time of the transaction represented by this single order.
                example: Mon Apr 29 12:50:33 IST 2024
              execId:
                type: string
                description: The unique identifier of execution message.
                example: ABC123
              avgPx:
                type: number
                description: Calculated average price of all fills on this order.
                example: 0
              orderId:
                type: number
                description: >-
                  The Citi-assigned order ID. This is not populated for REJECTED
                  deals.
                example: 3714864
              orderStatus:
                type: string
                description: >-
                  Value = CANCELLED (if cancellation request is accepted by
                  pricing system) Value = CANCELLATION_REJECTED (if cancellation
                  request is rejected by pricing system).
                example: CANCELLED or CANCELLATION_REJECTED
              lastQty:
                type: number
                description: The dealt amount.
                example: 1234.56
              secondaryClOrdId:
                type: string
                description: Secondary order reference.
                example: OR12345
      example:
        action: cancel-response
        senderCompId: TESTCLIENT0
        onBehalfOfCompId: TCL0
        jsonReqId: 27SepT30
        sendingTime: 20180829-04:49:25.125
        dealResponses:
          - clOrdId: CANCELTEST01
            side: B
            execId: 363747-1538036158154
            avgPx: '0'
            orderId: TCL0-TEST01
            orderStatus: CANCELLED
            cumQty: '0'
            leavesQty: '0'
            execType: '4'
            ordRejReason: '99'
            text: Quote TCL0-TEST01 processed in eDealer.