openapi.yaml

openapi: 3.1.0
info:
  title: Grid API
  description: |
    API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://grid.lightspark.com/.
  version: '2025-10-13'
  contact:
    name: Lightspark Support
    email: support@lightspark.com
  license:
    name: Proprietary
    url: https://lightspark.com/terms
servers:
  - url: https://api.lightspark.com/grid/2025-10-13
    description: Production server
security:
  - BasicAuth: []
tags:
  - name: Platform Configuration
    description: Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard.
  - name: Customers
    description: Customer management endpoints for creating and updating customer information
  - name: KYC/KYB Verifications
    description: Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers.
  - name: Documents
    description: Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements.
  - name: Internal Accounts
    description: Internal account management endpoints for creating and managing internal accounts
  - name: External Accounts
    description: External account management endpoints for creating and managing external bank accounts
  - name: Same-Currency Transfers
    description: Endpoints for transferring funds between internal and external accounts with the same currency
  - name: Cross-Currency Transfers
    description: Endpoints for creating and confirming quotes for cross-currency transfers
  - name: Transactions
    description: Endpoints for retrieving transaction information
  - name: Webhooks
    description: Webhook endpoints and configuration for receiving notifications
  - name: Invitations
    description: Endpoints for creating, claiming and managing UMA invitations
  - name: Sandbox
    description: Endpoints to trigger test cases in sandbox
  - name: API Tokens
    description: Endpoints to programmatically manage API tokens
  - name: Exchange Rates
    description: Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees.
