openapi: 3.2.0
info:
  title: Gateway Services Certification 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: Certification
  description: KYC certification submission and retrieval
paths:
  /merchants/v1/certification:
    post:
      summary: Submit Certification
      description: This endpoint allows you to submit certification information to verify a merchant or update existing KYC details, and trigger review workflows required for compliance and account readiness.
      operationId: submitCertification
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - Certification
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Idempotency-Id'
      - $ref: '#/components/parameters/Country-Code'
      - $ref: '#/components/parameters/Merchant-Id'
      - $ref: '#/components/parameters/Operation'
      requestBody:
        required: true
        description: Request body for the certification request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certification-Request'
            examples:
              Certification-Request:
                $ref: '#/components/examples/Certification-Request'
              Certification-Request-CN:
                $ref: '#/components/examples/Certification-Request-Cn'
              Certification-Request-HK:
                $ref: '#/components/examples/Certification-Request-Hk'
      responses:
        '200':
          description: Certification request accepted for processing.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sync-Response'
              examples:
                Certification-Save-Acknowledgement:
                  $ref: '#/components/examples/Certification-Save-Acknowledgement'
                Certification-Submit-Acknowledgement:
                  $ref: '#/components/examples/Certification-Submit-Acknowledgement'
        '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
      callbacks:
        certification-webhook:
          '{$notificationURL}':
            post:
              summary: Certification Webhook
              description: Webhook notification for certification status updates. Pushes updates of the KYC certification request.
              operationId: certificationWebhook
              parameters:
              - $ref: '#/components/parameters/Event-Type'
              - $ref: '#/components/parameters/Event-Name'
              - $ref: '#/components/parameters/Apim-Guid'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Webhook-Certification'
                    examples:
                      Certification-Approved-Webhook-Example:
                        $ref: '#/components/examples/Certification-Approved-Webhook-Example'
                      Certification-Declined-Webhook-Example:
                        $ref: '#/components/examples/Certification-Declined-Webhook-Example'
                      Certification-Rfi-Pending-Webhook-Example:
                        $ref: '#/components/examples/Certification-Rfi-Pending-Webhook-Example'
              responses:
                '200':
                  description: Webhook received successfully.
        rfi:
          '{$notificationURL}':
            post:
              operationId: rfiNotification
              summary: Request for Information (RFI) Notification Webhook
              description: This webhook pushes notifications of Request for Information.
              tags:
              - RFI Webhook
              parameters:
              - $ref: '#/components/parameters/Event-Type'
              - $ref: '#/components/parameters/Event-Name'
              - $ref: '#/components/parameters/Apim-Guid'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/RFI-Notification'
                    examples:
                      rfi-notification-example:
                        $ref: '#/components/examples/RFI-Notification-Example'
              responses:
                '200':
                  description: Webhook received successfully.
    get:
      summary: Get Certification
      description: Check the status of a merchant's KYC review using the merchant_id returned during onboarding, including progress indicators, review outcomes, and required follow-up actions when applicable.
      operationId: getCertification
      servers:
      - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
      - Certification
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Country-Code'
      - $ref: '#/components/parameters/Merchant-Id'
      responses:
        '200':
          description: Certification details retrieved successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-Certification-Response'
              examples:
                Get-Certification:
                  $ref: '#/components/examples/Get-Certification'
        '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:
  schemas:
    RFI-Question:
      title: RFI-Question
      description: An individual RFI question with its associated information requests and certification source.
      allOf:
      - $ref: '#/components/schemas/Common-Question'
      - type: object
        properties:
          information_request:
            type: array
            title: information_request
            description: The information need to be responded.
            items:
              $ref: '#/components/schemas/Information-Request-Webhook'
    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
    Name:
      type: string
      title: name
      minLength: 1
      maxLength: 128
      example: SHASHANK VIJAYSHANKAR TIWARI
    RFI-Notification:
      type: object
      title: RFI-Notification
      description: Request for Information (RFI) notification.
      allOf:
      - $ref: '#/components/schemas/Common-Rfi'
      - type: object
        required:
        - merchant_id
        properties:
          merchant_id:
            $ref: '#/components/schemas/Merchant-Id'
          questions:
            type: array
            title: questions
            description: An array of RFI questions
            items:
              $ref: '#/components/schemas/RFI-Question'
    Business:
      title: Business
      type: object
      description: Detailed information of the business for certification.
      required:
      - name
      properties:
        name:
          allOf:
          - $ref: '#/components/schemas/Name'
          - description: The full legal name of the business in English. Required for CN and HK.
            example: payment service provider
        name_in_local_language:
          type: string
          title: name_in_local_language
          minLength: 1
          maxLength: 128
          description: The full legal name of the business in the local language. Required for CN and HK.
          example: payment service provider
        establishment_date:
          allOf:
          - $ref: '#/components/schemas/Common-Date'
          title: establishment_date
          description: Company establishment date. Required for CN and HK.
        license_expiry_date:
          allOf:
          - $ref: '#/components/schemas/Common-Date'
          title: license_expiry_date
          description: Expiry date of company license; format yyyy-mm-dd. Fill in 9999-12-31 for a long-term license. Required for CN. For HK, this is expiry date of business registration.
        address:
          $ref: '#/components/schemas/Business-Address'
        products_and_services_category:
          type: string
          title: products_and_services_category
          description: Products and services category. Required for CN and HK.
          example: KC02001008
          minLength: 1
          maxLength: 20
        tax_id_type:
          type: string
          title: tax_id_type
          description: Tax id type.
          enum:
          - EIN
          - SSN
          - VAT
          - TIN
          - UTR
          example: VAT
        tax_id_number:
          type: string
          title: tax_id_number
          minLength: 1
          maxLength: 128
          description: Tax id number.
          example: tax_id_number1111
        account_usage:
          type: array
          title: account_usage
          description: List of account usage. Required for CN and HK.
          items:
            $ref: '#/components/schemas/Account-Usage'
          minItems: 1
          maxItems: 25
        description:
          type: string
          title: description
          minLength: 1
          maxLength: 2048
          description: Description of the business. This is one of the three ways of proving the business.
          example: Selling products or purchasing raw materials on online platforms
        website:
          type: string
          title: website
          minLength: 1
          maxLength: 2048
          description: Website URL. This is one of the three ways of proving the business.
          example: http://www.company.cn
        business_proof_file_id:
          allOf:
          - $ref: '#/components/schemas/File-Id'
          title: business_proof_file_id
          description: File ID for a screenshot of the business website/dashboards.
          example: N1234567891011121314151622
        documents:
          type: array
          title: documents
          description: List of documents.
          items:
            $ref: '#/components/schemas/Document'
        business_persons:
          type: array
          title: business_persons
          description: List of business person.
          items:
            $ref: '#/components/schemas/Business-Person'
    Common-Rfi:
      title: Common-Rfi
      type: object
      description: Response containing RFI list and details.
      properties:
        rfi_id:
          $ref: '#/components/schemas/Rfi-Id'
        type:
          type: string
          title: type
          minLength: 1
          maxLength: 64
          description: RFI type. Currently supports KYC, RECIPIENT.
        status:
          allOf:
          - $ref: '#/components/schemas/Status'
          title: status
          description: 'RFI status. Possible values: OPEN, CLOSED.'
        created_time:
          allOf:
          - $ref: '#/components/schemas/Created-Time'
          description: RFI Creation date time in ISO 8601 format.
          title: created_time
        expiry_time:
          allOf:
          - $ref: '#/components/schemas/Created-Time'
          description: RFI expiration time in ISO 8601 format.
          title: expiry_time
        creditor_id:
          allOf:
          - $ref: '#/components/schemas/Creditor-Id'
          title: creditor_id
          description: Recipient id (use for RECIPIENT RFI type).
    Sync-Response:
      title: SyncResponse
      type: object
      description: Acknowledgement.
      properties:
        status_details:
          $ref: '#/components/schemas/Status-Details'
    Business-Address:
      title: BusinessAddress
      type: object
      description: Address information for company.
      properties:
        street_name:
          type: string
          title: street_name
          minLength: 1
          maxLength: 200
          description: Street name. Required for CHINA and HONGKONG.
          example: Schillerstrasse 23
        postal_code:
          type: string
          title: postal_code
          minLength: 1
          maxLength: 16
          description: Postal code or ZIP code. Required for CHINA and HONGKONG.
          example: '999077'
        city:
          type: string
          title: city
          minLength: 1
          maxLength: 200
          description: City name. Required for CHINA and HONGKONG.
          example: Ras Al Khaimah
        district:
          type: string
          title: district
          minLength: 1
          maxLength: 200
          description: District name. Required for CHINA and HONGKONG.
          example: district1111
        state:
          type: string
          title: state
          minLength: 1
          maxLength: 200
          description: State or province name. Required for CHINA and HONGKONG.
          example: Ras al Khaymah
    Document:
      title: Document
      type: object
      description: Document information for KYC validation including document type, sub-type, and file reference.
      required:
      - type
      properties:
        type:
          type: string
          title: type
          description: Type of identity document (ID). <br> certificate_of_registration is applicable for CHINA. <br> certificate_of_incorporation and business_registration are applicable for HONGKONG.
          enum:
          - CERTIFICATE_OF_REGISTRATION
          - CERTIFICATE_OF_INCORPORATION
          - BUSINESS_REGISTRATION
          - SHARE_STRUCTURE
          - COMPANY_CONSTITUTION_OR_ANNUAL_REPORT
          - ARTICLE_OF_ASSOCIATION
          - UBO_DECLARATION
          - PARTNERSHIP_MINUTES_OF_MEETING
          - PARTNERSHIP_DEED
          - CERTIFICATE_OF_INCUMBENCY
          - INDONESIA_MINISTRY_OFFICIAL_APPROVAL_PROOF
          - OFFICE_PHOTO
          - PROOF_OF_ADDRESS
          - BANK_ACCOUNT_PROOF
          - BUSINESS_URL_OWNERSHIP
          example: CERTIFICATE_OF_REGISTRATION
        sub_type:
          type: string
          title: sub_type
          description: Applicable only if the type is certificate_of_registration.
          enum:
          - ACRA
          - GST
          - MSME
          - CERTIFICATE_OF_REGISTRATION
          example: ACRA
        number:
          type: string
          title: number
          minLength: 1
          maxLength: 128
          description: Document ID number. <br> required if type is certificate_of_registration for CHINA. <br> required if type are certificate_of_incorporation and business_registration for HONGKONG.
          example: DE123456789
        file_id:
          $ref: '#/components/schemas/File-Id'
    Account-Usage:
      type: string
      title: account_usage
      description: Description of merchant's business purpose of using PSP account. Required for CN and HK.
      example: ONLINE_MARKETPLACE_TRADING
    File-Id:
      type: string
      description: Unique identifier for the document uploaded.
      title: file_id
      minLength: 1
      maxLength: 128
      example: '112213'
    Common-Question:
      title: Common-Question
      type: object
      description: An individual RFI question.
      properties:
        question_id:
          type: string
          title: question_id
          minLength: 1
          maxLength: 64
          description: The unique id for specific question.
          example: Q123456789
        description_code:
          type: string
          title: description_code
          minLength: 1
          maxLength: 64
          description: The code for question's description.
        description_english:
          type: string
          title: description_english
          minLength: 1
          maxLength: 2048
          description: Question description in English.
        description_chinese:
          type: string
          title: description_chinese
          minLength: 1
          maxLength: 2048
          description: Question description in Chinese.
        certification_source:
          $ref: '#/components/schemas/Certification-Source'
    Information-Name:
      type: string
      title: information_name
      minLength: 1
      maxLength: 64
      description: Information name.
      example: id_doc_front
    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
    Merchant-Type:
      type: string
      title: merchant_type
      description: Type of merchant.
      enum:
      - INDIVIDUAL
      - ENTERPRISE
    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'
    Creditor-Id:
      type: string
      title: creditor_id
      description: The unique creditor identifier assigned by payment service provider.
      minLength: 1
      maxLength: 36
      example: R202501080950209789
    Rfi-Id:
      type: string
      title: rfi_id
      minLength: 1
      maxLength: 128
      description: RFI unique id.
    Personal-Details:
      title: Personal-Details
      type: object
      description: This section contains the name details.
      properties:
        first_name:
          type: string
          title: first_name
          minLength: 1
          maxLength: 64
          description: Business person's first name in English. Required for CN and HK.
          example: Hongbo
        first_name_in_local_language:
          type: string
          title: first_name_in_local_language
          minLength: 1
          maxLength: 64
          description: Business person's first name in local language. Required for CN and HK.
          example: first name
        middle_name:
          type: string
          title: middle_name
          minLength: 1
          maxLength: 64
          description: Business person's middle name in English. Optional for CN and HK.
          example: s
        middle_name_in_local_language:
          type: string
          title: middle_name_in_local_language
          minLength: 1
          maxLength: 64
          description: Business person's middle name in local language. Optional for CN and HK.
          example: middle name
        last_name:
          type: string
          title: last_name
          minLength: 1
          maxLength: 64
          description: Business person's last name in English. Required for CN and HK.
          example: Lin
        last_name_in_local_language:
          type: string
          title: last_name_in_local_language
          minLength: 1
          maxLength: 64
          description: Business person's full name in local language. Required for CN and HK.
          example: last name
    Message:
      type: string
      description: Description of the status.
      title: message
      minLength: 1
      maxLength: 500
      example: Request is in-progress
    Certification-Source:
      title: CertificationSource
      description: Information related to the KYC source.
      allOf:
      - $ref: '#/components/schemas/Personal-Details'
      - type: object
        properties:
          role:
            type: string
            title: role
            description: Role of business person. Supported values are OWNER_OR_OPERATOR, PARTNER, UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON.
            example: AGENT_OR_AUTHORISED_PERSON
          merchant_type:
            $ref: '#/components/schemas/Merchant-Type'
    Status-Details:
      title: StatusDetails
      description: Status Details.
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        message:
          $ref: '#/components/schemas/Message'
    Person-Document:
      title: PersonDocument
      type: object
      description: Document information for business person KYC validation.
      required:
      - type
      - sub_type
      properties:
        type:
          type: string
          title: type
          description: Type of identity document (ID). Provide details for one primary identity document (CHINESE_RESIDENT_IDENTITY_CARD, NATIONAL_OR_STATE_ID, PASSPORT, DRIVERS_LICENSE, RESIDENCE_PERMIT, TAX_ID, PROOF_OF_AGE_CARD, MY_NUMBER_CARD, MAINLAND_TRAVEL_PERMIT), optionally supplemented by AUTHORISED_LETTER, PROOF_OF_ADDRESS, or HAND_HOLD_PHOTO if required. <br> AUTHORISED_LETTER is required if the role is AUTHORISED_PERSON <br> NATIONAL_OR_STATE_ID, PASSPORT, RESIDENCE_PERMIT, MAINLAND_TRAVEL_PERMIT are applicable for CHINA. <br> NATIONAL_OR_STATE_ID, PASSPORT, RESIDENCE_PERMIT, CHINESE_RESIDENT_IDENTITY_CARD, MAINLAND_TRAVEL_PERMIT are applicable for HONGHONG.
          enum:
          - CHINESE_RESIDENT_IDENTITY_CARD
          - NATIONAL_OR_STATE_ID
          - PASSPORT
          - DRIVERS_LICENSE
          - RESIDENCE_PERMIT
          - TAX_ID
          - PROOF_OF_AGE_CARD
          - MY_NUMBER_CARD
          - MAINLAND_TRAVEL_PERMIT
          - AUTHORISED_LETTER
          - PROOF_OF_ADDRESS
          - HAND_HOLD_PHOTO
          example: NATIONAL_OR_STATE_ID
        sub_type:
          type: string
          title: sub_type
          description: Applicable for all id type other than PASSPORT. Front and Back both sub_type is applicable for CN and HK. When BACK is used, number, expiry_date, issue_date, issuing_authority are not required.
          enum:
          - FRONT
          - BACK
          example: FRONT
        number:
          type: string
          title: number
          minLength: 1
          maxLength: 128
          description: Document ID number. Required for CHINA and HONGKONG.
          example: ID123456789
        expiry_date:
          allOf:
          - $ref: '#/components/schemas/Common-Date'
          title: expiry_date
          description: The expiry date of the ID document; format yyyy-mm-dd. Fill in 9999-12-31 if there is no expiry date. Required for CHINA and HONGKONG.
        issue_date:
          allOf:
          - $ref: '#/components/schemas/Common-Date'
          title: issue_date
          description: Issuing date of the ID document; format yyyy-mm-dd. Required for CHINA and HONGKONG.
        issuing_authority:
          type: string
          title: issuing_authority
          minLength: 1
          maxLength: 2048
          description: Issuing authority of merchant's identity document. Required for CHINA and HONGKONG.
          example: Government of China
        file_id:
          $ref: '#/components/schemas/File-Id'
    Business-Person-Address:
      title: BusinessPersonAddress
      description: Business person address information.
      allOf:
      - $ref: '#/components/schemas/Business-Address'
      - type: object
        title: Business-Person-Address
        properties:
          country_code:
            allOf:
            - $ref: '#/components/schemas/Country-Code'
            title: country_code
            description: Country code. Required for CHINA and HONGKONG.
    Information-Type:
      type: string
      title: information_type
      minLength: 1
      maxLength: 32
      description: 'Information type: text or file.'
    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'
    Certification-Common-Details:
      title: CertificationCommonDetails
      type: object
      description: Certification details.
      properties:
        country_code:
          allOf:
          - $ref: '#/components/schemas/Country-Code'
          title: country_code
          description: Country code.
        merchant_ack:
          type: string
          title: merchant_ack
          description: Has the merchant signed the payment service provider service terms? YES or NO.
          enum:
          - 'YES'
          - 'NO'
          example: 'YES'
        business:
          $ref: '#/components/schemas/Business'
    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'
    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
    Get-Certification-Response:
      title: GetCertificationResponse
      description: Response body for retrieving certification details including KYC status and business information.
      allOf:
      - $ref: '#/components/schemas/Certification-Common-Details'
      - type: object
        title: Get-Certification-Response
        properties:
          status:
            allOf:
            - $ref: '#/components/schemas/Status'
            title: status
            description: The status of the certification. Allowed values PENDING_SAVED, PENDING_SUBMITTED, APPROVED, DECLINED, RFI_PENDING.
          message:
            type: string
            title: message
            minLength: 1
            maxLength: 500
            description: Description of certification status.
            example: KYC approved
          merchant_type:
            $ref: '#/components/schemas/Merchant-Type'
          product_code:
            type: string
            title: product_code
            description: Product code. Currently supports PAYMENT_CORE and ACQ_ONLINE.
            minLength: 1
            maxLength: 15
            example: PAYMENT_CORE
    Webhook-Certification:
      title: WebhookCertification
      description: Notification for certification status updates.
      allOf:
      - $ref: '#/components/schemas/Common-Error-Response'
      - type: object
        properties:
          business_name:
            type: string
            title: business_name
            minLength: 1
            maxLength: 256
            description: Business name in English.
            example: business name
          business_name_in_local_language:
            type: string
            title: business_name_in_local_language
            minLength: 1
            maxLength: 64
            description: Business name in local language.
            example: business name in local
    Country-Code:
      type: string
      title: country_code
      pattern: ^[A-Z]{2,2}$
      description: Country code.
      example: CN
    Business-Person:
      title: BusinessPerson
      description: Business person details for KYC certification.
      allOf:
      - $ref: '#/components/schemas/Personal-Details'
      - type: object
        properties:
          role:
            type: string
            title: role
            description: Role of business person. Required for both CHINA and HONGKONG. <br> UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON are applicable for CHINA. <br> UBO, DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP, AGENT_OR_AUTHORISED_PERSON are applicable for HONGKONG. <br> For the limitation on the number of business persons- <br> UBO - 4 maximum across all regions (as UBO is defined as shareholding above 25%). <br> Legal rep/Director - 1 for CN (only one legal rep per CN law) and up to 25 directors for HK. <br> Agent - 1, as there can only be 1 agent.
            enum:
            - OWNER_OR_OPERATOR
            - PARTNER
            - UBO
            - DIRECTOR_CONTROL_PERSON_OR_LEGAL_REP
            - AGENT_OR_AUTHORISED_PERSON
            example: AGENT_OR_AUTHORISED_PERSON
          alias:
            type: string
            title: alias
            minLength: 1
            maxLength: 2048
            description: Business person's alias name.
            example: Hongbo
          nationality:
            type: string
            title: nationality
            description: Business person's nationality. Required for CHINA and HONGKONG.
            example: CN
            pattern: ^[A-Z]{2,2}$
          gender:
            type: string
            title: gender
            description: Business person's gender.
            enum:
            - MALE
            - FEMALE
            example: MALE
          birth_details:
            $ref: '#/components/schemas/Birth-Details'
          address:
            $ref: '#/components/schemas/Business-Person-Address'
          tax_id_number:
            type: string
            title: tax_id_number
            minLength: 1
            maxLength: 128
            description: Tax id number.
            example: tax123456
          business_title:
            type: string
            title: business_title
            minLength: 1
            maxLength: 2048
            description: Business title.
            example: Director
          documents:
            type: array
            description: List of documents
            title: documents
            items:
              $ref: '#/components/schemas/Person-Document'
    Certification-Request:
      title: CertificationRequest
      description: Request body for submitting certification information for KYC verification.
      allOf:
      - $ref: '#/components/schemas/Certification-Common-Details'
      - type: object
        title: Certification-Request
        required:
        - country_code
        - merchant_ack
        - business
    Birth-Details:
      title: BirthDetails
      type: object
      description: Birth information of the business person.
      properties:
        date:
          allOf:
          - $ref: '#/components/schemas/Common-Date'
          title: date
          description: ISO 8601 (YYYY-MM-DD), birth_date is required for CN and HK.
        country_code:
          allOf:
          - $ref: '#/components/schemas/Country-Code'
          title: country_code
          description: Country code.
        state:
          type: string
          title: state
          minLength: 1
          maxLength: 2048
          description: State (province of birth).
          example: beijing
    Information-Request-Webhook:
      type: object
      title: Information-Request-Webhook
      description: Information that needs to be responded to for the RFI question.
      properties:
        information_name:
          $ref: '#/components/schemas/Information-Name'
        information_type:
          $ref: '#/components/schemas/Information-Type'
    Status:
      type: string
      description: Status of the request.
      title: status
      minLength: 1
      maxLength: 64
  responses:
    Gateway-Timeout:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Gateway-Error-Response'
    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'
    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'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Service-Error-Response'
    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'
    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'
  examples:
    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
    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
    Unauthorized-Gateway-Error-Example:
      value:
        httpCode: '401'
        httpMessage: Unauthorized
        moreInformation: The server could not verify that you are authorized to access the URL
    Certification-Request-Cn:
      value:
        country_code: CN
        merchant_ack: 'YES'
        business:
          name: payment service provider
          name_in_local_language: payment service provider
          establishment_date: '1975-03-07'
          license_expiry_date: '1975-03-07'
          address:
            street_name: Schillerstrasse 23
            postal_code: '999077'
            city: Ras Al Khaimah
            district: district1111
            state: Ras al Khaymah
          products_and_services_category: KC02001008
          account_usage:
          - ONLINE_MARKETPLACE_TRADING
          documents:
          - type: CERTIFICATE_OF_REGISTRATION
            sub_type: CERTIFICATE_OF_REGISTRATION
            number: DE123456789
            file_id: N1234567891011121314151617
          business_persons:
          - role: AGENT_OR_AUTHORISED_PERSON
            first_name: Hongbo
            first_name_in_local_language: first name
            last_name: Lin
            last_name_in_local_language: last name
            nationality: CN
            birth_details:
              date: '1975-03-07'
            address:
              street_name: Schillerstrasse 23
              postal_code: '999077'
              city: Ras Al Khaimah
              district: district1111
              state: Ras al Khaymah
              country_code: CN
            documents:
            - type: NATIONAL_OR_STATE_ID
              sub_type: FRONT
              number: ID123456789
              expiry_date: '1975-03-07'
              issue_date: '1975-03-07'
              issuing_authority: Government of China
              file_id: N1234567891011121314151617
            - type: NATIONAL_OR_STATE_ID
              sub_type: BACK
              file_id: N1234567891011121314151617
    Un-Supported-Media-Type-Gateway-Error-Example:
      value:
        httpCode: '415'
        httpMessage: Unsupported Media Type
        moreInformation: Unsupported Content-Type application/octet-stream
    Too-Many-Requests-Gateway-Example:
      value:
        httpCode: '429'
        httpMessage: Too Many Requests
        moreInformation: Rate Limit exceeded
    Certification-Request-Hk:
      value:
        country_code: CN
        merchant_ack: 'YES'
        business:
          name: payment service provider
          name_in_local_language: payment service provider
          establishment_date: '1975-03-07'
          license_expiry_date: '1975-03-07'
          address:
            street_name: Schillerstrasse 23
            postal_code: '999077'
            city: Ras Al Khaimah
            district: district1111
            state: Ras al Khaymah
          products_and_services_category: KC02001008
          tax_id_type: VAT
          tax_id_number: tax_id_number1111
          account_usage:
          - ONLINE_MARKETPLACE_TRADING
          description: Selling products or purchasing raw materials on online platforms
          website: http://www.company.cn
          business_proof_file_id: N1234567891011121314151622
          documents:
          - type: CERTIFICATE_OF_REGISTRATION
            sub_type: ACRA
            number: DE123456789
            file_id: N1234567891011121314151617
          business_persons:
          - role: AGENT_OR_AUTHORISED_PERSON
            first_name: Hongbo
            first_name_in_local_language: first name
            middle_name: s
            middle_name_in_local_language: middle name
            last_name: Lin
            last_name_in_local_language: last name
            alias: Hongbo
            nationality: CN
            gender: MALE
            birth_details:
              date: '1975-03-07'
              country_code: CN
              state: beijing
            address:
              street_name: Schillerstrasse 23
              postal_code: '999077'
              city: Ras Al Khaimah
              district: district1111
              state: Ras al Khaymah
              country_code: CN
            tax_id_number: tax123456
            business_title: Director
            documents:
            - type: NATIONAL_OR_STATE_ID
              sub_type: FRONT
              number: ID123456789
              expiry_date: '1975-03-07'
              issue_date: '1975-03-07'
              issuing_authority: Government of China
              file_id: N1234567891011121314151617
    Not-Found-Gateway-Error-Example:
      value:
        httpCode: '404'
        httpMessage: Not Found
        moreInformation: No resources match requested URI
    Certification-Rfi-Pending-Webhook-Example:
      value:
        merchant_id: 27162edf-9429-453e-8289-ddbba0627327
        status: RFI_PENDING
        business_name: company.enterprise.name
        business_name_in_local_language: 北京科技有限责任公司
        message: Englishname is not standard-英文名不规范,fm_return_company_certificates_expiration-补充材料_证照过期_企业
    Bad-Request-Gateway-Error-Example:
      value:
        httpCode: '400'
        httpMessage: Bad Request
        moreInformation: please provide valid value for request
    Certification-Request:
      value:
        country_code: CN
        merchant_ack: 'YES'
        business:
          name: payment service provider
          name_in_local_language: payment service provider
          establishment_date: '1975-03-07'
          license_expiry_date: '1975-03-07'
          address:
            street_name: Schillerstrasse 23
            postal_code: '999077'
            city: Ras Al Khaimah
            district: district1111
            state: Ras al Khaymah
          products_and_services_category: KC02001008
          tax_id_type: VAT
          tax_id_number: tax_id_number1111
          account_usage:
          - ONLINE_MARKETPLACE_TRADING
          description: Selling products or purchasing raw materials on online platforms
          website: http://www.company.cn
          business_proof_file_id: N1234567891011121314151622
          documents:
          - type: CERTIFICATE_OF_REGISTRATION
            sub_type: ACRA
            number: DE123456789
            file_id: N1234567891011121314151617
          business_persons:
          - role: AGENT_OR_AUTHORISED_PERSON
            first_name: Hongbo
            first_name_in_local_language: first name
            middle_name: s
            middle_name_in_local_language: middle name
            last_name: Lin
            last_name_in_local_language: last name
            alias: Hongbo
            nationality: CN
            gender: MALE
            birth_details:
              date: '1975-03-07'
              country_code: CN
              state: beijing
            address:
              street_name: Schillerstrasse 23
              postal_code: '999077'
              city: Ras Al Khaimah
              district: district1111
              state: Ras al Khaymah
              country_code: CN
            tax_id_number: tax123456
            business_title: Director
            documents:
            - type: NATIONAL_OR_STATE_ID
              sub_type: FRONT
              number: ID123456789
              expiry_date: '1975-03-07'
              issue_date: '1975-03-07'
              issuing_authority: Government of China
              file_id: N1234567891011121314151617
    Certification-Declined-Webhook-Example:
      value:
        merchant_id: 99f7f4b6-490c-468b-bd1b-f29310f9ebdd
        status: DECLINED
        business_name: company.enterprise.name
        business_name_in_local_language: 北京科技有限责任公司
        message: reject_all
    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.
    Service-Unavailable-Gateway-Example:
      value:
        httpCode: '503'
        httpMessage: Service is temporarily unavailable
        moreInformation: Retry the request after some time
    Method-Not-Allowed-Gateway-Error-Example:
      value:
        httpCode: '405'
        httpMessage: Method Not Allowed
        moreInformation: The method is not allowed for the requested URL
    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
    RFI-Notification-Example:
      summary: Example RFI notification payload
      value:
        merchant_id: ClientCustomerID1234
        rfi_id: RFI123
        type: KYC
        status: OPEN
        created_time: '2025-01-08T09:50:20Z'
        expiry_time: '2025-02-08T09:50:20Z'
        creditor_id: CR21245734
        questions:
        - question_id: Q123654
          description_code: KYCDR02001
          description_english: '[Business person name] - Please upload a photo of an original ID. (not a copy or screenshot)'
          description_chinese: '[姓名] - 提供的证件照片非证件原件照片，请提供证件原件照片。'
          information_request:
          - information_name: ID Photo
            information_type: TEXT
          certification_source:
            merchant_type: ENTERPRISE
            role: UBO
            first_name: Hongbo
            middle_name: Su
            last_name: Lin
            first_name_in_local_language: first name
            middle_name_in_local_language: middle name
            last_name_in_local_language: last name
    Certification-Approved-Webhook-Example:
      value:
        merchant_id: ec689822-9864-4c4d-9d68-222467627901
        status: APPROVED
        message: KYC request is approved
        business_name: business name
        business_name_in_local_language: business name in local
    Get-Certification:
      value:
        country_code: CN
        merchant_ack: 'YES'
        business:
          name: payment service provider
          name_in_local_language: payment service provider
          establishment_date: '1975-03-07'
          license_expiry_date: '1975-03-07'
          address:
            street_name: Schillerstrasse 23
            postal_code: '999077'
            city: Ras Al Khaimah
            district: district1111
            state: Ras al Khaymah
          products_and_services_category: KC02001008
          tax_id_type: VAT
          tax_id_number: tax_id_number1111
          account_usage:
          - ONLINE_MARKETPLACE_TRADING
          description: Selling products or purchasing raw materials on online platforms
          website: http://www.company.cn
          business_proof_file_id: N1234567891011121314151622
          documents:
          - type: CERTIFICATE_OF_REGISTRATION
            sub_type: ACRA
            number: DE123456789
            file_id: N1234567891011121314151617
          business_persons:
          - role: AGENT_OR_AUTHORISED_PERSON
            first_name: Hongbo
            first_name_in_local_language: first name
            middle_name: s
            middle_name_in_local_language: middle name
            last_name: Lin
            last_name_in_local_language: last name
            alias: Hongbo
            nationality: CN
            gender: MALE
            birth_details:
              date: '1975-03-07'
              country_code: CN
              state: beijing
            address:
              street_name: Schillerstrasse 23
              postal_code: '999077'
              city: Ras Al Khaimah
              district: district1111
              state: Ras al Khaymah
              country_code: CN
            tax_id_number: tax123456
            business_title: Director
            documents:
            - type: NATIONAL_OR_STATE_ID
              sub_type: FRONT
              number: ID123456789
              expiry_date: '1975-03-07'
              issue_date: '1975-03-07'
              issuing_authority: Government of China
              file_id: N1234567891011121314151617
        certification_status: APPROVED
        message: KYC approved
        merchant_type: ENTERPRISE
        product_code: PAYMENT_CORE
    Certification-Save-Acknowledgement:
      value:
        status_details:
          status: PENDING_SAVED
          message: Request is accepted and the further processing is in-progress
    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
    Certification-Submit-Acknowledgement:
      value:
        status_details:
          status: PENDING_SUBMITTED
          message: Request is accepted and the further processing is in-progress
  parameters:
    Operation:
      name: Operation
      in: header
      required: true
      description: Operation to indicate which functionality to be invoked.
      schema:
        type: string
        title: Operation
        enum:
        - SAVE
        - SUBMIT
      example: SAVE
    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
    Event-Type:
      name: Event-Type
      in: header
      required: true
      description: Type of event (e.g., CERTIFICATION, WALLET_ACTIVATION, LINK_ACCOUNT, PAYMENT, INBOUND, RFI).
      schema:
        type: string
        title: event-type
        minLength: 1
        maxLength: 64
        example: Webhook
    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
    Apim-Guid:
      in: header
      name: 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
    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
    Event-Name:
      name: Event-Name
      in: header
      description: Name of event (e.g., PAYOUT, PAYIN).
      schema:
        type: string
        title: event-name
        minLength: 1
        maxLength: 64
        example: Payout
    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
  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
  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