openapi: 3.2.0
info:
  title: Gateway Services Reporting API
  description: Self onboarding services for merchants to register on the platform, create wallets, and perform withdrawals or payouts to their designated settlement and external beneficiary accounts.
  contact:
    name: Standards & Developer Hub
    url: https://tts.sandbox.developer.citi.com/citiconnect/
    email: developer-support@citi.com
  version: 1.0.0
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
security:
- oAuth2:
  - /authenticationservices/v1
tags:
- name: Reporting
  description: Transaction and balance reporting operations
paths:
  /merchants/v1/transactions:
    get:
      summary: Transaction Reporting
      description: Retrieves list and details of transactions, suitable for reporting purposes such as ledgers, finance Operations and analytics.
      operationId: getTransactions
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - Reporting
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Country-Code'
      - $ref: '#/components/parameters/Merchant-Id'
      - $ref: '#/components/parameters/From-Date-Time'
      - $ref: '#/components/parameters/To-Date-Time'
      - $ref: '#/components/parameters/Page-No'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Uetr'
      - $ref: '#/components/parameters/Payment-Type'
      - $ref: '#/components/parameters/Reporting-Status'
      responses:
        '200':
          description: Transaction report retrieved successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
            Pagination-Metadata:
              description: This header contains a JSON object with details about the response. The full schema is available in the 'Pagination-Metadata' schema section below
              schema:
                $ref: '#/components/schemas/Pagination-Metadata'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction-Report-Response'
              examples:
                Transaction-Report:
                  $ref: '#/components/examples/Transaction-Report'
                Transaction-Report-For-WITHDRAW-&-INBOUND:
                  $ref: '#/components/examples/Transaction-Report-For-WITHDRAW-INBOUND'
                Transaction-Report-For-PAYOUT:
                  $ref: '#/components/examples/Transaction-Report-For-PAYOUT'
        '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'
        '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
  /merchants/v1/balance-report:
    get:
      summary: Balance Report
      description: This helps financial reconciliation, enabling tracking of opening and closing balances for a period, along with updated running balances following each transaction. This report helps you track changes to your account balance and reconcile the balance whenever required.
      operationId: getBalanceReport
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - Reporting
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Country-Code'
      - $ref: '#/components/parameters/Merchant-Id'
      - $ref: '#/components/parameters/From-Date-Time'
      - $ref: '#/components/parameters/To-Date-Time'
      - $ref: '#/components/parameters/Page-No'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Uetr'
      - $ref: '#/components/parameters/Currency-Code'
      - $ref: '#/components/parameters/Virtual-Account-Id'
      responses:
        '200':
          description: Balance report retrieved successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
            Pagination-Metadata:
              description: This header contains a JSON object with details about the response. The full schema is available in the 'Pagination-Metadata' schema section below
              schema:
                $ref: '#/components/schemas/Pagination-Metadata'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance-Report-Response'
              examples:
                Balance-Report:
                  $ref: '#/components/examples/Balance-Report'
        '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'
        '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