paths:
  /config:
    get:
      summary: Get platform configuration
      description: Retrieve the current platform configuration
      operationId: getPlatformConfig
      tags:
        - Platform Configuration
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfig'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    patch:
      summary: Update platform configuration
      description: Update the platform configuration settings
      operationId: updatePlatformConfig
      tags:
        - Platform Configuration
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformConfigUpdateRequest'
            example:
              umaDomain: mycompany.com
              webhookEndpoint: https://api.mycompany.com/webhooks/uma
              supportedCurrencies:
                - currencyCode: USD
                  minAmount: 100
                  maxAmount: 1000000
                  enabledTransactionTypes:
                    - OUTGOING
                    - INCOMING
                  requiredCounterpartyFields:
                    - name: FULL_NAME
                      mandatory: true
                    - name: NATIONALITY
                      mandatory: true
                    - name: BIRTH_DATE
                      mandatory: true
      responses:
        '200':
          description: Configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformConfig'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
  /exchange-rates:
    get:
      summary: Get exchange rates
      description: |
        Retrieve cached exchange rates for currency corridors. Returns FX rates that are cached
        for approximately 5 minutes. Rates include fees specific to your platform for authenticated requests.

        **Filtering Options:**
        - Filter by source currency to get all available destination corridors
        - Filter by specific destination currency or currencies
        - Provide a sending amount to get calculated receiving amounts
      operationId: getExchangeRates
      tags:
        - Exchange Rates
      security:
        - BasicAuth: []
      parameters:
        - name: sourceCurrency
          in: query
          description: Filter by source currency code (e.g., USD)
          required: false
          schema:
            type: string
          example: USD
        - name: destinationCurrency
          in: query
          description: Filter by destination currency code(s). Can be repeated for multiple currencies (e.g., &destinationCurrency=INR&destinationCurrency=GBP)
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          example:
            - INR
        - name: sendingAmount
          in: query
          description: Sending amount in the smallest unit of the source currency (e.g., cents for USD).  If no amount is provided, the default is 10000 in the sending currency smallest unit.
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
            default: 10000
          example: 10000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: List of exchange rates matching the filter criteria
                    items:
                      $ref: '#/components/schemas/ExchangeRate'
              examples:
                allRatesFromUSD:
                  summary: All exchange rates from USD
                  value:
                    data:
                      - sourceCurrency:
                          code: USD
                          decimals: 2
                          name: US Dollar
                          symbol: $
                        sendingAmount: 10000
                        minSendingAmount: 100
                        maxSendingAmount: 10000000
                        destinationCurrency:
                          code: INR
                          decimals: 2
                          name: Indian Rupee
                          symbol: ₹
                        destinationPaymentRail: UPI
                        receivingAmount: 825000
                        exchangeRate: 82.5
                        fees:
                          fixed: 100
                        updatedAt: '2025-02-05T12:00:00Z'
                      - sourceCurrency:
                          code: USD
                          decimals: 2
                          name: US Dollar
                          symbol: $
                        sendingAmount: 10000
                        minSendingAmount: 100
                        maxSendingAmount: 10000000
                        destinationCurrency:
                          code: EUR
                          decimals: 2
                          name: Euro
                          symbol: €
                        destinationPaymentRail: SEPA_INSTANT
                        receivingAmount: 18500
                        exchangeRate: 0.925
                        fees:
                          fixed: 10
                        updatedAt: '2025-02-05T12:00:00Z'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers:
    post:
      summary: Add a new customer
      description: Register a new customer in the system with an account identifier and bank account information
      operationId: createCustomer
      tags:
        - Customers
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateRequestOneOf'
            examples:
              individualCustomer:
                summary: Create an individual customer
                value:
                  customerType: INDIVIDUAL
                  platformCustomerId: ind-9f84e0c2
                  fullName: Jane Smith
                  birthDate: '1990-01-15'
                  nationality: US
              businessCustomer:
                summary: Create a business customer
                value:
                  customerType: BUSINESS
                  platformCustomerId: biz-acme-001
                  businessInfo:
                    legalName: Acme Corporation
                    doingBusinessAs: Acme
                    country: US
                    registrationNumber: '5523041'
                    incorporatedOn: '2018-03-14'
                    entityType: LLC
                    taxId: 47-1234567
                    countriesOfOperation:
                      - US
                    businessType: FINANCE_AND_INSURANCE
                    purposeOfAccount: Payout to contractors
                    sourceOfFunds: Funds derived from customer payments for software services
                    expectedMonthlyTransactionCount: 100_TO_500
                    expectedMonthlyTransactionVolume: 100K_TO_1M
                    expectedRecipientJurisdictions:
                      - US
                      - MX
                  address:
                    line1: 123 Market Street
                    line2: Suite 400
                    city: San Francisco
                    state: CA
                    postalCode: '94105'
                    country: US
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOneOf'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Customer with the UMA address already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
    get:
      summary: List customers
      description: |
        Retrieve a list of customers with optional filtering parameters. Returns all customers that match
        the specified filters. If no filters are provided, returns all customers (paginated).
      operationId: listCustomers
      tags:
        - Customers
      security:
        - BasicAuth: []
      parameters:
        - name: platformCustomerId
          in: query
          description: Filter by platform-specific customer identifier
          required: false
          schema:
            type: string
        - name: customerType
          in: query
          description: Filter by customer type
          required: false
          schema:
            $ref: '#/components/schemas/CustomerType'
        - name: createdAfter
          in: query
          description: Filter customers created after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter customers created before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedAfter
          in: query
          description: Filter customers updated after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedBefore
          in: query
          description: Filter customers updated before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
        - name: umaAddress
          in: query
          description: Filter by uma address
          required: false
          schema:
            type: string
        - name: isIncludingDeleted
          in: query
          description: Whether to include deleted customers in the results. Default is false.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of customers matching the filter criteria
                    items:
                      $ref: '#/components/schemas/CustomerOneOf'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of customers matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/{customerId}:
    parameters:
      - name: customerId
        in: path
        description: System-generated unique customer identifier
        required: true
        schema:
          type: string
    get:
      summary: Get customer by ID
      description: Retrieve a customer by their system-generated ID
      operationId: getCustomerById
      tags:
        - Customers
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOneOf'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    patch:
      summary: Update customer by ID
      description: Update a customer's metadata by their system-generated ID
      operationId: updateCustomerById
      tags:
        - Customers
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdateRequestOneOf'
            examples:
              individualUpdate:
                summary: Update individual customer example
                value:
                  customerType: INDIVIDUAL
                  fullName: John Smith
                  birthDate: '1985-06-15'
                  address:
                    line1: 456 Market St
                    city: San Francisco
                    state: CA
                    postalCode: '94103'
                    country: US
              businessUpdate:
                summary: Update business customer example
                value:
                  customerType: BUSINESS
                  businessInfo:
                    legalName: New Tech Solutions LLC
                    registrationNumber: BRN-987654321
                    taxId: EIN-123456789
                  address:
                    line1: 100 Technology Parkway
                    city: Palo Alto
                    state: CA
                    postalCode: '94304'
                    country: US
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOneOf'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    delete:
      summary: Delete customer by ID
      description: Delete a customer by their system-generated ID
      operationId: deleteCustomerById
      tags:
        - Customers
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Customer deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerOneOf'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '410':
          description: Customer deleted already
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error410'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/kyc-link:
    parameters:
      - name: redirectUri
        in: query
        description: An optional uri a customer will be redirected to after completing the hosted KYC flow
        required: false
        schema:
          type: string
      - name: platformCustomerId
        in: query
        description: The platform id of the customer to onboard
        required: true
        schema:
          type: string
    get:
      summary: Get a KYC link for onboarding a customer
      description: Generate a hosted KYC link to onboard a customer
      operationId: getKycLinkForCustomer
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycLinkResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/internal-accounts:
    get:
      summary: List Customer internal accounts
      description: |
        Retrieve a list of internal accounts with optional filtering parameters. Returns all
        internal accounts that match the specified filters. If no filters are provided, returns all internal accounts
        (paginated).

        Internal accounts are created automatically when a customer is created based on the platform configuration.
      operationId: listCustomerInternalAccounts
      tags:
        - Internal Accounts
      security:
        - BasicAuth: []
      parameters:
        - name: currency
          in: query
          description: Filter by currency code
          required: false
          schema:
            type: string
        - name: customerId
          in: query
          description: Filter by internal accounts associated with a specific customer
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of internal accounts matching the filter criteria
                    items:
                      $ref: '#/components/schemas/InternalAccount'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of customers matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /platform/internal-accounts:
    get:
      summary: List platform internal accounts
      description: |
        Retrieve a list of all internal accounts that belong to the platform, as opposed to an individual customer.

        These accounts are created automatically when the platform is configured for each supported currency. They can be used for things like distributing bitcoin rewards to customers, or for other platform-wide purposes.
      operationId: listPlatformInternalAccounts
      tags:
        - Internal Accounts
      security:
        - BasicAuth: []
      parameters:
        - name: currency
          in: query
          description: Filter by currency code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: List of internal accounts matching the filter criteria
                    items:
                      $ref: '#/components/schemas/InternalAccount'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/external-accounts:
    get:
      summary: List Customer external accounts
      description: |
        Retrieve a list of external accounts with optional filtering parameters. Returns all
        external accounts that match the specified filters. If no filters are provided, returns all external accounts
        (paginated).

        External accounts are bank accounts, cryptocurrency wallets, or other payment destinations that customers can use to receive funds from the platform.
      operationId: listCustomerExternalAccounts
      tags:
        - External Accounts
      security:
        - BasicAuth: []
      parameters:
        - name: currency
          in: query
          description: Filter by currency code
          required: false
          schema:
            type: string
        - name: customerId
          in: query
          description: Filter by external accounts associated with a specific customer
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of external accounts matching the filter criteria
                    items:
                      $ref: '#/components/schemas/ExternalAccount'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of external accounts matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    post:
      summary: Add a new external account
      description: Register a new external bank account for a customer.
      operationId: createCustomerExternalAccount
      tags:
        - External Accounts
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalAccountCreateRequest'
            examples:
              usBankAccount:
                summary: Create external US bank account
                value:
                  customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                  currency: USD
                  accountInfo:
                    accountType: USD_ACCOUNT
                    paymentRails:
                      - ACH
                    accountNumber: '12345678901'
                    routingNumber: '123456789'
                    accountCategory: CHECKING
                    bankName: Chase Bank
                    platformAccountId: ext_acc_123456
                    beneficiary:
                      beneficiaryType: INDIVIDUAL
                      fullName: John Doe
                      birthDate: '1990-01-15'
                      nationality: US
                      address:
                        line1: 123 Main Street
                        city: San Francisco
                        state: CA
                        postalCode: '94105'
                        country: US
              sparkWallet:
                summary: Create external Spark wallet
                value:
                  customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                  currency: BTC
                  accountInfo:
                    accountType: SPARK_WALLET
                    address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
      responses:
        '201':
          description: External account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - External account already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /platform/external-accounts:
    get:
      summary: List platform external accounts
      description: |
        Retrieve a list of all external accounts that belong to the platform, as opposed to an individual customer.

        These accounts are used for platform-wide operations such as receiving funds from external sources or managing platform-level payment destinations.
      operationId: listPlatformExternalAccounts
      tags:
        - External Accounts
      security:
        - BasicAuth: []
      parameters:
        - name: currency
          in: query
          description: Filter by currency code
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: List of external accounts matching the filter criteria
                    items:
                      $ref: '#/components/schemas/ExternalAccount'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    post:
      summary: Add a new platform external account
      description: Register a new external bank account for the platform.
      operationId: createPlatformExternalAccount
      tags:
        - External Accounts
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformExternalAccountCreateRequest'
            examples:
              usBankAccount:
                summary: Create external US bank account
                value:
                  currency: USD
                  accountInfo:
                    accountType: USD_ACCOUNT
                    paymentRails:
                      - ACH
                    accountNumber: '12345678901'
                    routingNumber: '123456789'
                    accountCategory: CHECKING
                    bankName: Chase Bank
                    platformAccountId: ext_acc_123456
                    beneficiary:
                      beneficiaryType: INDIVIDUAL
                      fullName: John Doe
                      birthDate: '1990-01-15'
                      nationality: US
                      address:
                        line1: 123 Main Street
                        city: San Francisco
                        state: CA
                        postalCode: '94105'
                        country: US
              sparkWallet:
                summary: Create external Spark wallet
                value:
                  currency: BTC
                  accountInfo:
                    accountType: SPARK_WALLET
                    address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
      responses:
        '201':
          description: External account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - External account already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /beneficial-owners:
    post:
      summary: Create a beneficial owner
      description: |
        Add a beneficial owner, director, or company officer to a business customer. The beneficial owner will go through KYC verification automatically.
      operationId: createBeneficialOwner
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwnerCreateRequest'
      responses:
        '201':
          description: Beneficial owner created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwner'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    get:
      summary: List beneficial owners
      description: |
        Retrieve a list of beneficial owners with optional filtering by customer ID and role.
      operationId: listBeneficialOwners
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      parameters:
        - name: customerId
          in: query
          description: Filter by business customer ID
          required: false
          schema:
            type: string
        - name: role
          in: query
          description: Filter by role
          required: false
          schema:
            $ref: '#/components/schemas/BeneficialOwnerRole'
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of beneficial owners matching the filter criteria
                    items:
                      $ref: '#/components/schemas/BeneficialOwner'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of results matching the criteria
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /beneficial-owners/{beneficialOwnerId}:
    get:
      summary: Get a beneficial owner
      description: Retrieve details of a specific beneficial owner by ID.
      operationId: getBeneficialOwner
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      parameters:
        - name: beneficialOwnerId
          in: path
          description: Beneficial owner ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwner'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Beneficial owner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    patch:
      summary: Update a beneficial owner
      description: Update details of a specific beneficial owner. Only provided fields are updated.
      operationId: updateBeneficialOwner
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      parameters:
        - name: beneficialOwnerId
          in: path
          description: Beneficial owner ID
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficialOwnerUpdateRequest'
      responses:
        '200':
          description: Beneficial owner updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwner'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Beneficial owner not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /documents:
    post:
      summary: Upload a document
      description: |
        Upload a verification document for a customer or beneficial owner. The request must use multipart/form-data with the file in the `file` field and metadata in the remaining fields.

        Supported file types: PDF, JPEG, PNG. Maximum file size: 10 MB.
      operationId: uploadDocument
      tags:
        - Documents
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad request - Invalid file type, size, or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Document holder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    get:
      summary: List documents
      description: |
        Retrieve a list of documents with optional filtering by document holder.
      operationId: listDocuments
      tags:
        - Documents
      security:
        - BasicAuth: []
      parameters:
        - name: documentHolder
          in: query
          description: Filter by document holder ID (Customer or BeneficialOwner)
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of documents matching the filter criteria
                    items:
                      $ref: '#/components/schemas/Document'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of results matching the criteria
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /documents/{documentId}:
    get:
      summary: Get a document by ID
      description: Retrieve details and metadata of a specific document by ID.
      operationId: getDocument
      tags:
        - Documents
      security:
        - BasicAuth: []
      parameters:
        - name: documentId
          in: path
          description: Document ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    put:
      summary: Replace a document
      description: |
        Replace an existing document with a new file and/or updated metadata. This is useful when a document was rejected and needs to be re-uploaded. The request must use multipart/form-data.
      operationId: replaceDocument
      tags:
        - Documents
      security:
        - BasicAuth: []
      parameters:
        - name: documentId
          in: path
          description: Document ID
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DocumentReplaceRequest'
      responses:
        '200':
          description: Document replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad request - Invalid file type, size, or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    delete:
      summary: Delete a document
      description: |
        Delete an uploaded document. This cannot be undone. Documents that have already been submitted for verification may not be deletable.
      operationId: deleteDocument
      tags:
        - Documents
      security:
        - BasicAuth: []
      parameters:
        - name: documentId
          in: path
          description: Document ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Document deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Conflict - Document cannot be deleted (already submitted for verification)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /verifications:
    post:
      summary: Submit customer for verification
      description: |
        Trigger KYC (individual) or KYB (business) verification for a customer. The response indicates whether all required information has been provided. If data is missing, the `errors` array describes exactly what needs to be supplied before verification can proceed.

        Call this endpoint again after resolving errors to re-submit.
      operationId: createVerification
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
      responses:
        '200':
          description: |
            Verification status returned. Check `verificationStatus` and `errors` to determine next steps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verification'
              examples:
                missingInfo:
                  summary: Verification blocked by missing data
                  value:
                    id: Verification:019542f5-b3e7-1d02-0000-000000000001
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    verificationStatus: RESOLVE_ERRORS
                    errors:
                      - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001
                        type: MISSING_FIELD
                        field: customer.address.line1
                        reason: Business address line 1 is required
                      - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001
                        type: MISSING_DOCUMENT
                        acceptedDocumentTypes:
                          - PROOF_OF_ADDRESS
                          - UTILITY_BILL
                          - BANK_STATEMENT
                        reason: Proof of address document is required
                      - resourceId: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002
                        type: MISSING_FIELD
                        field: personalInfo.birthDate
                        reason: Date of birth is required for beneficial owners
                    createdAt: '2025-10-03T12:00:00Z'
                submitted:
                  summary: Verification submitted successfully
                  value:
                    id: Verification:019542f5-b3e7-1d02-0000-000000000002
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    verificationStatus: IN_PROGRESS
                    errors: []
                    createdAt: '2025-10-03T12:00:00Z'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    get:
      summary: List verifications
      description: |
        Retrieve a list of verifications with optional filtering by customer ID and status.
      operationId: listVerifications
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      parameters:
        - name: customerId
          in: query
          description: Filter by customer ID
          required: false
          schema:
            type: string
        - name: verificationStatus
          in: query
          description: Filter by verification status
          required: false
          schema:
            $ref: '#/components/schemas/VerificationStatus'
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of verifications matching the filter criteria
                    items:
                      $ref: '#/components/schemas/Verification'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of results matching the criteria
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /verifications/{verificationId}:
    get:
      summary: Get a verification
      description: Retrieve details of a specific verification by ID.
      operationId: getVerification
      tags:
        - KYC/KYB Verifications
      security:
        - BasicAuth: []
      parameters:
        - name: verificationId
          in: path
          description: Verification ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verification'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Verification not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /plaid/link-tokens:
    post:
      summary: Request Plaid Link token
      description: |
        Creates a Plaid Link token that can be used to initialize Plaid Link in your application.
        The Link token is used to authenticate the customer and allow them to select their bank account.

        **Async Flow:**
        1. Platform calls this endpoint to get a link_token and callbackUrl
        2. Platform displays Plaid Link UI to the end customer using the link_token
        3. End customer authenticates with their bank and selects an account
        4. Plaid returns a public_token to the platform
        5. Platform POSTs the public_token to the callbackUrl
        6. Lightspark exchanges the public_token with Plaid and creates the external account asynchronously
        7. Platform receives a webhook notification when the external account is ready
      operationId: createPlaidLinkToken
      tags:
        - External Accounts
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaidLinkTokenRequest'
            example:
              customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
      responses:
        '200':
          description: Link token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaidLinkTokenResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /plaid/callback/{plaid_link_token}:
    post:
      summary: Submit Plaid public token
      description: |
        After the customer completes Plaid Link authentication, the platform should POST
        the public_token to this callback URL (provided in the link token response).

        This will trigger asynchronous processing:
        1. Lightspark exchanges the public_token for an access_token with Plaid
        2. Lightspark retrieves and verifies the account details
        3. An external account is created
        4. A webhook notification is sent to the platform when complete
      operationId: submitPlaidPublicToken
      tags:
        - External Accounts
      parameters:
        - name: plaid_link_token
          in: path
          required: true
          description: The Plaid link token from the link token response, used to identify the session
          schema:
            type: string
          example: link-sandbox-abc123xyz-1234-5678
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaidCallbackRequest'
            example:
              publicToken: public-sandbox-12345678-1234-1234-1234-123456789012
              accountId: plaid_account_id_123
      responses:
        '202':
          description: |
            A pending external account resource will be created and returned while the Grid API asynchronously processes the Plaid public token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalAccount'
        '400':
          description: Bad request - Invalid public token or link token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '404':
          description: Link token not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Link token already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transfer-in:
    post:
      summary: Create a transfer-in request
      description: |
        Transfer funds from an external account to an internal account for a specific customer. This endpoint should only be used for external account sources with pull functionality (e.g. ACH Pull). Otherwise, use the paymentInstructions on the internal account to deposit funds.
      operationId: createTransferIn
      tags:
        - Same-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: |
            A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferInRequest'
            examples:
              transferIn:
                summary: Transfer from external to internal account
                value:
                  source:
                    accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  amount: 12550
      responses:
        '201':
          description: Transfer-in request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionOneOf'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer or account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transfer-out:
    post:
      summary: Create a transfer-out request
      description: |
        Transfer funds from an internal account to an external account for a specific customer.
      operationId: createTransferOut
      tags:
        - Same-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: |
            A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOutRequest'
            examples:
              transferOut:
                summary: Transfer from internal to external account
                value:
                  source:
                    accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  destination:
                    accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  amount: 12550
      responses:
        '201':
          description: Transfer-out request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionOneOf'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Customer or account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /receiver/uma/{receiverUmaAddress}:
    get:
      summary: Look up an UMA address for payment
      description: |
        Lookup a receiving UMA address to determine supported currencies and exchange rates.
        This endpoint helps platforms determine what currencies they can send to a given UMA address.
      operationId: lookupUma
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: receiverUmaAddress
          in: path
          description: UMA address of the intended recipient
          required: true
          schema:
            type: string
        - name: senderUmaAddress
          in: query
          description: UMA address of the sender (optional if customerId is provided)
          required: false
          schema:
            type: string
        - name: customerId
          in: query
          description: System ID of the sender (optional if senderUmaAddress is provided)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful lookup
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ReceiverLookupResponse'
                  - type: object
                    required:
                      - receiverUmaAddress
                    properties:
                      receiverUmaAddress:
                        type: string
                        description: The UMA address that was looked up
                        example: $receiver@uma.domain
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: UMA address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '412':
          description: Counterparty doesn't support UMA version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error412'
        '424':
          description: Counterparty issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error424'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /receiver/external-account/{accountId}:
    get:
      summary: Look up an external account for payment
      description: |
        Lookup an external account by ID to determine supported currencies and exchange rates.
        This endpoint helps platforms determine what currencies they can send to a given external account, along with the current estimated exchange rates and minimum and maximum amounts that can be sent.
      operationId: lookupExternalAccount
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: accountId
          in: path
          description: System-generated ID of the external account
          required: true
          schema:
            type: string
            example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
        - name: senderUmaAddress
          in: query
          description: UMA address of the sender (optional if customerId is provided)
          required: false
          schema:
            type: string
        - name: customerId
          in: query
          description: System ID of the sender (optional if senderUmaAddress is provided)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful lookup
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ReceiverLookupResponse'
                  - type: object
                    required:
                      - accountId
                    properties:
                      accountId:
                        type: string
                        description: The external account ID that was looked up
                        example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: External account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '412':
          description: Counterparty doesn't support UMA version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error412'
        '424':
          description: Counterparty issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error424'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /quotes/{quoteId}:
    get:
      summary: Get quote by ID
      description: |
        Retrieve a quote by its ID. If the quote has been settled, it will include
        the transaction ID. This allows clients to track the full lifecycle of a payment
        from quote creation to settlement.
      operationId: getQuoteById
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: quoteId
          in: path
          description: ID of the quote to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Quote retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Quote not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /quotes:
    post:
      summary: Create a transfer quote
      description: |
        Generate a quote for a cross-currency transfer between any combination of accounts
        and UMA addresses. This endpoint handles currency exchange and provides the necessary
        instructions to execute the transfer.

        **Transfer Types Supported:**
        - **Account to Account**: Transfer between internal/external accounts with currency exchange.
        - **Account to UMA**: Transfer from an internal account to an UMA address.
        - **UMA to Account or UMA to UMA**: This transfer type will only be funded by payment instructions, not from an internal account.

        **Key Features:**
        - **Flexible Amount Locking**: Always specify whether you want to lock the sending amount or receiving amount
        - **Currency Exchange**: Handles all cross-currency transfers with real-time exchange rates
        - **Payment Instructions**: For UMA or customer ID sources, provides banking details needed for execution

        **Important:** If you are transferring funds in the same currency (no exchange required),
        use the `/transfer-in` or `/transfer-out` endpoints instead.
      operationId: createQuote
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            examples:
              accountToAccount:
                summary: Account to Account Transfer
                value:
                  source:
                    sourceType: ACCOUNT
                    accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    destinationType: ACCOUNT
                    accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  lockedCurrencySide: SENDING
                  lockedCurrencyAmount: 10000
                  description: Transfer between accounts, either internal or external.
              accountToUma:
                summary: Account to UMA Address Transfer
                value:
                  lookupId: LookupRequest:019542f5-b3e7-1d02-0000-000000000009
                  source:
                    sourceType: ACCOUNT
                    accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                  destination:
                    destinationType: UMA_ADDRESS
                    umaAddress: $receiver@uma.domain.com
                    currency: EUR
                  lockedCurrencySide: SENDING
                  lockedCurrencyAmount: 1000
                  description: 'Payment for invoice #1234'
              realTimeFundingToSparkWallet:
                summary: Real-time funding to Spark Wallet as an on-ramp flow. Immediate execution.
                value:
                  source:
                    sourceType: REALTIME_FUNDING
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000009
                    currency: USD
                  destination:
                    destinationType: EXTERNAL_ACCOUNT_DETAILS
                    externalAccountDetails:
                      customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                      currency: BTC
                      accountInfo:
                        accountType: SPARK_WALLET
                        address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
                  lockedCurrencySide: RECEIVING
                  lockedCurrencyAmount: 10000
                  immediatelyExecute: true
                  description: Bitcoin reward payout!
      responses:
        '201':
          description: |
            Transfer quote created successfully. The response includes exchange rates,
            fees, and transfer details. For transfers involving UMA addresses, payment
            instructions are also included for execution through banking systems.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
              example:
                id: Quote:019542f5-b3e7-1d02-0000-000000000006
                status: PENDING
                createdAt: '2025-10-03T12:00:00Z'
                expiresAt: '2025-10-03T12:05:00Z'
                source:
                  sourceType: ACCOUNT
                  accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                destination:
                  destinationType: ACCOUNT
                  accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                sendingCurrency:
                  code: USD
                  name: United States Dollar
                  symbol: $
                  decimals: 2
                receivingCurrency:
                  code: EUR
                  name: Euro
                  symbol: €
                  decimals: 2
                totalSendingAmount: 10000
                totalReceivingAmount: 9200
                exchangeRate: 0.92
                feesIncluded: 10
                transactionId: Transaction:019542f5-b3e7-1d02-0000-000000000005
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '412':
          description: Counterparty doesn't support UMA version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error412'
        '424':
          description: Counterparty issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error424'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
    get:
      summary: List transfer quotes
      description: |
        Retrieve a list of transfer quotes with optional filtering parameters. Returns all
        quotes that match the specified filters. If no filters are provided, returns all quotes
        (paginated).
      operationId: listQuotes
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: customerId
          in: query
          description: Filter by sending customer ID
          required: false
          schema:
            type: string
        - name: sendingAccountId
          in: query
          description: Filter by sending account ID
          required: false
          schema:
            type: string
        - name: receivingAccountId
          in: query
          description: Filter by receiving account ID
          required: false
          schema:
            type: string
        - name: sendingUmaAddress
          in: query
          description: Filter by sending UMA address
          required: false
          schema:
            type: string
        - name: receivingUmaAddress
          in: query
          description: Filter by receiving UMA address
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Filter by quote status
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - PROCESSING
              - COMPLETED
              - FAILED
              - EXPIRED
        - name: createdAfter
          in: query
          description: Filter quotes created after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter quotes created before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of quotes matching the criteria
                    items:
                      $ref: '#/components/schemas/Quote'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of quotes matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /quotes/{quoteId}/execute:
    post:
      summary: Execute a quote
      description: |
        Execute a quote by its ID. This endpoint initiates the transfer between
        the source and destination accounts.

        This endpoint can only be used for quotes with a `source` which is either an internal account,
        or has direct pull functionality (e.g. ACH pull with an external account).

        Once executed, the quote cannot be cancelled and the transfer will be processed.
      operationId: executeQuote
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      parameters:
        - name: quoteId
          in: path
          required: true
          description: The unique identifier of the quote to execute
          schema:
            type: string
          example: Quote:019542f5-b3e7-1d02-0000-000000000001
      responses:
        '200':
          description: |
            Quote confirmed successfully. The transfer has been initiated and
            the quote status has been updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '400':
          description: Bad request - Invalid quote ID or quote cannot be confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Quote not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Conflict - Quote already confirmed, expired, or in invalid state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transactions:
    get:
      summary: List transactions
      description: |
        Retrieve a paginated list of transactions with optional filtering.
        The transactions can be filtered by customer ID, platform customer ID, UMA address,
        date range, status, and transaction type.
      operationId: listTransactions
      tags:
        - Transactions
      security:
        - BasicAuth: []
      parameters:
        - name: customerId
          in: query
          description: Filter by system customer ID
          required: false
          schema:
            type: string
        - name: platformCustomerId
          in: query
          description: Filter by platform-specific customer ID
          required: false
          schema:
            type: string
        - name: senderAccountIdentifier
          in: query
          description: Filter by sender account identifier
          required: false
          schema:
            type: string
        - name: receiverAccountIdentifier
          in: query
          description: Filter by receiver account identifier
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Filter by transaction status
          required: false
          schema:
            $ref: '#/components/schemas/TransactionStatus'
        - name: type
          in: query
          description: Filter by transaction type
          required: false
          schema:
            $ref: '#/components/schemas/TransactionType'
        - name: reference
          in: query
          description: Filter by reference
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          description: Filter by start date (inclusive) in ISO 8601 format
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: Filter by end date (inclusive) in ISO 8601 format
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
        - name: sortOrder
          in: query
          description: Order to sort results in
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of transactions matching the criteria
                    items:
                      $ref: '#/components/schemas/TransactionOneOf'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of transactions matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transactions/{transactionId}:
    parameters:
      - name: transactionId
        in: path
        description: Unique identifier of the transaction
        required: true
        schema:
          type: string
    get:
      summary: Get transaction by ID
      description: Retrieve detailed information about a specific transaction.
      operationId: getTransactionById
      tags:
        - Transactions
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionOneOf'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transactions/{transactionId}/approve:
    post:
      summary: Approve a pending incoming payment
      description: |
        Approve a pending incoming payment that was previously acknowledged with a 202 response.
        This endpoint allows platforms to asynchronously approve payments after async processing.
      operationId: approvePendingPayment
      tags:
        - Transactions
      security:
        - BasicAuth: []
      parameters:
        - name: transactionId
          in: path
          description: Unique identifier of the transaction to approve
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovePaymentRequest'
      responses:
        '200':
          description: Payment approved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingTransaction'
        '400':
          description: Bad request - Invalid parameters or payment cannot be approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Conflict - Payment is not in a pending state or has already been processed or timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /transactions/{transactionId}/reject:
    post:
      summary: Reject a pending incoming payment
      description: |
        Reject a pending incoming payment that was previously acknowledged with a 202 response.
        This endpoint allows platforms to asynchronously reject payments after additional processing.
      operationId: rejectPendingPayment
      tags:
        - Transactions
      security:
        - BasicAuth: []
      parameters:
        - name: transactionId
          in: path
          description: Unique identifier of the transaction to reject
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectPaymentRequest'
      responses:
        '200':
          description: Payment rejected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingTransaction'
        '400':
          description: Bad request - Invalid parameters or payment cannot be rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Conflict - Payment is not in a pending state or has already been processed or timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /crypto/estimate-withdrawal-fee:
    post:
      summary: Estimate crypto withdrawal fee
      description: |
        Estimate the network and application fees for a cryptocurrency withdrawal from a crypto internal account to an external blockchain address. Use this to show fee information to customers before they initiate a withdrawal.
      operationId: estimateCryptoWithdrawalFee
      tags:
        - Cross-Currency Transfers
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateCryptoWithdrawalFeeRequest'
            examples:
              estimateUSDCWithdrawal:
                summary: Estimate fee for USDC withdrawal on Solana
                value:
                  internalAccountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                  currency: USDC
                  cryptoNetwork: SOLANA_MAINNET
                  amount: 1000000
                  destinationAddress: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
      responses:
        '200':
          description: Fee estimation returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateCryptoWithdrawalFeeResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Internal account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /sandbox/webhooks/test:
    post:
      summary: Send a test webhook
      description: Send a test webhook to the configured endpoint
      operationId: sendTestWebhook
      tags:
        - Sandbox
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Webhook delivered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestWebhookResponse'
        '400':
          description: Bad request - Webhook delivery failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/bulk/csv:
    post:
      summary: Upload customers via CSV file
      description: |
        Upload a CSV file containing customer information for bulk creation. The CSV file should follow
        a specific format with required and optional columns based on customer type.

        ### CSV Format
        The CSV file should have the following columns:

        Required columns for all customers:
        - umaAddress: The customer's UMA address (e.g., $john.doe@uma.domain.com)
        - platformCustomerId: Your platform's unique identifier for the customer
        - customerType: Either "INDIVIDUAL" or "BUSINESS"

        Required columns for individual customers:
        - fullName: Individual's full name
        - birthDate: Date of birth in YYYY-MM-DD format
        - addressLine1: Street address line 1
        - city: City
        - state: State/Province/Region
        - postalCode: Postal/ZIP code
        - country: Country code (ISO 3166-1 alpha-2)

        Required columns for business customers:
        - businessLegalName: Legal name of the business
        - addressLine1: Street address line 1
        - city: City
        - state: State/Province/Region
        - postalCode: Postal/ZIP code
        - country: Country code (ISO 3166-1 alpha-2)

        Optional columns for all customers:
        - addressLine2: Street address line 2
        - platformAccountId: Your platform's identifier for the bank account
        - description: Optional description for the customer

        Optional columns for individual customers:
        - email: Customer's email address

        Optional columns for business customers:
        - businessRegistrationNumber: Business registration number
        - businessTaxId: Tax identification number

        ### Example CSV
        ```csv
        umaAddress,platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,platformAccountId,businessLegalName
        john.doe@uma.domain.com,customer123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US
        acme@uma.domain.com,biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US
        ```

        The upload process is asynchronous and will return a job ID that can be used to track progress.
        You can monitor the job status using the `/customers/bulk/jobs/{jobId}` endpoint.
      operationId: uploadCustomersCsv
      tags:
        - Customers
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file containing customer information
      responses:
        '202':
          description: CSV upload accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCustomerImportJobAccepted'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /customers/bulk/jobs/{jobId}:
    get:
      summary: Get bulk import job status
      description: |
        Retrieve the current status and results of a bulk customer import job. This endpoint can be used
        to track the progress of both CSV uploads.

        The response includes:
        - Overall job status
        - Progress statistics
        - Detailed error information for failed entries
        - Completion timestamp when finished
      operationId: getBulkCustomerImportJob
      tags:
        - Customers
      security:
        - BasicAuth: []
      parameters:
        - name: jobId
          in: path
          description: ID of the bulk import job to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCustomerImportJob'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /invitations:
    post:
      summary: Create an UMA invitation
      description: |
        Create an UMA invitation from a given platform customer.
      operationId: createInvitation
      tags:
        - Invitations
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UmaInvitationCreateRequest'
      responses:
        '201':
          description: Invitation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UmaInvitation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /invitations/{invitationCode}:
    get:
      summary: Get an UMA invitation by code
      description: |
        Retrieve details about an UMA invitation by its invitation code.
      operationId: getInvitation
      tags:
        - Invitations
      security:
        - BasicAuth: []
      parameters:
        - name: invitationCode
          in: path
          description: The code of the invitation to get
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invitation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UmaInvitation'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /invitations/{invitationCode}/claim:
    post:
      summary: Claim an UMA invitation
      description: |
        Claim an UMA invitation by associating it with an invitee UMA address.

        When an invitation is successfully claimed:
        1. The invitation status changes from PENDING to CLAIMED
        2. The invitee UMA address is associated with the invitation
        3. An INVITATION_CLAIMED webhook is triggered to notify the platform that created the invitation

        This endpoint allows customers to accept invitations sent to them by other UMA customers.
      operationId: claimInvitation
      tags:
        - Invitations
      security:
        - BasicAuth: []
      parameters:
        - name: invitationCode
          in: path
          description: The code of the invitation to claim
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UmaInvitationClaimRequest'
      responses:
        '200':
          description: Invitation claimed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UmaInvitation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /invitations/{invitationCode}/cancel:
    post:
      summary: Cancel an UMA invitation
      description: |
        Cancel a pending UMA invitation. Only the inviter or platform can cancel an invitation.

        When an invitation is cancelled:
        1. The invitation status changes from PENDING to CANCELLED
        2. The invitation can no longer be claimed
        3. The invitation URL will show as cancelled when accessed

        Only pending invitations can be cancelled. Attempting to cancel an invitation
        that is already claimed, expired, or cancelled will result in an error.
      operationId: cancelInvitation
      tags:
        - Invitations
      security:
        - BasicAuth: []
      parameters:
        - name: invitationCode
          in: path
          description: The code of the invitation to cancel
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invitation cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UmaInvitation'
        '400':
          description: Bad request - Invitation cannot be cancelled (already claimed, expired, or cancelled)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - Only the platform which created the invitation can cancel it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /sandbox/send:
    post:
      summary: Simulate sending funds
      description: |
        Simulate sending funds to the bank account as instructed in the quote.
        This endpoint is only for the sandbox environment and will fail for production platforms/keys.
      operationId: sandboxSend
      tags:
        - Sandbox
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxSendRequest'
      responses:
        '200':
          description: Funds received successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutgoingTransaction'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - request was made with a production platform token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Quote not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /sandbox/uma/receive:
    post:
      summary: Simulate payment send to test receiving an UMA payment
      description: |
        Simulate sending payment from an sandbox uma address to a platform customer to test payment receive.
        This endpoint is only for the sandbox environment and will fail for production platforms/keys.
      operationId: sandboxReceive
      tags:
        - Sandbox
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxUmaReceiveRequest'
      responses:
        '200':
          description: Payment triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingTransaction'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - request was made with a production platform token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Sender or receiver not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /sandbox/internal-accounts/{accountId}/fund:
    post:
      summary: Simulate funding an internal account
      description: |
        Simulate receiving funds into an internal account in the sandbox environment. This is useful for testing scenarios where you need to add funds to a customer's or platform's internal account without going through a real bank transfer or following payment instructions.
        This endpoint is only for the sandbox environment and will fail for production platforms/keys.
      operationId: sandboxFundInternalAccount
      tags:
        - Sandbox
      security:
        - BasicAuth: []
      parameters:
        - name: accountId
          in: path
          required: true
          description: The ID of the internal account to fund
          schema:
            type: string
          example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxFundRequest'
            examples:
              fundUSDAccount:
                summary: Fund USD internal account with $1,000
                value:
                  amount: 100000
              fundBTCAccount:
                summary: Fund BTC internal account with 0.01 BTC
                value:
                  amount: 1000000
      responses:
        '200':
          description: Internal account funded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden - request was made with a production platform token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Internal account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /uma-providers:
    get:
      summary: List available Counterparty Providers
      description: |
        Retrieve a list of available Counterparty Providers. The response includes basic information about each provider, such as its UMA address, name, and supported currencies.
      operationId: getAvailableUmaProviders
      tags:
        - Available UMA Providers
      parameters:
        - in: query
          name: countryCode
          description: The alpha-2 representation of a country, as defined by the ISO 3166-1 standard.
          required: false
          schema:
            type: string
            example: US
        - in: query
          name: currencyCode
          description: The ISO 4217 currency code to filter providers by supported currency.
          required: false
          schema:
            type: string
            example: USD
        - in: query
          name: hasBlockedProviders
          description: Whether to include providers which are not on your allowlist in the response. By default the response will include blocked providers.
          required: false
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
        - name: sortOrder
          in: query
          description: Order to sort results in
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: List of available UMA Providers using Grid
                    type: array
                    items:
                      $ref: '#/components/schemas/UmaProvider'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of transactions matching the criteria (excluding pagination)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /tokens:
    post:
      summary: Create a new API token
      description: Create a new API token to access the Grid APIs.
      operationId: createToken
      tags:
        - API Tokens
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTokenCreateRequest'
      responses:
        '201':
          description: API token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiToken'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    get:
      summary: List tokens
      description: |
        Retrieve a list of API tokens with optional filtering parameters. Returns all tokens that match
        the specified filters. If no filters are provided, returns all tokens (paginated).
      operationId: listTokens
      tags:
        - API Tokens
      security:
        - BasicAuth: []
      parameters:
        - name: name
          in: query
          description: Filter by name of the token
          required: false
          schema:
            type: string
        - name: createdAfter
          in: query
          description: Filter customers created after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: createdBefore
          in: query
          description: Filter customers created before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedAfter
          in: query
          description: Filter customers updated after this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: updatedBefore
          in: query
          description: Filter customers updated before this timestamp (inclusive)
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results to return (default 20, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (returned from previous request)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    description: List of tokens matching the filter criteria
                    items:
                      $ref: '#/components/schemas/ApiToken'
                  hasMore:
                    type: boolean
                    description: Indicates if more results are available beyond this page
                  nextCursor:
                    type: string
                    description: Cursor to retrieve the next page of results (only present if hasMore is true)
                  totalCount:
                    type: integer
                    description: Total number of tokens matching the criteria (excluding pagination)
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /tokens/{tokenId}:
    parameters:
      - name: tokenId
        in: path
        description: System-generated unique token identifier
        required: true
        schema:
          type: string
    get:
      summary: Get API token by ID
      description: Retrieve an API token by their system-generated ID
      operationId: getTokenById
      tags:
        - API Tokens
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiToken'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
    delete:
      summary: Delete API token by ID
      description: Delete an API token by their system-generated ID
      operationId: deleteTokenById
      tags:
        - API Tokens
      security:
        - BasicAuth: []
      responses:
        '204':
          description: API token deleted successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
webhooks:
  incoming-payment:
    post:
      summary: Incoming payment webhook and approval mechanism
      description: |
        Webhook that is called when an incoming payment is received by a customer's UMA address.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

        ### Payment Approval Flow
        When a transaction has `status: "PENDING"`, this webhook serves as an approval mechanism:

        1. The client should check the `counterpartyInformation` against their requirements
        2. To APPROVE the payment synchronously, return a 200 OK response
        3. To REJECT the payment, return a 403 Forbidden response with an Error object
        4. To request more information, return a 422 Unprocessable Entity with specific missing fields
        5. To process the payment asynchronously, return a 202 Accepted response and then call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint within 5 seconds. Note that synchronous approval/rejection is preferred where possible.

        The Grid system will proceed or cancel the payment based on your response.

        For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational.
      operationId: incomingPaymentWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingPaymentWebhook'
            examples:
              pendingPayment:
                summary: Pending payment example requiring approval
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: INCOMING_PAYMENT.PENDING
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: PENDING
                    type: INCOMING
                    destination:
                      destinationType: UMA_ADDRESS
                      umaAddress: $recipient@uma.domain
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    senderUmaAddress: $sender@external.domain
                    receiverUmaAddress: $recipient@uma.domain
                    receivedAmount:
                      amount: 50000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    counterpartyInformation:
                      FULL_NAME: John Sender
                      BIRTH_DATE: '1985-06-15'
                      NATIONALITY: US
                    reconciliationInstructions:
                      reference: REF-123456789
                    requestedReceiverCustomerInfoFields:
                      - name: NATIONALITY
                        mandatory: true
                      - name: POSTAL_ADDRESS
                        mandatory: false
              incomingCompletedPayment:
                summary: Completed payment notification
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: INCOMING_PAYMENT.COMPLETED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: COMPLETED
                    type: INCOMING
                    destination:
                      destinationType: UMA_ADDRESS
                      umaAddress: $recipient@uma.domain
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    senderUmaAddress: $sender@external.domain
                    receiverUmaAddress: $recipient@uma.domain
                    receivedAmount:
                      amount: 50000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    settledAt: '2025-08-15T14:30:00Z'
                    createdAt: '2025-08-15T14:25:18Z'
                    description: Payment for services
                    reconciliationInstructions:
                      reference: REF-123456789
      responses:
        '200':
          description: |
            Webhook received successfully.
            For PENDING transactions, this indicates approval to proceed with the payment.
            If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverCustomerInfo` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPaymentWebhookResponse'
        '202':
          description: |
            Webhook received and will be processed asynchronously. The synchronous 200 response should be preferred where possible. This asycnhronous path should only be used in
            cases where the platform's architecture requires async (but still very quick) processing before approving or rejecting the payment.
            The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: |
            Forbidden - Payment rejected by the client.
            Only applicable for PENDING transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPaymentWebhookForbiddenResponse'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '422':
          description: |
            Unprocessable Entity - Additional counterparty information required.
            Only applicable for PENDING transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomingPaymentWebhookUnprocessableResponse'
  outgoing-payment:
    post:
      summary: Outgoing payment status webhook
      description: |
        Webhook that is called when an outgoing payment's status changes.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

        This webhook is informational only and is sent when an outgoing payment completes successfully, fails, or is refunded.
      operationId: outgoingPaymentWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutgoingPaymentWebhook'
            examples:
              outgoingCompletedPayment:
                summary: Completed outgoing payment
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: OUTGOING_PAYMENT.COMPLETED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: COMPLETED
                    type: OUTGOING
                    source:
                      sourceType: ACCOUNT
                      accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                    destination:
                      destinationType: ACCOUNT
                      accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    senderUmaAddress: $sender@uma.domain
                    receiverUmaAddress: $recipient@external.domain
                    sentAmount:
                      amount: 10550
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    receivedAmount:
                      amount: 9706
                      currency:
                        code: EUR
                        name: Euro
                        symbol: €
                        decimals: 2
                    exchangeRate: 0.92
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    settledAt: '2025-08-15T14:30:00Z'
                    createdAt: '2025-08-15T14:25:18Z'
                    description: 'Payment for invoice #1234'
                    paymentInstructions: []
                    rateDetails:
                      counterpartyMultiplier: 1.08
                      counterpartyFixedFee: 10
                      gridApiMultiplier: 0.925
                      gridApiFixedFee: 10
                      gridApiVariableFeeRate: 0.003
                      gridApiVariableFeeAmount: 30
              failedPayment:
                summary: Failed outgoing payment
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: OUTGOING_PAYMENT.FAILED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Transaction:019542f5-b3e7-1d02-0000-000000000005
                    status: FAILED
                    type: OUTGOING
                    source:
                      sourceType: ACCOUNT
                      accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
                    destination:
                      destinationType: ACCOUNT
                      accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 18d3e5f7b4a9c2
                    senderUmaAddress: $sender@uma.domain
                    receiverUmaAddress: $recipient@external.domain
                    sentAmount:
                      amount: 10550
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    createdAt: '2025-08-15T14:25:18Z'
                    quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006
                    failureReason: QUOTE_EXECUTION_FAILED
      responses:
        '200':
          description: Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  test-webhook:
    post:
      summary: Test webhook for integration verification
      description: |
        Webhook that is sent once to verify your webhook endpoint is correctly set up.
        This is sent when you configure or update your platform settings with a webhook URL.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by the Grid API.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

        This webhook is purely for testing your endpoint integration and signature verification.
      operationId: testWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestWebhookRequest'
            examples:
              testWebhook:
                summary: Test webhook example
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000001
                  type: TEST
                  timestamp: '2025-08-15T14:32:00Z'
                  data: {}
      responses:
        '200':
          description: Webhook received successfully. This confirms your webhook endpoint is properly configured.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  bulk-upload:
    post:
      summary: Bulk upload status webhook
      description: |
        Webhook that is called when a bulk customer upload job completes or fails.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

        This webhook is sent when a bulk upload job completes or fails, providing detailed information about the results.
      operationId: bulkUploadWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUploadWebhook'
            examples:
              completedUpload:
                summary: Successful bulk upload completion
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: BULK_UPLOAD.COMPLETED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Job:019542f5-b3e7-1d02-0000-000000000006
                    status: COMPLETED
                    progress:
                      total: 5000
                      processed: 5000
                      successful: 5000
                      failed: 0
                    errors: []
              failedUpload:
                summary: Failed bulk upload
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: BULK_UPLOAD.FAILED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Job:019542f5-b3e7-1d02-0000-000000000006
                    status: FAILED
                    progress:
                      total: 5000
                      processed: 5000
                      successful: 0
                      failed: 5000
                    errors:
                      - correlationId: row_1
                        error:
                          code: invalid_csv_format
                          message: Invalid CSV format
                          details:
                            reason: missing_required_column
                            column: umaAddress
      responses:
        '200':
          description: Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  invitation-claimed:
    post:
      summary: Invitation claimed webhook
      description: |
        Webhook that is called when an invitation is claimed by a customer.
        This endpoint should be implemented by platform clients of the Grid API.

        When a customer claims an invitation, this webhook is triggered to notify the platform that:
        1. The invitation has been successfully claimed
        2. The invitee UMA address is now associated with the invitation
        3. The invitation status has changed from PENDING to CLAIMED

        This allows platforms to:
        - Track invitation usage and conversion rates
        - Trigger onboarding flows for new customers who joined via invitation
        - Apply referral bonuses or rewards to the inviter
        - Update their UI to reflect the claimed status

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
      operationId: invitationClaimedWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvitationClaimedWebhook'
            examples:
              claimedInvitation:
                summary: Invitation claimed notification
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: INVITATION.CLAIMED
                  timestamp: '2025-09-01T15:45:00Z'
                  data:
                    code: 019542f5
                    createdAt: '2025-09-01T14:30:00Z'
                    claimedAt: '2025-09-01T15:45:00Z'
                    inviterUma: $inviter@uma.domain
                    inviteeUma: $invitee@uma.domain
                    status: CLAIMED
                    url: https://uma.me/i/019542f5
      responses:
        '200':
          description: Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  customer-update:
    post:
      summary: Customer status change
      description: |
        Webhook that is called when the status of a customer is updated, including KYC and KYB status changes.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid API public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
      operationId: customerStatusWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerWebhook'
            examples:
              kycApprovedWebhook:
                summary: When an individual customer KYC has been approved
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: CUSTOMER.KYC_APPROVED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Customer:019542f5-b3e7-1d02-0000-000000000001
                    platformCustomerId: 9f84e0c2a72c4fa
                    customerType: INDIVIDUAL
                    umaAddress: $john.doe@uma.domain.com
                    kycStatus: APPROVED
                    fullName: John Michael Doe
                    birthDate: '1990-01-15'
                    nationality: US
                    address:
                      line1: 123 Main Street
                      line2: Apt 4B
                      city: San Francisco
                      state: CA
                      postalCode: '94105'
                      country: US
                    createdAt: '2025-07-21T17:32:28Z'
                    updatedAt: '2025-07-21T17:32:28Z'
                    isDeleted: false
              kycRejectedWebhook:
                summary: When an individual customer KYC has been rejected
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000008
                  type: CUSTOMER.KYC_REJECTED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Customer:019542f5-b3e7-1d02-0000-000000000002
                    platformCustomerId: 4b7c1e9d3f5a8e2
                    customerType: INDIVIDUAL
                    umaAddress: $jane.smith@uma.domain.com
                    kycStatus: REJECTED
                    fullName: Jane Smith
                    birthDate: '1988-03-22'
                    nationality: US
                    createdAt: '2025-07-21T17:32:28Z'
                    updatedAt: '2025-08-15T14:32:00Z'
                    isDeleted: false
              kybApprovedWebhook:
                summary: When a business customer KYB has been approved
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000009
                  type: CUSTOMER.KYB_APPROVED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Customer:019542f5-b3e7-1d02-0000-000000000003
                    platformCustomerId: 7a2f9d4e1b8c3f5
                    customerType: BUSINESS
                    umaAddress: $acme.corp@uma.domain.com
                    kybStatus: APPROVED
                    address:
                      line1: 456 Business Ave
                      city: New York
                      state: NY
                      postalCode: '10001'
                      country: US
                    businessInfo:
                      legalName: Acme Corporation
                      registrationNumber: '12345678'
                      taxId: 98-7654321
                    createdAt: '2025-07-21T17:32:28Z'
                    updatedAt: '2025-08-15T14:32:00Z'
                    isDeleted: false
              kybRejectedWebhook:
                summary: When a business customer KYB has been rejected
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000010
                  type: CUSTOMER.KYB_REJECTED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Customer:019542f5-b3e7-1d02-0000-000000000004
                    platformCustomerId: 3c8e5f2a9d1b7e4
                    customerType: BUSINESS
                    umaAddress: $globex.inc@uma.domain.com
                    kybStatus: REJECTED
                    address:
                      line1: 789 Corporate Blvd
                      city: Chicago
                      state: IL
                      postalCode: '60601'
                      country: US
                    businessInfo:
                      legalName: Globex Inc
                    createdAt: '2025-07-21T17:32:28Z'
                    updatedAt: '2025-08-15T14:32:00Z'
                    isDeleted: false
      responses:
        '200':
          description: |
            Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  internal-account-status:
    post:
      summary: Internal account status webhook
      description: |
        Webhook that is called when the status of an internal account changes. This includes balance updates and may include additional account events in the future.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

        ### Event types
        - `INTERNAL_ACCOUNT.BALANCE_UPDATED` — Fired when the balance of an internal account changes. The `data` payload contains the full internal account object.
      operationId: internalAccountStatusWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalAccountStatusWebhook'
            examples:
              balanceDecrease:
                summary: A transaction just cleared a customer account and the balance has decreased
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000007
                  type: INTERNAL_ACCOUNT.BALANCE_UPDATED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    balance:
                      amount: 10000
                      currency:
                        code: USD
                        name: United States Dollar
                        symbol: $
                        decimals: 2
                    fundingPaymentInstructions: []
                    createdAt: '2025-08-01T10:00:00Z'
                    updatedAt: '2025-08-15T14:32:00Z'
      responses:
        '200':
          description: |
            Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
  verification-update:
    post:
      summary: Verification status change
      description: |
        Webhook that is called when a customer's KYC/KYB verification status changes.
        This endpoint should be implemented by clients of the Grid API.

        ### Authentication
        The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid API public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
      operationId: verificationStatusWebhook
      tags:
        - Webhooks
      security:
        - WebhookSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationWebhook'
            examples:
              approved:
                summary: Verification approved
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000030
                  type: VERIFICATION.APPROVED
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Verification:019542f5-b3e7-1d02-0000-000000000010
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    verificationStatus: APPROVED
                    errors: []
                    createdAt: '2025-08-15T14:00:00Z'
              resolveErrors:
                summary: Verification requires action
                value:
                  id: Webhook:019542f5-b3e7-1d02-0000-000000000031
                  type: VERIFICATION.RESOLVE_ERRORS
                  timestamp: '2025-08-15T14:32:00Z'
                  data:
                    id: Verification:019542f5-b3e7-1d02-0000-000000000011
                    customerId: Customer:019542f5-b3e7-1d02-0000-000000000001
                    verificationStatus: RESOLVE_ERRORS
                    errors:
                      - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001
                        type: MISSING_DOCUMENT
                        acceptedDocumentTypes:
                          - PROOF_OF_ADDRESS
                          - UTILITY_BILL
                          - BANK_STATEMENT
                        reason: Proof of address document is required
                    createdAt: '2025-08-15T14:00:00Z'
      responses:
        '200':
          description: |
            Webhook received successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized - Signature validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '409':
          description: Conflict - Webhook has already been processed (duplicate id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: API token authentication using format `<api token id>:<api client secret>`
    WebhookSignature:
      type: apiKey
      in: header
      name: X-Grid-Signature
      description: |
        Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid.
        To verify the signature:
        1. Get the Grid public key provided to you during integration
        2. Decode the base64 signature from the header
        3. Create a SHA-256 hash of the request body
        4. Verify the signature using the public key and the hash

        If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
  schemas:
    CustomerInfoFieldName:
      type: string
      enum:
        - FULL_NAME
        - BIRTH_DATE
        - NATIONALITY
        - PHONE_NUMBER
        - EMAIL
        - POSTAL_ADDRESS
        - TAX_ID
        - REGISTRATION_NUMBER
        - USER_TYPE
        - COUNTRY_OF_RESIDENCE
        - ACCOUNT_IDENTIFIER
        - FI_LEGAL_ENTITY_NAME
        - FI_ADDRESS
        - PURPOSE_OF_PAYMENT
        - ULTIMATE_INSTITUTION_COUNTRY
        - IDENTIFIER
        - BUSINESS_TYPE
      description: Name of a type of field containing info about a platform's customer or counterparty customer.
      example: FULL_NAME
    CounterpartyFieldDefinition:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/CustomerInfoFieldName'
        mandatory:
          type: boolean
          description: Whether the field is mandatory
          example: true
      required:
        - name
        - mandatory
    TransactionType:
      type: string
      enum:
        - INCOMING
        - OUTGOING
      description: Type of transaction (incoming payment or outgoing payment)
    PlatformCurrencyConfig:
      type: object
      properties:
        currencyCode:
          type: string
          description: Three-letter currency code (ISO 4217)
          example: USD
        minAmount:
          type: integer
          format: int64
          description: Minimum amount that can be sent in the smallest unit of this currency
          minimum: 0
          example: 100
        maxAmount:
          type: integer
          format: int64
          description: Maximum amount that can be sent in the smallest unit of this currency
          minimum: 0
          example: 1000000
        requiredCounterpartyFields:
          type: array
          items:
            $ref: '#/components/schemas/CounterpartyFieldDefinition'
          description: List of fields which the platform requires from the counterparty institutions about counterparty customers. Platforms can set mandatory to false if the platform does not require the field, but would like to have it available. Some fields may be required by the underlying UMA provider.
          example:
            - name: FULL_NAME
              mandatory: true
            - name: BIRTH_DATE
              mandatory: true
            - name: NATIONALITY
              mandatory: true
        providerRequiredCustomerFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomerInfoFieldName'
          description: List of customer info field names that are required by the underlying UMA provider when creating a customer for this currency. These fields must be supplied when creating or updating a customer if this currency is intended to be used by that customer. If no fields are required, this field is omitted.
          readOnly: true
          example:
            - NATIONALITY
            - BIRTH_DATE
        providerRequiredCounterpartyCustomerFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomerInfoFieldName'
          description: List of fields that are required by the underlying UMA provider for this currency. If the counterparty does not provide these fields, quote requests will fail.
          readOnly: true
          example:
            - FULL_NAME
            - COUNTRY_OF_RESIDENCE
        enabledTransactionTypes:
          type: array
          items:
            $ref: '#/components/schemas/TransactionType'
          description: List of transaction types that are enabled for this currency.
          example:
            - OUTGOING
            - INCOMING
      required:
        - currencyCode
        - minAmount
        - maxAmount
        - requiredCounterpartyFields
        - enabledTransactionTypes
    PlatformConfig:
      type: object
      properties:
        id:
          type: string
          description: System-generated unique identifier
          readOnly: true
          example: PlatformConfig:019542f5-b3e7-1d02-0000-000000000003
        umaDomain:
          type: string
          description: UMA domain for this platform
          example: platform.uma.domain
        proxyUmaSubdomain:
          type: string
          description: The subdomain that incoming requests will be proxied to
          example: platform
        webhookEndpoint:
          type: string
          description: URL where webhook notifications will be sent
          example: https://api.mycompany.com/webhooks/uma
        supportedCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/PlatformCurrencyConfig'
          description: |
            List of currencies supported by the platform. This is what the platform's
            customers are able to hold, send, and receive.
        isRegulatedFinancialInstitution:
          type: boolean
          description: |
            Whether the platform is a regulated financial institution. This is used to
            determine if the platform's customers must be KYC/KYB'd by Lightspark via
            the KYC link flow. This can only be set by Lightspark during platform
            creation.
          example: false
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          readOnly: true
          example: '2025-06-15T12:30:45Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          readOnly: true
          example: '2025-06-15T12:30:45Z'
    Error401:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 401
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | UNAUTHORIZED | Issue with API credentials |
            | INVALID_SIGNATURE | Signature header is invalid |
          enum:
            - UNAUTHORIZED
            - INVALID_SIGNATURE
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error500:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 500
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | GRID_SWITCH_ERROR | Grid switch error |
            | INTERNAL_ERROR | Internal server or UMA error |
          enum:
            - GRID_SWITCH_ERROR
            - INTERNAL_ERROR
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    PlatformConfigUpdateRequest:
      type: object
      properties:
        umaDomain:
          type: string
          example: mycompany.com
        webhookEndpoint:
          type: string
          example: https://api.mycompany.com/webhooks/uma
        supportedCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/PlatformCurrencyConfig'
    Error400:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 400
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | INVALID_INPUT | Invalid input provided |
            | MISSING_MANDATORY_USER_INFO | Required customer information is missing |
            | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed |
            | INVITATIONS_NOT_CONFIGURED | Invitations are not configured |
            | INVALID_UMA_ADDRESS | UMA address format is invalid |
            | INVITATION_CANCELLED | Invitation has been cancelled |
            | QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable |
            | INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid |
            | INVALID_RECEIVER | Receiver is invalid |
            | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response |
            | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid |
            | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired |
            | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid |
            | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing |
            | SENDER_NOT_ACCEPTED | Sender is not accepted |
            | AMOUNT_OUT_OF_RANGE | Amount is out of range |
            | INVALID_CURRENCY | Currency is invalid |
            | INVALID_TIMESTAMP | Timestamp is invalid |
            | INVALID_NONCE | Nonce is invalid |
            | INVALID_REQUEST_FORMAT | Request format is invalid |
            | INVALID_BANK_ACCOUNT | Bank account is invalid |
            | SELF_PAYMENT | Self payment not allowed |
            | LOOKUP_REQUEST_FAILED | Lookup request failed |
            | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response |
            | INVALID_AMOUNT | Amount is invalid |
            | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set |
            | WEBHOOK_DELIVERY_ERROR | Webhook delivery error |
            | LOW_QUALITY | Document quality too low to process |
            | DATA_MISMATCH | Document details don't match provided information |
            | EXPIRED | Document has expired |
            | SUSPECTED_FRAUD | Document suspected of being forged or edited |
            | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported |
            | INCOMPLETE | Document is missing pages or sides |
          enum:
            - INVALID_INPUT
            - MISSING_MANDATORY_USER_INFO
            - INVITATION_ALREADY_CLAIMED
            - INVITATIONS_NOT_CONFIGURED
            - INVALID_UMA_ADDRESS
            - INVITATION_CANCELLED
            - QUOTE_REQUEST_FAILED
            - INVALID_PAYREQ_RESPONSE
            - INVALID_RECEIVER
            - PARSE_PAYREQ_RESPONSE_ERROR
            - CERT_CHAIN_INVALID
            - CERT_CHAIN_EXPIRED
            - INVALID_PUBKEY_FORMAT
            - MISSING_REQUIRED_UMA_PARAMETERS
            - SENDER_NOT_ACCEPTED
            - AMOUNT_OUT_OF_RANGE
            - INVALID_CURRENCY
            - INVALID_TIMESTAMP
            - INVALID_NONCE
            - INVALID_REQUEST_FORMAT
            - INVALID_BANK_ACCOUNT
            - SELF_PAYMENT
            - LOOKUP_REQUEST_FAILED
            - PARSE_LNURLP_RESPONSE_ERROR
            - INVALID_AMOUNT
            - WEBHOOK_ENDPOINT_NOT_SET
            - WEBHOOK_DELIVERY_ERROR
            - LOW_QUALITY
            - DATA_MISMATCH
            - EXPIRED
            - SUSPECTED_FRAUD
            - UNSUITABLE_DOCUMENT
            - INCOMPLETE
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error501:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 501
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY | Unrecognized mandatory payee data key |
            | NOT_IMPLEMENTED | Feature not implemented |
          enum:
            - UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY
            - NOT_IMPLEMENTED
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Currency:
      type: object
      properties:
        code:
          type: string
          description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.)
          example: USD
        name:
          type: string
          description: Full name of the currency
          example: United States Dollar
        symbol:
          type: string
          description: Symbol of the currency
          example: $
        decimals:
          type: integer
          description: Number of decimal places for the currency
          minimum: 0
          example: 2
    ExchangeRateFees:
      type: object
      description: Fees associated with an exchange rate
      properties:
        fixed:
          type: integer
          format: int64
          description: Fixed fee in the smallest unit of the sending currency (e.g., cents for USD)
          minimum: 0
          example: 100
    ExchangeRate:
      type: object
      description: Exchange rate information for a currency corridor
      required:
        - sourceCurrency
        - destinationCurrency
        - destinationPaymentRail
        - minSendingAmount
        - maxSendingAmount
        - sendingAmount
        - receivingAmount
        - exchangeRate
        - fees
        - updatedAt
      properties:
        sourceCurrency:
          $ref: '#/components/schemas/Currency'
        sendingAmount:
          type: integer
          format: int64
          description: The sending amount in the smallest unit of the source currency (e.g., cents for USD). Echoed back from the request if provided.
          minimum: 0
          example: 10000
        minSendingAmount:
          type: integer
          format: int64
          description: The minimum supported sending amount in the smallest unit of the source currency.
          minimum: 0
          example: 100
        maxSendingAmount:
          type: integer
          format: int64
          description: The maximum supported sending amount in the smallest unit of the source currency.
          minimum: 0
          example: 10000000
        destinationCurrency:
          $ref: '#/components/schemas/Currency'
        destinationPaymentRail:
          type: string
          description: The payment rail used for the destination (e.g., UPI, SEPA_INSTANT, MOBILE_MONEY, FASTER_PAYMENTS)
          example: UPI
        receivingAmount:
          type: integer
          format: int64
          description: The receiving amount in the smallest unit of the destination currency
          minimum: 0
          example: 1650000
        exchangeRate:
          type: number
          description: Number of sending currency units per receiving currency unit.
          exclusiveMinimum: 0
          example: 82.5
        fees:
          $ref: '#/components/schemas/ExchangeRateFees'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this exchange rate was last refreshed
          example: '2025-02-05T12:00:00Z'
    CustomerType:
      type: string
      enum:
        - INDIVIDUAL
        - BUSINESS
      description: Whether the customer is an individual or a business entity
      example: INDIVIDUAL
    Customer:
      type: object
      required:
        - umaAddress
        - platformCustomerId
        - customerType
      properties:
        id:
          type: string
          description: System-generated unique identifier
          readOnly: true
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        platformCustomerId:
          type: string
          description: Platform-specific customer identifier
          example: 9f84e0c2a72c4fa
        customerType:
          $ref: '#/components/schemas/CustomerType'
        umaAddress:
          type: string
          description: Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
          example: $john.doe@uma.domain.com
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          readOnly: true
          example: '2025-07-21T17:32:28Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          readOnly: true
          example: '2025-07-21T17:32:28Z'
        isDeleted:
          type: boolean
          description: Whether the customer is marked as deleted
          example: false
          readOnly: true
    KycStatus:
      type: string
      enum:
        - UNVERIFIED
        - PENDING
        - APPROVED
        - REJECTED
      description: The current KYC status of a customer
      example: APPROVED
    Address:
      type: object
      required:
        - line1
        - postalCode
        - country
      properties:
        line1:
          type: string
          description: Street address line 1
          example: 123 Main Street
        line2:
          type: string
          description: Street address line 2
          example: Apt 4B
        city:
          type: string
          description: City
          example: San Francisco
        state:
          type: string
          description: State/Province/Region
          example: CA
        postalCode:
          type: string
          description: Postal/ZIP code
          example: '94105'
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US
    IndividualCustomerFields:
      type: object
      required:
        - customerType
      properties:
        customerType:
          type: string
          enum:
            - INDIVIDUAL
        kycStatus:
          $ref: '#/components/schemas/KycStatus'
        fullName:
          type: string
          description: Individual's full name
          example: John Michael Doe
        birthDate:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD)
          example: '1990-01-15'
        nationality:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US
        address:
          $ref: '#/components/schemas/Address'
    IndividualCustomer:
      title: Individual Customer
      allOf:
        - $ref: '#/components/schemas/Customer'
        - $ref: '#/components/schemas/IndividualCustomerFields'
    KybStatus:
      type: string
      enum:
        - UNVERIFIED
        - PENDING
        - APPROVED
        - REJECTED
      description: The current KYB status of a business customer
      example: APPROVED
    EntityType:
      type: string
      enum:
        - SOLE_PROPRIETORSHIP
        - PARTNERSHIP
        - LLC
        - CORPORATION
        - S_CORPORATION
        - NON_PROFIT
        - OTHER
      description: Legal entity type of the business
      example: LLC
    BusinessType:
      type: string
      description: The high-level industry category of the business
      enum:
        - AGRICULTURE_FORESTRY_FISHING_AND_HUNTING
        - MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION
        - UTILITIES
        - CONSTRUCTION
        - MANUFACTURING
        - WHOLESALE_TRADE
        - RETAIL_TRADE
        - TRANSPORTATION_AND_WAREHOUSING
        - INFORMATION
        - FINANCE_AND_INSURANCE
        - REAL_ESTATE_AND_RENTAL_AND_LEASING
        - PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES
        - MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES
        - ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES
        - EDUCATIONAL_SERVICES
        - HEALTH_CARE_AND_SOCIAL_ASSISTANCE
        - ARTS_ENTERTAINMENT_AND_RECREATION
        - ACCOMMODATION_AND_FOOD_SERVICES
        - OTHER_SERVICES
        - PUBLIC_ADMINISTRATION
    BusinessInfoUpdate:
      type: object
      description: Additional information for business entities
      properties:
        legalName:
          type: string
          description: Legal name of the business
          example: Acme Corporation, Inc.
        doingBusinessAs:
          type: string
          description: Trade name or DBA name of the business, if different from the legal name
          example: Acme
        country:
          type: string
          description: Country of incorporation or registration (ISO 3166-1 alpha-2)
          example: US
        registrationNumber:
          type: string
          description: Business registration number
          example: '5523041'
        incorporatedOn:
          type: string
          format: date
          description: Date of incorporation in ISO 8601 format (YYYY-MM-DD)
          example: '2018-03-14'
        entityType:
          $ref: '#/components/schemas/EntityType'
        taxId:
          type: string
          description: Tax identification number
          example: 47-1234567
        countriesOfOperation:
          type: array
          items:
            type: string
          description: List of countries where the business operates (ISO 3166-1 alpha-2)
          example:
            - US
        businessType:
          $ref: '#/components/schemas/BusinessType'
        purposeOfAccount:
          type: string
          description: The intended purpose for using the Grid account
          example: Payout to contractors
        sourceOfFunds:
          type: string
          description: The primary source of funds for the business
          example: Funds derived from customer payments for software services
        expectedMonthlyTransactionCount:
          type: string
          description: Expected number of transactions per month
          example: 100_TO_500
        expectedMonthlyTransactionVolume:
          type: string
          description: Expected total transaction volume per month in USD equivalent
          example: 100K_TO_1M
        expectedRecipientJurisdictions:
          type: array
          items:
            type: string
          description: List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
          example:
            - US
    BusinessCustomerFields:
      type: object
      required:
        - customerType
      properties:
        customerType:
          type: string
          enum:
            - BUSINESS
        kybStatus:
          $ref: '#/components/schemas/KybStatus'
        address:
          $ref: '#/components/schemas/Address'
        businessInfo:
          $ref: '#/components/schemas/BusinessInfoUpdate'
    BusinessInfo:
      type: object
      description: Additional information required for business entities
      required:
        - legalName
      properties:
        legalName:
          type: string
          description: Legal name of the business
          example: Acme Corporation, Inc.
        doingBusinessAs:
          type: string
          description: Trade name or DBA name of the business, if different from the legal name
          example: Acme
        country:
          type: string
          description: Country of incorporation or registration (ISO 3166-1 alpha-2)
          example: US
        registrationNumber:
          type: string
          description: Business registration number
          example: '5523041'
        incorporatedOn:
          type: string
          format: date
          description: Date of incorporation in ISO 8601 format (YYYY-MM-DD)
          example: '2018-03-14'
        entityType:
          $ref: '#/components/schemas/EntityType'
        taxId:
          type: string
          description: Tax identification number
          example: 47-1234567
        countriesOfOperation:
          type: array
          items:
            type: string
          description: List of countries where the business operates (ISO 3166-1 alpha-2)
          example:
            - US
        businessType:
          $ref: '#/components/schemas/BusinessType'
        purposeOfAccount:
          type: string
          description: The intended purpose for using the Grid account
          example: Payout to contractors
        sourceOfFunds:
          type: string
          description: The primary source of funds for the business
          example: Funds derived from customer payments for software services
        expectedMonthlyTransactionCount:
          type: string
          description: Expected number of transactions per month
          example: 100_TO_500
        expectedMonthlyTransactionVolume:
          type: string
          description: Expected total transaction volume per month in USD equivalent
          example: 100K_TO_1M
        expectedRecipientJurisdictions:
          type: array
          items:
            type: string
          description: List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
          example:
            - US
    UltimateBeneficialOwner:
      type: object
      required:
        - fullName
        - individualType
      properties:
        fullName:
          type: string
          description: Individual's full name
          example: John Michael Doe
        emailAddress:
          type: string
          format: email
          description: Email address of the individual
          example: example@test.com
        phoneNumber:
          type: string
          description: Phone number of the individual in E.164 format
          example: '+5555555555'
          pattern: ^\+[1-9]\d{1,14}$
        taxId:
          type: string
          description: Tax identification number of the individual. This could be a Social Security Number (SSN) for US individuals, Tax Identification Number (TIN) for non-US individuals, or a Passport Number.
          example: EIN-987654321
        birthDate:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD)
          example: '1990-01-15'
        nationality:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: US
        address:
          $ref: '#/components/schemas/Address'
        individualType:
          type: string
          enum:
            - DIRECTOR
            - CONTROL_PERSON
            - BUSINESS_POINT_OF_CONTACT
            - TRUSTEE
            - SETTLOR
            - GENERAL_PARTNER
          description: Type of individual in the corporation
          example: DIRECTOR
        percentageOwnership:
          type: number
          description: Percent of ownership when individual type is beneficial owner
          example: 25
        title:
          type: string
          description: Title at company
          example: CEO, COO, President
    BusinessCustomer:
      title: Business Customer
      allOf:
        - $ref: '#/components/schemas/Customer'
        - $ref: '#/components/schemas/BusinessCustomerFields'
        - type: object
          properties:
            businessInfo:
              $ref: '#/components/schemas/BusinessInfo'
            beneficialOwners:
              type: array
              items:
                $ref: '#/components/schemas/UltimateBeneficialOwner'
    CustomerOneOf:
      oneOf:
        - $ref: '#/components/schemas/IndividualCustomer'
        - $ref: '#/components/schemas/BusinessCustomer'
      discriminator:
        propertyName: customerType
        mapping:
          INDIVIDUAL: '#/components/schemas/IndividualCustomer'
          BUSINESS: '#/components/schemas/BusinessCustomer'
    CustomerCreateRequest:
      type: object
      required:
        - customerType
        - platformCustomerId
      properties:
        platformCustomerId:
          type: string
          description: Platform-specific customer identifier. If not provided, one will be generated by the system.
          example: 9f84e0c2a72c4fa
        customerType:
          $ref: '#/components/schemas/CustomerType'
        umaAddress:
          type: string
          description: Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer.
          example: $john.doe@uma.domain.com
    IndividualCustomerCreateRequest:
      title: Individual Customer Create Request
      allOf:
        - $ref: '#/components/schemas/CustomerCreateRequest'
        - $ref: '#/components/schemas/IndividualCustomerFields'
    BusinessCustomerCreateRequest:
      title: Business Customer Create Request
      allOf:
        - $ref: '#/components/schemas/CustomerCreateRequest'
        - $ref: '#/components/schemas/BusinessCustomerFields'
        - type: object
          properties:
            businessInfo:
              $ref: '#/components/schemas/BusinessInfo'
    CustomerCreateRequestOneOf:
      oneOf:
        - $ref: '#/components/schemas/IndividualCustomerCreateRequest'
        - $ref: '#/components/schemas/BusinessCustomerCreateRequest'
      discriminator:
        propertyName: customerType
        mapping:
          INDIVIDUAL: '#/components/schemas/IndividualCustomerCreateRequest'
          BUSINESS: '#/components/schemas/BusinessCustomerCreateRequest'
    Error409:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 409
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval |
            | UMA_ADDRESS_EXISTS | UMA address already exists |
          enum:
            - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL
            - UMA_ADDRESS_EXISTS
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error404:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 404
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | TRANSACTION_NOT_FOUND | Transaction not found |
            | INVITATION_NOT_FOUND | Invitation not found |
            | USER_NOT_FOUND | Customer not found |
            | QUOTE_NOT_FOUND | Quote not found |
            | LOOKUP_REQUEST_NOT_FOUND | Lookup request not found |
            | TOKEN_NOT_FOUND | Token not found |
            | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found |
            | REFERENCE_NOT_FOUND | Reference not found |
          enum:
            - TRANSACTION_NOT_FOUND
            - INVITATION_NOT_FOUND
            - USER_NOT_FOUND
            - QUOTE_NOT_FOUND
            - LOOKUP_REQUEST_NOT_FOUND
            - TOKEN_NOT_FOUND
            - BULK_UPLOAD_JOB_NOT_FOUND
            - REFERENCE_NOT_FOUND
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error410:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 410
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | CUSTOMER_DELETED | Customer has been permanently deleted |
          enum:
            - CUSTOMER_DELETED
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    CustomerUpdateRequest:
      type: object
      required:
        - customerType
      properties:
        customerType:
          $ref: '#/components/schemas/CustomerType'
        umaAddress:
          type: string
          description: Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer.
          example: $john.doe@uma.domain.com
    IndividualCustomerUpdateRequest:
      title: Individual Customer Update Request
      allOf:
        - $ref: '#/components/schemas/CustomerUpdateRequest'
        - $ref: '#/components/schemas/IndividualCustomerFields'
    BusinessCustomerUpdateRequest:
      title: Business Customer Update Request
      allOf:
        - $ref: '#/components/schemas/CustomerUpdateRequest'
        - $ref: '#/components/schemas/BusinessCustomerFields'
    CustomerUpdateRequestOneOf:
      oneOf:
        - $ref: '#/components/schemas/IndividualCustomerUpdateRequest'
        - $ref: '#/components/schemas/BusinessCustomerUpdateRequest'
      discriminator:
        propertyName: customerType
        mapping:
          INDIVIDUAL: '#/components/schemas/IndividualCustomerUpdateRequest'
          BUSINESS: '#/components/schemas/BusinessCustomerUpdateRequest'
    KycLinkResponse:
      type: object
      properties:
        kycUrl:
          type: string
          description: A hosted KYC link for your customer to complete KYC
          example: https://example.com/redirect
        platformCustomerId:
          type: string
          description: The platform id of the customer to onboard
          example: 019542f5-b3e7-1d02-0000-000000000001
        customerId:
          type: string
          description: The customer id of the newly created customer on the system
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
    CurrencyAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          format: int64
          description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
          example: 12550
        currency:
          $ref: '#/components/schemas/Currency'
    PaymentAccountType:
      type: string
      enum:
        - USD_ACCOUNT
        - BRL_ACCOUNT
        - MXN_ACCOUNT
        - DKK_ACCOUNT
        - EUR_ACCOUNT
        - INR_ACCOUNT
        - NGN_ACCOUNT
        - CAD_ACCOUNT
        - GBP_ACCOUNT
        - HKD_ACCOUNT
        - IDR_ACCOUNT
        - MYR_ACCOUNT
        - PHP_ACCOUNT
        - SGD_ACCOUNT
        - THB_ACCOUNT
        - VND_ACCOUNT
        - SPARK_WALLET
        - LIGHTNING
        - SOLANA_WALLET
        - TRON_WALLET
        - POLYGON_WALLET
        - BASE_WALLET
        - ETHEREUM_WALLET
      description: Type of payment account or wallet
      example: USD_ACCOUNT
    BasePaymentAccountInfo:
      type: object
      required:
        - accountType
      properties:
        accountType:
          $ref: '#/components/schemas/PaymentAccountType'
    UsdAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - accountNumber
        - routingNumber
      properties:
        accountType:
          type: string
          enum:
            - USD_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - ACH
              - WIRE
              - RTP
              - FEDNOW
        accountNumber:
          type: string
          description: The account number of the bank
          minLength: 1
          maxLength: 34
        routingNumber:
          type: string
          description: The ABA routing number
          example: '021000021'
          minLength: 9
          maxLength: 9
          pattern: ^[0-9]{9}$
    PaymentUsdAccountInfo:
      title: USD Bank Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/UsdAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    PaymentBrlAccountInfo:
      title: BRL Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - type: object
          required:
            - qrCode
          properties:
            accountType:
              type: string
              enum:
                - BRL_ACCOUNT
            qrCode:
              type: string
              description: A PIX QR code payload that can be used to fund the transaction. This can be rendered as a QR code image or pasted into a PIX-compatible banking app.
              minLength: 1
    MxnAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - clabeNumber
      properties:
        accountType:
          type: string
          enum:
            - MXN_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - SPEI
        clabeNumber:
          type: string
          description: The CLABE number of the bank
          example: '123456789012345678'
          minLength: 18
          maxLength: 18
          pattern: ^[0-9]{18}$
    PaymentMxnAccountInfo:
      title: MXN Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/MxnAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    DkkAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - iban
      properties:
        accountType:
          type: string
          enum:
            - DKK_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - SEPA
              - SEPA_INSTANT
        iban:
          type: string
          description: The IBAN of the bank account
          example: DE89370400440532013000
          minLength: 15
          maxLength: 34
          pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: DEUTDEFF
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentDkkAccountInfo:
      title: DKK Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/DkkAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    EurAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - iban
      properties:
        accountType:
          type: string
          enum:
            - EUR_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - SEPA
              - SEPA_INSTANT
        iban:
          type: string
          description: The IBAN of the bank account
          example: DE89370400440532013000
          minLength: 15
          maxLength: 34
          pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: DEUTDEFF
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentEurAccountInfo:
      title: EUR Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/EurAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    InrAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - vpa
      properties:
        accountType:
          type: string
          enum:
            - INR_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - UPI
        vpa:
          type: string
          description: The UPI Virtual Payment Address
          example: user@upi
          minLength: 3
          maxLength: 255
          pattern: ^[a-zA-Z0-9.\-_]+@[a-zA-Z0-9]+$
    PaymentInrAccountInfo:
      title: INR Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/InrAccountInfo'
    NgnAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - accountNumber
        - bankName
      properties:
        accountType:
          type: string
          enum:
            - NGN_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        accountNumber:
          type: string
          description: Nigerian bank account number
          minLength: 10
          maxLength: 10
          example: 123456789
          pattern: ^[0-9]{10}$
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
    PaymentNgnAccountInfo:
      title: NGN Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/NgnAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    CadAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankCode
        - branchCode
        - accountNumber
      properties:
        accountType:
          type: string
          enum:
            - CAD_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankCode:
          type: string
          description: Canadian financial institution number (3 digits)
          example: '001'
          minLength: 3
          maxLength: 3
          pattern: ^[0-9]{3}$
        branchCode:
          type: string
          description: Transit number identifying the branch (5 digits)
          example: '00012'
          minLength: 5
          maxLength: 5
          pattern: ^[0-9]{5}$
        accountNumber:
          type: string
          description: Bank account number (7-12 digits)
          example: '1234567'
          minLength: 7
          maxLength: 12
          pattern: ^[0-9]{7,12}$
    PaymentCadAccountInfo:
      title: CAD Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/CadAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    GbpAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - sortCode
        - accountNumber
      properties:
        accountType:
          type: string
          enum:
            - GBP_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - FASTER_PAYMENTS
        sortCode:
          type: string
          description: The UK sort code
          example: '123456'
          minLength: 6
          maxLength: 6
          pattern: ^[0-9]{6}$
        accountNumber:
          type: string
          description: UK bank account number (8 digits)
          minLength: 8
          maxLength: 8
          example: '12345678'
          pattern: ^[0-9]{8}$
    PaymentGbpAccountInfo:
      title: GBP Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/GbpAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    HkdAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
      properties:
        accountType:
          type: string
          enum:
            - HKD_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
        accountNumber:
          type: string
          description: Hong Kong bank account number
          minLength: 1
          maxLength: 34
          example: '123456789012'
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: HSBCHKHHHKH
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentHkdAccountInfo:
      title: HKD Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/HkdAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    IdrAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
        - phoneNumber
      properties:
        accountType:
          type: string
          enum:
            - IDR_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
          example: Bank Central Asia
        accountNumber:
          type: string
          description: Indonesian bank account number
          minLength: 1
          maxLength: 34
          example: '1234567890'
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: CENAIDJA
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
        phoneNumber:
          type: string
          description: Indonesian phone number for e-wallet payments
          example: '+6281234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+62[0-9]{9,12}$
    PaymentIdrAccountInfo:
      title: IDR Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/IdrAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    MyrAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
      properties:
        accountType:
          type: string
          enum:
            - MYR_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
        accountNumber:
          type: string
          description: Malaysian bank account number
          minLength: 1
          maxLength: 34
          example: '1234567890'
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: MABORUMMYYY
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentMyrAccountInfo:
      title: MYR Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/MyrAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    PhpAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
      properties:
        accountType:
          type: string
          enum:
            - PHP_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: Name of the beneficiary's bank
          minLength: 1
          maxLength: 255
          example: BDO Unibank
        accountNumber:
          type: string
          description: Bank account number
          minLength: 1
          maxLength: 34
          example: 1234567890
    PaymentPhpAccountInfo:
      title: PHP Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/PhpAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    SgdAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
      properties:
        accountType:
          type: string
          enum:
            - SGD_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - PAYNOW
              - FAST
              - BANK_TRANSFER
        bankName:
          type: string
          description: Name of the beneficiary's bank
          minLength: 1
          maxLength: 255
          example: DBS Bank Ltd
        accountNumber:
          type: string
          description: Bank account number
          minLength: 1
          maxLength: 34
          example: 123456789
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: DBSSSGSG
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentSgdAccountInfo:
      title: SGD Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/SgdAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    ThbAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
      properties:
        accountType:
          type: string
          enum:
            - THB_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
        accountNumber:
          type: string
          description: Thai bank account number
          minLength: 1
          maxLength: 34
          example: '1234567890'
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: BKKBTHBK
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentThbAccountInfo:
      title: THB Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/ThbAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    VndAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - bankName
        - accountNumber
        - swiftCode
      properties:
        accountType:
          type: string
          enum:
            - VND_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
        accountNumber:
          type: string
          description: Vietnamese bank account number
          minLength: 1
          maxLength: 34
          example: '1234567890'
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: BFTVVNVX
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentVndAccountInfo:
      title: VND Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/VndAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    SparkWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - SPARK_WALLET
        address:
          type: string
          description: Spark wallet address
          example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
    PaymentSparkWalletInfo:
      title: Spark Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/SparkWalletInfo'
        - type: object
          required:
            - assetType
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - BTC
                - USDB
            invoice:
              type: string
              description: Invoice for the payment
              example: sparkrt1pgss8ter0fhc4c220f3zftmpz49h8wqte8eg3m5zkrraplgc048jucgszg3ssqgjzqqekv73mmh842yj7drsjwh7t7tz5zt8wf5kghm5v4ehggszppjp5s80cg3qjdzc55g2567tn3lj705hdsr577tg8ah795mlnt6807y657qhkmgfkf9w75p4wz3l8vhua85zdn6ryj32zuj0p00pv2l5z4u47mw6h4s
    PaymentLightningInvoiceInfo:
      title: Lightning Invoice
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - type: object
          required:
            - invoice
          properties:
            accountType:
              type: string
              enum:
                - LIGHTNING
            invoice:
              type: string
              description: Invoice for the payment
              example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
    SolanaWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - SOLANA_WALLET
        address:
          type: string
          description: Solana wallet address
          example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg
    PaymentSolanaWalletInfo:
      title: Solana Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/SolanaWalletInfo'
        - type: object
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - USDC
                - USDT
    TronWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - TRON_WALLET
        address:
          type: string
          description: Tron wallet address
          example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
    PaymentTronWalletInfo:
      title: Tron Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/TronWalletInfo'
        - type: object
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - USDT
    PolygonWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - POLYGON_WALLET
        address:
          type: string
          description: Polygon eth wallet address
          example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12'
    PaymentPolygonWalletInfo:
      title: Polygon Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/PolygonWalletInfo'
        - type: object
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - USDC
    BaseWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - BASE_WALLET
        address:
          type: string
          description: Base eth wallet address
          example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12'
    PaymentBaseWalletInfo:
      title: Base Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/BaseWalletInfo'
        - type: object
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - USDC
    EthereumWalletInfo:
      type: object
      required:
        - address
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - ETHEREUM_WALLET
        address:
          type: string
          description: Ethereum L1 wallet address
          example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12'
    PaymentEthereumWalletInfo:
      title: Ethereum Wallet
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/EthereumWalletInfo'
        - type: object
          properties:
            assetType:
              type: string
              description: Type of asset
              enum:
                - USDC
    AedAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - iban
      properties:
        accountType:
          type: string
          enum:
            - AED_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        iban:
          type: string
          description: UAE IBAN (23 characters, starting with AE)
          example: AE070331234567890123456
          minLength: 23
          maxLength: 23
          pattern: ^AE[0-9]{21}$
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: EBILAEAD
          minLength: 8
          maxLength: 11
          pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
    PaymentAedAccountInfo:
      title: AED Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/AedAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    KesAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - KES_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: Kenyan mobile money phone number
          example: '+254712345678'
          minLength: 7
          maxLength: 15
          pattern: ^\+254[0-9]{9}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentKesAccountInfo:
      title: KES Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/KesAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    MwkAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - MWK_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: The phone number in international format
          example: '+1234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+[0-9]{6,14}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentMwkAccountInfo:
      title: MWK Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/MwkAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    RwfAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - RWF_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: Rwandan mobile money phone number
          example: '+250781234567'
          minLength: 7
          maxLength: 15
          pattern: ^\+250[0-9]{9}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentRwfAccountInfo:
      title: RWF Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/RwfAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    TzsAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - TZS_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: Tanzanian mobile money phone number
          example: '+255712345678'
          minLength: 7
          maxLength: 15
          pattern: ^\+255[0-9]{9}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentTzsAccountInfo:
      title: TZS Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/TzsAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    UgxAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - UGX_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: The phone number in international format
          example: '+1234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+[0-9]{6,14}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentUgxAccountInfo:
      title: UGX Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/UgxAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    XofAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
        - region
      properties:
        accountType:
          type: string
          enum:
            - XOF_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: The phone number in international format
          example: '+1234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+[0-9]{6,14}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
        region:
          type: string
          description: Country code within the West African CFA franc zone
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          enum:
            - BJ
            - CI
            - SN
            - TG
    PaymentXofAccountInfo:
      title: XOF Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/XofAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    ZarAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - accountNumber
        - bankName
      properties:
        accountType:
          type: string
          enum:
            - ZAR_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - BANK_TRANSFER
        accountNumber:
          type: string
          description: South African bank account number
          minLength: 9
          maxLength: 13
          example: '1234567890'
          pattern: ^[0-9]{9,13}$
        bankName:
          type: string
          description: The name of the bank
          minLength: 1
          maxLength: 255
    PaymentZarAccountInfo:
      title: ZAR Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/ZarAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    ZmwAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - ZMW_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: Zambian mobile money phone number
          example: '+260971234567'
          minLength: 7
          maxLength: 15
          pattern: ^\+260[0-9]{9}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentZmwAccountInfo:
      title: ZMW Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/ZmwAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    BwpAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
      properties:
        accountType:
          type: string
          enum:
            - BWP_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: The phone number in international format
          example: '+1234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+[0-9]{6,14}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
    PaymentBwpAccountInfo:
      title: BWP Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/BwpAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    XafAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - phoneNumber
        - provider
        - region
      properties:
        accountType:
          type: string
          enum:
            - XAF_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - MOBILE_MONEY
        phoneNumber:
          type: string
          description: The phone number in international format
          example: '+1234567890'
          minLength: 7
          maxLength: 15
          pattern: ^\+[0-9]{6,14}$
        provider:
          type: string
          description: The mobile money provider name
          minLength: 1
          maxLength: 255
        region:
          type: string
          description: Country code within the Central African CFA franc zone
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          enum:
            - CM
            - CG
    PaymentXafAccountInfo:
      title: XAF Account
      allOf:
        - $ref: '#/components/schemas/BasePaymentAccountInfo'
        - $ref: '#/components/schemas/XafAccountInfo'
        - type: object
          required:
            - reference
          properties:
            reference:
              type: string
              description: Unique reference code that must be included with the payment to properly credit it
              example: UMA-Q12345-REF
    PaymentInstructions:
      type: object
      required:
        - accountOrWalletInfo
      properties:
        instructionsNotes:
          type: string
          description: Additional human-readable instructions for making the payment
          example: Please ensure the reference code is included in the payment memo/description field
        isPlatformAccount:
          type: boolean
          description: Indicates whether the account is a platform account or a customer account.
          example: true
        accountOrWalletInfo:
          oneOf:
            - $ref: '#/components/schemas/PaymentUsdAccountInfo'
            - $ref: '#/components/schemas/PaymentBrlAccountInfo'
            - $ref: '#/components/schemas/PaymentMxnAccountInfo'
            - $ref: '#/components/schemas/PaymentDkkAccountInfo'
            - $ref: '#/components/schemas/PaymentEurAccountInfo'
            - $ref: '#/components/schemas/PaymentInrAccountInfo'
            - $ref: '#/components/schemas/PaymentNgnAccountInfo'
            - $ref: '#/components/schemas/PaymentCadAccountInfo'
            - $ref: '#/components/schemas/PaymentGbpAccountInfo'
            - $ref: '#/components/schemas/PaymentHkdAccountInfo'
            - $ref: '#/components/schemas/PaymentIdrAccountInfo'
            - $ref: '#/components/schemas/PaymentMyrAccountInfo'
            - $ref: '#/components/schemas/PaymentPhpAccountInfo'
            - $ref: '#/components/schemas/PaymentSgdAccountInfo'
            - $ref: '#/components/schemas/PaymentThbAccountInfo'
            - $ref: '#/components/schemas/PaymentVndAccountInfo'
            - $ref: '#/components/schemas/PaymentAedAccountInfo'
            - $ref: '#/components/schemas/PaymentKesAccountInfo'
            - $ref: '#/components/schemas/PaymentMwkAccountInfo'
            - $ref: '#/components/schemas/PaymentRwfAccountInfo'
            - $ref: '#/components/schemas/PaymentTzsAccountInfo'
            - $ref: '#/components/schemas/PaymentUgxAccountInfo'
            - $ref: '#/components/schemas/PaymentXofAccountInfo'
            - $ref: '#/components/schemas/PaymentZarAccountInfo'
            - $ref: '#/components/schemas/PaymentZmwAccountInfo'
            - $ref: '#/components/schemas/PaymentBwpAccountInfo'
            - $ref: '#/components/schemas/PaymentXafAccountInfo'
            - $ref: '#/components/schemas/PaymentSparkWalletInfo'
            - $ref: '#/components/schemas/PaymentLightningInvoiceInfo'
            - $ref: '#/components/schemas/PaymentSolanaWalletInfo'
            - $ref: '#/components/schemas/PaymentTronWalletInfo'
            - $ref: '#/components/schemas/PaymentPolygonWalletInfo'
            - $ref: '#/components/schemas/PaymentBaseWalletInfo'
            - $ref: '#/components/schemas/PaymentEthereumWalletInfo'
          discriminator:
            propertyName: accountType
            mapping:
              USD_ACCOUNT: '#/components/schemas/PaymentUsdAccountInfo'
              BRL_ACCOUNT: '#/components/schemas/PaymentBrlAccountInfo'
              MXN_ACCOUNT: '#/components/schemas/PaymentMxnAccountInfo'
              DKK_ACCOUNT: '#/components/schemas/PaymentDkkAccountInfo'
              EUR_ACCOUNT: '#/components/schemas/PaymentEurAccountInfo'
              INR_ACCOUNT: '#/components/schemas/PaymentInrAccountInfo'
              NGN_ACCOUNT: '#/components/schemas/PaymentNgnAccountInfo'
              CAD_ACCOUNT: '#/components/schemas/PaymentCadAccountInfo'
              GBP_ACCOUNT: '#/components/schemas/PaymentGbpAccountInfo'
              HKD_ACCOUNT: '#/components/schemas/PaymentHkdAccountInfo'
              IDR_ACCOUNT: '#/components/schemas/PaymentIdrAccountInfo'
              MYR_ACCOUNT: '#/components/schemas/PaymentMyrAccountInfo'
              PHP_ACCOUNT: '#/components/schemas/PaymentPhpAccountInfo'
              SGD_ACCOUNT: '#/components/schemas/PaymentSgdAccountInfo'
              THB_ACCOUNT: '#/components/schemas/PaymentThbAccountInfo'
              VND_ACCOUNT: '#/components/schemas/PaymentVndAccountInfo'
              SPARK_WALLET: '#/components/schemas/PaymentSparkWalletInfo'
              LIGHTNING: '#/components/schemas/PaymentLightningInvoiceInfo'
              SOLANA_WALLET: '#/components/schemas/PaymentSolanaWalletInfo'
              TRON_WALLET: '#/components/schemas/PaymentTronWalletInfo'
              POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo'
              BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo'
              ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo'
              AED_ACCOUNT: '#/components/schemas/PaymentAedAccountInfo'
              KES_ACCOUNT: '#/components/schemas/PaymentKesAccountInfo'
              MWK_ACCOUNT: '#/components/schemas/PaymentMwkAccountInfo'
              RWF_ACCOUNT: '#/components/schemas/PaymentRwfAccountInfo'
              TZS_ACCOUNT: '#/components/schemas/PaymentTzsAccountInfo'
              UGX_ACCOUNT: '#/components/schemas/PaymentUgxAccountInfo'
              XOF_ACCOUNT: '#/components/schemas/PaymentXofAccountInfo'
              ZAR_ACCOUNT: '#/components/schemas/PaymentZarAccountInfo'
              ZMW_ACCOUNT: '#/components/schemas/PaymentZmwAccountInfo'
              BWP_ACCOUNT: '#/components/schemas/PaymentBwpAccountInfo'
              XAF_ACCOUNT: '#/components/schemas/PaymentXafAccountInfo'
    InternalAccount:
      type: object
      required:
        - id
        - balance
        - fundingPaymentInstructions
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: The ID of the internal account
          example: InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123
        customerId:
          type: string
          description: The ID of the customer associated with the internal account. If this field is empty, the internal account belongs to the platform.
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        balance:
          $ref: '#/components/schemas/CurrencyAmount'
        fundingPaymentInstructions:
          type: array
          description: Payment instructions for funding the account
          items:
            $ref: '#/components/schemas/PaymentInstructions'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the internal account was created
          example: '2025-10-03T12:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the internal account was last updated
          example: '2025-10-03T12:30:00Z'
    ExternalAccountStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - UNDER_REVIEW
        - INACTIVE
      description: Status of an external account
    BeneficiaryVerificationStatus:
      type: string
      enum:
        - MATCHED
        - PARTIAL_MATCH
        - NOT_MATCHED
        - UNSUPPORTED
        - CHECKED_BY_RECEIVING_FI
        - PENDING
      description: |
        The result of verifying the beneficiary name against the account holder name.

        | Status | Description |
        |--------|-------------|
        | `MATCHED` | The beneficiary name is an exact match |
        | `PARTIAL_MATCH` | The beneficiary name is a fuzzy match |
        | `NOT_MATCHED` | The beneficiary name does not match |
        | `UNSUPPORTED` | The payment rail does not support name verification |
        | `CHECKED_BY_RECEIVING_FI` | Verification is deferred to the receiving financial institution (e.g. ACH) |
        | `PENDING` | Verification is still in progress |
    BeneficiaryVerifiedData:
      type: object
      properties:
        fullName:
          type: string
          description: The verified full name of the account holder as returned by the payment rail
          example: John Doe
    ExternalAccountType:
      type: string
      enum:
        - GBP_ACCOUNT
        - PHP_ACCOUNT
        - SGD_ACCOUNT
        - SPARK_WALLET
        - LIGHTNING
        - SOLANA_WALLET
        - TRON_WALLET
        - POLYGON_WALLET
        - BASE_WALLET
        - ETHEREUM_WALLET
        - AED_ACCOUNT
        - BRL_ACCOUNT
        - BWP_ACCOUNT
        - CAD_ACCOUNT
        - DKK_ACCOUNT
        - EUR_ACCOUNT
        - HKD_ACCOUNT
        - IDR_ACCOUNT
        - INR_ACCOUNT
        - KES_ACCOUNT
        - MWK_ACCOUNT
        - MXN_ACCOUNT
        - MYR_ACCOUNT
        - NGN_ACCOUNT
        - RWF_ACCOUNT
        - THB_ACCOUNT
        - TZS_ACCOUNT
        - UGX_ACCOUNT
        - USD_ACCOUNT
        - VND_ACCOUNT
        - XAF_ACCOUNT
        - XOF_ACCOUNT
        - ZAR_ACCOUNT
        - ZMW_ACCOUNT
      description: Type of external account or wallet
      example: GBP_ACCOUNT
    BaseExternalAccountInfo:
      type: object
      required:
        - accountType
      properties:
        accountType:
          $ref: '#/components/schemas/ExternalAccountType'
    BrlAccountInfo:
      type: object
      required:
        - accountType
        - paymentRails
        - pixKey
        - pixKeyType
        - taxId
      properties:
        accountType:
          type: string
          enum:
            - BRL_ACCOUNT
        paymentRails:
          type: array
          items:
            type: string
            enum:
              - PIX
        pixKey:
          type: string
          description: The PIX key (email, phone, CPF, CNPJ, or random)
          minLength: 1
          maxLength: 77
        pixKeyType:
          type: string
          description: The type of PIX key
          enum:
            - CPF
            - CNPJ
            - EMAIL
            - PHONE
            - RANDOM
        taxId:
          type: string
          description: The tax ID (CPF or CNPJ)
          minLength: 11
          maxLength: 14
          pattern: ^[0-9]{11,14}$
    BrlBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    BusinessBeneficiary:
      title: Business Beneficiary
      type: object
      required:
        - beneficiaryType
        - legalName
      properties:
        beneficiaryType:
          type: string
          enum:
            - BUSINESS
        legalName:
          type: string
          description: The legal name of the business
        registrationNumber:
          type: string
          description: The registration number of the business
        taxId:
          type: string
          description: The tax identification number of the business
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    BrlExternalAccountInfo:
      title: BRL Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/BrlAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/BrlBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/BrlBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    CadBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    CadExternalAccountInfo:
      title: CAD Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/CadAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/CadBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/CadBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    DkkBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    DkkExternalAccountInfo:
      title: DKK Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/DkkAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/DkkBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/DkkBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    EurBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    EurExternalAccountInfo:
      title: EUR Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/EurAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/EurBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/EurBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    GbpBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    GbpExternalAccountInfo:
      title: GBP Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/GbpAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/GbpBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/GbpBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    HkdBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    HkdExternalAccountInfo:
      title: HKD Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/HkdAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/HkdBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/HkdBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    IdrBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    IdrExternalAccountInfo:
      title: IDR Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/IdrAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/IdrBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/IdrBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    InrBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    InrExternalAccountInfo:
      title: INR Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/InrAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/InrBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/InrBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    KesBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    KesExternalAccountInfo:
      title: KES Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/KesAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/KesBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/KesBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    MwkBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    MwkExternalAccountInfo:
      title: MWK Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/MwkAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/MwkBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/MwkBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    MxnBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    MxnExternalAccountInfo:
      title: MXN Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/MxnAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/MxnBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/MxnBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    MyrBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    MyrExternalAccountInfo:
      title: MYR Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/MyrAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/MyrBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/MyrBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    NgnBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    NgnExternalAccountInfo:
      title: NGN Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/NgnAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/NgnBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/NgnBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    PhpBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    PhpExternalAccountInfo:
      title: PHP Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/PhpAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/PhpBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/PhpBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    RwfBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    RwfExternalAccountInfo:
      title: RWF Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/RwfAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/RwfBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/RwfBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    SgdBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    SgdExternalAccountInfo:
      title: SGD Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/SgdAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/SgdBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/SgdBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    ThbBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    ThbExternalAccountInfo:
      title: THB Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/ThbAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/ThbBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/ThbBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    TzsBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    TzsExternalAccountInfo:
      title: TZS Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/TzsAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/TzsBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/TzsBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    UgxBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    UgxExternalAccountInfo:
      title: UGX Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/UgxAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/UgxBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/UgxBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    UsdBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - birthDate
        - fullName
        - nationality
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    UsdExternalAccountInfo:
      title: USD Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/UsdAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/UsdBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/UsdBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    VndBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    VndExternalAccountInfo:
      title: VND Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/VndAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/VndBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/VndBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    XofBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    XofExternalAccountInfo:
      title: XOF Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/XofAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/XofBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/XofBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    ZarBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    ZarExternalAccountInfo:
      title: ZAR Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/ZarAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/ZarBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/ZarBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    ZmwBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    ZmwExternalAccountInfo:
      title: ZMW Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/ZmwAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/ZmwBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/ZmwBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    SparkWalletExternalAccountInfo:
      title: Spark Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/SparkWalletInfo'
    LightningInfo:
      type: object
      description: |
        Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided.
      required:
        - accountType
      properties:
        accountType:
          type: string
          enum:
            - LIGHTNING
        invoice:
          type: string
          description: 1-time use lightning bolt11 invoice payout destination
          example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
        bolt12:
          type: string
          description: A bolt12 offer which can be reused as a payment destination
          example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
        lightningAddress:
          type: string
          description: A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination.
          example: john.doe@lightningwallet.com
    LightningExternalAccountInfo:
      title: Lightning
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/LightningInfo'
    SolanaWalletExternalAccountInfo:
      title: Solana Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/SolanaWalletInfo'
    TronWalletExternalAccountInfo:
      title: Tron Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/TronWalletInfo'
    PolygonWalletExternalAccountInfo:
      title: Polygon Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/PolygonWalletInfo'
    BaseWalletExternalAccountInfo:
      title: Base Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/BaseWalletInfo'
    EthereumWalletExternalAccountInfo:
      title: Ethereum L1 Wallet
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/EthereumWalletInfo'
    AedBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    AedExternalAccountInfo:
      title: AED Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/AedAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/AedBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/AedBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    BwpBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    BwpExternalAccountInfo:
      title: BWP Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/BwpAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/BwpBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/BwpBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    XafBeneficiary:
      title: Individual Beneficiary
      type: object
      required:
        - beneficiaryType
        - fullName
      properties:
        beneficiaryType:
          type: string
          enum:
            - INDIVIDUAL
        fullName:
          type: string
          description: The full name of the beneficiary
        birthDate:
          type: string
          description: The birth date of the beneficiary
        nationality:
          type: string
          description: The nationality of the beneficiary
        email:
          type: string
          description: The email of the beneficiary
        phoneNumber:
          type: string
          description: The phone number of the beneficiary
        registrationNumber:
          type: string
          description: The registration number of the beneficiary
        countryOfResidence:
          type: string
          description: The country of residence of the beneficiary
        address:
          $ref: '#/components/schemas/Address'
    XafExternalAccountInfo:
      title: XAF Account
      allOf:
        - $ref: '#/components/schemas/BaseExternalAccountInfo'
        - $ref: '#/components/schemas/XafAccountInfo'
        - type: object
          required:
            - beneficiary
          properties:
            beneficiary:
              oneOf:
                - title: Individual Beneficiary
                  $ref: '#/components/schemas/XafBeneficiary'
                - title: Business Beneficiary
                  $ref: '#/components/schemas/BusinessBeneficiary'
              discriminator:
                propertyName: beneficiaryType
                mapping:
                  INDIVIDUAL: '#/components/schemas/XafBeneficiary'
                  BUSINESS: '#/components/schemas/BusinessBeneficiary'
    ExternalAccountInfoOneOf:
      oneOf:
        - $ref: '#/components/schemas/BrlExternalAccountInfo'
        - $ref: '#/components/schemas/CadExternalAccountInfo'
        - $ref: '#/components/schemas/DkkExternalAccountInfo'
        - $ref: '#/components/schemas/EurExternalAccountInfo'
        - $ref: '#/components/schemas/GbpExternalAccountInfo'
        - $ref: '#/components/schemas/HkdExternalAccountInfo'
        - $ref: '#/components/schemas/IdrExternalAccountInfo'
        - $ref: '#/components/schemas/InrExternalAccountInfo'
        - $ref: '#/components/schemas/KesExternalAccountInfo'
        - $ref: '#/components/schemas/MwkExternalAccountInfo'
        - $ref: '#/components/schemas/MxnExternalAccountInfo'
        - $ref: '#/components/schemas/MyrExternalAccountInfo'
        - $ref: '#/components/schemas/NgnExternalAccountInfo'
        - $ref: '#/components/schemas/PhpExternalAccountInfo'
        - $ref: '#/components/schemas/RwfExternalAccountInfo'
        - $ref: '#/components/schemas/SgdExternalAccountInfo'
        - $ref: '#/components/schemas/ThbExternalAccountInfo'
        - $ref: '#/components/schemas/TzsExternalAccountInfo'
        - $ref: '#/components/schemas/UgxExternalAccountInfo'
        - $ref: '#/components/schemas/UsdExternalAccountInfo'
        - $ref: '#/components/schemas/VndExternalAccountInfo'
        - $ref: '#/components/schemas/XofExternalAccountInfo'
        - $ref: '#/components/schemas/ZarExternalAccountInfo'
        - $ref: '#/components/schemas/ZmwExternalAccountInfo'
        - $ref: '#/components/schemas/SparkWalletExternalAccountInfo'
        - $ref: '#/components/schemas/LightningExternalAccountInfo'
        - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo'
        - $ref: '#/components/schemas/TronWalletExternalAccountInfo'
        - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo'
        - $ref: '#/components/schemas/BaseWalletExternalAccountInfo'
        - $ref: '#/components/schemas/EthereumWalletExternalAccountInfo'
        - $ref: '#/components/schemas/AedExternalAccountInfo'
        - $ref: '#/components/schemas/BwpExternalAccountInfo'
        - $ref: '#/components/schemas/XafExternalAccountInfo'
      discriminator:
        propertyName: accountType
        mapping:
          BRL_ACCOUNT: '#/components/schemas/BrlExternalAccountInfo'
          CAD_ACCOUNT: '#/components/schemas/CadExternalAccountInfo'
          DKK_ACCOUNT: '#/components/schemas/DkkExternalAccountInfo'
          EUR_ACCOUNT: '#/components/schemas/EurExternalAccountInfo'
          GBP_ACCOUNT: '#/components/schemas/GbpExternalAccountInfo'
          HKD_ACCOUNT: '#/components/schemas/HkdExternalAccountInfo'
          IDR_ACCOUNT: '#/components/schemas/IdrExternalAccountInfo'
          INR_ACCOUNT: '#/components/schemas/InrExternalAccountInfo'
          KES_ACCOUNT: '#/components/schemas/KesExternalAccountInfo'
          MWK_ACCOUNT: '#/components/schemas/MwkExternalAccountInfo'
          MXN_ACCOUNT: '#/components/schemas/MxnExternalAccountInfo'
          MYR_ACCOUNT: '#/components/schemas/MyrExternalAccountInfo'
          NGN_ACCOUNT: '#/components/schemas/NgnExternalAccountInfo'
          PHP_ACCOUNT: '#/components/schemas/PhpExternalAccountInfo'
          RWF_ACCOUNT: '#/components/schemas/RwfExternalAccountInfo'
          SGD_ACCOUNT: '#/components/schemas/SgdExternalAccountInfo'
          THB_ACCOUNT: '#/components/schemas/ThbExternalAccountInfo'
          TZS_ACCOUNT: '#/components/schemas/TzsExternalAccountInfo'
          UGX_ACCOUNT: '#/components/schemas/UgxExternalAccountInfo'
          USD_ACCOUNT: '#/components/schemas/UsdExternalAccountInfo'
          VND_ACCOUNT: '#/components/schemas/VndExternalAccountInfo'
          XOF_ACCOUNT: '#/components/schemas/XofExternalAccountInfo'
          ZAR_ACCOUNT: '#/components/schemas/ZarExternalAccountInfo'
          ZMW_ACCOUNT: '#/components/schemas/ZmwExternalAccountInfo'
          SPARK_WALLET: '#/components/schemas/SparkWalletExternalAccountInfo'
          LIGHTNING: '#/components/schemas/LightningExternalAccountInfo'
          SOLANA_WALLET: '#/components/schemas/SolanaWalletExternalAccountInfo'
          TRON_WALLET: '#/components/schemas/TronWalletExternalAccountInfo'
          POLYGON_WALLET: '#/components/schemas/PolygonWalletExternalAccountInfo'
          BASE_WALLET: '#/components/schemas/BaseWalletExternalAccountInfo'
          ETHEREUM_WALLET: '#/components/schemas/EthereumWalletExternalAccountInfo'
          AED_ACCOUNT: '#/components/schemas/AedExternalAccountInfo'
          BWP_ACCOUNT: '#/components/schemas/BwpExternalAccountInfo'
          XAF_ACCOUNT: '#/components/schemas/XafExternalAccountInfo'
    ExternalAccount:
      allOf:
        - type: object
          required:
            - id
            - status
            - currency
            - accountInfo
          properties:
            id:
              type: string
              description: The system generated identifier of this account
              example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
            customerId:
              type: string
              description: The customer this account is tied to, or null if the account is on behalf of the platform.
              example: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7
            status:
              $ref: '#/components/schemas/ExternalAccountStatus'
              description: Status of the external account
              example: ACTIVE
            platformAccountId:
              type: string
              description: Optional platform-specific identifier for this account
              example: acc_123456789
            currency:
              type: string
              description: The ISO 4217 currency code
              example: USD
            defaultUmaDepositAccount:
              type: boolean
              description: Whether this account is the default UMA deposit account for the customer. If true, incoming UMA payments to this customer's UMA address will be automatically deposited into this account instead of the primary internal account. False if not provided. Note that at most, one external account can be set as the default UMA deposit account for a customer. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer.
              example: false
            beneficiaryVerificationStatus:
              $ref: '#/components/schemas/BeneficiaryVerificationStatus'
              description: The result of verifying the beneficiary name against the account holder name
            beneficiaryVerifiedData:
              $ref: '#/components/schemas/BeneficiaryVerifiedData'
              description: Verified beneficiary data returned by the payment rail, if available
            cryptoNetwork:
              type: string
              description: 'The blockchain network for this external account, if applicable. Present when the account is a cryptocurrency wallet. Example values: SOLANA_MAINNET, ETHEREUM_MAINNET, POLYGON_MAINNET, TRON_MAINNET.'
              example: SOLANA_MAINNET
            accountInfo:
              $ref: '#/components/schemas/ExternalAccountInfoOneOf'
    ExternalAccountCreateRequest:
      allOf:
        - type: object
          required:
            - currency
            - accountInfo
          properties:
            customerId:
              type: string
              description: The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform.
              example: Customer:019542f5-b3e7-1d02-0000-000000000001
            currency:
              type: string
              description: The ISO 4217 currency code
              example: USD
            platformAccountId:
              type: string
              description: Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier.
              example: ext_acc_123456
            defaultUmaDepositAccount:
              type: boolean
              description: Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer.
              default: false
            cryptoNetwork:
              type: string
              description: 'The blockchain network for this external account. Required when the account is a cryptocurrency wallet (e.g. SolanaWallet, PolygonWallet, TronWallet). Specifies which network the wallet is on. Example values: SOLANA_MAINNET, SOLANA_DEVNET, ETHEREUM_MAINNET, POLYGON_MAINNET, TRON_MAINNET.'
              example: SOLANA_MAINNET
            accountInfo:
              $ref: '#/components/schemas/ExternalAccountInfoOneOf'
    PlatformExternalAccountCreateRequest:
      type: object
      required:
        - currency
        - accountInfo
      properties:
        currency:
          type: string
          description: The ISO 4217 currency code
          example: USD
        platformAccountId:
          type: string
          description: Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier.
          example: ext_acc_123456
        accountInfo:
          $ref: '#/components/schemas/ExternalAccountInfoOneOf'
    BeneficialOwnerRole:
      type: string
      enum:
        - UBO
        - DIRECTOR
        - COMPANY_OFFICER
        - CONTROL_PERSON
        - TRUSTEE
        - GENERAL_PARTNER
      description: Role of the beneficial owner within the business
      example: UBO
    IdentificationType:
      type: string
      enum:
        - SSN
        - PASSPORT
        - NATIONAL_ID
        - DRIVERS_LICENSE
        - TAX_ID
        - ITIN
        - CPF
      description: Type of personal identification document
      example: SSN
    PersonalIdentification:
      type: object
      required:
        - idType
        - identifier
      properties:
        idType:
          $ref: '#/components/schemas/IdentificationType'
        identifier:
          type: string
          description: The identification number or value
          example: 123-45-6789
        countryOfIssuance:
          type: string
          description: Country that issued the identification (ISO 3166-1 alpha-2)
          example: US
    BeneficialOwnerPersonalInfo:
      type: object
      required:
        - firstName
        - lastName
        - birthDate
        - nationality
        - address
        - personalIds
      properties:
        firstName:
          type: string
          description: First name of the individual
          example: Jane
        lastName:
          type: string
          description: Last name of the individual
          example: Smith
        middleName:
          type: string
          description: Middle name of the individual
          example: Marie
        birthDate:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD)
          example: '1978-06-15'
        nationality:
          type: string
          description: Country of nationality (ISO 3166-1 alpha-2)
          example: US
        email:
          type: string
          format: email
          description: Email address of the individual
          example: jane.smith@acmecorp.com
        phoneNumber:
          type: string
          description: Phone number in E.164 format
          example: '+14155550192'
          pattern: ^\+[1-9]\d{1,14}$
        address:
          $ref: '#/components/schemas/Address'
        personalIds:
          $ref: '#/components/schemas/PersonalIdentification'
    BeneficialOwner:
      type: object
      required:
        - id
        - customerId
        - roles
        - personalInfo
        - kycStatus
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier for this beneficial owner
          example: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001
        customerId:
          type: string
          description: The ID of the business customer this beneficial owner is associated with
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        roles:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwnerRole'
          description: Roles of this person within the business
          example:
            - UBO
            - DIRECTOR
        ownershipPercentage:
          type: number
          format: float
          description: Percentage of ownership in the business (0-100)
          minimum: 0
          maximum: 100
          example: 51
        personalInfo:
          $ref: '#/components/schemas/BeneficialOwnerPersonalInfo'
        kycStatus:
          $ref: '#/components/schemas/KycStatus'
        createdAt:
          type: string
          format: date-time
          description: When this beneficial owner was created
          example: '2025-10-03T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When this beneficial owner was last updated
          example: '2025-10-03T12:00:00Z'
    BeneficialOwnerCreateRequest:
      type: object
      required:
        - customerId
        - roles
        - personalInfo
      properties:
        customerId:
          type: string
          description: The ID of the business customer this beneficial owner is associated with
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        roles:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwnerRole'
          description: Roles of this person within the business
          example:
            - UBO
            - DIRECTOR
        ownershipPercentage:
          type: number
          format: float
          description: Percentage of ownership in the business (0-100). Relevant when role includes UBO.
          minimum: 0
          maximum: 100
          example: 51
        personalInfo:
          $ref: '#/components/schemas/BeneficialOwnerPersonalInfo'
    BeneficialOwnerPersonalInfoUpdate:
      type: object
      description: Partial update for beneficial owner personal information. Only provided fields are updated.
      properties:
        firstName:
          type: string
          description: First name of the individual
          example: Jane
        lastName:
          type: string
          description: Last name of the individual
          example: Smith
        middleName:
          type: string
          description: Middle name of the individual
          example: Marie
        birthDate:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD)
          example: '1978-06-15'
        nationality:
          type: string
          description: Country of nationality (ISO 3166-1 alpha-2)
          example: US
        email:
          type: string
          format: email
          description: Email address of the individual
          example: jane.smith@acmecorp.com
        phoneNumber:
          type: string
          description: Phone number in E.164 format
          example: '+14155550192'
          pattern: ^\+[1-9]\d{1,14}$
        address:
          $ref: '#/components/schemas/Address'
        personalIds:
          $ref: '#/components/schemas/PersonalIdentification'
    BeneficialOwnerUpdateRequest:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwnerRole'
          description: Roles of this person within the business
          example:
            - UBO
            - DIRECTOR
        ownershipPercentage:
          type: number
          format: float
          description: Percentage of ownership in the business (0-100)
          minimum: 0
          maximum: 100
          example: 51
        personalInfo:
          $ref: '#/components/schemas/BeneficialOwnerPersonalInfoUpdate'
    DocumentType:
      type: string
      enum:
        - PASSPORT
        - DRIVERS_LICENSE
        - NATIONAL_ID
        - PROOF_OF_ADDRESS
        - BANK_STATEMENT
        - TAX_RETURN
        - CERTIFICATE_OF_INCORPORATION
        - ARTICLES_OF_INCORPORATION
        - ARTICLES_OF_ASSOCIATION
        - STATE_REGISTRY_EXCERPT
        - GOOD_STANDING_CERTIFICATE
        - INFORMATION_STATEMENT
        - INCUMBENCY_CERTIFICATE
        - BUSINESS_LICENSE
        - SHAREHOLDER_REGISTER
        - POWER_OF_ATTORNEY
        - UTILITY_BILL
        - SELFIE
        - OTHER
      description: Type of identity or business verification document
      example: PASSPORT
    Document:
      type: object
      required:
        - id
        - documentHolder
        - documentType
        - country
        - fileName
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier for this document
          example: Document:019542f5-b3e7-1d02-0000-000000000001
        documentHolder:
          type: string
          description: ID of the entity that owns this document. Can be a Customer ID or a BeneficialOwner ID.
          example: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001
        documentType:
          $ref: '#/components/schemas/DocumentType'
        side:
          type: string
          enum:
            - FRONT
            - BACK
          description: Which side of the document this upload represents. Relevant for two-sided documents like driver's licenses or national IDs.
          example: FRONT
        country:
          type: string
          description: Country that issued the document (ISO 3166-1 alpha-2)
          example: US
        documentNumber:
          type: string
          description: Document identification number (e.g., passport number)
          example: A12345678
        fileName:
          type: string
          description: Original file name of the uploaded document
          example: passport_scan.pdf
        createdAt:
          type: string
          format: date-time
          description: When this document was uploaded
          example: '2025-10-03T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When this document was last updated
          example: '2025-10-03T12:00:00Z'
    BaseDocumentRequest:
      type: object
      required:
        - file
        - documentType
        - country
      properties:
        file:
          type: string
          format: binary
          description: The document file (PDF, JPEG, or PNG, max 10 MB)
        documentType:
          $ref: '#/components/schemas/DocumentType'
        side:
          type: string
          enum:
            - FRONT
            - BACK
          description: Which side of the document (for two-sided documents like driver's licenses)
          example: FRONT
        country:
          type: string
          description: Country that issued the document (ISO 3166-1 alpha-2)
          example: US
        documentNumber:
          type: string
          description: Document identification number (e.g., passport number)
          example: A12345678
    DocumentUploadRequest:
      title: Document Upload Request
      allOf:
        - $ref: '#/components/schemas/BaseDocumentRequest'
        - type: object
          required:
            - documentHolder
          properties:
            documentHolder:
              type: string
              description: ID of the entity that owns this document. Can be a Customer ID or a BeneficialOwner ID.
              example: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001
    DocumentReplaceRequest:
      title: Document Replace Request
      allOf:
        - $ref: '#/components/schemas/BaseDocumentRequest'
    VerificationStatus:
      type: string
      enum:
        - RESOLVE_ERRORS
        - PENDING_MANUAL_REVIEW
        - IN_PROGRESS
        - APPROVED
        - REJECTED
      description: Current status of the KYC/KYB verification
      example: RESOLVE_ERRORS
    VerificationErrorType:
      type: string
      enum:
        - MISSING_FIELD
        - INVALID_FIELD
        - MISSING_DOCUMENT
        - INVALID_DOCUMENT
        - EXPIRED_DOCUMENT
        - MISSING_BENEFICIAL_OWNER
      description: Type of verification error
      example: MISSING_FIELD
    VerificationError:
      type: object
      required:
        - resourceId
        - type
        - reason
      properties:
        resourceId:
          type: string
          description: ID of the resource with the issue (Customer, BeneficialOwner, or Document)
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        type:
          $ref: '#/components/schemas/VerificationErrorType'
        field:
          type: string
          description: Dot-notation path to the field with the issue. Present when type is MISSING_FIELD or INVALID_FIELD.
          example: customer.address.line1
        acceptedDocumentTypes:
          type: array
          items:
            $ref: '#/components/schemas/DocumentType'
          description: Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT.
        reason:
          type: string
          description: Human-readable description of the issue
          example: Business address line 1 is required
    Verification:
      type: object
      required:
        - id
        - customerId
        - verificationStatus
        - errors
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier for this verification
          example: Verification:019542f5-b3e7-1d02-0000-000000000001
        customerId:
          type: string
          description: The ID of the customer being verified
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        verificationStatus:
          $ref: '#/components/schemas/VerificationStatus'
        errors:
          type: array
          description: List of issues preventing verification from proceeding. Empty when verificationStatus is APPROVED or IN_PROGRESS.
          items:
            $ref: '#/components/schemas/VerificationError'
        createdAt:
          type: string
          format: date-time
          description: When this verification was created
          example: '2025-10-03T12:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When this verification was last updated
          example: '2025-10-03T12:00:00Z'
    VerificationRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          description: The ID of the customer to verify
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
    PlaidLinkTokenRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          description: The ID of the customer for whom to create the Plaid Link token and external account
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
    PlaidLinkTokenResponse:
      type: object
      required:
        - linkToken
        - expiration
        - callbackUrl
      properties:
        linkToken:
          type: string
          description: |
            The Plaid Link token to be used to initialize Plaid Link in your application. This token is single-use and expires after the specified expiration time.
          example: link-sandbox-af1a0311-da53-4636-b754-dd15cc058176
        expiration:
          type: string
          format: date-time
          description: |
            The ISO 8601 timestamp when this link token expires. Link tokens typically expire after 4 hours.
          example: '2025-10-05T18:30:00Z'
        callbackUrl:
          type: string
          description: |
            The URL where the platform should POST the public_token after the customer completes Plaid Link authentication. This will trigger asynchronous external account creation. The URL includes the linkToken as the path parameter.
          example: https://api.lightspark.com/grid/2025-10-13/plaid/callback/{plaid_link_token}
        requestId:
          type: string
          description: A unique identifier for this request, useful for debugging
          example: req_abc123def456
    PlaidCallbackRequest:
      type: object
      required:
        - publicToken
      properties:
        publicToken:
          type: string
          description: |
            The public token returned by Plaid Link after the customer successfully
            authenticates and selects an account.
          example: public-sandbox-12345678-1234-1234-1234-123456789012
        accountId:
          type: string
          description: |
            Optional Plaid account ID if the customer selected a specific account.
            If not provided, the default account will be used.
          example: plaid_account_id_123
    ExternalAccountReference:
      type: object
      required:
        - accountId
      properties:
        accountId:
          type: string
          description: Reference to an external account ID
          example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
    InternalAccountReference:
      type: object
      required:
        - accountId
      properties:
        accountId:
          type: string
          description: Reference to an internal account ID
          example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
    TransferInRequest:
      type: object
      required:
        - source
        - destination
      properties:
        source:
          $ref: '#/components/schemas/ExternalAccountReference'
          description: Source external account details
        destination:
          $ref: '#/components/schemas/InternalAccountReference'
          description: Destination internal account details
        amount:
          type: integer
          format: int64
          description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
          example: 12550
    TransactionStatus:
      type: string
      enum:
        - CREATED
        - PENDING
        - PROCESSING
        - COMPLETED
        - REJECTED
        - FAILED
        - REFUNDED
        - EXPIRED
      description: |
        Status of a payment transaction.

        | Status | Description |
        |--------|-------------|
        | `CREATED` | Initial lookup has been created |
        | `PENDING` | Quote has been created |
        | `PROCESSING` | Funding has been received and payment initiated |
        | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network |
        | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded |
        | `FAILED` | An error occurred during payment |
        | `REFUNDED` | Payment was unable to complete and refunded |
        | `EXPIRED` | Quote has expired |
    TransactionDestinationType:
      type: string
      enum:
        - ACCOUNT
        - UMA_ADDRESS
        - EXTERNAL_ACCOUNT_DETAILS
      description: Type of transaction destination
      example: ACCOUNT
    BaseTransactionDestination:
      type: object
      required:
        - destinationType
      properties:
        destinationType:
          $ref: '#/components/schemas/TransactionDestinationType'
        currency:
          type: string
          description: Currency code for the destination
          example: EUR
    AccountTransactionDestination:
      title: Account Destination
      allOf:
        - $ref: '#/components/schemas/BaseTransactionDestination'
        - type: object
          required:
            - accountId
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - ACCOUNT
            accountId:
              type: string
              description: Destination account identifier
              example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
          description: Destination account details
    UmaAddressTransactionDestination:
      title: UMA Address Destination
      allOf:
        - $ref: '#/components/schemas/BaseTransactionDestination'
        - type: object
          required:
            - umaAddress
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - UMA_ADDRESS
            umaAddress:
              type: string
              description: UMA address of the recipient
              example: $receiver@uma.domain.com
          description: UMA address destination details
    ExternalAccountDetailsTransactionDestination:
      title: External Account Details Destination
      allOf:
        - $ref: '#/components/schemas/BaseTransactionDestination'
        - type: object
          required:
            - externalAccountDetails
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - EXTERNAL_ACCOUNT_DETAILS
            externalAccountDetails:
              $ref: '#/components/schemas/ExternalAccountCreateRequest'
          description: Transaction destination where external account details were provided inline at quote creation rather than using a pre-registered external account.
    TransactionDestinationOneOf:
      oneOf:
        - $ref: '#/components/schemas/AccountTransactionDestination'
        - $ref: '#/components/schemas/UmaAddressTransactionDestination'
        - $ref: '#/components/schemas/ExternalAccountDetailsTransactionDestination'
      discriminator:
        propertyName: destinationType
        mapping:
          ACCOUNT: '#/components/schemas/AccountTransactionDestination'
          UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination'
          EXTERNAL_ACCOUNT_DETAILS: '#/components/schemas/ExternalAccountDetailsTransactionDestination'
    CounterpartyInformation:
      type: object
      description: Additional information about the counterparty, if available and relevant to the transaction and platform.
      additionalProperties: true
      example:
        FULL_NAME: John Sender
        BIRTH_DATE: '1985-06-15'
        NATIONALITY: DE
    Transaction:
      type: object
      required:
        - id
        - status
        - type
        - destination
        - customerId
        - platformCustomerId
      properties:
        id:
          type: string
          description: Unique identifier for the transaction
          example: Transaction:019542f5-b3e7-1d02-0000-000000000004
        status:
          $ref: '#/components/schemas/TransactionStatus'
        type:
          $ref: '#/components/schemas/TransactionType'
        destination:
          $ref: '#/components/schemas/TransactionDestinationOneOf'
        customerId:
          type: string
          description: System ID of the customer (sender for outgoing, recipient for incoming)
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        platformCustomerId:
          type: string
          description: Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
          example: 18d3e5f7b4a9c2
        settledAt:
          type: string
          format: date-time
          description: When the payment was or will be settled
          example: '2025-08-15T14:30:00Z'
        createdAt:
          type: string
          format: date-time
          description: When the transaction was created
          example: '2025-08-15T14:25:18Z'
        updatedAt:
          type: string
          format: date-time
          description: When the transaction was last updated
          example: '2025-08-15T14:30:00Z'
        description:
          type: string
          description: Optional memo or description for the payment
          example: 'Payment for invoice #1234'
        counterpartyInformation:
          $ref: '#/components/schemas/CounterpartyInformation'
    TransactionSourceType:
      type: string
      enum:
        - ACCOUNT
        - UMA_ADDRESS
        - REALTIME_FUNDING
      description: Type of transaction source
      example: ACCOUNT
    BaseTransactionSource:
      type: object
      required:
        - sourceType
      properties:
        sourceType:
          $ref: '#/components/schemas/TransactionSourceType'
        currency:
          type: string
          description: Currency code for the source
          example: USD
    AccountTransactionSource:
      title: Account Source
      allOf:
        - $ref: '#/components/schemas/BaseTransactionSource'
        - type: object
          required:
            - accountId
            - sourceType
          properties:
            sourceType:
              type: string
              enum:
                - ACCOUNT
            accountId:
              type: string
              description: Source account identifier
              example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
          description: Source account details
    UmaAddressTransactionSource:
      title: UMA Address Source
      allOf:
        - $ref: '#/components/schemas/BaseTransactionSource'
        - type: object
          required:
            - umaAddress
            - sourceType
          properties:
            sourceType:
              type: string
              enum:
                - UMA_ADDRESS
            umaAddress:
              type: string
              description: UMA address of the sender
              example: $sender@uma.domain.com
          description: UMA address source details
    RealtimeFundingTransactionSource:
      title: Real-time Funding Source
      allOf:
        - $ref: '#/components/schemas/BaseTransactionSource'
        - type: object
          required:
            - currency
            - sourceType
          properties:
            sourceType:
              type: string
              enum:
                - REALTIME_FUNDING
            customerId:
              type: string
              description: The customer on whose behalf the transaction was initiated.
              example: Customer:019542f5-b3e7-1d02-0000-000000000009
            currency:
              type: string
              description: Currency code for the funding source
              example: USDC
          description: Transaction was funded using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.).
    TransactionSourceOneOf:
      oneOf:
        - $ref: '#/components/schemas/AccountTransactionSource'
        - $ref: '#/components/schemas/UmaAddressTransactionSource'
        - $ref: '#/components/schemas/RealtimeFundingTransactionSource'
      discriminator:
        propertyName: sourceType
        mapping:
          ACCOUNT: '#/components/schemas/AccountTransactionSource'
          UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource'
          REALTIME_FUNDING: '#/components/schemas/RealtimeFundingTransactionSource'
    ReconciliationInstructions:
      type: object
      required:
        - reference
      properties:
        reference:
          type: string
          description: Unique reference code that must be included with the payment to match it with the correct incoming transaction
          example: UMA-Q12345-REF
    IncomingRateDetails:
      description: Details about the rate and fees for an incoming transaction.
      type: object
      required:
        - gridApiMultiplier
        - gridApiFixedFee
        - gridApiVariableFeeRate
        - gridApiVariableFeeAmount
      properties:
        gridApiMultiplier:
          type: number
          format: double
          description: The underlying multiplier from the mSATS to the receiving currency, including variable fees.
          exclusiveMinimum: 0
          example: 0.925
        gridApiFixedFee:
          type: integer
          format: int64
          description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents).
          minimum: 0
          example: 10
        gridApiVariableFeeRate:
          type: number
          format: double
          description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the receiving currency amount.
          exclusiveMinimum: 0
          example: 0.003
        gridApiVariableFeeAmount:
          type: number
          format: int64
          description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate.
          minimum: 0
          example: 30
    IncomingTransactionFailureReason:
      type: string
      enum:
        - LNURLP_FAILED
        - PAY_REQUEST_FAILED
        - PAYMENT_APPROVAL_WEBHOOK_ERROR
        - PAYMENT_APPROVAL_TIMED_OUT
        - OFFRAMP_FAILED
        - MISSING_MANDATORY_PAYEE_DATA
        - QUOTE_EXPIRED
        - QUOTE_EXECUTION_FAILED
      description: Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted.
    IncomingTransaction:
      title: Incoming Transaction
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          required:
            - type
            - receivedAmount
          properties:
            type:
              type: string
              enum:
                - INCOMING
            source:
              $ref: '#/components/schemas/TransactionSourceOneOf'
            receivedAmount:
              $ref: '#/components/schemas/CurrencyAmount'
              description: Amount received in the recipient's currency
            reconciliationInstructions:
              $ref: '#/components/schemas/ReconciliationInstructions'
              description: Included for all transactions except those with "CREATED" status
            rateDetails:
              $ref: '#/components/schemas/IncomingRateDetails'
              description: Details about the rate and fees for the transaction.
            failureReason:
              $ref: '#/components/schemas/IncomingTransactionFailureReason'
              description: If the transaction failed, this field provides the reason for failure.
    OutgoingTransactionStatus:
      type: string
      enum:
        - PENDING
        - EXPIRED
        - PROCESSING
        - COMPLETED
        - FAILED
      description: |
        Status of an outgoing payment transaction.

        | Status | Description |
        |--------|-------------|
        | `PENDING` | Quote is pending confirmation |
        | `EXPIRED` | Quote wasn't executed before expiry window |
        | `PROCESSING` | Executing the quote after receiving funds |
        | `COMPLETED` | Payout successfully reached the destination |
        | `FAILED` | Something went wrong — accompanied by a `failureReason` |
    Refund:
      type: object
      required:
        - reference
        - initiatedAt
        - status
      properties:
        reference:
          type: string
          description: The unique reference ID of the refund
          example: UMA-Q12345-REFUND
        initiatedAt:
          type: string
          format: date-time
          description: When the refund was initiated
          example: '2025-08-15T14:30:00Z'
        settledAt:
          type: string
          format: date-time
          description: When the refund was settled
          example: '2025-08-15T14:35:00Z'
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
          description: Current status of the refund
          example: COMPLETED
        reason:
          type: string
          enum:
            - TRANSACTION_FAILED
            - USER_CANCELLATION
          description: Reason for the refund
          example: TRANSACTION_FAILED
    OutgoingRateDetails:
      description: Details about the rate and fees for an outgoing transaction or quote.
      type: object
      required:
        - counterpartyMultiplier
        - counterpartyFixedFee
        - gridApiMultiplier
        - gridApiFixedFee
        - gridApiVariableFeeRate
        - gridApiVariableFeeAmount
      properties:
        counterpartyMultiplier:
          type: number
          format: double
          description: The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution.
          exclusiveMinimum: 0
          example: 1.08
        counterpartyFixedFee:
          type: integer
          format: int64
          description: The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents).
          minimum: 0
          example: 10
        gridApiMultiplier:
          type: number
          format: double
          description: The underlying multiplier from the sending currency to mSATS, including variable fees.
          exclusiveMinimum: 0
          example: 0.925
        gridApiFixedFee:
          type: integer
          format: int64
          description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents).
          minimum: 0
          example: 10
        gridApiVariableFeeRate:
          type: number
          format: double
          description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount.
          exclusiveMinimum: 0
          example: 0.003
        gridApiVariableFeeAmount:
          type: number
          format: int64
          description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate.
          minimum: 0
          example: 30
    OutgoingTransactionFailureReason:
      type: string
      enum:
        - QUOTE_EXPIRED
        - QUOTE_EXECUTION_FAILED
        - LIGHTNING_PAYMENT_FAILED
        - FUNDING_AMOUNT_MISMATCH
        - COUNTERPARTY_POST_TX_FAILED
        - TIMEOUT
      description: Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted.
    OutgoingTransaction:
      title: Outgoing Transaction
      allOf:
        - $ref: '#/components/schemas/Transaction'
        - type: object
          required:
            - type
            - sentAmount
            - source
          properties:
            status:
              $ref: '#/components/schemas/OutgoingTransactionStatus'
            type:
              type: string
              enum:
                - OUTGOING
            source:
              $ref: '#/components/schemas/TransactionSourceOneOf'
            sentAmount:
              $ref: '#/components/schemas/CurrencyAmount'
              description: Amount sent in the sender's currency
            receivedAmount:
              $ref: '#/components/schemas/CurrencyAmount'
              description: Amount to be received by recipient in the recipient's currency
            exchangeRate:
              type: number
              description: Number of sending currency units per receiving currency unit.
              exclusiveMinimum: 0
              example: 1.08
            fees:
              type: integer
              format: int64
              description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
              minimum: 0
              example: 10
            quoteId:
              type: string
              description: The ID of the quote that was used to trigger this payment
              example: Quote:019542f5-b3e7-1d02-0000-000000000006
            paymentInstructions:
              type: array
              description: Payment instructions for executing the payment.
              items:
                $ref: '#/components/schemas/PaymentInstructions'
              example:
                - accountOrWalletInfo:
                    accountType: USD_ACCOUNT
                    paymentRails:
                      - ACH
                      - WIRE
                    accountNumber: '1234567890'
                    routingNumber: '021000021'
                    bankName: Chase Bank
                    reference: UMA-Q12345-REF
                  instructionsNotes: Include reference UMA-Q12345-REF in memo
                - accountOrWalletInfo:
                    accountType: SPARK_WALLET
                    assetType: BTC
                    address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
                    invoice: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
            refund:
              $ref: '#/components/schemas/Refund'
              description: The refund if transaction was refunded.
            rateDetails:
              $ref: '#/components/schemas/OutgoingRateDetails'
              description: Details about the rate and fees for the transaction.
            failureReason:
              $ref: '#/components/schemas/OutgoingTransactionFailureReason'
              description: If the transaction failed, this field provides the reason for failure.
    TransactionOneOf:
      oneOf:
        - $ref: '#/components/schemas/IncomingTransaction'
        - $ref: '#/components/schemas/OutgoingTransaction'
      discriminator:
        propertyName: type
        mapping:
          INCOMING: '#/components/schemas/IncomingTransaction'
          OUTGOING: '#/components/schemas/OutgoingTransaction'
    TransferOutRequest:
      type: object
      required:
        - source
        - destination
      properties:
        source:
          $ref: '#/components/schemas/InternalAccountReference'
          description: Source internal account details
        destination:
          $ref: '#/components/schemas/ExternalAccountReference'
          description: Destination external account details
        amount:
          type: integer
          format: int64
          description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
          example: 12550
    CurrencyPreference:
      type: object
      required:
        - currency
        - estimatedExchangeRate
        - min
        - max
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
        estimatedExchangeRate:
          type: number
          description: An estimated exchange rate from the sender's currency to this currency. This is not a locked rate and is subject to change when calling the quotes endpoint.
          exclusiveMinimum: 0
          example: 1.08
        min:
          type: integer
          format: int64
          description: The minimum amount that can be received in this currency.
          exclusiveMinimum: 0
          example: 1
        max:
          type: integer
          format: int64
          description: The maximum amount that can be received in this currency.
          exclusiveMinimum: 0
          example: 1000000
    ReceiverLookupResponse:
      type: object
      required:
        - supportedCurrencies
        - lookupId
      properties:
        supportedCurrencies:
          type: array
          description: List of currencies supported by the receiving account
          items:
            $ref: '#/components/schemas/CurrencyPreference'
        requiredPayerDataFields:
          type: array
          description: Fields required by the receiving institution about the payer before payment can be completed
          items:
            $ref: '#/components/schemas/CounterpartyFieldDefinition'
        lookupId:
          type: string
          description: Unique identifier for the lookup. Needed in the subsequent create quote request.
          example: Lookup:019542f5-b3e7-1d02-0000-000000000009
    Error412:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 412
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | UNSUPPORTED_UMA_VERSION | Counterparty doesn't support the Grid UMA version |
          enum:
            - UNSUPPORTED_UMA_VERSION
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    Error424:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 424
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | PAYREQ_REQUEST_FAILED | Payment request failed |
            | COUNTERPARTY_PUBKEY_FETCH_ERROR | Error fetching counterparty public key |
            | NO_COMPATIBLE_UMA_VERSION | No compatible UMA version |
            | LNURLP_REQUEST_FAILED | LNURLP request failed |
          enum:
            - PAYREQ_REQUEST_FAILED
            - COUNTERPARTY_PUBKEY_FETCH_ERROR
            - NO_COMPATIBLE_UMA_VERSION
            - LNURLP_REQUEST_FAILED
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    QuoteSourceType:
      type: string
      enum:
        - ACCOUNT
        - REALTIME_FUNDING
      description: Type of quote funding source
      example: ACCOUNT
    BaseQuoteSource:
      type: object
      required:
        - sourceType
      properties:
        sourceType:
          $ref: '#/components/schemas/QuoteSourceType'
    AccountQuoteSource:
      title: Account
      allOf:
        - $ref: '#/components/schemas/BaseQuoteSource'
        - type: object
          required:
            - accountId
            - sourceType
          properties:
            sourceType:
              type: string
              enum:
                - ACCOUNT
            accountId:
              type: string
              description: Source account identifier
              example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
            customerId:
              type: string
              description: Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated.  Otherwise, will default to the customerId of the account owner.
              example: Customer:019542f5-b3e7-1d02-0000-000000000001
          description: Source account details
    RealtimeFundingQuoteSource:
      title: Real-time Funding
      allOf:
        - $ref: '#/components/schemas/BaseQuoteSource'
        - type: object
          required:
            - currency
            - sourceType
          properties:
            sourceType:
              type: string
              enum:
                - REALTIME_FUNDING
            customerId:
              type: string
              description: Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself.
              example: Customer:019542f5-b3e7-1d02-0000-000000000009
            currency:
              type: string
              description: Currency code for the funding source. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
              example: USD
            cryptoNetwork:
              type: string
              description: 'The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA_MAINNET`, `SOLANA_DEVNET`, `ETHEREUM_MAINNET`.'
              example: SOLANA_MAINNET
          description: Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.).
    QuoteSourceOneOf:
      oneOf:
        - $ref: '#/components/schemas/AccountQuoteSource'
        - $ref: '#/components/schemas/RealtimeFundingQuoteSource'
      discriminator:
        propertyName: sourceType
        mapping:
          ACCOUNT: '#/components/schemas/AccountQuoteSource'
          REALTIME_FUNDING: '#/components/schemas/RealtimeFundingQuoteSource'
    DestinationType:
      type: string
      enum:
        - ACCOUNT
        - UMA_ADDRESS
        - EXTERNAL_ACCOUNT_DETAILS
      description: Type of payment destination
      example: ACCOUNT
    BaseDestination:
      type: object
      required:
        - destinationType
      properties:
        destinationType:
          $ref: '#/components/schemas/DestinationType'
    AccountDestination:
      title: Account
      allOf:
        - $ref: '#/components/schemas/BaseDestination'
        - type: object
          required:
            - accountId
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - ACCOUNT
            accountId:
              type: string
              description: Destination account identifier
              example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
            paymentRail:
              type: string
              description: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail.
              example: ACH
          description: Destination account details
    UmaAddressDestination:
      title: UMA Address
      allOf:
        - $ref: '#/components/schemas/BaseDestination'
        - type: object
          required:
            - umaAddress
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - UMA_ADDRESS
            umaAddress:
              type: string
              description: UMA address of the recipient
              example: $receiver@uma.domain.com
            currency:
              type: string
              description: Currency code for the destination. See [Supported Currencies](https://grid.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies.
              example: EUR
          description: UMA address destination details
    ExternalAccountDetailsDestination:
      title: External Account Details
      allOf:
        - $ref: '#/components/schemas/BaseDestination'
        - type: object
          required:
            - externalAccountDetails
            - destinationType
          properties:
            destinationType:
              type: string
              enum:
                - EXTERNAL_ACCOUNT_DETAILS
            externalAccountDetails:
              $ref: '#/components/schemas/ExternalAccountCreateRequest'
          description: A convenient destination option which adds the external account and creates the quote in one step rather than first needing to call /external-accounts to add the account. Useful for one-off payments to some destination. See the Sandbox Testing guide in the API reference for test values.
    QuoteDestinationOneOf:
      oneOf:
        - $ref: '#/components/schemas/AccountDestination'
        - $ref: '#/components/schemas/UmaAddressDestination'
        - $ref: '#/components/schemas/ExternalAccountDetailsDestination'
      discriminator:
        propertyName: destinationType
        mapping:
          ACCOUNT: '#/components/schemas/AccountDestination'
          UMA_ADDRESS: '#/components/schemas/UmaAddressDestination'
          EXTERNAL_ACCOUNT_DETAILS: '#/components/schemas/ExternalAccountDetailsDestination'
    Quote:
      type: object
      required:
        - id
        - status
        - expiresAt
        - createdAt
        - source
        - destination
        - sendingCurrency
        - receivingCurrency
        - totalSendingAmount
        - totalReceivingAmount
        - exchangeRate
        - feesIncluded
        - transactionId
      properties:
        id:
          type: string
          description: Unique identifier for this quote
          example: Quote:019542f5-b3e7-1d02-0000-000000000006
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
            - EXPIRED
          description: Current status of the quote
          example: PENDING
        createdAt:
          type: string
          format: date-time
          description: When this quote was created
          example: '2025-10-03T12:00:00Z'
        expiresAt:
          type: string
          format: date-time
          description: When this quote expires (typically 1-5 minutes after creation)
          example: '2025-10-03T12:05:00Z'
        source:
          $ref: '#/components/schemas/QuoteSourceOneOf'
        destination:
          $ref: '#/components/schemas/QuoteDestinationOneOf'
        sendingCurrency:
          $ref: '#/components/schemas/Currency'
          description: Currency for the sending amount
        receivingCurrency:
          $ref: '#/components/schemas/Currency'
          description: Currency for the receiving amount
        totalSendingAmount:
          type: integer
          format: int64
          description: The total amount that will be sent in the smallest unit of the sending currency (eg. cents).
          exclusiveMinimum: 0
          example: 123010
        totalReceivingAmount:
          type: integer
          format: int64
          description: The total amount that will be received in the smallest unit of the receiving currency (eg. cents).
          exclusiveMinimum: 0
          example: 1000
        exchangeRate:
          type: number
          description: Number of sending currency units per receiving currency unit.
          exclusiveMinimum: 0
        feesIncluded:
          type: integer
          format: int64
          description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents).
          minimum: 0
          example: 10
        paymentInstructions:
          type: array
          description: Payment instructions for executing the payment. This is not required when using an internal account source.
          items:
            $ref: '#/components/schemas/PaymentInstructions'
          example:
            - accountOrWalletInfo:
                accountType: USD_ACCOUNT
                paymentRails:
                  - ACH
                  - WIRE
                accountNumber: '1234567890'
                routingNumber: '021000021'
                bankName: Chase Bank
                reference: UMA-Q12345-REF
              instructionsNotes: Include reference UMA-Q12345-REF in memo
            - accountOrWalletInfo:
                accountType: SPARK_WALLET
                assetType: BTC
                address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu
                invoice: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs
        transactionId:
          type: string
          description: The ID of the transaction created from this quote.
          example: Transaction:019542f5-b3e7-1d02-0000-000000000005
        counterpartyInformation:
          $ref: '#/components/schemas/CounterpartyInformation'
          description: Additional information about the counterparty, if available and required by the platform in their configuration.
        rateDetails:
          $ref: '#/components/schemas/OutgoingRateDetails'
          description: Details about the rate and fees for the transaction.
    QuoteLockSide:
      type: string
      enum:
        - SENDING
        - RECEIVING
      description: The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents).
    PurposeOfPayment:
      type: string
      description: The purpose of the payment. This may be required when sending to certain geographies (e.g. India).
      enum:
        - GIFT
        - SELF
        - GOODS_OR_SERVICES
        - EDUCATION
        - HEALTH_OR_MEDICAL
        - REAL_ESTATE_PURCHASE
        - TAX_PAYMENT
        - LOAN_PAYMENT
        - UTILITY_BILL
        - DONATION
        - TRAVEL
        - OTHER
    QuoteRequest:
      type: object
      required:
        - source
        - destination
        - lockedCurrencySide
        - lockedCurrencyAmount
      properties:
        lookupId:
          type: string
          description: |-
            Lookup ID from a previous receiver lookup request. If provided, this can make the quote creation more efficient by reusing cached lookup data.
            NOTE: This is required for UMA destinations due to counterparty institution requirements. See `senderCustomerInfo` for more information.
          example: Lookup:019542f5-b3e7-1d02-0000-000000000009
        source:
          $ref: '#/components/schemas/QuoteSourceOneOf'
        destination:
          $ref: '#/components/schemas/QuoteDestinationOneOf'
        lockedCurrencySide:
          $ref: '#/components/schemas/QuoteLockSide'
        lockedCurrencyAmount:
          type: integer
          format: int64
          description: The amount to send/receive in the smallest unit of the locked currency (eg. cents). See `lockedCurrencySide` for more information.
          exclusiveMinimum: 0
          maximum: 9000000000000000
          example: 1000
        immediatelyExecute:
          type: boolean
          description: |-
            Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the `/quotes/{quoteId}/execute` endpoint instead. This is false by default.
            This can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account).
          example: false
        description:
          type: string
          description: Optional description/memo for the transfer
          example: 'Invoice #1234 payment'
        purposeOfPayment:
          $ref: '#/components/schemas/PurposeOfPayment'
        senderCustomerInfo:
          type: object
          additionalProperties: true
          description: |
            Key-value pairs of additional information about the sender which was requested by the destination. This is relevant when the destination requires more sender info than was provided during customer creation.
            Any fields specified in `requiredPayerDataFields` from the response of the `/receiver/uma/{receiverUmaAddress}` (lookupUma) or `/receiver/external-account/{accountId}` (lookupExternalAccount) endpoints MUST be provided here if they were requested. If the destination did not request any additional information, this field can be omitted.
          example:
            FULL_NAME: Jane Receiver
            NATIONALITY: FR
    ApprovePaymentRequest:
      type: object
      properties:
        receiverCustomerInfo:
          type: object
          additionalProperties: true
          description: Information about the recipient, provided by the platform if requested in the original webhook via `requestedReceiverCustomerInfoFields`.
    RejectPaymentRequest:
      type: object
      properties:
        reason:
          type: string
          description: Optional reason for rejecting the payment. This is just for debugging purposes or can be used for a platform's own purposes.
          example: RESTRICTED_JURISDICTION
    EstimateCryptoWithdrawalFeeRequest:
      type: object
      required:
        - internalAccountId
        - currency
        - cryptoNetwork
        - amount
        - destinationAddress
      properties:
        internalAccountId:
          type: string
          description: The ID of the crypto internal account to withdraw from.
          example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
        currency:
          type: string
          description: The currency code of the asset to withdraw (e.g. USDC).
          example: USDC
        cryptoNetwork:
          type: string
          description: 'The blockchain network for the withdrawal. Example values: SOLANA_MAINNET, SOLANA_DEVNET, ETHEREUM_MAINNET, POLYGON_MAINNET, TRON_MAINNET.'
          example: SOLANA_MAINNET
        amount:
          type: integer
          description: The amount to withdraw in the smallest unit of the currency.
          example: 1000000
        destinationAddress:
          type: string
          description: The blockchain address to withdraw funds to.
          example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
    EstimateCryptoWithdrawalFeeResponse:
      type: object
      required:
        - networkFee
        - networkFeeAsset
        - applicationFee
        - totalFee
        - netAmount
      properties:
        networkFee:
          type: integer
          description: The estimated network (gas) fee in the smallest unit of the network fee asset (e.g. lamports for SOL). This is provided for informational purposes to show the raw on-chain cost. Note that this value is denominated in networkFeeAsset, not in the withdrawal currency — it cannot be directly added to applicationFee or compared to totalFee.
          example: 5000
        networkFeeAsset:
          type: string
          description: The asset used to pay the network fee (e.g. SOL for Solana transactions).
          example: SOL
        applicationFee:
          type: integer
          description: The application fee charged by the platform in the smallest unit of the withdrawal currency. Zero if no application fee applies.
          example: 0
        totalFee:
          type: integer
          description: The total cost of the withdrawal in the smallest unit of the withdrawal currency. This equals the network fee converted to the withdrawal currency at current rates plus the application fee. This is the amount deducted from the withdrawal in addition to netAmount.
          example: 5000
        netAmount:
          type: integer
          description: The net amount the recipient will receive after fees, in the smallest unit of the withdrawal currency.
          example: 995000
    TestWebhookResponse:
      type: object
      required:
        - response_status
      properties:
        url:
          type: string
          format: uri
          description: URL where the webhook was sent
          example: https://api.mycompany.com/webhooks/uma
        response_status:
          type: integer
          description: The HTTP status code returned by the webhook endpoint
          example: 200
        response_body:
          type: string
          description: The raw body content returned by the webhook endpoint in response to the request
    BulkCustomerImportJobAccepted:
      type: object
      required:
        - jobId
        - status
      properties:
        jobId:
          type: string
          description: Unique identifier for the bulk import job
          example: Job:019542f5-b3e7-1d02-0000-000000000006
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
    GridError:
      type: object
      title: GridError
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    BulkCustomerImportErrorEntry:
      allOf:
        - $ref: '#/components/schemas/GridError'
        - type: object
          description: Error information for a failed bulk import entry
          required:
            - correlationId
          properties:
            correlationId:
              type: string
              description: Platform customer ID or row number for the failed entry
              example: biz456
    BulkCustomerImportJob:
      type: object
      required:
        - id
        - status
        - progress
      properties:
        id:
          type: string
          description: Unique identifier for the bulk import job
          example: Job:019542f5-b3e7-1d02-0000-000000000006
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
          description: Current status of the job
          example: PROCESSING
        progress:
          type: object
          required:
            - total
            - processed
            - successful
            - failed
          properties:
            total:
              type: integer
              description: Total number of customers to process
              example: 5000
            processed:
              type: integer
              description: Number of customers processed so far
              example: 2500
            successful:
              type: integer
              description: Number of customers successfully created
              example: 2450
            failed:
              type: integer
              description: Number of customers that failed to create
              example: 50
        errors:
          type: array
          description: Detailed error information for failed entries
          items:
            $ref: '#/components/schemas/BulkCustomerImportErrorEntry'
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the job completed (only present for COMPLETED or FAILED status)
          example: '2025-08-15T14:32:00Z'
    UmaInvitationCreateRequest:
      type: object
      required:
        - inviterUma
      properties:
        inviterUma:
          type: string
          description: The UMA address of the customer creating the invitation
          example: $inviter@uma.domain
        firstName:
          type: string
          description: First name of the invitee to show as part of the invite
          example: Alice
        amountToSend:
          description: |
            An amount to send (in the smallest unit of the customer's currency) to the invitee when the invitation is claimed.
            This is optional and if not provided, the invitee will not receive any amount. Note that the actual sending of
            the amount must be done by the inviter platform once the INVITATION_CLAIMED webhook is received. If the inviter
            platform either does not send the payment or the payment fails, the invitee will not receive this amount. This
            field is primarily used for display purposes on the claiming side of the invitation.
          type: integer
          format: int64
          example: 12550
        expiresAt:
          type: string
          format: date-time
          description: When the invitation expires (if at all)
          example: '2025-09-01T14:30:00Z'
    UmaInvitation:
      type: object
      required:
        - code
        - createdAt
        - inviterUma
        - status
        - url
      properties:
        code:
          type: string
          description: The unique code of the invitation
          example: 019542f5
        createdAt:
          type: string
          format: date-time
          description: When the invitation was created
          example: '2025-09-01T14:30:00Z'
        claimedAt:
          type: string
          format: date-time
          description: When the invitation was claimed if it has been claimed
          example: '2025-09-01T14:30:00Z'
        url:
          type: string
          description: The URL where this invitation can be claimed.
          example: https://uma.me/i/019542f5
        expiresAt:
          type: string
          format: date-time
          description: When the invitation expires (if at all)
          example: '2025-09-01T14:30:00Z'
        inviterUma:
          type: string
          description: The UMA address of the inviter
          example: $inviter@uma.domain
        inviteeUma:
          type: string
          description: The UMA address of the invitee
          example: $invitee@uma.domain
        status:
          type: string
          enum:
            - PENDING
            - CLAIMED
            - EXPIRED
            - CANCELLED
          description: The status of the invitation
          example: PENDING
        firstName:
          type: string
          description: The inviter's first name. Will be displayed when the recipient clicks the invite link
          example: Jane
        amountToSend:
          $ref: '#/components/schemas/CurrencyAmount'
          description: |-
            The amount to send to the invitee when the invitation is claimed. This is optional and if not provided, the invitee will not receive any amount. Note that the actual sending of the amount must be done by the inviter platform once the INVITATION_CLAIMED webhook is received. If the inviter platform either does not send the payment or the payment fails, the invitee will not receive this amount. This field is primarily used for display purposes on the claiming side of the invitation.
            This field is useful for "send-by-link" style customer flows where an inviter can send a payment simply by sharing a link without knowing the receiver's UMA address. Note that these sends can only be sender-locked, meaning that the sender will not know ahead of time how much the receiver will receive in the receiving currency.
    UmaInvitationClaimRequest:
      type: object
      required:
        - inviteeUma
      properties:
        inviteeUma:
          type: string
          description: The UMA address of the customer claiming the invitation
          example: $invitee@uma.domain
    Error403:
      type: object
      required:
        - message
        - status
        - code
      properties:
        status:
          type: integer
          enum:
            - 403
          description: HTTP status code
        code:
          type: string
          description: |
            | Error Code | Description |
            |------------|-------------|
            | FORBIDDEN | Insufficient permissions |
            | USER_NOT_READY | Customer exists but is not ready for operation |
            | COUNTERPARTY_NOT_ALLOWED | Counterparty has not been enabled for your account |
            | VELOCITY_LIMIT_EXCEEDED | Counterparty has exceeded velocity limits |
          enum:
            - FORBIDDEN
            - USER_NOT_READY
            - COUNTERPARTY_NOT_ALLOWED
            - VELOCITY_LIMIT_EXCEEDED
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
    SandboxSendRequest:
      type: object
      required:
        - quoteId
        - currencyCode
      properties:
        quoteId:
          type: string
          description: The unique identifier of the quote
          example: Quote:019542f5-b3e7-1d02-0000-000000000006
        currencyCode:
          type: string
          description: Currency code for the funds to be sent
          example: USD
        currencyAmount:
          type: integer
          format: int64
          description: The amount to send in the smallest unit of the currency (eg. cents). If not provided, the amount will be derived from the quote.
          exclusiveMinimum: 0
          example: 1000
    SandboxUmaReceiveRequest:
      type: object
      required:
        - senderUmaAddress
        - receivingCurrencyCode
        - receivingCurrencyAmount
      properties:
        senderUmaAddress:
          type: string
          description: UMA address of the sender from the sandbox
          example: $success.usd@sandbox.grid.uma.money
        receiverUmaAddress:
          type: string
          description: UMA address of the receiver (optional if customerId is provided)
          example: $receiver@uma.domain
        customerId:
          type: string
          description: System ID of the receiver (optional if receiverUmaAddress is provided)
          example: Customer:019542f5-b3e7-1d02-0000-000000000001
        receivingCurrencyCode:
          type: string
          description: The currency code for the receiving amount
          example: USD
        receivingCurrencyAmount:
          type: integer
          format: int64
          description: The amount to be received in the smallest unit of the currency (eg. cents)
          exclusiveMinimum: 0
          example: 1000
    SandboxFundRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: integer
          format: int64
          description: Amount to add in the smallest unit of the account's currency (e.g., cents for USD/EUR, satoshis for BTC)
          exclusiveMinimum: 0
          maximum: 100000000000
          example: 100000
    UmaProvider:
      type: object
      properties:
        name:
          type: string
          description: Name of the UMA Provider
          example: Lightspark Group
        supportedRegions:
          type: array
          items:
            type: string
          description: Region(s) this UMA Provider operates in
          example:
            - US
        domain:
          type: string
          description: Domain this VASP uses for UMA addresses
          example: uma.me
        logoUrl:
          type: string
          description: Logo URL for the VASP
          format: uri
          example: https://uma.me/logo.png
        supportedCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/Currency'
          description: List of currencies supported by this UMA Provider
          example:
            - code: USD
              name: United States Dollar
              symbol: $
              decimals: 2
        lei:
          type: string
          description: Legal Entity Identifier for the UMA Provider
          example: 5493001KJTIIGC8Y1R12
        allowListStatus:
          type: boolean
          description: Whether this UMA Provider is on your allow list
          example: true
    Permission:
      type: string
      enum:
        - VIEW
        - TRANSACT
        - MANAGE
      description: 'Permission of an API token that determines what actions the token can perform: VIEW: Can view all data, including platform config, customers and transactions TRANSACT: Can send payments MANAGE: Can manage platform config, api tokens and customers'
    ApiToken:
      type: object
      required:
        - id
        - name
        - permissions
        - clientId
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: System-generated unique identifier
          example: Token:019542f5-b3e7-1d02-0000-000000000001
        name:
          type: string
          description: Name of the token
          example: Sandbox read-only token
        permissions:
          type: array
          description: A list of permissions granted to the token
          items:
            $ref: '#/components/schemas/Permission'
        clientId:
          type: string
          description: An opaque identifier that should be used as a client_id (or username)  in the HTTP Basic Authentication scheme when issuing http requests to Grid.
          example: 01947d2284054f890000e63bca4810df
        clientSecret:
          type: string
          description: The secret that should be used to authenticate against Grid API. This secret is not stored and will never be available again after creation. Platform must keep this secret secure as it grants access to the account.
          example: ed0ad25881e234cc28fb2dec0a4fe64e4172
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2025-07-21T17:32:28Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2025-07-21T17:32:28Z'
    ApiTokenCreateRequest:
      type: object
      required:
        - name
        - permissions
      properties:
        name:
          type: string
          description: Name of the token to help identify it
          example: Sandbox read-only
        permissions:
          type: array
          description: A list of permissions to grant to the token
          items:
            $ref: '#/components/schemas/Permission'
    WebhookType:
      type: string
      enum:
        - OUTGOING_PAYMENT.PENDING
        - OUTGOING_PAYMENT.PROCESSING
        - OUTGOING_PAYMENT.COMPLETED
        - OUTGOING_PAYMENT.FAILED
        - OUTGOING_PAYMENT.EXPIRED
        - OUTGOING_PAYMENT.REFUND_PENDING
        - OUTGOING_PAYMENT.REFUND_COMPLETED
        - OUTGOING_PAYMENT.REFUND_FAILED
        - INCOMING_PAYMENT.PENDING
        - INCOMING_PAYMENT.COMPLETED
        - INCOMING_PAYMENT.FAILED
        - CUSTOMER.KYC_APPROVED
        - CUSTOMER.KYC_REJECTED
        - CUSTOMER.KYC_PENDING
        - CUSTOMER.KYB_APPROVED
        - CUSTOMER.KYB_REJECTED
        - CUSTOMER.KYB_PENDING
        - VERIFICATION.APPROVED
        - VERIFICATION.REJECTED
        - VERIFICATION.RESOLVE_ERRORS
        - VERIFICATION.IN_PROGRESS
        - VERIFICATION.PENDING_MANUAL_REVIEW
        - INTERNAL_ACCOUNT.BALANCE_UPDATED
        - INVITATION.CLAIMED
        - BULK_UPLOAD.COMPLETED
        - BULK_UPLOAD.FAILED
        - TEST
      description: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status.
    BaseWebhook:
      type: object
      required:
        - timestamp
        - id
        - type
      properties:
        id:
          type: string
          description: Unique identifier for this webhook delivery (can be used for idempotency)
          example: Webhook:019542f5-b3e7-1d02-0000-000000000007
        type:
          $ref: '#/components/schemas/WebhookType'
          description: Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED)
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the webhook was sent
          example: '2025-08-15T14:32:00Z'
    IncomingPaymentWebhookData:
      title: Incoming Payment Webhook Data
      allOf:
        - $ref: '#/components/schemas/IncomingTransaction'
        - type: object
          properties:
            requestedReceiverCustomerInfoFields:
              type: array
              items:
                $ref: '#/components/schemas/CounterpartyFieldDefinition'
              description: Information required by the sender's VASP about the recipient. Platform must provide these in the 200 OK response if approving. Note that this only includes fields which Grid does not already have from initial customer registration.
    IncomingPaymentWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/IncomingPaymentWebhookData'
            type:
              type: string
              enum:
                - INCOMING_PAYMENT.PENDING
                - INCOMING_PAYMENT.COMPLETED
                - INCOMING_PAYMENT.FAILED
    IncomingPaymentWebhookResponse:
      type: object
      properties:
        receiverCustomerInfo:
          type: object
          additionalProperties: true
          description: Information about the recipient, provided by the platform if requested in the webhook via `requestedReceiverCustomerInfoFields` and the payment is approved.
    IncomingPaymentWebhookForbiddenResponse:
      allOf:
        - $ref: '#/components/schemas/GridError'
        - type: object
          properties:
            reason:
              type: string
              description: Optional reason for rejecting the payment. This is just for debugging purposes or can be used for a platform's own purposes.
              example: RESTRICTED_JURISDICTION
    IncomingPaymentWebhookUnprocessableResponse:
      allOf:
        - $ref: '#/components/schemas/GridError'
        - type: object
          properties:
            requiredFields:
              type: array
              items:
                type: string
              description: List of fields that are required by the platform, but are not present in the counterparty information.
              example:
                - TAX_ID
                - REGISTRATION_NUMBER
    OutgoingPaymentWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OutgoingTransaction'
            type:
              type: string
              enum:
                - OUTGOING_PAYMENT.PENDING
                - OUTGOING_PAYMENT.PROCESSING
                - OUTGOING_PAYMENT.COMPLETED
                - OUTGOING_PAYMENT.FAILED
                - OUTGOING_PAYMENT.EXPIRED
                - OUTGOING_PAYMENT.REFUND_PENDING
                - OUTGOING_PAYMENT.REFUND_COMPLETED
                - OUTGOING_PAYMENT.REFUND_FAILED
    TestWebhookRequest:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          properties:
            type:
              type: string
              enum:
                - TEST
    BulkUploadWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/BulkCustomerImportJob'
            type:
              type: string
              enum:
                - BULK_UPLOAD.COMPLETED
                - BULK_UPLOAD.FAILED
    InvitationClaimedWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/UmaInvitation'
            type:
              type: string
              enum:
                - INVITATION.CLAIMED
    CustomerWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/CustomerOneOf'
            type:
              type: string
              enum:
                - CUSTOMER.KYC_APPROVED
                - CUSTOMER.KYC_REJECTED
                - CUSTOMER.KYC_PENDING
                - CUSTOMER.KYB_APPROVED
                - CUSTOMER.KYB_REJECTED
                - CUSTOMER.KYB_PENDING
    InternalAccountStatusWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/InternalAccount'
            type:
              type: string
              enum:
                - INTERNAL_ACCOUNT.BALANCE_UPDATED
    VerificationWebhook:
      allOf:
        - $ref: '#/components/schemas/BaseWebhook'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/Verification'
            type:
              type: string
              enum:
                - VERIFICATION.APPROVED
                - VERIFICATION.REJECTED
                - VERIFICATION.RESOLVE_ERRORS
                - VERIFICATION.IN_PROGRESS
                - VERIFICATION.PENDING_MANUAL_REVIEW