openapi: 3.1.0
info:
  title: GlobalX Business API
  version: 0.2.0
  summary: API contract for GlobalX business banking integrations.
  description: >-
    This API reference is intended for teams integrating with Roecny GlobalX. All JSON responses use a consistent
    envelope. Success responses return { success: true, data, meta: { requestId, timestamp } }. Failure responses return
    { success: false, error: { code, message, details?, hint? }, meta: { requestId, timestamp } }. Recommended
    integration flow: authenticate with your API key; create or identify an end user; create and update the corporate
    onboarding application; submit the hosted KYB/KYC journey; wait for customer status callbacks; assign receiving
    accounts for supported funding currencies; list wallets and accounts; create FX quotes and conversions as needed;
    create route-specific recipients; validate and submit payouts; track payouts, transaction RFIs, pay-ins, FX
    conversions, and wallet transfers from API lookups plus webhooks. Route configuration should be cached locally by
    your application. Use the supported corridors endpoint to build or refresh payout routes by destination country,
    destination currency, and payout method. Do not call corridor discovery before every payout; use payout validation
    as the final transaction-level check and refresh cached routes when validation indicates route or required-field
    changes. Webhook receivers should return a 2xx response after persisting the event. Treat `eventId` as idempotent
    and keep webhook processing asynchronous so money-movement actions are not blocked by a slow callback handler.
servers:
  - url: https://api.globalx.roecny.com
    description: GlobalX API environment.
tags:
  - name: System
    description: Health and platform metadata.
  - name: Access
    description: Credential context for your integration.
  - name: Users
    description: Create and manage end users.
  - name: Onboarding
    description: Corporate customer onboarding, secure verification handoff, and status refresh.
  - name: Wallets
    description: Wallet balances and supported wallet funding operations.
  - name: Receiving Accounts
    description: Virtual receiving account and payment ID assignment for pay-in rails.
  - name: FX
    description: Quote, conversion creation, conversion execution, and conversion lookup.
  - name: Recipients
    description: Recipient schema discovery, verification, and creation.
  - name: Transactions
    description: Transaction listing and transaction RFI response flows.
  - name: Payouts
    description: Payout validation, payout initiation, and payout audit trail.
  - name: Wallet Transfers
    description: Same-currency wallet-to-wallet transfer operations.
  - name: Webhooks
    description: Outbound event payloads delivered to your configured callback endpoints.
x-tagGroups:
  - name: Business Integration API
    tags:
      - System
      - Access
      - Users
      - Onboarding
      - Wallets
      - Receiving Accounts
      - FX
      - Recipients
      - Transactions
      - Payouts
      - Wallet Transfers
      - Webhooks
