Citi

Citi Gateway Services API

Marketplace and gateway management for CitiConnect: onboarding, entitlement and configuration operations used to administer a client's API estate. Citi publishes 1 machine-readable specification for this family covering 19 operations, served from developer.citi.com.

GitHub OpenAPI

Operations 19

POST /merchants/v1/onboard Create merchant #
GET /merchants/v1/onboard Get Merchant ID #
POST /merchants/v1/documents/upload Documents upload for verification #
POST /merchants/v1/documents/download File Download #
POST /merchants/v1/certification Submit Certification #
GET /merchants/v1/certification Get Certification #
POST /merchants/v1/wallets/activation Activate wallet for virtual accounts #
GET /merchants/v1/wallets/balances Get wallet balances #
GET /merchants/v1/wallets Get wallet status #
POST /merchants/v1/link-accounts Link external account for payments #
GET /merchants/v1/link-accounts Get linked account details #
POST /merchants/v1/fx-rate FX Query #
POST /merchants/v1/payments Create Payment #
GET /merchants/v1/payments Get Payment #
POST /merchants/v1/rfi RFI Response #
GET /merchants/v1/rfi RFI Query #
POST /merchants/v1/rfi/submit RFI Submit #
GET /merchants/v1/transactions Transaction Reporting #
GET /merchants/v1/balance-report Balance Report #

Documentation

📖
Documentation
https://developer.citi.com/apidocs/gateway-services/gateway-services-user-guide
📖
APIReference
https://developer.citi.com/apidocs/gateway-services/gateway-services-api-reference
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/authentication/citi-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/openapi/citi-marketplace-management-openapi.yaml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/overlays/citi-gateway-services-overlay.yaml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/conventions/citi-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/errors/citi-problem-types.yml
🔗
Sandbox
https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/sandbox/citi-sandbox.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/citi-gateway-services-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

citi-marketplace-management-openapi.yaml Raw ↑ 
openapi: 3.0.2
info:
  title: Gateway Services
  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
tags:
  - name: MerchantCreation
    description: Merchant onboarding and management operations
  - name: File
    description: File management
  - name: Certification
    description: KYC certification submission and retrieval
  - name: Rfi
    description: Request for Information operations
  - name: Wallet
    description: Wallet management and balance operations
  - name: LinkAccount
    description: Account linkage operations for external payments
  - name: Payment
    description: Payout and payment query operations
  - name: Fx
    description: FX Rate Inquiry
  - name: Reporting
    description: Transaction and balance reporting operations
security:
  - oAuth2:
      - /authenticationservices/v1
