openapi: 3.2.0
info:
  title: Gateway Services File 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: File
  description: File management
paths:
  /merchants/v1/documents/upload:
    post:
      tags:
      - File
      summary: Documents upload for verification
      description: This endpoint is where you securely upload files to send to payment service provider, including KYC and KYB documentation to support customer verification.
      operationId: fileUpload
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Idempotency-Id'
      - $ref: '#/components/parameters/Merchant-Id'
      - $ref: '#/components/parameters/Country-Code'
      requestBody:
        required: true
        description: Multipart file upload allows client to send files (e.g., images, documents) as part of a request. The request content type must be multipart/form-data. Supported formats are image/png, image/jpeg, image/jpg, image/bmp, application/pdf. Supported file size <10000000 bytes. Client should pass single file per request
        content:
          multipart/form-data:
            schema:
              title: Upload-Document-Request
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                  maxLength: 10000000
              additionalProperties: false
            encoding:
              file:
                contentType: image/png, image/jpeg, image/jpg, image/bmp, application/pdf.
                headers:
                  Content-Length:
                    schema:
                      type: integer
                      maximum: 10000000
      responses:
        '200':
          description: Merchant ID creation Response
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File-Upload-Response'
              examples:
                File-Upload-Positive-Response:
                  $ref: '#/components/examples/File-Upload-Positive-Response-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'
      deprecated: false
      security:
      - oAuth2:
        - /authenticationservices/v1
  /merchants/v1/documents/download:
    post:
      summary: File Download
      description: Retrieve secure download links for previously uploaded merchant files by providing one or more file identifiers, allowing clients to fetch supported documents in a controlled and traceable manner.
      operationId: downloadFile
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - File
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Country-Code'
      - $ref: '#/components/parameters/Merchant-Id'
      requestBody:
        content:
          application/json:
            schema:
              title: Download-Document-Request
              type: object
              properties:
                file_ids:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: string
                    maxLength: 128
                  description: File ID returned by PingPong at upload. List file ids to get download links for multiple files in one call.
              required:
              - file_ids
            example:
              file_ids:
              - N1234567891011121314151620
              - N1234567891011121314151621
              - N1234567891011121314151622
      responses:
        '200':
          description: File downloaded successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File-Download-Response'
              examples:
                File-Download-Response-Example:
                  $ref: '#/components/examples/File-Download-Response-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'
        '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'
      deprecated: false
      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
    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
    File-Download-Response-Example:
      value:
      - file_id: '112213'
        file_download_link: https://pingpongx.com/
    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
    File-Upload-Positive-Response-Example:
      value:
        file_id: '112213'
        created_time: '2026-01-06T10:56:25Z'
        status_details:
          status: SUCCESS
          message: File upload is success
    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
    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.
    Too-Many-Requests-Gateway-Example:
      value:
        httpCode: '429'
        httpMessage: Too Many Requests
        moreInformation: Rate Limit exceeded
  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
  schemas:
    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'
    File-Download-Response:
      title: FileDownloadResponse
      type: array
      description: Response for file download.
      items:
        $ref: '#/components/schemas/File-Download'
    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
    Message:
      type: string
      description: Description of the status.
      title: message
      minLength: 1
      maxLength: 500
      example: Request is in-progress
    File-Id:
      type: string
      description: Unique identifier for the document uploaded.
      title: file_id
      minLength: 1
      maxLength: 128
      example: '112213'
    File-Download:
      title: FileDownload
      type: object
      description: File download details.
      properties:
        file_id:
          $ref: '#/components/schemas/File-Id'
        file_download_link:
          type: string
          title: file_download_link
          description: File link for downloading the file. The link is valid for 15 minutes and can be used only once.
          minLength: 1
          maxLength: 256
          example: https://pingpongx.com/
    Status-Details:
      title: StatusDetails
      description: Status Details.
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        message:
          $ref: '#/components/schemas/Message'
    File-Upload-Response:
      title: FileUploadResponse
      description: Response parameters for file upload.
      type: object
      properties:
        file_id:
          $ref: '#/components/schemas/File-Id'
        created_time:
          $ref: '#/components/schemas/Created-Time'
        status_details:
          $ref: '#/components/schemas/Status-Details'
    Status:
      type: string
      description: Status of the request.
      title: status
      minLength: 1
      maxLength: 64
    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
  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