openapi: 3.2.0
info:
  title: Citi Fx API
  version: '1.0'
  description: 'Operations tagged Fx across 2 of this provider''s published API definitions: citi-marketplace-management-openapi.yaml, fx_authentication_api.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
  description: production gateway url
- url: https://sandbox.b2b.api.icg.citi.com/citiconnect/sb/gatewayservices
  description: sbox url
- url: https://sandbox.api.citivelocity.com/markets/cv/api
  description: sandbox URL
- url: https://api.citivelocity.com/markets/cv/api
  description: production URL
tags:
- name: FX
  description: FX Rate Inquiry
paths:
  /merchants/v1/fx-rate:
    post:
      summary: FX Query
      description: You can use this to get fx rate to be used for transaction. The latest rate you get is valid for 5 minutes , during which time you can use this rate to transaction
      operationId: fxQuery
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - FX
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Idempotency-Id'
      - $ref: '#/components/parameters/Merchant-Id'
      - $ref: '#/components/parameters/Country-Code'
      requestBody:
        description: This section holds the request parameters for FX Rate Inquiry.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fx-Query-Request'
            examples:
              fxquery-request:
                $ref: '#/components/examples/Fx-Query-Request-Example'
      responses:
        '200':
          description: FX Query completed successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fx-Query-Response'
              examples:
                success-response:
                  $ref: '#/components/examples/Fx-Query-Success-Example'
        '400':
          $ref: '#/components/responses/Bad-Request'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/Not-Found'
        '405':
          $ref: '#/components/responses/Method-Not-Allowed'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/Unsupported-Media-Type'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
        '504':
          $ref: '#/components/responses/Gateway-Timeout'
      security:
      - oAuth2:
        - /authenticationservices/v1
    servers:
    - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      description: production gateway url
    - url: https://sandbox.b2b.api.icg.citi.com/citiconnect/sb/gatewayservices
      description: sbox url
  /fx/oauth2/token:
    post:
      summary: Request Access Token
      description: The OAuth token request authenticates your API message and responds with an access token.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                httpMessage: Bad Request
                httpCode: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: invalid_client
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                httpMessage: NOT FOUND
                httpCode: 404
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                httpMessage: METHOD NOT ALLOWED
                httpCode: 405
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                httpMessage: Internal Server Error
                httpCode: 500
      deprecated: false
      security:
      - basicAuth: []
      tags:
      - FX
      operationId: postFxOauth2Token
      x-operation-id-source: derived
    servers:
    - url: https://sandbox.api.citivelocity.com/markets/cv/api
      description: sandbox URL
    - url: https://api.citivelocity.com/markets/cv/api
      description: production URL