paths:
  /merchants/v1/onboard:
    post:
      tags:
        - MerchantCreation
      summary: Create merchant
      description: >-
        This endpoint allows you to create or onboard a merchant on the Payment
        Service Provider platform, validate onboarding data, and receive a
        merchant identifier for downstream service requests.
      operationId: merchantCreation
      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/Country-Code'
      requestBody:
        required: true
        description: >-
          This request body contains the necessary merchant details for creating
          a new merchant entity in PSP.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Merchant-Onboarding-Request'
            examples:
              Merchant-Creation-For-Enterprise-Request:
                $ref: >-
                  #/components/examples/Merchant-Creation-For-Enterprise-Request-Example
      responses:
        '200':
          description: >-
            This response body will return the unique identifier for the newly
            created merchant along with status.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant-Onboarding-Response'
              examples:
                merchant_creation_success_response:
                  $ref: >-
                    #/components/examples/Merchant-Creation-Success-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'
      security:
        - oAuth2:
            - /authenticationservices/v1
    get:
      summary: Get Merchant ID
      description: >-
        Use the partner user ID on your platform to look up the merchant ID on
        the payment service provider platform (the merchant_id returned when you
        create a merchant).
      operationId: getMerchantId
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - MerchantCreation
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Country-Code'
        - $ref: '#/components/parameters/Partner-User-Id'
      responses:
        '200':
          description: Merchant ID retrieved successfully.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-Merchant-Onboarding'
        '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/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
  /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
  /merchants/v1/wallets/activation:
    post:
      summary: Activate wallet for virtual accounts
      description: >-
        Use this endpoint to apply for Virtual Accounts (VAs) to start
        sending/receiving funds. You can only apply for VAs when the kyc_status
        of your account is APPROVED.
      operationId: activateWallet
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - Wallet
      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: >-
          This section holds the request parameters for virtual account
          activation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Wallet-Activation-Request'
            examples:
              wallet-activation-request:
                $ref: '#/components/examples/Wallet-Activation-Request-Example'
      responses:
        '200':
          description: >-
            This section holds the successful response for virtual account
            activation.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sync-Response'
              examples:
                wallet-activation-response:
                  $ref: '#/components/examples/Wallet-Activation-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'
      security:
        - oAuth2:
            - /authenticationservices/v1
      callbacks:
        walletActivationWebhook:
          '{$notificationURL}':
            post:
              summary: Wallet activation webhook notification
              description: >-
                Webhook notification sent when a wallet activation status
                changes.
              operationId: walletActivationWebhookNotification
              tags:
                - Wallet
              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-Wallet-Activation'
                    examples:
                      Wallet-Activation-Available-Webhook-Example:
                        $ref: >-
                          #/components/examples/Wallet-Activation-Available-Webhook-Example
                      Wallet-Activation-Closed-Webhook-Example:
                        $ref: >-
                          #/components/examples/Wallet-Activation-Closed-Webhook-Example
                      wallet-activation-Declined-webhook:
                        $ref: >-
                          #/components/examples/Wallet-Activation-Declined-Webhook-Example
              responses:
                '200':
                  description: Webhook received successfully.
  /merchants/v1/wallets/balances:
    get:
      summary: Get wallet balances
      description: >
        Retrieve available and related wallet account balance information for
        the specified merchant and account filters, enabling reconciliation,
        reporting, and operational funding decisions.
      operationId: getWalletBalances
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - Wallet
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Merchant-Id'
        - $ref: '#/components/parameters/Currency-Code'
        - $ref: '#/components/parameters/Country-Code'
        - $ref: '#/components/parameters/Virtual-Account-Id'
      responses:
        '200':
          description: This section holds the virtual balances.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-Wallet-Balances'
              examples:
                get-wallet-balances-response:
                  $ref: '#/components/examples/Get-Wallet-Balances-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'
        '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/wallets:
    get:
      summary: Get wallet status
      description: >-
        Check the status of virtual accounts using the virtual_account_id
        returned from wallet activation, and review account state details needed
        to determine operational readiness and lifecycle stage.
      operationId: getWallet
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - Wallet
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Merchant-Id'
        - $ref: '#/components/parameters/Country-Code'
        - $ref: '#/components/parameters/Virtual-Account-Id'
      responses:
        '200':
          description: >-
            This section holds the successful response for virtual account
            status inquiry.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-Wallet-Activation-Response'
              examples:
                get-wallet-response:
                  $ref: '#/components/examples/Get-Wallet-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'
        '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/link-accounts:
    post:
      summary: Link external account for payments
      description: >-
        Use this endpoint to verify an external creditor account and receive a
        creditor_id for successfully validated beneficiaries, so the account can
        be used in subsequent payout transactions.
      operationId: linkAccount
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - LinkAccount
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Merchant-Id'
        - $ref: '#/components/parameters/Idempotency-Id'
        - $ref: '#/components/parameters/Country-Code'
      requestBody:
        required: true
        description: This section holds the request parameters used to verify the Creditor.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Link-Account-Request'
            examples:
              account-linkage-request:
                $ref: '#/components/examples/Account-Linkage-Request-Example'
              Account-Linkage-Request-Example-HK:
                $ref: '#/components/examples/Account-Linkage-Request-Example-HK'
              Account-Linkage-Request-Example-CN:
                $ref: '#/components/examples/Account-Linkage-Request-Example-CN'
      responses:
        '200':
          description: >-
            This section holds the successful response for creditor
            verification.
          headers:
            apim-guid:
              $ref: '#/components/headers/Apim-Guid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sync-Response'
              examples:
                account-linkage-response:
                  $ref: '#/components/examples/Account-Linkage-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'
      security:
        - oAuth2:
            - /authenticationservices/v1
      callbacks:
        accountLinkageWebhook:
          '{$notificationURL}':
            description: >-
              This endpoint used to push the status notification for creditor
              verification.
            post:
              summary: Account linkage webhook notification
              description: >-
                Webhook notification sent when an account linkage status
                changes. This callback is triggered for status updates on linked
                accounts.
              operationId: accountLinkageWebhookNotification
              tags:
                - Account-Linkage
              parameters:
                - $ref: '#/components/parameters/Event-Type'
                - $ref: '#/components/parameters/Event-Name'
                - $ref: '#/components/parameters/Apim-Guid'
              requestBody:
                description: >-
                  This section holds the request parameters for creditor
                  verification notification.
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/Webhook-Link-Account'
                    examples:
                      Account-Linkage-Available-Webhook-Example:
                        $ref: >-
                          #/components/examples/Account-Linkage-Available-Webhook-Example
                      Account-Linkage-Declined-Webhook-Example:
                        $ref: >-
                          #/components/examples/Account-Linkage-Declined-Webhook-Example
              responses:
                '200':
                  description: Webhook received successfully.
    get:
      summary: Get linked account details
      description: >-
        You can use this to check the status of the creditor. Creditor must be
        verified and have an 'AVAILABLE' status before sending external
        payments.
      operationId: getLinkedAccount
      servers:
        - url: https://b2b.api.icg.citi.com/citiconnect/prod/gatewayservices
      tags:
        - LinkAccount
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Merchant-Id'
        - $ref: '#/components/parameters/Country-Code'
        - $ref: '#/components/parameters/Creditor-Id'
        - $ref: '#/components/parameters/Creditor-Partner-User-Id'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Page-No'
      responses:
        '200':
          description: >-
            This section holds the successful response for creditor verification
            inquiry.
          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/Get-Link-Account-Response'
              examples:
          

# --- truncated at 32 KB (190 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/citi/refs/heads/main/openapi/citi-marketplace-management-openapi.yaml