components:
  examples:
    Service-Unavailable-Gateway-Example:
      value:
        httpCode: '503'
        httpMessage: Service is temporarily unavailable
        moreInformation: Retry the request after some time
    Transaction-Report-For-PAYOUT:
      value:
      - status: SUCCESS
        creditor:
          account:
            number: '1781610740'
        transaction:
          end_to_end_id: A1781689100
          currency_code: USD
          amount: 257
          buy_currency_code: USD
          buy_amount: 257
          uetr: SP0926061717382948219612
          fx_rate: 1
          payment_type: PAYOUT
          created_time: '2026-06-17T09:38:29Z'
          completed_time: '2026-06-17T11:39:04Z'
    Transaction-Report:
      value:
      - debtor:
          account:
            number: '456456547'
            branch_code: VA202501080950209789
            virtual_account_id: VA202501080950209789
        creditor:
          id: R202501080950209789
          account:
            number: '456456547'
            branch_code: VA202501080950209789
            virtual_account_id: VA202501080950209789
        transaction:
          end_to_end_id: SM37864746
          currency_code: CNY
          amount: 10000
          buy_currency_code: CNY
          buy_amount: 10000
          sell_currency_code: USD
          sell_amount: 1000
          payment_details: INV123
          uetr: '202501092053115499258'
          fx_rate: 0
          payment_type: PAYOUT
          created_time: '2026-01-06T10:56:25Z'
          completed_time: '2026-01-06T11:00:25Z'
        status: SUCCESS
    Not-Found-Gateway-Error-Example:
      value:
        httpCode: '404'
        httpMessage: Not Found
        moreInformation: No resources match requested URI
    Transaction-Report-For-WITHDRAW-INBOUND:
      value:
      - status: SUCCESS
        creditor:
          account:
            number: '6258591914237939405'
        transaction:
          end_to_end_id: A1781686585
          currency_code: USD
          amount: 21.71
          buy_currency_code: CNY
          buy_amount: 154
          uetr: WC0926061716563217599935
          fx_rate: 7.0945
          payment_type: WITHDRAW
          created_time: '2026-06-17T08:56:32Z'
          completed_time: '2026-06-17T11:42:26Z'
      - status: SUCCESS
        debtor:
          account:
            number: newAccountNo
        transaction:
          currency_code: USD
          amount: 8000001
          sell_currency_code: USD
          sell_amount: 8000001
          uetr: '202606162012563459642'
          fx_rate: 1
          payment_type: INBOUND
          created_time: '2026-06-16T12:12:56Z'
          completed_time: '2026-06-16T12:21:00Z'
    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
    Bad-Request-Gateway-Error-Example:
      value:
        httpCode: '400'
        httpMessage: Bad Request
        moreInformation: please provide valid value for request
    Balance-Report:
      value:
      - virtual_account_id: ec689822-9864-4c4d-9d68-222467627901
        uetr: '202501092053115499258'
        opening_balance: 5000
        closing_balance: 4000
        created_time: '2026-01-06T10:56:25Z'
        amount: 1000
        currency_code: USD
        direction: debit
    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
    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.
    Too-Many-Requests-Gateway-Example:
      value:
        httpCode: '429'
        httpMessage: Too Many Requests
        moreInformation: Rate Limit exceeded
  schemas:
    Common-Transaction:
      title: CommonTransaction
      type: object
      description: Transaction details.
      properties:
        end_to_end_id:
          $ref: '#/components/schemas/End-To-End-Id'
        currency_code:
          allOf:
          - $ref: '#/components/schemas/Currency-Code'
          title: target_currency_code
          description: The currency that the creditor receives. Required for payment to wallet and payment to external.
        amount:
          allOf:
          - $ref: '#/components/schemas/Amount'
          title: target_amount
          description: Amount in target currency. Required for payment to wallet and payment to external.
        payment_details:
          type: string
          title: payment_details
          description: Reference information.
          minLength: 1
          maxLength: 140
          example: INV123
    Amount:
      type: number
      title: amount
      description: Amount in currency.
      minimum: 0.01
      maximum: 10000000000000
      example: 1000
    Completed-Time:
      type: string
      title: completed_on
      format: date-time
      description: The time the transaction was finished. Pattern YYYY-MM-DDTHH:mm:ssZ
      example: '2026-01-06T11:00:25Z'
    Reporting-Payment-Type:
      type: string
      title: payment_type
      description: Transaction type.
      enum:
      - INBOUND
      - PAYOUT
      - WITHDRAW
      example: INBOUND
    Merchant-Id:
      type: string
      description: Unique identifier generated by Citi for each seller. Seller to use this id for the further functional calls.
      title: merchant_id
      minLength: 1
      maxLength: 36
      example: ec689822-9864-4c4d-9d68-222467627901
    Balance-Transaction:
      title: Balance-Transaction
      type: object
      description: Transaction details for balance reporting including opening and closing balances.
      properties:
        virtual_account_id:
          $ref: '#/components/schemas/Virtual-Account-Id'
        uetr:
          $ref: '#/components/schemas/Uetr'
        end_to_end_id:
          $ref: '#/components/schemas/End-To-End-Id'
        opening_balance:
          allOf:
          - $ref: '#/components/schemas/Balance'
          title: opening_balance
          description: The balance before the transaction.
          example: 5000
        closing_balance:
          allOf:
          - $ref: '#/components/schemas/Balance'
          title: closing_balance
          description: The balance after the transaction.
          example: 4000
        payment_type:
          $ref: '#/components/schemas/Reporting-Payment-Type'
        created_time:
          allOf:
          - $ref: '#/components/schemas/Created-Time'
          title: created_on
          description: The creation time of the transaction.
        amount:
          allOf:
          - $ref: '#/components/schemas/Amount'
          title: amount
          description: The transaction amount.
        currency_code:
          allOf:
          - $ref: '#/components/schemas/Currency-Code'
          title: currency_code
        direction:
          type: string
          title: direction
          description: Whether the transaction is a debit or credit.
          example: debit
    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'
    Payment-Creditor:
      title: Creditor
      type: object
      description: Information pertaining to creditor of the payment.
      properties:
        id:
          type: string
          title: id
          minLength: 1
          maxLength: 64
          description: Required when paying into a bank account.             creditor_id is returned when you call Link Account endpoint. <br> Required for payment to external.
          example: R202501080950209789
        account:
          $ref: '#/components/schemas/Account'
    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
    Report-Transaction-Detail:
      title: ReportTransactionDetails
      type: object
      description: Transaction details for reporting.
      allOf:
      - $ref: '#/components/schemas/Common-Transaction'
      - $ref: '#/components/schemas/Multiple-Currency-Amount'
      - type: object
        properties:
          uetr:
            $ref: '#/components/schemas/Uetr'
          fx_rate:
            $ref: '#/components/schemas/Fx-Rate'
          payment_type:
            $ref: '#/components/schemas/Reporting-Payment-Type'
          created_time:
            $ref: '#/components/schemas/Created-Time'
          completed_time:
            $ref: '#/components/schemas/Completed-Time'
    Name:
      type: string
      title: name
      minLength: 1
      maxLength: 128
      example: SHASHANK VIJAYSHANKAR TIWARI
    Message:
      type: string
      description: Description of the status.
      title: message
      minLength: 1
      maxLength: 500
      example: Request is in-progress
    Account:
      title: Account
      type: object
      description: Account details.
      properties:
        number:
          type: string
          title: number
          description: Account number.
          example: '456456547'
        branch_code:
          type: string
          title: branch_code
          description: Branch code which holds the account number.
          example: VA202501080950209789
        virtual_account_id:
          allOf:
          - $ref: '#/components/schemas/Virtual-Account-Id'
          description: virtual_account_id received when you call wallet activation endpoint. <br> Required at creditor side when paying to wallet. <br> Required at debtor side for payment to external.
    Virtual-Account-Id:
      type: string
      title: Virtual-Account-Id
      description: Account ID for a specific virtual account.
      minLength: 1
      maxLength: 36
      example: R200801012359590001
    Balance-Report-Response:
      title: BalanceReportResponse
      type: array
      items:
        $ref: '#/components/schemas/Balance-Transaction'
    Currency-Code:
      type: string
      title: currency_code
      description: The currency code in the transaction.
      pattern: ^[A-Z]{3}$
      example: USD
    Report-Transaction:
      title: ReportTransaction
      description: Transaction details for reporting.
      allOf:
      - $ref: '#/components/schemas/Common-Error-Response'
      - type: object
        properties:
          debtor:
            $ref: '#/components/schemas/Reporting-Debtor'
          creditor:
            $ref: '#/components/schemas/Reporting-Creditor'
          transaction:
            $ref: '#/components/schemas/Report-Transaction-Detail'
    Country-Code:
      type: string
      title: country_code
      pattern: ^[A-Z]{2,2}$
      description: Country code.
      example: CN
    Transaction-Report-Response:
      type: array
      title: TransactionReportResponse
      items:
        $ref: '#/components/schemas/Report-Transaction'
    Pagination-Metadata:
      description: '<br> current_page: Current page number<br> total_pages: Total number of pages available for this request<br> page_size: The number of records to display per page<br> has_more: Any more messages or records expected'
      type: object
      title: Pagination Metadata
      properties:
        current_page:
          description: Current page number
          type: integer
          minimum: 1
          maximum: 1000
          example: 1
          title: current_page
        total_pages:
          description: Total number of pages available for this request
          type: integer
          minimum: 1
          maximum: 1000
          example: 1
          title: total_pages
        page_size:
          description: Number of records to display per page
          type: integer
          minimum: 1
          maximum: 10000
          example: 1
          title: page_size
        has_more:
          description: Any more messages or records expected
          type: boolean
          example: true
          title: has_more
      example:
        current_page: 1
        total_pages: 10
        page_size: 100
        has_more: true
    Reporting-Debtor:
      title: ReportingDebtor
      description: Debtor details for reporting.
      allOf:
      - $ref: '#/components/schemas/Payment-Debtor'
      - type: object
        properties:
          name:
            allOf:
            - $ref: '#/components/schemas/Name'
            - description: Name of the debtor.
    Reporting-Creditor:
      title: ReportingCreditor
      description: Crediotr details for reporting.
      allOf:
      - $ref: '#/components/schemas/Payment-Creditor'
      - type: object
        properties:
          name:
            allOf:
            - $ref: '#/components/schemas/Name'
            - description: Name of the creditor.
    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.
    Status:
      type: string
      description: Status of the request.
      title: status
      minLength: 1
      maxLength: 64
    Balance:
      type: number
      title: opening_balance
      description: Balance.
    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
    Payment-Debtor:
      title: Debtor
      type: object
      description: Information pertaining to debtor of the payment.
      properties:
        account:
          $ref: '#/components/schemas/Account'
        country_code:
          allOf:
          - $ref: '#/components/schemas/Country-Code'
          title: country_code
          description: Country code where the fund is credited.
    Common-Error-Response:
      title: CommonErrorResponse
      description: Details of error in the request.
      type: object
      properties:
        merchant_id:
          $ref: '#/components/schemas/Merchant-Id'
        status:
          allOf:
          - $ref: '#/components/schemas/Status'
          description: Status description. <br> Certification Webhook - Allowed values are APPROVED, DECLINED, RFI_PENDING. <br> Wallet Activation Webhook - Allowed values are AVAILABLE - account is available to be used; DECLINED - account application rejected; SUSPENDED - account is frozen; CLOSED - account is no longer available. <br> Link Account Webhook - Allowed values are AVAILABLE and DECLINED <br> Payment Webhook - Allowed values are SUCCESS, REJECTED. <br> Inbound Webhook - Allowed values is SUCCESS. <br> Transaction Reporting - PENDING, SUCCESS, REJECTED.
        message:
          $ref: '#/components/schemas/Message'
    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
    End-To-End-Id:
      type: string
      title: end_to_end_id
      description: The unique payment request ID from your system. If the request is for payment to wallet, this field should contain maximum 16 character and should be in UPPER CASE.
      minLength: 1
      maxLength: 35
      example: SM37864746
    Uetr:
      type: string
      title: uetr
      description: This is a unique payment service provider ID assigned to all individual transactions.
      minLength: 1
      maxLength: 36
      example: '202501092053115499258'
  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'
    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'
    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:
    Uetr:
      name: uetr
      required: false
      in: query
      description: The unique payment identifier assigned during payment initiation.
      schema:
        type: string
        title: uetr
        minLength: 1
        maxLength: 36
    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
    Payment-Type:
      name: payment_type
      in: query
      required: false
      description: 'Transaction type filter. Supported values: INBOUND, PAYOUT.'
      schema:
        type: array
        title: payment_type
        items:
          type: string
          enum:
          - INBOUND
          - PAYOUT
          - WITHDRAW
    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
    Page-No:
      name: page_no
      in: query
      required: false
      description: Page number (default- 1).
      schema:
        type: integer
        title: page_no
        minimum: 1
        maximum: 5000
        default: 1
    Reporting-Status:
      name: status
      in: query
      required: false
      description: 'Transaction status filter. Supported values: PENDING, SUCCESS, REJECTED.'
      schema:
        type: array
        title: status
        items:
          type: string
          enum:
          - PENDING
          - SUCCESS
          - REJECTED
    Currency-Code:
      name: currency_code
      in: query
      required: false
      description: Query the balance for a specific currency code.
      schema:
        type: string
        title: currency_code
        pattern: ^[A-Z]{3}$
      example: USD
    Virtual-Account-Id:
      name: virtual_account_id
      in: query
      description: The unique ID returned when you call wallet activation.
      schema:
        type: string
        title: virtual_account_id
        minLength: 1
        maxLength: 36
        example: R200801012359590001
    To-Date-Time:
      name: to_date_time
      in: query
      required: false
      description: 'The end date for the requested period. Pattern: YYYY-MM-DDTHH:mm:ssZ'
      schema:
        type: string
        title: to_date_time
        format: date-time
        example: '2024-03-17T10:30:00Z'
    From-Date-Time:
      name: from_date_time
      in: query
      required: false
      description: 'The start date for the requested period. Pattern: YYYY-MM-DDTHH:mm:ssZ. When from_date_time is used to_date_time is required and the supported range should be 1 year. '
      schema:
        type: string
        title: from_date_time
        format: date-time
        example: '2024-03-17T10:30:00Z'
    Limit:
      name: limit
      in: query
      required: false
      description: Number of results per page (default- 50).
      schema:
        type: integer
        title: limit
        minimum: 1
        maximum: 100
        default: 50
    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