paths:
  /v1/health:
    get:
      summary: Health check
      operationId: getHealth
      tags:
        - System
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/Health'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/access:
    get:
      summary: Get API credential access context
      operationId: getBusinessAccess
      tags:
        - Access
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Access context resolved from the API key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessAccessSummary'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/users/register:
    post:
      summary: Register an end user
      operationId: registerBusinessUser
      tags:
        - Users
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUserRegistrationRequest'
      responses:
        '201':
          description: Registered customer user
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CustomerUserRegistrationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding:
    get:
      summary: Get onboarding status
      operationId: getBusinessOnboarding
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Normalized onboarding case
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingCase'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/requirements:
    get:
      summary: Get corporate onboarding requirements
      description: |-
        Returns the current corporate onboarding contract used before creating or updating an application.
        Use this endpoint before rendering your onboarding form. The response includes shared steps plus
        regionRequirements for SG, HK, and US so your UI can collect the correct business type, stakeholder,
        document, KYC, and external bank account information for the selected registered country.
      operationId: getBusinessOnboardingRequirements
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Corporate business verification field contract used by the onboarding UI
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingRequirements'
              examples:
                regionMatrix:
                  summary: SG, HK, and US onboarding requirement matrix
                  value:
                    success: true
                    data:
                      version: corporate_onboarding_current
                      fixedValues:
                        type: corporate
                        kycType: full
                        region: derived_from_registeredCountry
                        supportedRegions:
                          - SG
                          - HK
                          - US
                      payloadRoot: v5Payload
                      fieldValueCatalog:
                        registeredCountry:
                          - value: SG
                            label: Singapore
                          - value: HK
                            label: Hong Kong
                          - value: US
                            label: United States
                        businessTypeByRegion:
                          SG:
                            - value: private_company
                              label: Private company
                            - value: partnership
                              label: Partnership
                          HK:
                            - value: private_company
                              label: Private company
                            - value: foreign_company_office
                              label: Foreign company office
                          US:
                            - value: corporation
                              label: Corporation
                            - value: limited_liability_company
                              label: Limited liability company
                        expectedAccountUsage:
                          monthlyTransactionVolumeByRegion:
                            SG:
                              - value: MVSG01
                                label: Less than SGD 5,000
                              - value: MVSG10
                                label: SGD 1,000,000 to SGD 10,000,000
                            HK:
                              - value: MVHK01
                                label: Less than HKD 5,000
                            US:
                              - value: MVUS01
                                label: Less than USD 5,000
                          monthlyTransactions:
                            - value: ATC01
                              label: 1 to 5 transactions
                            - value: ATC03
                              label: 11 to 20 transactions
                        bankAccountType:
                          - value: current
                            label: Current account
                          - value: saving
                            label: Savings account
                      regionRequirements:
                        SG:
                          summary: Singapore corporate onboarding. Set registeredCountry and region to SG.
                          businessTypes:
                            - private_company
                            - public_company
                            - sole_trader
                            - partnership
                            - association
                            - trust
                            - government_entity
                          businessRegistrationNumber: Use the official Singapore UEN or business registration number.
                          businessDocuments:
                            - businessTypes:
                                - private_company
                                - public_company
                                - sole_trader
                                - government_entity
                              documents:
                                - business_registration_doc
                            - businessTypes:
                                - partnership
                              documents:
                                - partnership_deed
                            - businessTypes:
                                - association
                              documents:
                                - association_deed
                            - businessTypes:
                                - trust
                              documents:
                                - trust_deed
                          stakeholderRules:
                            - >-
                              Submit every natural-person shareholder, controller or UBO with 25% or greater direct or
                              indirect ownership.
                            - >-
                              For corporate shareholders, submit the corporate layer and final natural-person UBOs or
                              controllers.
                        HK:
                          summary: Hong Kong corporate onboarding. Set registeredCountry and region to HK.
                          businessTypes:
                            - private_company
                            - public_company
                            - sole_trader
                            - general_partnership
                            - limited_partnership
                            - foreign_company_office
                            - other
                          businessRegistrationNumber: >-
                            Use the accepted company registry number format. If only an 8-digit BRN/UBI is available,
                            confirm businessType handling before final submission.
                          addressNotes:
                            - For Hong Kong addresses, pass postcode as 0000 when no postcode exists.
                          businessDocuments:
                            - businessTypes:
                                - private_company
                                - public_company
                              documents:
                                - business_registration_doc
                                - nar1 or nnc1
                            - businessTypes:
                                - foreign_company_office
                              documents:
                                - nar1 or nnc1 or nn3
                            - businessTypes:
                                - general_partnership
                                - limited_partnership
                              documents:
                                - business_registration_doc
                                - partnership_deed
                          stakeholderRules:
                            - >-
                              Submit every natural-person shareholder, controller or UBO with 25% or greater direct or
                              indirect ownership.
                            - >-
                              Manual KYC documents are expected for applicable Hong Kong stakeholders unless the hosted
                              flow requests otherwise.
                        US:
                          summary: United States corporate onboarding. Set registeredCountry and region to US.
                          businessTypes:
                            - corporation
                            - limited_liability_company
                            - public_company
                            - sole_trader
                            - general_partnership
                            - limited_liability_partnership
                            - limited_partnership
                            - trust
                            - estate
                            - unincorp_association
                          businessRegistrationNumber: Use the EIN. The value must be nine digits.
                          website: >-
                            Optional, but collect proof_of_business when no active business website or public profile is
                            available.
                          businessDocuments:
                            - businessTypes:
                                - corporation
                                - limited_liability_company
                                - unincorp_association
                              documents:
                                - business_registration_doc
                            - businessTypes:
                                - limited_partnership
                              documents:
                                - business_registration_doc
                                - partnership_deed
                            - businessTypes:
                                - trust
                              documents:
                                - trust_deed
                          conditionalDocuments:
                            - certificate_of_good_standing for Delaware or New Jersey registrations when requested
                            - proof_of_business when no active business website is available
                            - ownership_chart when the business is multilayered
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications:
    post:
      summary: Create an onboarding application
      description: >-
        Create a corporate onboarding application for SG, HK, or US. The request accepts a flexible

        v5Payload object so you can submit the region-specific fields returned by the requirements endpoint. Before
        final submission, upload KYB/KYC files with the document upload endpoint and place the returned

        file IDs into v5Payload.documents, v5Payload.applicant.documents, and each stakeholder document object. The
        initial payload should include every individual stakeholder who directly or indirectly owns 25% or

        more of the business. For multilayer ownership, include the corporate shareholder layer and the final

        natural-person UBOs or controllers.
      operationId: createBusinessOnboardingApplication
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingApplicationCreateRequest'
            examples:
              sgPrivateCompany:
                summary: SG private company
                value:
                  userEmail: applicant@example.sg
                  businessName: Example Trading Pte. Ltd.
                  registeredCountry: SG
                  website: https://www.example.sg
                  v5Payload:
                    type: corporate
                    kycType: full
                    region: SG
                    registeredCountry: SG
                    businessType: private_company
                    businessName: Example Trading Pte. Ltd.
                    tradeName: Example Trading
                    businessRegistrationNumber: 202605020001K
                    registeredDate: '2020-07-20'
                    website: https://www.example.sg
                    isMultiLayeredCompany: false
                    addresses:
                      isBusinessAddressSameAsRegisteredAddress: true
                      registeredAddress:
                        addressLine1: 101 High Street
                        addressLine2: '#08-01'
                        city: Singapore
                        state: Singapore
                        postcode: '179098'
                        country: SG
                    applicant:
                      firstName: Mei
                      lastName: Tan
                      dateOfBirth: '1985-04-12'
                      nationality: SG
                      email: applicant@example.sg
                      mobileCountryCode: '65'
                      mobile: '88889999'
                      sharePercentage: '100'
                      positions:
                        - title: SIGNATORY
                      address:
                        addressLine1: 10 Orchard Road
                        city: Singapore
                        state: Singapore
                        postcode: '238841'
                        country: SG
                      documents:
                        - type: passport
                          fileIds:
                            - file_applicant_poi
                    stakeholders:
                      individual:
                        - firstName: Mei
                          lastName: Tan
                          dateOfBirth: '1985-04-12'
                          nationality: SG
                          sharePercentage: '100'
                          positions:
                            - title: UBO
                          address:
                            addressLine1: 10 Orchard Road
                            city: Singapore
                            state: Singapore
                            postcode: '238841'
                            country: SG
                          documents:
                            - type: passport
                              fileIds:
                                - file_stakeholder_poi
                      corporate: []
                    natureOfBusiness:
                      industryCodes:
                        - IS164
                      industryDescription: Trading and technology services.
                      operatingCountries:
                        - SG
                    expectedAccountUsage:
                      intendedUses:
                        - IU003
                      credit:
                        monthlyTransactionVolume: MVSG10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVSG02
                        topTransactionCountries:
                          - SG
                      debit:
                        monthlyTransactionVolume: MVSG10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVSG02
                        topTransactionCountries:
                          - SG
                    sizeOfBusiness:
                      totalEmployees: EM009
                      annualTurnover: SG011
                    bankAccountDetails:
                      accountName: Example Trading Pte. Ltd.
                      bankName: DBS Bank Ltd
                      accountNumber: '1234567890'
                      bankAccountType: current
                      bankCountry: SG
                      currency: SGD
                      routingCodes:
                        - type: SWIFT
                          value: DBSSSGSG
                      payoutMethod: SWIFT
                    documents:
                      - type: business_registration_doc
                        fileIds:
                          - file_business_registration
                    applicantDeclaration: true
              hkPrivateCompany:
                summary: HK private company
                value:
                  userEmail: applicant@example.hk
                  businessName: Example HK Limited
                  registeredCountry: HK
                  website: https://www.example.hk
                  v5Payload:
                    type: corporate
                    kycType: full
                    region: HK
                    registeredCountry: HK
                    businessType: private_company
                    businessName: Example HK Limited
                    tradeName: Example HK
                    businessRegistrationNumber: '2860653'
                    registeredDate: '2019-07-20'
                    website: https://www.example.hk
                    isMultiLayeredCompany: false
                    addresses:
                      isBusinessAddressSameAsRegisteredAddress: true
                      registeredAddress:
                        addressLine1: Unit 10, 10/F, Example Building
                        addressLine2: 1 Queen's Road Central
                        city: Hong Kong
                        state: HK
                        postcode: '0000'
                        country: HK
                    applicant:
                      firstName: Chi
                      lastName: Lee
                      dateOfBirth: '1980-09-09'
                      nationality: HK
                      email: applicant@example.hk
                      mobileCountryCode: '852'
                      mobile: '51234567'
                      positions:
                        - title: SIGNATORY
                      address:
                        addressLine1: Flat A, 10/F
                        city: Hong Kong
                        state: HK
                        postcode: '0000'
                        country: HK
                      documents:
                        - type: passport
                          fileIds:
                            - file_applicant_poi
                    stakeholders:
                      individual:
                        - firstName: Chi
                          lastName: Lee
                          dateOfBirth: '1980-09-09'
                          nationality: HK
                          sharePercentage: '100'
                          positions:
                            - title: UBO
                          address:
                            addressLine1: Flat A, 10/F
                            city: Hong Kong
                            state: HK
                            postcode: '0000'
                            country: HK
                          documents:
                            - type: passport
                              fileIds:
                                - file_stakeholder_poi
                      corporate: []
                    natureOfBusiness:
                      industryCodes:
                        - IS164
                      industryDescription: Cross-border trading and services.
                      operatingCountries:
                        - HK
                        - SG
                    expectedAccountUsage:
                      intendedUses:
                        - IU003
                      credit:
                        monthlyTransactionVolume: MVHK10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVHK02
                        topTransactionCountries:
                          - HK
                          - SG
                      debit:
                        monthlyTransactionVolume: MVHK10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVHK02
                        topTransactionCountries:
                          - HK
                          - SG
                    sizeOfBusiness:
                      totalEmployees: EM009
                      annualTurnover: HK011
                    bankAccountDetails:
                      accountName: Example HK Limited
                      bankName: DBS Bank Hong Kong
                      accountNumber: '123456789'
                      bankAccountType: current
                      bankCountry: HK
                      currency: HKD
                      routingCodes:
                        - type: BANK CODE
                          value: '016'
                    documents:
                      - type: business_registration_doc
                        fileIds:
                          - file_hk_business_registration
                      - type: nar1
                        fileIds:
                          - file_hk_nar1_or_nnc1
                    applicantDeclaration: true
              usCorporation:
                summary: US corporation
                value:
                  userEmail: applicant@example.com
                  businessName: Example Inc
                  registeredCountry: US
                  website: https://www.example.com
                  v5Payload:
                    type: corporate
                    kycType: full
                    region: US
                    registeredCountry: US
                    businessType: corporation
                    businessName: Example Inc
                    tradeName: Example Inc
                    businessRegistrationNumber: '123456789'
                    registeredDate: '2021-03-15'
                    website: https://www.example.com
                    isMultiLayeredCompany: false
                    addresses:
                      isBusinessAddressSameAsRegisteredAddress: true
                      registeredAddress:
                        addressLine1: 100 Market Street
                        city: New York
                        state: NY
                        postcode: '10001'
                        country: US
                    applicant:
                      firstName: Alex
                      lastName: Smith
                      dateOfBirth: '1982-06-22'
                      nationality: US
                      email: applicant@example.com
                      mobileCountryCode: '1'
                      mobile: '2125550100'
                      positions:
                        - title: SIGNATORY
                      address:
                        addressLine1: 200 Park Avenue
                        city: New York
                        state: NY
                        postcode: '10017'
                        country: US
                      documents:
                        - type: passport
                          fileIds:
                            - file_applicant_poi
                    stakeholders:
                      individual:
                        - firstName: Alex
                          lastName: Smith
                          dateOfBirth: '1982-06-22'
                          nationality: US
                          sharePercentage: '100'
                          positions:
                            - title: UBO
                          address:
                            addressLine1: 200 Park Avenue
                            city: New York
                            state: NY
                            postcode: '10017'
                            country: US
                          documents:
                            - type: passport
                              fileIds:
                                - file_stakeholder_poi
                      corporate: []
                    natureOfBusiness:
                      industryCodes:
                        - IS164
                      industryDescription: Software and business services.
                      operatingCountries:
                        - US
                    expectedAccountUsage:
                      intendedUses:
                        - IU003
                      credit:
                        monthlyTransactionVolume: MVUS10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVUS02
                        topTransactionCountries:
                          - US
                      debit:
                        monthlyTransactionVolume: MVUS10
                        monthlyTransactions: ATC03
                        averageTransactionValue: ATVUS02
                        topTransactionCountries:
                          - US
                    sizeOfBusiness:
                      totalEmployees: EM009
                      annualTurnover: US011
                    bankAccountDetails:
                      accountName: Example Inc
                      bankName: Example Bank
                      accountNumber: '1234567890'
                      bankAccountType: checking
                      bankCountry: US
                      currency: USD
                      routingCodes:
                        - type: ACH CODE
                          value: '021000021'
                    documents:
                      - type: business_registration_doc
                        fileIds:
                          - file_us_business_registration
                    applicantDeclaration: true
      responses:
        '201':
          description: Created onboarding application
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications/{applicationId}:
    get:
      summary: Get an onboarding application
      operationId: getBusinessOnboardingApplication
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Onboarding application
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
    patch:
      summary: Update an onboarding application draft
      operationId: updateBusinessOnboardingApplication
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingApplicationUpdateRequest'
      responses:
        '200':
          description: Updated onboarding application draft
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications/{applicationId}/documents:
    get:
      summary: List staged onboarding documents
      operationId: listBusinessOnboardingDocuments
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Staged documents for the onboarding application
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/OnboardingDocument'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Upload an onboarding document
      operationId: uploadBusinessOnboardingDocument
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - fieldId
                - file
              properties:
                fieldId:
                  type: string
                  description: Onboarding payload path that this file supports, for example documents[0].fileIds.
                file:
                  type: string
                  format: binary
                  description: PDF, PNG, JPG or JPEG document. Maximum size is 10 MB.
      responses:
        '201':
          description: Staged onboarding document
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingDocument'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications/{applicationId}/documents/{documentId}:
    delete:
      summary: Remove a staged onboarding document from the application draft
      operationId: deleteBusinessOnboardingDocument
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
        - name: documentId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Removed onboarding document
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: object
                        properties:
                          deleted:
                            type: boolean
                            example: true
                          document:
                            $ref: '#/components/schemas/OnboardingDocument'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications/{applicationId}/submit-kyb-kyc:
    post:
      summary: Mark the hosted KYB KYC journey as submitted and move the application into approval waiting state
      operationId: submitBusinessHostedKYBKYC
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Updated onboarding application
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/onboarding/applications/{applicationId}/refresh:
    post:
      summary: Refresh the onboarding application against the latest business verification status
      operationId: refreshBusinessOnboardingApplication
      tags:
        - Onboarding
      security:
        - BusinessApiKey: []
      parameters:
        - name: applicationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Refreshed onboarding application
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/OnboardingApplication'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/wallets:
    get:
      summary: List wallets
      operationId: listBusinessWallets
      tags:
        - Wallets
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Wallet list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/WalletListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/accounts:
    get:
      summary: List receiving accounts
      operationId: listBusinessAccounts
      tags:
        - Receiving Accounts
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Account list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/AccountListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/accounts/payment-ids:
    post:
      summary: Assign a virtual account / payment ID to the customer wallet
      description: >-
        Opens a receiving account / virtual account / payment ID for an approved customer wallet. This endpoint is

        only for inbound funding accounts and is separate from payout corridors, payout recipients, and wallet-to-wallet

        transfers. Required payload fields:

        - accountCategory: SELF_FUNDING_ACCOUNT

        - bankName: one of the supported bank rails for the customer's onboarding program region

        - currencyCode: one of the supported currencies for that bank rail and region The customer's program region is
        derived from the approved onboarding profile or customerHashId. If an

        unsupported bankName + currencyCode pair is submitted, the API returns 400 with enabledRailSet in the error

        details so integrators can show the valid choices. Supported bankName + currencyCode values: SG program:

        - JPM_SG: AED, AUD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PLN, SAR, SEK, SGD,
        THB, TRY, USD, ZAR

        - CFSB_USINTL: USD

        - DBS_SG: SGD, USD

        - DBS_HK: EUR, GBP, HKD

        - BOL_LT: EUR

        - CB_GB: GBP

        - CUSCAL_AU: AUD

        - NETBANK_PH: PHP

        - COBRE_MX: MXN

        - COBRE_CO: COP

        - JPM_NZ: NZD HK program:

        - JPM_SG: AED, AUD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HUF, ILS, JPY, MXN, NOK, NZD, PHP, PLN, SAR, SEK, THB,
        TRY, USD, ZAR

        - DBS_HK: HKD, USD

        - DBS_SG: SGD

        - BOL_LT: EUR

        - CB_GB: GBP

        - CUSCAL_AU: AUD

        - JPM_NZ: NZD US program:

        - JPM_SG: AED, AUD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PLN, SAR, SEK, SGD,
        THB, TRY, USD, ZAR

        - CFSB_USINTL: USD

        - DBS_SG: SGD, USD

        - DBS_HK: EUR, GBP, HKD

        - BOL_LT: EUR

        - CB_GB: GBP

        - CUSCAL_AU: AUD

        - NETBANK_PH: PHP

        - COBRE_MX: MXN

        - COBRE_CO: COP

        - JPM_NZ: NZD
      operationId: assignBusinessPaymentId
      tags:
        - Receiving Accounts
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
            examples:
              sgJpmSgUsd:
                summary: SG program - open JPM_SG USD receiving account
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    accountCategory: SELF_FUNDING_ACCOUNT
                    bankName: JPM_SG
                    currencyCode: USD
              hkDbsHkUsd:
                summary: HK program - open DBS_HK USD receiving account
                value:
                  walletHashId: da0260ea-1055-4ce8-ae21-045abef818d1
                  payload:
                    accountCategory: SELF_FUNDING_ACCOUNT
                    bankName: DBS_HK
                    currencyCode: USD
              usCfsbUsd:
                summary: US program - open CFSB_USINTL USD receiving account
                value:
                  walletHashId: us-wallet-hash-id
                  payload:
                    accountCategory: SELF_FUNDING_ACCOUNT
                    bankName: CFSB_USINTL
                    currencyCode: USD
      responses:
        '200':
          description: Receiving account assignment response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/corridors:
    get:
      summary: Get supported payout corridors
      description: >-
        Returns available payout routes for the requested destination. Current payout scope is Local bank transfer
        (`LOCAL`), International wire (`SWIFT`), Wallet payout (`WALLET`), and Proxy payout (`PROXY`). Card payout is
        technically supportable only if separately enabled and is not exposed in the current implementation scope. Cash
        pickup is not exposed for the current scope. This endpoint uses the supported corridor route catalog and should
        be used to build or refresh our route configuration and recipient field requirements; normal payout submission
        should rely on cached/configured rules plus payout validation, not a fresh corridor lookup before every payout.
        Use this endpoint before creating a recipient: recipient details are channel-specific, so a LOCAL recipient,
        SWIFT recipient, WALLET recipient and PROXY recipient should be treated as different saved recipients even if
        the payee name is the same.
      operationId: listBusinessCorridors
      tags:
        - Payouts
        - Recipients
      security:
        - BusinessApiKey: []
      parameters:
        - name: destinationCountry
          in: query
          schema:
            type: string
            example: US
          description: ISO 3166-1 alpha-2 destination country code.
        - name: destinationCurrency
          in: query
          schema:
            type: string
            example: USD
          description: ISO 4217 payout currency code.
        - name: payoutMethod
          in: query
          schema:
            type: string
            enum:
              - LOCAL
              - SWIFT
              - WALLET
              - PROXY
          description: Payout method to evaluate for this route lookup.
        - name: beneficiaryAccountType
          in: query
          schema:
            type: string
            enum:
              - CORPORATE
              - INDIVIDUAL
          description: Optional recipient account owner type. Leave empty first when discovering available routes.
        - name: routingCodeType
          in: query
          schema:
            type: string
            example: ACH CODE
          description: Optional routing rail filter when the required local routing type is already known.
        - name: page
          in: query
          schema:
            type: integer
            example: 0
          description: Optional V3 page index for route catalog refreshes.
        - name: size
          in: query
          schema:
            type: integer
            example: 50
          description: Optional page size for V3 route catalog refreshes.
      responses:
        '200':
          description: Supported corridors response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/fx/quotes:
    post:
      summary: Create a locked FX quote
      description: >-
        Optional locked-rate flow. Use this only when a rate must be held before conversion. For ordinary market-rate
        conversion, call POST /v1/business/fx/conversions directly without a quoteId.
      operationId: createBusinessFXQuote
      tags:
        - FX
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
      responses:
        '200':
          description: FX quote response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/fx/conversions:
    post:
      summary: Create a market-rate FX conversion
      description: >-
        Converts available wallet funds using the live market FX rate. Provide sourceCurrencyCode,
        destinationCurrencyCode and either sourceAmount or destinationAmount. A quoteId is optional and should only be
        supplied when using a previously created locked quote.
      operationId: createBusinessFXConversion
      tags:
        - FX
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
      responses:
        '200':
          description: FX conversion response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/fx/conversions/{conversionId}:
    get:
      summary: Get an FX conversion
      operationId: getBusinessFXConversion
      tags:
        - FX
      security:
        - BusinessApiKey: []
      parameters:
        - name: conversionId
          in: path
          required: true
          schema:
            type: string
        - name: walletId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: FX conversion detail response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/fx/conversions/{conversionId}/execute:
    post:
      summary: Execute an FX conversion when explicitly required
      description: >-
        Not used for the normal market-rate immediate conversion flow. Only call this endpoint when a conversion status
        explicitly requires manual execution.
      operationId: executeBusinessFXConversion
      tags:
        - FX
      security:
        - BusinessApiKey: []
      parameters:
        - name: conversionId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
      responses:
        '200':
          description: FX conversion execution response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/beneficiaries/validation-schemas:
    get:
      summary: Get beneficiary required field schema for a currency
      description: >-
        Returns the broad recipient field schema for a currency. This is useful for validation, but it is not a
        substitute for corridor discovery. For channel-specific recipient creation, first call supported corridors with
        destinationCountry, destinationCurrency, payoutMethod, beneficiaryAccountType and routingCodeType, then create a
        recipient using the matching channel fields.
      operationId: getBusinessBeneficiaryValidationSchema
      tags:
        - Recipients
      security:
        - BusinessApiKey: []
      parameters:
        - name: currencyCode
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Beneficiary validation schema response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/beneficiaries/verifications:
    post:
      summary: Verify beneficiary account or proxy details
      description: >-
        Verifies recipient account or proxy details for a selected route. Include the same channel attributes that will
        be used to create the recipient, such as destinationCountry, destinationCurrency, payoutMethod,
        beneficiaryAccountType, routingCodeType1 and routingCodeValue1. Verification requirements vary by route.
      operationId: verifyBusinessBeneficiary
      tags:
        - Recipients
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
      responses:
        '200':
          description: Beneficiary verification response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/beneficiaries:
    post:
      summary: Create a beneficiary
      description: >-
        Creates a saved payout recipient. Recipients are route/channel-specific. Required routing attributes for a
        normal bank recipient:

        - destinationCountry

        - destinationCurrency

        - payoutMethod: LOCAL, SWIFT, WALLET, or PROXY

        - beneficiaryAccountType: Corporate or Individual

        - routingCodeType1 and routingCodeValue1 when required by the selected corridor

        - clientLegalEntity is normally inferred from the business profile if omitted Do not reuse one saved recipient
        across incompatible channels. For example, a US/USD LOCAL ACH recipient and a

        US/USD SWIFT recipient should be created as separate recipients because the routing code type, bank identifiers,

        delivery rail, and payout validation rules are different.
      operationId: createBusinessBeneficiary
      tags:
        - Recipients
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
            examples:
              usLocalAchBusiness:
                summary: US local ACH business recipient
                value:
                  payload:
                    beneficiaryName: ROECNY GROUP LLC
                    beneficiaryAccountType: Corporate
                    beneficiaryCountryCode: US
                    destinationCountry: US
                    destinationCurrency: USD
                    payoutMethod: LOCAL
                    beneficiaryAccountNumber: '1234567890'
                    beneficiaryBankAccountType: Current
                    beneficiaryBankName: Column National Association
                    routingCodeType1: ACH CODE
                    routingCodeValue1: '121145349'
                    beneficiaryAddress: 13631 41ST AVE 8B
                    beneficiaryCity: FLUSHING
                    beneficiaryState: NY
                    beneficiaryPostcode: '11355'
                    beneficiaryEmail: treasury@example.com
                    remitterBeneficiaryRelationship: SELF
              sgLocalFastBusiness:
                summary: Singapore local business recipient
                value:
                  payload:
                    beneficiaryName: EXAMPLE PTE LTD
                    beneficiaryAccountType: Corporate
                    beneficiaryCountryCode: SG
                    destinationCountry: SG
                    destinationCurrency: SGD
                    payoutMethod: LOCAL
                    beneficiaryAccountNumber: '0012345678'
                    beneficiaryBankAccountType: Current
                    beneficiaryBankName: DBS Bank Ltd
                    routingCodeType1: SWIFT
                    routingCodeValue1: DBSSSGSG
                    beneficiaryAddress: 12 Marina Boulevard
                    beneficiaryCity: Singapore
                    beneficiaryPostcode: '018982'
                    beneficiaryEmail: treasury@example.sg
                    remitterBeneficiaryRelationship: SELF
              swiftBusiness:
                summary: International SWIFT business recipient
                value:
                  payload:
                    beneficiaryName: EXAMPLE GLOBAL LTD
                    beneficiaryAccountType: Corporate
                    beneficiaryCountryCode: HK
                    destinationCountry: HK
                    destinationCurrency: USD
                    payoutMethod: SWIFT
                    beneficiaryAccountNumber: '123456789'
                    beneficiaryBankAccountType: Current
                    beneficiaryBankName: DBS Bank Hong Kong
                    routingCodeType1: SWIFT
                    routingCodeValue1: DHBKHKHH
                    beneficiaryAddress: 1 Queen's Road Central
                    beneficiaryCity: Hong Kong
                    beneficiaryPostcode: '0000'
                    beneficiaryEmail: treasury@example.hk
                    remitterBeneficiaryRelationship: SUPPLIER
              proxyRecipient:
                summary: Proxy recipient
                value:
                  payload:
                    beneficiaryName: EXAMPLE PAYEE
                    beneficiaryAccountType: Corporate
                    destinationCountry: SG
                    destinationCurrency: SGD
                    payoutMethod: PROXY
                    proxyType: uen
                    proxyValue: 202012345K
                    beneficiaryBankName: PayNow
                    beneficiaryEmail: treasury@example.sg
                    remitterBeneficiaryRelationship: SUPPLIER
      responses:
        '200':
          description: Beneficiary create response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/transactions:
    get:
      summary: List transactions
      operationId: listBusinessTransactions
      tags:
        - Transactions
      security:
        - BusinessApiKey: []
      responses:
        '200':
          description: Transaction list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/TransactionListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/transactions/{authCode}/rfi-response:
    post:
      summary: Submit transaction compliance RFI response
      operationId: uploadBusinessTransactionRFI
      tags:
        - Transactions
      security:
        - BusinessApiKey: []
      parameters:
        - name: authCode
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
      responses:
        '200':
          description: Transaction RFI upload response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/payouts:
    post:
      summary: Create a payout
      description: >-
        Creates a payout to a saved recipient after the instruction has been validated. Current production payout
        methods are:

        - LOCAL: local bank rails, such as ACH/Fedwire-style local routing or local clearing where available

        - SWIFT: international bank payout using SWIFT/BIC routing

        - WALLET: supported wallet-style payout routes where enabled

        - PROXY: supported proxy routes where enabled, such as local proxy identifiers Card payout and cash pickup are
        not exposed in the current production scope. The payout method is selected when the recipient is created. At
        payout time, pass the saved recipient

        `beneficiaryHashId` under `payload.beneficiary.id`; do not pass the payout account hash or try to switch a

        recipient from LOCAL to SWIFT, WALLET, or PROXY during payout creation. If the same payee must be reachable

        through more than one method, create separate recipients for each channel. The payout debits the wallet currency
        used by the selected recipient. If that wallet does not have enough

        available balance, convert funds first through the FX endpoints, then validate and create the payout. The create

        payout endpoint does not silently choose another currency for the customer.
      operationId: createBusinessPayout
      tags:
        - Payouts
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessPayoutRequest'
            examples:
              localAchPayout:
                summary: Create a US local payout to a saved ACH recipient
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    beneficiary:
                      id: beneficiary_hash_id_from_create_recipient
                    payout:
                      sourceCurrency: USD
                      sourceAmount: 1795.24
                    purposeCode: IR01801
                    sourceOfFunds: Corporate Account
              swiftPayout:
                summary: Create a SWIFT payout to a saved bank recipient
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    beneficiary:
                      id: beneficiary_hash_id_from_create_recipient
                    payout:
                      sourceCurrency: USD
                      sourceAmount: 1000
                      swiftFeeType: OUR
                    purposeCode: IR01811
                    sourceOfFunds: Business Owner/Shareholder
              proxyPayout:
                summary: Create a proxy payout to a saved proxy recipient
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    beneficiary:
                      id: beneficiary_hash_id_from_create_recipient
                    payout:
                      sourceCurrency: SGD
                      sourceAmount: 250
                    purposeCode: IR01802
                    sourceOfFunds: Corporate Account
      responses:
        '202':
          description: Payout accepted
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PayoutAccepted'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/payouts/validate:
    post:
      summary: Validate a payout before creation
      description: >-
        Validates the payout instruction before releasing funds. Call this endpoint with the same payload that will be

        sent to create payout. Validation checks the saved recipient, route/channel compatibility, amount, purpose code,
        source of funds and

        required route fields. This should be the final pre-submit check after the customer has selected a saved LOCAL,

        SWIFT, WALLET, or PROXY recipient and reviewed the amount. The selected recipient controls the destination
        country, destination currency and payout method. A payout should

        not reuse a recipient created for a different channel. Use the saved recipient `beneficiaryHashId` under

        `payload.beneficiary.id`.
      operationId: validateBusinessPayout
      tags:
        - Payouts
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
            examples:
              validateLocalPayout:
                summary: Validate a payout to a saved LOCAL recipient
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    beneficiary:
                      id: beneficiary_hash_id_from_create_recipient
                    payout:
                      sourceCurrency: USD
                      sourceAmount: 1795.24
                    purposeCode: IR01801
                    sourceOfFunds: Corporate Account
              validateSwiftPayout:
                summary: Validate a payout to a saved SWIFT recipient
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    beneficiary:
                      id: beneficiary_hash_id_from_create_recipient
                    payout:
                      sourceCurrency: USD
                      sourceAmount: 1000
                      swiftFeeType: OUR
                    purposeCode: IR01811
                    sourceOfFunds: Business Owner/Shareholder
      responses:
        '200':
          description: Payout validation response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/payouts/{systemReferenceNumber}/audit:
    get:
      summary: Get payout audit timeline
      description: >-
        Returns the audit timeline for a submitted payout. Use this with transaction webhooks and transaction list sync
        to reconcile processing, compliance review, RFI, completed, rejected, returned, or failed payout states.
      operationId: getBusinessPayoutAudit
      tags:
        - Payouts
      security:
        - BusinessApiKey: []
      parameters:
        - name: systemReferenceNumber
          in: path
          required: true
          schema:
            type: string
        - name: walletId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Payout audit response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/transfers/recipient-lookup:
    post:
      summary: Resolve a wallet transfer recipient by business email
      operationId: lookupBusinessWalletTransferRecipient
      tags:
        - Wallet Transfers
      description: >-
        Use this endpoint before a same-currency wallet transfer to confirm the recipient business name for a
        customer-entered email address. The lookup searches eligible approved GlobalX businesses across tenants and
        returns minimal recipient information only when the recipient can receive the selected currency. If the email
        does not exist, the customer is not approved, the currency wallet is unavailable, or the lookup is ambiguous,
        the response is deliberately generic and does not reveal which condition failed. The create transfer endpoint
        can also accept the same recipient email directly.
      security:
        - BusinessApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessWalletTransferRecipientLookupRequest'
            examples:
              lookupUsdRecipient:
                summary: Lookup approved USD wallet recipient by email
                value:
                  recipientEmail: info.hk@example.com
                  currency: USD
              lookupWithSourceWallet:
                summary: Lookup while preventing self-transfer
                value:
                  recipientEmail: info.sg@example.com
                  currency: SGD
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
      responses:
        '200':
          description: Recipient lookup response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessWalletTransferRecipientLookupResponse'
              examples:
                matched:
                  summary: Recipient can receive this currency
                  value:
                    success: true
                    data:
                      matched: true
                      recipient:
                        displayName: XINE CORPORATION LIMITED
                        businessName: XINE CORPORATION LIMITED
                        email: info.hk@example.com
                        registeredCountry: HK
                        currency: USD
                notMatched:
                  summary: Generic non-match response
                  value:
                    success: true
                    data:
                      matched: false
                      message: Invalid recipient email or unavailable currency.
        default:
          $ref: '#/components/responses/ErrorResponse'
  /v1/business/transfers:
    post:
      summary: Create a same-currency wallet-to-wallet transfer
      description: >-
        Creates an internal same-currency wallet transfer. You may pass destinationWalletHashId directly, or pass
        recipientEmail / destinationWalletEmail plus currency. When an email is supplied, GlobalX resolves the approved
        recipient business and same-currency wallet first, strips the email from the network payload, and submits the
        transfer using the resolved wallet reference. Use recipient-lookup first when you want to show the recipient
        business name for customer confirmation.
      operationId: createBusinessWalletTransfer
      tags:
        - Wallet Transfers
      security:
        - BusinessApiKey: []
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessOperationRequest'
            examples:
              transferByEmail:
                summary: Same-currency transfer by recipient business email
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    recipientEmail: info.hk@example.com
                    currency: USD
                    destinationAmount: 100
                    customerComments: Invoice 1001
                    purposeCode: IR01802
              transferByWalletReference:
                summary: Same-currency transfer by destination wallet reference
                value:
                  walletHashId: b67b6d29-5caf-4050-a74a-ba1f00fa0f38
                  payload:
                    destinationWalletHashId: a572fce1-d933-4080-8287-5fa9582557c3
                    sourceCurrencyCode: USD
                    destinationCurrencyCode: USD
                    destinationAmount: 100
                    customerComments: Invoice 1001
                    purposeCode: IR01802
      responses:
        '200':
          description: Wallet transfer response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/BusinessOperationResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