components:
  examples:
    Service-Unavailable-Gateway-Example:
      value:
        httpCode: '503'
        httpMessage: Service is temporarily unavailable
        moreInformation: Retry the request after some time
    Not-Found-Gateway-Error-Example:
      value:
        httpCode: '404'
        httpMessage: Not Found
        moreInformation: No resources match requested URI
    Method-Not-Allowed-Service-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627901
        error_details:
        - issue: Method not supported
          action: Method not supported for this endpoint, please use valid http verb
          code: CC00001
    Method-Not-Allowed-Gateway-Error-Example:
      value:
        httpCode: '405'
        httpMessage: Method Not Allowed
        moreInformation: The method is not allowed for the requested URL
    Un-Supported-Media-Type-Service-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: Media type not supported
          action: please use valid content-type in header
          code: CC00002
    Bad-Request-Gateway-Error-Example:
      value:
        httpCode: '400'
        httpMessage: Bad Request
        moreInformation: please provide valid value for request
    Internal-Server-Gateway-Error-Example:
      value:
        httpCode: '500'
        httpMessage: Internal Server Error
        moreInformation: Internal Server Error
    Bad-Request-Service-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627901
        error_details:
        - issue: record that you are searching is not found
          action: resend the request with valid values
          code: VC00003
    Unauthorized-Gateway-Error-Example:
      value:
        httpCode: '401'
        httpMessage: Unauthorized
        moreInformation: The server could not verify that you are authorized to access the URL
    Internal-Server-Service-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: unable to serve your request at this moment
          action: Please refer to documentation provided or contact support team
          code: CC00004
    Unauthorized-Service-Error-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - issue: User not authorized for this functionality
          action: please use valid credentials to access this functionality
          code: CC00007
    Fx-Query-Request-Example:
      summary: Sample FX Query request
      value:
        buy_currency_code: CNH
        buy_amount: 100.11
        sell_currency_code: USD
        sell_amount: 80.1
        reference_id: '12456'
        seller_markup: CN-150
    Un-Supported-Media-Type-Gateway-Error-Example:
      value:
        httpCode: '415'
        httpMessage: Unsupported Media Type
        moreInformation: Unsupported Content-Type application/octet-stream
    Forbidden-Service-Example:
      value:
        ref_id: ec689822-9864-4c4d-9d68-222467627902
        error_details:
        - code: CC00008
          issue: User does not have privilege to access this functionality.
          action: Please reach out to support team to enable this feature.
    Fx-Query-Success-Example:
      summary: Sample 200 response
      value:
        buy_currency_code: CNH
        buy_amount: 100.11
        sell_currency_code: USD
        sell_amount: 80.1
        value_date: '2025-12-15'
        fx_rate_id: '16098876465273400000'
        fx_rate: 7.13909
        expiry_time: '2025-08-22T12:00:00Z'
        reference_id: '12456'
    Too-Many-Requests-Gateway-Example:
      value:
        httpCode: '429'
        httpMessage: Too Many Requests
        moreInformation: Rate Limit exceeded
  schemas:
    Amount:
      type: number
      title: amount
      description: Amount in currency.
      minimum: 0.01
      maximum: 10000000000000
      example: 1000
    Service-Error-Response:
      title: ServiceErrorResponse
      type: object
      required:
      - ref_id
      - error_details
      properties:
        ref_id:
          type: string
          maxLength: 120
          description: Unique ID for the Transaction
          title: ref_id
          example: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        error_details:
          type: array
          description: List of error details
          title: error_details
          items:
            $ref: '#/components/schemas/Error-Detail'
    Created-Time:
      type: string
      format: date-time
      description: Date and time of the file created. Pattern YYYY-MM-DDTHH:mm:ssZ
      title: created_time
      example: '2026-01-06T10:56:25Z'
    Fx-Query-Response:
      title: FxQueryResponse
      allOf:
      - $ref: '#/components/schemas/Multiple-Currency-Amount'
      - type: object
        title: Fx-Query-Response
        required:
        - buy_currency_code
        - buy_amount
        - sell_currency_code
        - sell_amount
        - fx_rate
        - reference_id
        properties:
          fx_rate_id:
            $ref: '#/components/schemas/Fx-Rate-Id'
          fx_rate:
            $ref: '#/components/schemas/Fx-Rate'
          value_date:
            allOf:
            - $ref: '#/components/schemas/Common-Date'
            title: value_date
            description: Settlement date of the FX transaction (yyyy-MM-dd, not required for Instant FX transactions).
          expiry_time:
            allOf:
            - $ref: '#/components/schemas/Created-Time'
            title: expiry_time
            description: 'The expiration timestamp of the quote. If the transaction is not executed, the `fx_rate_id` will expire after the date and time. After the expiration timestamp, you should request new fx_rate format : YYYY-MM-DDTHH:mm:ssZ).'
          reference_id:
            $ref: '#/components/schemas/Reference-Id'
    Common-Date:
      type: string
      title: date
      format: date
      description: Date in ISO 8601 (YYYY-MM-DD).
      example: '1975-03-07'
    Error-Detail:
      type: object
      title: ErrorDetail
      properties:
        issue:
          type: string
          minLength: 1
          maxLength: 200
          description: more details about the issue
          title: issue
          example: property emailAddress is mandatory and it cannot be empty
        action:
          type: string
          maxLength: 350
          description: corrective action to be taken to resolve above issue
          title: action
          example: please provide valid value for property emailAddress
        code:
          type: string
          minLength: 1
          maxLength: 64
          description: unique code representing the issue
          title: code
          example: VC00010
    Fx-Query-Request:
      title: FxQueryRequest
      allOf:
      - $ref: '#/components/schemas/Multiple-Currency-Amount'
      - type: object
        title: Fx-Query-Request
        required:
        - buy_currency_code
        - sell_currency_code
        - reference_id
        - seller_markup
        properties:
          seller_markup:
            type: string
            title: seller_markup
            description: Seller markup consists of country code + markup.
            example: CN-150
          reference_id:
            $ref: '#/components/schemas/Reference-Id'
    Fx-Rate-Id:
      type: string
      title: fx_rate_id
      description: When you request a guaranteed quote of Instant FX and Reserved FX, the Citi will return a `fx_rate_id`, which is the unique ID only for guaranteed `fx_indi_rate. <b> fx_rate_id is mandatory for other than USD to USD transfer.
      minLength: 1
      maxLength: 64
      example: '16098876465273400000'
    Currency-Code:
      type: string
      title: currency_code
      description: The currency code in the transaction.
      pattern: ^[A-Z]{3}$
      example: USD
    Fx-Rate:
      type: number
      title: fx_rate
      description: The indicative FX rate which is for reference only. The number indicates how much units of buy_currency you can get from one unit of sell_currency.
    Multiple-Currency-Amount:
      title: FxQuery
      type: object
      properties:
        buy_currency_code:
          allOf:
          - $ref: '#/components/schemas/Currency-Code'
          title: buy_currency_code
          description: The currency that the client is buying.
          example: CNH
        buy_amount:
          allOf:
          - $ref: '#/components/schemas/Amount'
          title: buy_amount
          description: The amount of buy_currency for the transaction. (You ONLY need to define one amount, either buy_amount or sell_amount in a request.)
          example: 100.11
        sell_currency_code:
          allOf:
          - $ref: '#/components/schemas/Currency-Code'
          title: sell_currency_code
          description: The currency that the client is selling.
          example: USD
        sell_amount:
          allOf:
          - $ref: '#/components/schemas/Amount'
          title: sell_amount
          description: The amount of sell_currency for the transaction. (You ONLY need to define one amount, either buy_amount or sell_amount in a request.)
          example: 80.1
    Gateway-Error-Response:
      type: object
      title: GatewayErrorResponse
      required:
      - httpCode
      - httpMessage
      - moreInformation
      properties:
        httpCode:
          type: string
          maxLength: 3
          description: Numeric HTTP Staus code
          title: httpCode
        httpMessage:
          type: string
          maxLength: 128
          description: HTTP error message
          title: httpMessage
          example: Bad Request
        moreInformation:
          type: string
          maxLength: 128
          description: HTTP error message
          title: moreInformation
          example: please provide valid value for request
    Reference-Id:
      type: string
      title: reference_id
      description: Unique identifier for this request from your system.
      example: '12456'
      minLength: 1
      maxLength: 120
    Response:
      title: oAuthTokenResponse
      description: The response body to retrieve an OAuth token.
      required:
      - access_token
      - expires_in
      - scope
      properties:
        access_token:
          type: string
          description: Contains the OAuth Token that will be used for authenticating successive API calls. The token should be passed in the request header "Authorization", prefixed with "Bearer" and a space in between.
        token_type:
          type: string
          description: Default value will be “Bearer".
        scope:
          type: string
          description: The scope of the authentication call. The value will be `fxapi`.
        expires_in:
          type: string
          description: The expiry time of the OAuth Token in seconds.
      example:
        token_type: Bearer
        access_token: AAIkYWNkODQwNzgtZTczMi00ZjczLTg3MDktYmYzODE0MTU2OGYxKbY9QECipkzJXDAf5HQONqyXdZbeJUHEykY5cgI7zk3gHsXOqZrKMeAoHRoglUyCnQ6Iye5r21XB4nOr8_t0BQ0AiJAoLZleFFZYWt2y2YAhOKxd-yBQF8XtqiOs5z32Wr-eOZwIdnyvx7_Vak2Fzw
        expires_in: '900'
        scope: fxapi
    ErrorMessage:
      required:
      - httpCode
      properties:
        httpCode:
          type: integer
        httpMessage:
          type: string
    Request:
      required:
      - grantType
      - client_id
      - client_secret
      - scope
      properties:
        grantType:
          type: string
          description: You must always pass 'client_credentials' in this field because Citi only provides credentials-based authentication for API users.
        client_id:
          type: string
          description: Your client ID.
        client_secret:
          type: string
          description: Your client secret.
        scope:
          type: string
          description: This is the scope of the authentication call. Value should be `fxpai`.
      example:
        grantType: client_credentials
        scope: fxpai
        client_id: YOUR_CLIENT_ID_HERE
        client_secret: YOUR_CLIENT_SECRET_HERE
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            title: Unauthorized-Response
            oneOf:
            - $ref: '#/components/schemas/Service-Error-Response'
            - $ref: '#/components/schemas/Gateway-Error-Response'
          examples:
            Unauthorized-Service-Error-Example:
              $ref: '#/components/examples/Unauthorized-Service-Error-Example'
            Unauthorized-Gateway-Error-Example:
              $ref: '#/components/examples/Unauthorized-Gateway-Error-Example'
    Too-Many-Requests:
      description: Too Many Requests - Rate limit exceeded. Retry after the specified time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Gateway-Error-Response'
          examples:
            Too-Many-Requests-Gateway-Example:
              $ref: '#/components/examples/Too-Many-Requests-Gateway-Example'
    Gateway-Timeout:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Gateway-Error-Response'
    Not-Found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Gateway-Error-Response'
          examples:
            Not-Found-Gateway-Error-Example:
              $ref: '#/components/examples/Not-Found-Gateway-Error-Example'
    Service-Unavailable:
      description: Service Unavailable - The server is temporarily unable to  handle the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Gateway-Error-Response'
          examples:
            Service-Unavailable-Gateway-Example:
              $ref: '#/components/examples/Service-Unavailable-Gateway-Example'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Service-Error-Response'
          examples:
            Forbidden-Service-Example:
              $ref: '#/components/examples/Forbidden-Service-Example'
    Unsupported-Media-Type:
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            title: Unsupported-Media-Type-Response
            oneOf:
            - $ref: '#/components/schemas/Gateway-Error-Response'
            - $ref: '#/components/schemas/Service-Error-Response'
          examples:
            Un-Supported-Media-Type-Gateway-Error-Example:
              $ref: '#/components/examples/Un-Supported-Media-Type-Gateway-Error-Example'
            Un-Supported-Media-Type-Service-Error-Example:
              $ref: '#/components/examples/Un-Supported-Media-Type-Service-Error-Example'
    Internal-Server-Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            title: Internal-Server-Error-Response
            oneOf:
            - $ref: '#/components/schemas/Gateway-Error-Response'
            - $ref: '#/components/schemas/Service-Error-Response'
          examples:
            Internal-Server-Service-Error-Example:
              $ref: '#/components/examples/Internal-Server-Service-Error-Example'
            Internal-Server-Gateway-Error-Example:
              $ref: '#/components/examples/Internal-Server-Gateway-Error-Example'
    Method-Not-Allowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            title: Method-Not-Allowed-Response
            oneOf:
            - $ref: '#/components/schemas/Gateway-Error-Response'
            - $ref: '#/components/schemas/Service-Error-Response'
          examples:
            Method-Not-Allowed-Gateway-Error-Example:
              $ref: '#/components/examples/Method-Not-Allowed-Gateway-Error-Example'
            Method-Not-Allowed-Service-Error-Example:
              $ref: '#/components/examples/Method-Not-Allowed-Service-Error-Example'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Service-Error-Response'
    Bad-Request:
      description: Bad Request
      content:
        application/json:
          schema:
            title: Bad-Request-Response
            oneOf:
            - $ref: '#/components/schemas/Gateway-Error-Response'
            - $ref: '#/components/schemas/Service-Error-Response'
          examples:
            Bad-Request-Service-Error-Example:
              $ref: '#/components/examples/Bad-Request-Service-Error-Example'
            Bad-Request-Gateway-Error-Example:
              $ref: '#/components/examples/Bad-Request-Gateway-Error-Example'
  headers:
    Apim-Guid:
      description: Unique system generated reference number generated by   Citi. Refer to this number in case of any discrepancy reporting to a Citi representative.
      schema:
        type: string
        maxLength: 128
        minLength: 1
        title: Apim-Guid
      required: true
      example: na-apimgwgtds04~4a98cbc5-d813-4e65-bc81-d70f0f87f6ec
  parameters:
    Merchant-Id:
      in: header
      name: Merchant-Id
      description: CITI generated Merchant ID during merchant creation.
      schema:
        type: string
        title: Merchant-Id
        minLength: 1
        maxLength: 36
        example: ec689822-9864-4c4d-9d68-22246762901
      required: true
    Country-Code:
      in: header
      name: Country-Code
      description: Marketplace's country code.
      schema:
        pattern: ^[A-Z]{2,2}$
        type: string
        title: Country-Code
        example: US
      required: true
    Idempotency-Id:
      in: header
      name: Idempotency-Id
      description: "Your unique identification for a POST request \n - Maximum length is 128. \n-CitiConnect API responds with an error (HTTP status 4XX) if your POST request idempotency identification value is a duplicate across a recent history of idempotency identifications in Citi's database. \n- If you don't receive any response (HTTP status 2XX, 4XX or 5XX) from Citi to your POST request and you wish to retry, reinitiate your request with the same idempotency identification to prevent accidental duplicate payment."
      schema:
        type: string
        title: Idempotency-Id
        minLength: 1
        maxLength: 128
        example: a44cbb606de4edb9a7a123414bba3bb
      required: true
    Client-Id:
      in: query
      name: client_id
      description: Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding.
      schema:
        type: string
        title: Client-Id
        example: 6d3cf821-db6d-496d-bec0-064a362e9c31
        minimum: 1
        maximum: 128
      required: true
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://b2b.api.icg.citi.com/authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Access to marketplace management APIs
    basicAuth:
      type: http
      scheme: basic
      description: Username is the application's client_id and password is the client_secret.
x-refined-from:
- citi-marketplace-management-openapi.yaml
- fx_authentication_api.yaml