webhooks:
  customerStatus:
    post:
      summary: Customer onboarding status callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerStatusWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  receivingAccountStatus:
    post:
      summary: Receiving account assignment callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivingAccountWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  walletFundingStatus:
    post:
      summary: Pay-in and wallet funded callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletFundedWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  payoutStatus:
    post:
      summary: Payout lifecycle callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutStatusWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  transactionRfi:
    post:
      summary: Transaction compliance RFI callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRFIWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  fxConversionStatus:
    post:
      summary: FX conversion status callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FXConversionWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
  walletTransferStatus:
    post:
      summary: Wallet transfer status callback
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletTransferWebhook'
      responses:
        '200':
          description: Return any 2xx response after the event is accepted.
components:
  schemas:
    BusinessWalletTransferRecipientLookupResponse:
      type: object
      required:
        - matched
      properties:
        matched:
          type: boolean
          example: true
        message:
          type: string
          description: >-
            Generic non-match reason. Do not use this endpoint for email discovery; non-existent, inactive,
            unsupported-currency, and ambiguous matches are intentionally collapsed.
          example: Invalid recipient email or unavailable currency.
        recipient:
          $ref: '#/components/schemas/BusinessWalletTransferRecipient'
    BusinessWalletTransferRecipient:
      type: object
      properties:
        displayName:
          type: string
          example: XINE CORPORATION LIMITED
        businessName:
          type: string
          example: XINE CORPORATION LIMITED
        fullName:
          type: string
          example: Jie Luo
        email:
          type: string
          format: email
          example: info.hk@example.com
        registeredCountry:
          type: string
          example: HK
        currency:
          type: string
          example: USD
    BusinessWalletTransferRecipientLookupRequest:
      type: object
      required:
        - recipientEmail
        - currency
      properties:
        recipientEmail:
          type: string
          format: email
          description: >-
            Exact business email address entered by the sender. The lookup only returns details if this email maps to an
            approved business with a usable same-currency wallet.
          example: info.hk@example.com
        destinationWalletEmail:
          type: string
          format: email
          description: Alias for recipientEmail.
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: USD
        currencyCode:
          type: string
          minLength: 3
          maxLength: 3
          description: Alias for currency.
        customerHashId:
          type: string
          description: Optional source customer reference used to prevent self-transfer lookup.
        walletHashId:
          type: string
          description: Optional source wallet reference used to prevent self-transfer lookup.
        walletId:
          type: string
          description: Optional source wallet id used to prevent self-transfer lookup.
    PayoutAccepted:
      type: object
      properties:
        payoutId:
          type: string
        status:
          type: string
        message:
          type: string
        acceptedAt:
          type: string
          format: date-time
    BusinessPayoutRequest:
      type: object
      description: >-
        Payout creation request. The payout route is determined by the selected beneficiary, destination country,
        destination currency, and payout method. Production payout methods currently exposed by GlobalX are LOCAL,
        SWIFT, WALLET, and PROXY. Validate the payout before creation when route or recipient details have changed. The
        selected recipient controls the payout method; create separate recipients for separate channels.
      properties:
        beneficiaryName:
          type: string
        sourceWalletId:
          type: string
        amount:
          type: string
        currency:
          type: string
        reference:
          type: string
        walletId:
          type: string
        payload:
          type: object
          additionalProperties: true
          description: >-
            Route-specific payout parameters. For production payout create and validate calls, include beneficiary.id,
            payout.sourceCurrency, payout.sourceAmount, purposeCode, sourceOfFunds and optional route fields such as
            payout.swiftFeeType. Additional fields may be required by the selected corridor or recipient schema.
    TransactionListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        dataSource:
          type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        direction:
          type: string
        kind:
          type: string
        counterparty:
          type: string
        amount:
          type: string
        currency:
          type: string
        status:
          type: string
        complianceStatus:
          type: string
        createdAt:
          type: string
          format: date-time
    BusinessOperationResponse:
      type: object
      properties:
        operation:
          type: string
        live:
          type: boolean
        result:
          description: Endpoint-specific operation result returned using the standard response envelope.
    BusinessOperationRequest:
      type: object
      description: >-
        Generic money-movement request used by endpoints where the exact fields depend on route, country, currency,
        payout method, or operation type. Use documented top-level fields when available and place route-specific fields
        in `payload`.
      properties:
        walletId:
          type: string
          description: Optional GlobalX wallet id.
        walletHashId:
          type: string
          description: Optional source wallet reference. Required for wallet transfer when walletId is not provided.
        currencyCode:
          type: string
        conversionId:
          type: string
        systemReferenceNumber:
          type: string
        authCode:
          type: string
        payload:
          type: object
          additionalProperties: true
          description: >-
            Operation-specific parameters. Common examples include receiving-account assignment fields, FX quote fields,
            recipient verification fields, route-specific beneficiary fields, payout validation fields, and
            wallet-transfer details. For payouts, pass beneficiary.id, payout.sourceCurrency, payout.sourceAmount,
            purposeCode and sourceOfFunds. For wallet transfers, payload may include recipientEmail or
            destinationWalletEmail instead of destinationWalletHashId.
    AccountListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Account'
        dataSource:
          type: string
    Account:
      type: object
      properties:
        id:
          type: string
        bankName:
          type: string
        accountMask:
          type: string
        country:
          type: string
        currency:
          type: string
        rails:
          type: array
          items:
            type: string
        status:
          type: string
    WalletListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Wallet'
        dataSource:
          type: string
    Wallet:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        currency:
          type: string
        balance:
          type: string
        available:
          type: string
        status:
          type: string
        rail:
          type: string
    OnboardingDocument:
      type: object
      properties:
        documentId:
          type: string
          example: gxdoc_12ab34cd56ef
        fieldId:
          type: string
          example: documents[0].fileIds
        originalName:
          type: string
          example: business-registration.pdf
        contentType:
          type: string
          example: application/pdf
        sizeBytes:
          type: integer
          format: int64
          example: 124032
        sha256Hex:
          type: string
        status:
          type: string
          enum:
            - staged
            - uploaded
            - failed
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OnboardingApplicationUpdateRequest:
      type: object
      properties:
        businessName:
          type: string
        registeredCountry:
          type: string
        website:
          type: string
        v5Payload:
          type: object
          additionalProperties: true
          description: Partial corporate onboarding payload overlay. Allowed only before the onboarding application is approved.
    OnboardingApplication:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
          description: >-
            Customer user id returned by registerBusinessUser. If omitted, userEmail or email can be used to resolve the
            registered user.
        userEmail:
          type: string
          description: Registered customer user email. Used to resolve userId when userId is not provided.
        email:
          type: string
          description: Alias for userEmail.
        businessName:
          type: string
        registeredCountry:
          type: string
        website:
          type: string
          description: Optional business website.
        status:
          type: string
        currentStage:
          type: string
        nextAction:
          type: string
        hostedSessionKind:
          type: string
        hostedSessionUrl:
          type: string
        v5Payload:
          type: object
          additionalProperties: true
          description: >-
            -supplied corporate onboarding payload overlay. GlobalX enforces type=corporate and kycType=full for this
            flow.
        stepProgress:
          type: array
          description: >-
            Backend-derived step completion based on the latest saved v5Payload in GlobalX. A step is completed only
            after required fields are persisted successfully.
          items:
            $ref: '#/components/schemas/OnboardingApplicationStepProgress'
        progressPercent:
          type: integer
          minimum: 0
          maximum: 100
          description: Backend-derived completion percentage across required onboarding sections.
        canSubmit:
          type: boolean
          description: >-
            True only when all required sections are complete and the application has not been finally submitted
            network.
        mocked:
          type: boolean
        notes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    OnboardingApplicationStepProgress:
      type: object
      properties:
        id:
          type: string
          example: business-profile
        title:
          type: string
          example: Business profile
        status:
          type: string
          enum:
            - completed
            - in_progress
            - upcoming
        complete:
          type: boolean
        missingFields:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingApplicationMissingField'
    OnboardingApplicationMissingField:
      type: object
      properties:
        path:
          type: string
          example: businessRegistrationNumber
        label:
          type: string
          example: Business registration number
    OnboardingApplicationCreateRequest:
      type: object
      properties:
        userId:
          type: string
        businessName:
          type: string
        registeredCountry:
          type: string
          enum:
            - SG
            - HK
            - US
          description: Registered country for the corporate customer. This drives the region-specific onboarding requirements.
        website:
          type: string
          description: Optional business website.
        v5Payload:
          type: object
          additionalProperties: true
          description: >-
            Corporate full-verification onboarding payload collected from the business customer.

            Fields supplied here override the application draft before GlobalX submits the business verification
            package.

            Use GET /v1/business/onboarding/requirements to decide which fields, documents, stakeholders,

            and KYC materials are required for SG, HK, or US.
          example:
            type: corporate
            kycType: full
            region: SG
            businessName: Roecny Example Pte. Ltd.
            businessRegistrationNumber: 202605020001K
            registeredDate: '2020-07-20'
            registeredCountry: SG
            businessType: private_company
            website: https://www.example.com
            addresses:
              isBusinessAddressSameAsRegisteredAddress: true
              registeredAddress:
                addressLine1: High Street 101
                city: Singapore
                state: Singapore
                postcode: '28046'
                country: SG
            applicant:
              firstName: Business
              lastName: Owner
              email: owner@example.com
              mobileCountryCode: '65'
              mobile: '88889999'
              nationality: SG
              positions:
                - title: SIGNATORY
            natureOfBusiness:
              industryCodes:
                - IS164
              operatingCountries:
                - SG
                - HK
            expectedAccountUsage:
              intendedUses:
                - IU003
            sizeOfBusiness:
              totalEmployees: EM009
              annualTurnover: SG011
    OnboardingRequirements:
      type: object
      properties:
        version:
          type: string
        source:
          type: string
        fixedValues:
          type: object
          additionalProperties: true
        submissionEndpoint:
          type: string
        statusGate:
          type: object
          additionalProperties: true
        payloadRoot:
          type: string
        fieldValueCatalog:
          $ref: '#/components/schemas/OnboardingFieldValueCatalog'
        regionRequirements:
          $ref: '#/components/schemas/OnboardingRegionRequirements'
        steps:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
              description:
                type: string
              fields:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    label:
                      type: string
                    type:
                      type: string
                    required:
                      type: boolean
                    options:
                      type: array
                      items:
                        type: string
    OnboardingRegionRequirements:
      type: object
      description: Region-specific corporate onboarding requirements keyed by registered country code.
      additionalProperties:
        $ref: '#/components/schemas/OnboardingRegionRequirement'
      example:
        SG:
          summary: Singapore corporate onboarding. Set registeredCountry and region to SG.
          businessTypes:
            - private_company
            - public_company
            - partnership
          businessRegistrationNumber: Use the official Singapore UEN or business registration number.
          businessDocuments:
            - businessTypes:
                - private_company
              documents:
                - business_registration_doc
          stakeholderRules:
            - >-
              Submit every natural-person shareholder, controller or UBO with 25% or greater direct or indirect
              ownership.
    OnboardingRegionRequirement:
      type: object
      properties:
        summary:
          type: string
        businessTypes:
          type: array
          items:
            type: string
        businessRegistrationNumber:
          type: string
        tradeName:
          type: string
        website:
          type: string
        addressNotes:
          type: array
          items:
            type: string
        businessDocuments:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingBusinessDocumentRule'
        stakeholderRules:
          type: array
          items:
            type: string
        kycModes:
          type: array
          items:
            type: string
        conditionalDocuments:
          type: array
          items:
            type: string
        externalBankAccount:
          type: string
      additionalProperties: true
    OnboardingBusinessDocumentRule:
      type: object
      properties:
        businessTypes:
          type: array
          items:
            type: string
        documents:
          type: array
          items:
            type: string
    OnboardingFieldValueCatalog:
      type: object
      description: >-
        Selectable values and display labels for onboarding fields. Use this catalog to render dropdowns instead of
        hard-coding network codes in your UI.
      properties:
        registeredCountry:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        businessTypeByRegion:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/OnboardingValueOption'
        stakeholderRoleByRegion:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/OnboardingValueOption'
        documentType:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        industryCodes:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        intendedUses:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        expectedAccountUsage:
          type: object
          additionalProperties: true
          description: Includes monthlyTransactionVolumeByRegion, monthlyTransactions, and averageTransactionValueByRegion.
        sizeOfBusiness:
          type: object
          additionalProperties: true
          description: Includes totalEmployees and annualTurnoverByRegion.
        bankAccountType:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        routingCodeType:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
        kycMode:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingValueOption'
      additionalProperties: true
    OnboardingValueOption:
      type: object
      required:
        - value
        - label
      properties:
        value:
          type: string
        label:
          type: string
    OnboardingCase:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        currentStepId:
          type: string
        progressPercent:
          type: integer
        startedAt:
          type: string
          format: date-time
        submittedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        businessName:
          type: string
        contactEmail:
          type: string
        summary:
          type: string
        nextAction:
          type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingStep'
    OnboardingStep:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
        owner:
          type: string
        category:
          type: string
        checklist:
          type: array
          items:
            type: string
        fields:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingField'
    OnboardingField:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        kind:
          type: string
        placeholder:
          type: string
        value:
          type: string
        options:
          type: array
          items:
            type: string
        required:
          type: boolean
        helperText:
          type: string
    CustomerUserRegistrationResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/CustomerUser'
        onboardingRequired:
          type: boolean
        nextAction:
          type: string
        mocked:
          type: boolean
        notes:
          type: array
          items:
            type: string
    CustomerUser:
      type: object
      properties:
        id:
          type: string
        externalUserRef:
          type: string
        fullName:
          type: string
        email:
          type: string
        phone:
          type: string
          description: Full phone number retained for display and backward compatibility.
        phoneCountryCode:
          type: string
          description: Dialing prefix digits without plus sign, for example 65, 852 or 1.
        phoneNumber:
          type: string
          description: Local phone number digits without the country code.
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        lastLoginAt:
          type: string
          format: date-time
    CustomerUserRegistrationRequest:
      type: object
      properties:
        externalUserRef:
          type: string
        fullName:
          type: string
        email:
          type: string
        phone:
          type: string
          description: Full phone number. Prefer also passing phoneCountryCode and phoneNumber when available.
        phoneCountryCode:
          type: string
          description: Dialing prefix digits without plus sign, for example 65, 852 or 1.
        phoneNumber:
          type: string
          description: Local phone number digits without the country code.
    BusinessAccessSummary:
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/APICredential'
    APICredential:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        prefix:
          type: string
        status:
          type: string
        scopes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
    ApiErrorResponse:
      type: object
      required:
        - success
        - error
        - meta
      properties:
        success:
          type: boolean
          const: false
          example: false
        error:
          $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      additionalProperties: false
    ResponseMeta:
      type: object
      required:
        - requestId
        - timestamp
      properties:
        requestId:
          type: string
          format: uuid
          description: >-
            GlobalX request correlation id. Mirrors X-Request-Id when the caller supplies one; otherwise generated by
            GlobalX.
          example: 85f6b395-8e58-46e2-af8b-ceb3f380fb02
        timestamp:
          type: string
          format: date-time
          description: UTC response timestamp generated by GlobalX.
          example: '2026-04-14T08:02:36.493473777Z'
      additionalProperties: false
    ApiError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          examples:
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - platform_error
            - internal_error
        message:
          type: string
          description: Human-readable error message safe to show in dashboards or logs.
          example: Unauthorized
        details:
          type: object
          description: Optional structured details, including platform diagnostics when useful.
          additionalProperties: true
          example: {}
        hint:
          type: string
          description: Optional remediation hint for the caller.
          example: Check that the API key is active and belongs to the workspace.
      additionalProperties: false
    Health:
      type: object
      properties:
        service:
          type: string
        environment:
          type: string
        status:
          type: string
        timestamp:
          type: string
          format: date-time
    ApiSuccessResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          const: true
          example: true
        data:
          description: Endpoint-specific response payload.
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      additionalProperties: false
    WebhookEnvelope:
      type: object
      required:
        - eventId
        - eventType
        - createdAt
        - data
      properties:
        eventId:
          type: string
          description: Unique event delivery id. Store this id to make webhook processing idempotent.
          example: evt_01HX7TR0VQ8Y9T8FXRZ3W1P9BF
        eventType:
          type: string
          description: Stable event topic.
          example: payout.status.updated
        createdAt:
          type: string
          format: date-time
          example: '2026-05-14T08:15:30Z'
        data:
          type: object
          additionalProperties: true
      additionalProperties: true
    CustomerStatusWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - customer.status.updated
                - customer.rfi.requested
                - customer.rejected
            data:
              type: object
              properties:
                userId:
                  type: string
                  example: user_01HX7S6KDD2QNN71Q5SBT2Y2Z2
                customerId:
                  type: string
                  example: cus_01HX7S7M7ESDB3PBTD9N0KYGZ3
                status:
                  type: string
                  example: clear
                subStatus:
                  type:
                    - string
                    - 'null'
                  example: null
                applicationId:
                  type: string
                  example: oba_01HX7S7B64DBV9D99TF5BDB7NC
              additionalProperties: true
    ReceivingAccountWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - receiving_account.active
                - receiving_account.failed
            data:
              type: object
              properties:
                userId:
                  type: string
                walletId:
                  type: string
                accountId:
                  type: string
                currency:
                  type: string
                  example: USD
                bankName:
                  type: string
                  example: CFSB_USINTL
                accountNumber:
                  type: string
                  example: '85148490754'
                status:
                  type: string
                  example: active
              additionalProperties: true
    WalletFundedWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - wallet.funded
                - payin.pending
                - payin.completed
                - payin.rejected
            data:
              type: object
              properties:
                userId:
                  type: string
                walletId:
                  type: string
                transactionId:
                  type: string
                  example: FW8450970465
                currency:
                  type: string
                  example: SGD
                amount:
                  type: string
                  example: '1000.00'
                status:
                  type: string
                  example: completed
                bankReferenceNumber:
                  type: string
                  example: GXPI20260514112106
              additionalProperties: true
    PayoutStatusWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - payout.pending
                - payout.paid
                - payout.returned
                - payout.rejected
                - payout.rfi.requested
            data:
              type: object
              properties:
                userId:
                  type: string
                walletId:
                  type: string
                payoutId:
                  type: string
                systemReferenceNumber:
                  type: string
                  example: RT6504738316
                currency:
                  type: string
                  example: USD
                amount:
                  type: string
                  example: '100.00'
                status:
                  type: string
                  example: paid
                rfiReference:
                  type: string
              additionalProperties: true
    TransactionRFIWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - transaction.rfi.requested
                - transaction.compliance.completed
            data:
              type: object
              properties:
                userId:
                  type: string
                transactionId:
                  type: string
                systemReferenceNumber:
                  type: string
                requestedFields:
                  type: array
                  items:
                    type: string
                  example:
                    - creditor_firstName
                dueAt:
                  type: string
                  format: date-time
              additionalProperties: true
    FXConversionWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - fx.conversion.processing
                - fx.conversion.completed
                - fx.conversion.failed
            data:
              type: object
              properties:
                userId:
                  type: string
                walletId:
                  type: string
                quoteId:
                  type: string
                  example: quote_7anSSiG8NKklKPXWvIG4Ey
                conversionId:
                  type: string
                  example: conversion_3ed72hVUaIVpeegHUERaZy
                sellCurrency:
                  type: string
                  example: USD
                buyCurrency:
                  type: string
                  example: SGD
                amount:
                  type: string
                  example: '100.00'
                status:
                  type: string
                  example: completed
              additionalProperties: true
    WalletTransferWebhook:
      allOf:
        - $ref: '#/components/schemas/WebhookEnvelope'
        - type: object
          properties:
            eventType:
              type: string
              enum:
                - wallet_transfer.processing
                - wallet_transfer.completed
                - wallet_transfer.failed
            data:
              type: object
              properties:
                userId:
                  type: string
                sourceWalletId:
                  type: string
                destinationWalletId:
                  type: string
                currency:
                  type: string
                  example: SGD
                amount:
                  type: string
                  example: '50.00'
                status:
                  type: string
                  example: completed
                transactionId:
                  type: string
              additionalProperties: true
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
      description: >-
        Optional idempotency key for write APIs. Reusing the same key with the same method, path and body replays the
        original response; reusing it with different content returns 409.
  responses:
    ErrorResponse:
      description: GlobalX error envelope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          examples:
            unauthorized:
              summary: Unauthorized request
              value:
                success: false
                error:
                  code: unauthorized
                  message: Unauthorized
                meta:
                  requestId: 92b0f1fb-ecd5-4c31-958f-13caaa7d680d
                  timestamp: '2026-03-04T08:09:51.850744982Z'
  securitySchemes:
    BusinessApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Send this value in the `x-api-key` header on every API request. test environment can accept the API key by
        itself. Production integrations should also sign write requests with HMAC headers: `X-GlobalX-Signature`,
        `X-GlobalX-Timestamp`, and `X-GlobalX-Nonce`.
    BusinessHMACSignature:
      type: apiKey
      in: header
      name: X-GlobalX-Signature
      description: >-
        Optional test environment / recommended production HMAC-SHA256 signature. Canonical string is METHOD + "\n" +
        path + "\n" + rawQuery + "\n" + timestamp + "\n" + nonce + "\n" + SHA256(body).
    BusinessHMACTimestamp:
      type: apiKey
      in: header
      name: X-GlobalX-Timestamp
      description: >-
        Unix seconds or RFC3339 timestamp. Must be within the server tolerance window when X-GlobalX-Signature is
        supplied.
    BusinessHMACNonce:
      type: apiKey
      in: header
      name: X-GlobalX-Nonce
      description: Per-request nonce included in the HMAC canonical string.
